From f0fc4a0e40d77ea685453d7e326060396e9a2900 Mon Sep 17 00:00:00 2001
From: John Arthorne
Date: Fri, 5 Mar 2010 18:53:14 +0000
Subject: Bug 266384 - [repo] clarify behavior for various repo property flags
---
.../eclipse/equinox/p2/repository/IRepository.java | 16 +++++++++++++--
.../equinox/p2/repository/IRepositoryManager.java | 23 ++++++++++++++++------
2 files changed, 31 insertions(+), 8 deletions(-)
(limited to 'bundles/org.eclipse.equinox.p2.repository')
diff --git a/bundles/org.eclipse.equinox.p2.repository/src/org/eclipse/equinox/p2/repository/IRepository.java b/bundles/org.eclipse.equinox.p2.repository/src/org/eclipse/equinox/p2/repository/IRepository.java
index 94ff02bbd..69128c9bf 100644
--- a/bundles/org.eclipse.equinox.p2.repository/src/org/eclipse/equinox/p2/repository/IRepository.java
+++ b/bundles/org.eclipse.equinox.p2.repository/src/org/eclipse/equinox/p2/repository/IRepository.java
@@ -29,6 +29,9 @@ public interface IRepository extends IAdaptable, IQueryable {
* The key for a boolean property indicating that the repository
* is a system repository. System repositories are implementation details
* that are not subject to general access, hidden from the typical user, etc.
+ * This property is never stored in the repository itself, but is instead tracked and
+ * managed by an {@link IRepositoryManager}.
+ * @see IRepositoryManager#getRepositoryProperty(URI, String)
*/
public static final String PROP_SYSTEM = "p2.system"; //$NON-NLS-1$
@@ -37,40 +40,49 @@ public interface IRepository extends IAdaptable, IQueryable {
* stored in compressed form. A compressed repository will have lower
* bandwidth cost to read when remote, but higher processing cost to
* uncompress when reading.
+ * @see IRepository#getProperties()
*/
public static final String PROP_COMPRESSED = "p2.compressed"; //$NON-NLS-1$
/**
* The key for a string property providing a human-readable name for the repository.
+ * @see IRepositoryManager#getRepositoryProperty(URI, String)
+ * @see IRepository#getProperties()
*/
public static final String PROP_NAME = "name"; //$NON-NLS-1$
/**
* The key for a string property providing a user-defined name for the repository.
- * This property is never stored in the repository itself, but is instead tracked and managed
- * by an {@link IRepositoryManager}.
+ * This property is never stored in the repository itself, but is instead tracked and
+ * managed by an {@link IRepositoryManager}.
+ * @see IRepositoryManager#getRepositoryProperty(URI, String)
*/
public static final String PROP_NICKNAME = "p2.nickname"; //$NON-NLS-1$
/**
* The key for a string property providing a human-readable description for the repository.
+ * @see IRepositoryManager#getRepositoryProperty(URI, String)
+ * @see IRepository#getProperties()
*/
public static final String PROP_DESCRIPTION = "description"; //$NON-NLS-1$
/**
* The key for a string property providing the common base URL that should
* be replaced with the mirror URL.
+ * @see IRepository#getProperties()
*/
public static final String PROP_MIRRORS_BASE_URL = "p2.mirrorsBaseURL"; //$NON-NLS-1$
/**
* The key for a string property providing a URL that can return mirrors of this
* repository.
+ * @see IRepository#getProperties()
*/
public static final String PROP_MIRRORS_URL = "p2.mirrorsURL"; //$NON-NLS-1$
/**
* The key for a string property containing the time when the repository was last modified.
+ * @see IRepository#getProperties()
*/
public static final String PROP_TIMESTAMP = "p2.timestamp"; //$NON-NLS-1$
diff --git a/bundles/org.eclipse.equinox.p2.repository/src/org/eclipse/equinox/p2/repository/IRepositoryManager.java b/bundles/org.eclipse.equinox.p2.repository/src/org/eclipse/equinox/p2/repository/IRepositoryManager.java
index d5a432315..a6501632f 100644
--- a/bundles/org.eclipse.equinox.p2.repository/src/org/eclipse/equinox/p2/repository/IRepositoryManager.java
+++ b/bundles/org.eclipse.equinox.p2.repository/src/org/eclipse/equinox/p2/repository/IRepositoryManager.java
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2008, 2009 IBM Corporation and others.
+ * Copyright (c) 2008, 2010 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
@@ -123,14 +123,15 @@ public interface IRepositoryManager extends IQueryable {
* Returns the property associated with the repository at the given URI,
* without loading the repository.
*
- * Note that some properties for a repository can only be
- * determined when that repository is loaded. This method will return null
- * for such properties. Only values for the properties that are already
- * known by a repository manager will be returned.
+ * Note that only the repository properties referenced below are tracked by the
+ * repository manager itself. For all other properties, this method will return null
.
+ * Only values for the properties that are already known by a repository manager will be returned.
+ *
*
* If a client wishes to retrieve a property value from a repository
* regardless of the cost of retrieving it, the client should load the
* repository and then retrieve the property from the repository itself.
+ *
*
* @param location the absolute URI of the repository in question
* @param key the String key of the property desired
@@ -140,6 +141,10 @@ public interface IRepositoryManager extends IQueryable {
*
* @see IRepository#getProperties()
* @see #setRepositoryProperty(URI, String, String)
+ * @see IRepository#PROP_NAME
+ * @see IRepository#PROP_NICKNAME
+ * @see IRepository#PROP_DESCRIPTION
+ * @see IRepository#PROP_SYSTEM
*/
public String getRepositoryProperty(URI location, String key);
@@ -151,7 +156,9 @@ public interface IRepositoryManager extends IQueryable {
* not write the property to the backing repository. This is useful for making
* repository properties available without incurring the cost of loading the repository.
* When the repository is loaded, it will overwrite any conflicting properties that
- * have been set using this method.
+ * have been set using this method. Only the repository properties referenced
+ * below can be stored by the repository manager; attempts to set other
+ * repository properties will be ignored.
*
*
* To persistently set a property on a repository, clients must load
@@ -163,6 +170,10 @@ public interface IRepositoryManager extends IQueryable {
* @param value the value to set the property to
* @see #getRepositoryProperty(URI, String)
* @see IRepository#setProperty(String, String)
+ * @see IRepository#PROP_NAME
+ * @see IRepository#PROP_NICKNAME
+ * @see IRepository#PROP_DESCRIPTION
+ * @see IRepository#PROP_SYSTEM
*/
public void setRepositoryProperty(URI location, String key, String value);
--
cgit v1.2.3