bundles/org.eclipse.equinox.p2.repository/src/org/eclipse/equinox/p2/repository/IRepository.java - equinox/rt.equinox.p2 - Git at Google

 /*******************************************************************************
  *  Copyright (c) 2007, 2011 IBM Corporation and others.
  *
  *  This program and the accompanying materials
  *  are made available under the terms of the Eclipse Public License 2.0
  *  which accompanies this distribution, and is available at
  *  https://www.eclipse.org/legal/epl-2.0/
  *
  *  SPDX-License-Identifier: EPL-2.0
  *
  *  Contributors:
  *     IBM Corporation - initial API and implementation
  *******************************************************************************/
 package org.eclipse.equinox.p2.repository;

 import java.net.URI;
 import java.util.Map;
 import org.eclipse.core.runtime.IAdaptable;
 import org.eclipse.core.runtime.IProgressMonitor;
 import org.eclipse.equinox.p2.core.IProvisioningAgent;
 import org.eclipse.equinox.p2.query.IQueryable;

 /**
  * A p2 repository contains either metadata or artifacts related to software
  * provisioning. This base interface defines properties common to all types
  * of repositories.
  * @param <T> The type of contents contained in this repository
  *
  * @noimplement This interface is not intended to be implemented by clients. Instead the abstract classes implementing this interface should be used.
  * @noextend This interface is not intended to be extended by clients.
  * @since 2.0
  */
 public interface IRepository<T> extends IAdaptable, IQueryable<T> {
 	/**
 	 * 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$

 	/**
 	 * The key for a boolean property indicating that repository metadata is
 	 * 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}.
 	 * @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$

 	/**
 	 * The key for a string property providing the user name to an authenticated
 	 * URL.  This key is used in the secure preference store for repository data.
 	 * @see #PREFERENCE_NODE
 	 */
 	public static final String PROP_USERNAME = "username"; //$NON-NLS-1$

 	/**
 	 * The key for a string property providing the password to an authenticated
 	 * URL.  This key is used in the secure preference store for repository data.
 	 * @see #PREFERENCE_NODE
 	 */
 	public static final String PROP_PASSWORD = "password"; //$NON-NLS-1$

 	/**
 	 * The node identifier for repository secure preference store.
 	 */
 	public static final String PREFERENCE_NODE = "org.eclipse.equinox.p2.repository"; //$NON-NLS-1$

 	/**
 	 * A repository type constant (value 0) representing a metadata repository.
 	 */
 	public static final int TYPE_METADATA = 0;

 	/**
 	 * A repository type constant (value 1) representing an artifact repository.
 	 */
 	public static final int TYPE_ARTIFACT = 1;

 	/**
 	 * General purpose zero-valued bit mask constant. Useful whenever you need to
 	 * supply a bit mask with no bits set.
 	 */
 	public static final int NONE = 0;

 	/**
 	 * An option flag constant (value 1) indicating an enabled repository.
 	 */
 	public static final int ENABLED = 1;

 	/**
 	 * Returns the location of this repository.
 	 * @return the URI representing the repository location.
 	 */
 	public URI getLocation();

 	/**
 	 * Returns the name of the repository.
 	 * @return the name of the repository.
 	 */
 	public String getName();

 	/**
 	 * Returns a string representing the type of the repository. Note this method
 	 * does not indicate the type of repository contents (metadata or artifacts),
 	 * but instead the unique fully qualified id representing the repository implementation.
 	 * @return the type of the repository.
 	 */
 	public String getType();

 	/**
 	 * Returns a string representing the version for the repository type.
 	 * @return the version of the type of the repository.
 	 */
 	public String getVersion();

 	/**
 	 * Returns a brief description of the repository.
 	 * @return the description of the repository.
 	 */
 	public String getDescription();

 	/**
 	 * Returns the name of the provider of the repository.
 	 * @return the provider of this repository.
 	 */
 	public String getProvider();

 	/**
 	 * Returns a read-only collection of the properties of the repository.
 	 * @return the properties of this repository.
 	 */
 	public Map<String, String> getProperties();

 	/**
 	 * Returns the repository property with the given key, or <code>null</code>
 	 * if no such property is defined
 	 * @param key the property key
 	 * @return the property value, or <code>null</code>
 	 */
 	public String getProperty(String key);

 	/**
 	 * Returns the provisioning agent that manages this repository
 	 * @return A provisioning agent.
 	 */
 	public IProvisioningAgent getProvisioningAgent();

 	/**
 	 * Returns <code>true</code> if this repository can be modified, and
 	 * <code>false</code> otherwise. Attempts to change the contents of
 	 * an unmodifiable repository will fail.
 	 * @return whether or not this repository can be modified
 	 */
 	public boolean isModifiable();

 	/**
 	 * Sets the value of the property with the given key. Returns the old property
 	 * associated with that key, if any.  Setting a value of <code>null</code> will
 	 * remove the corresponding key from the properties of this repository.
 	 *
 	 * @param key The property key
 	 * @param value The new property value, or <code>null</code> to remove the key
 	 * @return The old property value, or <code>null</code> if there was no old value
 	 */
 	public String setProperty(String key, String value);

 	/**
 	 * Sets the value of the property with the given key. Returns the old property
 	 * associated with that key, if any.  Setting a value of <code>null</code> will
 	 * remove the corresponding key from the properties of this repository.
 	 *
 	 * @param key The property key
 	 * @param value The new property value, or <code>null</code> to remove the key
 	 * @param monitor A progress monitor use to track progress and cancel the operation.  This may
 	 * be a long running operation if another process holds the lock on this location
 	 * @return The old property value, or <code>null</code> if there was no old value
 	 * @since 2.1
 	 */
 	public String setProperty(String key, String value, IProgressMonitor monitor);
 }
	/*******************************************************************************
	* Copyright (c) 2007, 2011 IBM Corporation and others.
	*
	* This program and the accompanying materials
	* are made available under the terms of the Eclipse Public License 2.0
	* which accompanies this distribution, and is available at
	* https://www.eclipse.org/legal/epl-2.0/
	*
	* SPDX-License-Identifier: EPL-2.0
	*
	* Contributors:
	* IBM Corporation - initial API and implementation
	*******************************************************************************/
	package org.eclipse.equinox.p2.repository;

	import java.net.URI;
	import java.util.Map;
	import org.eclipse.core.runtime.IAdaptable;
	import org.eclipse.core.runtime.IProgressMonitor;
	import org.eclipse.equinox.p2.core.IProvisioningAgent;
	import org.eclipse.equinox.p2.query.IQueryable;

	/**
	* A p2 repository contains either metadata or artifacts related to software
	* provisioning. This base interface defines properties common to all types
	* of repositories.
	* @param <T> The type of contents contained in this repository
	*
	* @noimplement This interface is not intended to be implemented by clients. Instead the abstract classes implementing this interface should be used.
	* @noextend This interface is not intended to be extended by clients.
	* @since 2.0
	*/
	public interface IRepository<T> extends IAdaptable, IQueryable<T> {
	/**
	* 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$

	/**
	* The key for a boolean property indicating that repository metadata is
	* 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}.
	* @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$

	/**
	* The key for a string property providing the user name to an authenticated
	* URL. This key is used in the secure preference store for repository data.
	* @see #PREFERENCE_NODE
	*/
	public static final String PROP_USERNAME = "username"; //$NON-NLS-1$

	/**
	* The key for a string property providing the password to an authenticated
	* URL. This key is used in the secure preference store for repository data.
	* @see #PREFERENCE_NODE
	*/
	public static final String PROP_PASSWORD = "password"; //$NON-NLS-1$

	/**
	* The node identifier for repository secure preference store.
	*/
	public static final String PREFERENCE_NODE = "org.eclipse.equinox.p2.repository"; //$NON-NLS-1$

	/**
	* A repository type constant (value 0) representing a metadata repository.
	*/
	public static final int TYPE_METADATA = 0;

	/**
	* A repository type constant (value 1) representing an artifact repository.
	*/
	public static final int TYPE_ARTIFACT = 1;

	/**
	* General purpose zero-valued bit mask constant. Useful whenever you need to
	* supply a bit mask with no bits set.
	*/
	public static final int NONE = 0;

	/**
	* An option flag constant (value 1) indicating an enabled repository.
	*/
	public static final int ENABLED = 1;

	/**
	* Returns the location of this repository.
	* @return the URI representing the repository location.
	*/
	public URI getLocation();

	/**
	* Returns the name of the repository.
	* @return the name of the repository.
	*/
	public String getName();

	/**
	* Returns a string representing the type of the repository. Note this method
	* does not indicate the type of repository contents (metadata or artifacts),
	* but instead the unique fully qualified id representing the repository implementation.
	* @return the type of the repository.
	*/
	public String getType();

	/**
	* Returns a string representing the version for the repository type.
	* @return the version of the type of the repository.
	*/
	public String getVersion();

	/**
	* Returns a brief description of the repository.
	* @return the description of the repository.
	*/
	public String getDescription();

	/**
	* Returns the name of the provider of the repository.
	* @return the provider of this repository.
	*/
	public String getProvider();

	/**
	* Returns a read-only collection of the properties of the repository.
	* @return the properties of this repository.
	*/
	public Map<String, String> getProperties();

	/**
	* Returns the repository property with the given key, or <code>null</code>
	* if no such property is defined
	* @param key the property key
	* @return the property value, or <code>null</code>
	*/
	public String getProperty(String key);

	/**
	* Returns the provisioning agent that manages this repository
	* @return A provisioning agent.
	*/
	public IProvisioningAgent getProvisioningAgent();

	/**
	* Returns <code>true</code> if this repository can be modified, and
	* <code>false</code> otherwise. Attempts to change the contents of
	* an unmodifiable repository will fail.
	* @return whether or not this repository can be modified
	*/
	public boolean isModifiable();

	/**
	* Sets the value of the property with the given key. Returns the old property
	* associated with that key, if any. Setting a value of <code>null</code> will
	* remove the corresponding key from the properties of this repository.
	*
	* @param key The property key
	* @param value The new property value, or <code>null</code> to remove the key
	* @return The old property value, or <code>null</code> if there was no old value
	*/
	public String setProperty(String key, String value);

	/**
	* Sets the value of the property with the given key. Returns the old property
	* associated with that key, if any. Setting a value of <code>null</code> will
	* remove the corresponding key from the properties of this repository.
	*
	* @param key The property key
	* @param value The new property value, or <code>null</code> to remove the key
	* @param monitor A progress monitor use to track progress and cancel the operation. This may
	* be a long running operation if another process holds the lock on this location
	* @return The old property value, or <code>null</code> if there was no old value
	* @since 2.1
	*/
	public String setProperty(String key, String value, IProgressMonitor monitor);
	}