bundles/org.eclipse.equinox.p2.repository/src/org/eclipse/equinox/internal/provisional/p2/repository/IRepositoryManager.java - equinox/rt.equinox.p2 - Git at Google

 /*******************************************************************************
  * Copyright (c) 2008, 2009 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
  * http://www.eclipse.org/legal/epl-v10.html
  *
  * Contributors:
  *     IBM Corporation - initial API and implementation
  *******************************************************************************/
 package org.eclipse.equinox.internal.provisional.p2.repository;

 import java.net.URI;

 /**
  * The common base class for metadata and artifact repository managers.
  * <p>
  * A repository manager keeps track of a set of known repositories, and provides
  * caching of these known repositories to avoid unnecessary loading of repositories
  * from the disk or network.  The manager fires {@link RepositoryEvent}s when the
  * set of known repositories changes.
  * </p>
  * <p>
  * All {@link URI} instances provided to a repository manager must be absolute.
  * </p>
  *
  * @noimplement This interface is not intended to be implemented by clients.
  */
 public interface IRepositoryManager {
 	/**
 	 * Constant used to indicate that all enabled repositories are of interest.
 	 */
 	public static final int REPOSITORIES_ALL = 0;

 	/**
 	 * Constant used to indicate that disabled repositories are of interest.
 	 * @see #getKnownRepositories(int)
 	 */
 	public static final int REPOSITORIES_DISABLED = 1 << 3;

 	/**
 	 * Constant used to indicate that local repositories are of interest.
 	 * @see #getKnownRepositories(int)
 	 */
 	public static final int REPOSITORIES_LOCAL = 1 << 2;

 	/**
 	 * Constant used to indicate that non-system repositories are of interest.
 	 * @see IRepository#PROP_SYSTEM
 	 * @see #getKnownRepositories(int)
 	 */
 	public static final int REPOSITORIES_NON_SYSTEM = 1 << 1;

 	/**
 	 * Constant used to indicate that system repositories are of interest.
 	 * @see IRepository#PROP_SYSTEM
 	 * @see #getKnownRepositories(int)
 	 */
 	public static final int REPOSITORIES_SYSTEM = 1 << 0;

 	/**
 	 * Constant used to indicate that a repository manager should only load the
 	 * repository if the repository is modifiable.
 	 * @see IRepository#isModifiable()
 	 */
 	public static final int REPOSITORY_HINT_MODIFIABLE = 1 << 0;

 	/**
 	 * Adds the repository at the given location to the list of repositories tracked by
 	 * this repository manager.
 	 * <p>
 	 * If there is a known disabled repository at the given location, it will become
 	 * enabled as a result of this method. Thus the caller can be guaranteed that
 	 * there is a known, enabled repository at the given location when this method returns.
 	 *
 	 * @param location The absolute location of the repository to add
 	 * @see #isEnabled(URI)
 	 */
 	public void addRepository(URI location);

 	/**
 	 * Returns whether a repository at the given location is in the list of repositories
 	 * tracked by this repository manager.
 	 *
 	 * @param location The absolute location of the repository to look for
 	 * @return <code>true</code> if the repository is known to this manager,
 	 * and <code>false</code> otherwise
 	 */
 	public boolean contains(URI location);

 	/**
 	 * Returns the artifact repository locations known to the repository manager.
 	 * <p>
 	 * Note that the repository manager does not guarantee that a valid repository
 	 * exists at any of the returned locations at any particular moment in time.
 	 * A subsequent attempt to load a repository at any of the given locations may
 	 * or may not succeed.
 	 *
 	 * @param flags an integer bit-mask indicating which repositories should be
 	 * returned.  <code>REPOSITORIES_ALL</code> can be used as the mask when
 	 * all enabled repositories should be returned.
 	 * @return the locations of the repositories managed by this repository manager.
 	 *
 	 * @see #REPOSITORIES_ALL
 	 * @see #REPOSITORIES_SYSTEM
 	 * @see #REPOSITORIES_NON_SYSTEM
 	 * @see #REPOSITORIES_LOCAL
 	 * @see #REPOSITORIES_DISABLED
 	 */
 	public URI[] getKnownRepositories(int flags);

 	/**
 	 * Returns the property associated with the repository at the given URI,
 	 * without loading the repository.
 	 * <p>
 	 * Note that some properties for a repository can only be
 	 * determined when that repository is loaded.  This method will return <code>null</code>
 	 * for such properties.  Only values for the properties that are already
 	 * known by a repository manager will be returned.
 	 * <p>
 	 * 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
 	 * @return the value of the property, or <code>null</code> if the repository
 	 * does not exist, the value does not exist, or the property value
 	 * could not be determined without loading the repository.
 	 *
 	 * @see IRepository#getProperties()
 	 * @see #setRepositoryProperty(URI, String, String)
 	 */
 	public String getRepositoryProperty(URI location, String key);

 	/**
 	 * Sets the property associated with the repository at the given URI,
 	 * without loading the repository.
 	 * <p>
 	 * This method stores properties in a cache in the repository manager and does
 	 * 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.
 	 * </p>
 	 * <p>
 	 * To persistently set a property on a repository, clients must load
 	 * the repository and call {@link IRepository#setProperty(String, String)}.
 	 * </p>
 	 *
 	 * @param location the absolute URI of the repository in question
 	 * @param key the String key of the property desired
 	 * @param value the value to set the property to
 	 * @see #getRepositoryProperty(URI, String)
 	 * @see IRepository#setProperty(String, String)
 	 */
 	public void setRepositoryProperty(URI location, String key, String value);

 	/**
 	 * Returns the enablement value of a repository.  Disabled repositories are known
 	 * to the repository manager, but are never used in the context of provisioning
 	 * operations. Disabled repositories are useful as a form of bookmark to indicate that a
 	 * repository location is of interest, but not currently used.
 	 * <p>
 	 * Note that enablement is a property of the repository manager and not a property
 	 * of the affected repository. The enablement of the repository is discarded when
 	 * a repository is removed from the repository manager.
 	 *
 	 * @param location The absolute location of the repository whose enablement is requested
 	 * @return <code>true</code> if the repository is enabled, and
 	 * <code>false</code> if it is not enabled, or if the repository location
 	 * is not known to the repository manager.
 	 * @see #REPOSITORIES_DISABLED
 	 * @see #setEnabled(URI, boolean)
 	 */
 	public boolean isEnabled(URI location);

 	/**
 	 * Removes the repository at the given location from the list of
 	 * repositories known to this repository manager.  The underlying
 	 * repository is not deleted. This method has no effect if the given
 	 * repository is not already known to this repository manager.
 	 *
 	 * @param location The absolute location of the repository to remove
 	 * @return <code>true</code> if a repository was removed, and
 	 * <code>false</code> otherwise.
 	 */
 	public boolean removeRepository(URI location);

 	/**
 	 * Sets the enablement of a repository. Disabled repositories are known
 	 * to the repository manager, but are never used in the context of provisioning
 	 * operation. Disabled repositories are useful as a form of bookmark to indicate that a
 	 * repository location is of interest, but not currently used.
 	 * <p>
 	 * Note that enablement is a property of the repository manager and not a property
 	 * of the affected repository. The enablement of the repository is discarded when
 	 * a repository is removed from the repository manager.
 	 * <p>
 	 * This method has no effect if the given repository location is not known to the
 	 * repository manager.
 	 *
 	 * @param location The absolute location of the repository to enable or disable
 	 * @param enablement <code>true</code>to enable the repository, and
 	 * <code>false</code> to disable the repository
 	 * @see #REPOSITORIES_DISABLED
 	 * @see #isEnabled(URI)
 	 */
 	public void setEnabled(URI location, boolean enablement);

 }
	/*******************************************************************************
	* Copyright (c) 2008, 2009 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
	* http://www.eclipse.org/legal/epl-v10.html
	*
	* Contributors:
	* IBM Corporation - initial API and implementation
	*******************************************************************************/
	package org.eclipse.equinox.internal.provisional.p2.repository;

	import java.net.URI;

	/**
	* The common base class for metadata and artifact repository managers.
	* <p>
	* A repository manager keeps track of a set of known repositories, and provides
	* caching of these known repositories to avoid unnecessary loading of repositories
	* from the disk or network. The manager fires {@link RepositoryEvent}s when the
	* set of known repositories changes.
	* </p>
	* <p>
	* All {@link URI} instances provided to a repository manager must be absolute.
	* </p>
	*
	* @noimplement This interface is not intended to be implemented by clients.
	*/
	public interface IRepositoryManager {
	/**
	* Constant used to indicate that all enabled repositories are of interest.
	*/
	public static final int REPOSITORIES_ALL = 0;

	/**
	* Constant used to indicate that disabled repositories are of interest.
	* @see #getKnownRepositories(int)
	*/
	public static final int REPOSITORIES_DISABLED = 1 << 3;

	/**
	* Constant used to indicate that local repositories are of interest.
	* @see #getKnownRepositories(int)
	*/
	public static final int REPOSITORIES_LOCAL = 1 << 2;

	/**
	* Constant used to indicate that non-system repositories are of interest.
	* @see IRepository#PROP_SYSTEM
	* @see #getKnownRepositories(int)
	*/
	public static final int REPOSITORIES_NON_SYSTEM = 1 << 1;

	/**
	* Constant used to indicate that system repositories are of interest.
	* @see IRepository#PROP_SYSTEM
	* @see #getKnownRepositories(int)
	*/
	public static final int REPOSITORIES_SYSTEM = 1 << 0;

	/**
	* Constant used to indicate that a repository manager should only load the
	* repository if the repository is modifiable.
	* @see IRepository#isModifiable()
	*/
	public static final int REPOSITORY_HINT_MODIFIABLE = 1 << 0;

	/**
	* Adds the repository at the given location to the list of repositories tracked by
	* this repository manager.
	* <p>
	* If there is a known disabled repository at the given location, it will become
	* enabled as a result of this method. Thus the caller can be guaranteed that
	* there is a known, enabled repository at the given location when this method returns.
	*
	* @param location The absolute location of the repository to add
	* @see #isEnabled(URI)
	*/
	public void addRepository(URI location);

	/**
	* Returns whether a repository at the given location is in the list of repositories
	* tracked by this repository manager.
	*
	* @param location The absolute location of the repository to look for
	* @return <code>true</code> if the repository is known to this manager,
	* and <code>false</code> otherwise
	*/
	public boolean contains(URI location);

	/**
	* Returns the artifact repository locations known to the repository manager.
	* <p>
	* Note that the repository manager does not guarantee that a valid repository
	* exists at any of the returned locations at any particular moment in time.
	* A subsequent attempt to load a repository at any of the given locations may
	* or may not succeed.
	*
	* @param flags an integer bit-mask indicating which repositories should be
	* returned. <code>REPOSITORIES_ALL</code> can be used as the mask when
	* all enabled repositories should be returned.
	* @return the locations of the repositories managed by this repository manager.
	*
	* @see #REPOSITORIES_ALL
	* @see #REPOSITORIES_SYSTEM
	* @see #REPOSITORIES_NON_SYSTEM
	* @see #REPOSITORIES_LOCAL
	* @see #REPOSITORIES_DISABLED
	*/
	public URI[] getKnownRepositories(int flags);

	/**
	* Returns the property associated with the repository at the given URI,
	* without loading the repository.
	* <p>
	* Note that some properties for a repository can only be
	* determined when that repository is loaded. This method will return <code>null</code>
	* for such properties. Only values for the properties that are already
	* known by a repository manager will be returned.
	* <p>
	* 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
	* @return the value of the property, or <code>null</code> if the repository
	* does not exist, the value does not exist, or the property value
	* could not be determined without loading the repository.
	*
	* @see IRepository#getProperties()
	* @see #setRepositoryProperty(URI, String, String)
	*/
	public String getRepositoryProperty(URI location, String key);

	/**
	* Sets the property associated with the repository at the given URI,
	* without loading the repository.
	* <p>
	* This method stores properties in a cache in the repository manager and does
	* 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.
	* </p>
	* <p>
	* To persistently set a property on a repository, clients must load
	* the repository and call {@link IRepository#setProperty(String, String)}.
	* </p>
	*
	* @param location the absolute URI of the repository in question
	* @param key the String key of the property desired
	* @param value the value to set the property to
	* @see #getRepositoryProperty(URI, String)
	* @see IRepository#setProperty(String, String)
	*/
	public void setRepositoryProperty(URI location, String key, String value);

	/**
	* Returns the enablement value of a repository. Disabled repositories are known
	* to the repository manager, but are never used in the context of provisioning
	* operations. Disabled repositories are useful as a form of bookmark to indicate that a
	* repository location is of interest, but not currently used.
	* <p>
	* Note that enablement is a property of the repository manager and not a property
	* of the affected repository. The enablement of the repository is discarded when
	* a repository is removed from the repository manager.
	*
	* @param location The absolute location of the repository whose enablement is requested
	* @return <code>true</code> if the repository is enabled, and
	* <code>false</code> if it is not enabled, or if the repository location
	* is not known to the repository manager.
	* @see #REPOSITORIES_DISABLED
	* @see #setEnabled(URI, boolean)
	*/
	public boolean isEnabled(URI location);

	/**
	* Removes the repository at the given location from the list of
	* repositories known to this repository manager. The underlying
	* repository is not deleted. This method has no effect if the given
	* repository is not already known to this repository manager.
	*
	* @param location The absolute location of the repository to remove
	* @return <code>true</code> if a repository was removed, and
	* <code>false</code> otherwise.
	*/
	public boolean removeRepository(URI location);

	/**
	* Sets the enablement of a repository. Disabled repositories are known
	* to the repository manager, but are never used in the context of provisioning
	* operation. Disabled repositories are useful as a form of bookmark to indicate that a
	* repository location is of interest, but not currently used.
	* <p>
	* Note that enablement is a property of the repository manager and not a property
	* of the affected repository. The enablement of the repository is discarded when
	* a repository is removed from the repository manager.
	* <p>
	* This method has no effect if the given repository location is not known to the
	* repository manager.
	*
	* @param location The absolute location of the repository to enable or disable
	* @param enablement <code>true</code>to enable the repository, and
	* <code>false</code> to disable the repository
	* @see #REPOSITORIES_DISABLED
	* @see #isEnabled(URI)
	*/
	public void setEnabled(URI location, boolean enablement);

	}