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