Package org.eclipse.equinox.p2.repository

Interface IRepositoryManager<T>

Type Parameters:
T - the type of contents in the repositories controlled by this manager
All Superinterfaces:
IQueryable<T>
All Known Subinterfaces:
IArtifactRepositoryManager, IMetadataRepositoryManager
public interface IRepositoryManager<T> extends IQueryable<T>
The common base class for metadata and artifact repository managers.

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.

All URI instances provided to a repository manager must be absolute.

Since:
2.0
Restriction:
This interface is not intended to be implemented by clients.
Restriction:
This interface is not intended to be extended by clients.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    REPOSITORIES_ALL
    Constant used to indicate that all enabled repositories are of interest.
    static final int
    REPOSITORIES_DISABLED
    Constant used to indicate that only disabled repositories are of interest.
    static final int
    REPOSITORIES_LOCAL
    Constant used to indicate that only local repositories are of interest.
    static final int
    REPOSITORIES_NON_LOCAL
    Constant used to indicate that only remote repositories are of interest.
    static final int
    REPOSITORIES_NON_SYSTEM
    Constant used to indicate that only non-system repositories are of interest.
    static final int
    REPOSITORIES_SYSTEM
    Constant used to indicate that only system repositories are of interest.
    static final int
    REPOSITORY_HINT_MODIFIABLE
    Constant used to indicate that a repository manager should only load the repository if the repository is modifiable.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addRepository(URI location)
    Adds the repository at the given location to the list of repositories tracked by this repository manager.
    boolean
    contains(URI location)
    Returns whether a repository at the given location is in the list of repositories tracked by this repository manager.
    IRepository<T>
    createRepository(URI location, String name, String type, Map<String,String> properties)
    Creates and returns a new empty repository of the given type at the given location.
    IProvisioningAgent
    getAgent()
    Returns the provisioning agent in charge of this repository manager
    URI[]
    getKnownRepositories(int flags)
    Returns the repository locations known to the repository manager.
    String
    getRepositoryProperty(URI location, String key)
    Returns the property associated with the repository at the given URI, without loading the repository.
    boolean
    isEnabled(URI location)
    Returns the enablement value of a repository.
    IRepository<T>
    loadRepository(URI location, int flags, IProgressMonitor monitor)
    Loads the repository at the given location.
    IRepository<T>
    loadRepository(URI location, IProgressMonitor monitor)
    Loads the repository at the given location.
    IRepository<T>
    refreshRepository(URI location, IProgressMonitor monitor)
    Refreshes the repository corresponding to the given URL.
    boolean
    removeRepository(URI location)
    Removes the repository at the given location from the list of repositories known to this repository manager.
    void
    setEnabled(URI location, boolean enablement)
    Sets the enablement of a repository.
    void
    setRepositoryProperty(URI location, String key, String value)
    Sets the property associated with the repository at the given URI, without loading the repository.

    Methods inherited from interface org.eclipse.equinox.p2.query.IQueryable

    contains, query

  • Field Details

    • REPOSITORIES_ALL

      static final int REPOSITORIES_ALL
      Constant used to indicate that all enabled repositories are of interest.
      See Also:

    • REPOSITORIES_SYSTEM

      static final int REPOSITORIES_SYSTEM
      Constant used to indicate that only system repositories are of interest.
      See Also:

    • REPOSITORIES_NON_SYSTEM

      static final int REPOSITORIES_NON_SYSTEM
      Constant used to indicate that only non-system repositories are of interest.
      See Also:

    • REPOSITORIES_LOCAL

      static final int REPOSITORIES_LOCAL
      Constant used to indicate that only local repositories are of interest. Any repository that requires network communication will be omitted when this flag is used.
      See Also:

    • REPOSITORIES_NON_LOCAL

      static final int REPOSITORIES_NON_LOCAL
      Constant used to indicate that only remote repositories are of interest. Any repository that doesn't require network communication will be omitted when this flag is used.
      See Also:

    • REPOSITORIES_DISABLED

      static final int REPOSITORIES_DISABLED
      Constant used to indicate that only disabled repositories are of interest. When this flag is used, all enabled repositories will be ignored and all disabled repositories that match the remaining filters will be returned.
      See Also:

    • REPOSITORY_HINT_MODIFIABLE

      static final int REPOSITORY_HINT_MODIFIABLE
      Constant used to indicate that a repository manager should only load the repository if the repository is modifiable.
      See Also:

  • Method Details

    • addRepository

      void addRepository(URI location)
      Adds the repository at the given location to the list of repositories tracked by this repository manager. This method does not attempt to contact or load the repository, and makes no attempt to determine whether there is a valid repository at the provided location.

      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.

      Parameters:
      location - The absolute location of the repository to add
      See Also:

    • contains

      boolean contains(URI location)
      Returns whether a repository at the given location is in the list of repositories tracked by this repository manager.
      Parameters:
      location - The absolute location of the repository to look for
      Returns:
      true if the repository is known to this manager, and false otherwise

    • getAgent

      IProvisioningAgent getAgent()
      Returns the provisioning agent in charge of this repository manager
      Returns:
      The provisioning agent.

    • getKnownRepositories

      URI[] getKnownRepositories(int flags)
      Returns the repository locations known to the repository manager.

      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.

      Parameters:
      flags - an integer bit-mask indicating which repositories should be returned. REPOSITORIES_ALL can be used as the mask when all enabled repositories should be returned. Disabled repositories are automatically excluded unless the REPOSITORIES_DISABLED flag is set.
      Returns:
      the locations of the repositories managed by this repository manager.
      See Also:

    • getRepositoryProperty

      String getRepositoryProperty(URI location, String key)
      Returns the property associated with the repository at the given URI, without loading the repository.

      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.

      Parameters:
      location - the absolute URI of the repository in question
      key - the String key of the property desired
      Returns:
      the value of the property, or null if the repository does not exist, the value does not exist, or the property value could not be determined without loading the repository.
      See Also:

    • setRepositoryProperty

      void setRepositoryProperty(URI location, String key, String value)
      Sets the property associated with the repository at the given URI, without loading the repository.

      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. 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 the repository and call IRepository.setProperty(String, String).

      Parameters:
      location - the absolute URI of the repository in question
      key - the String key of the property desired
      value - the value to set the property to
      See Also:

    • isEnabled

      boolean isEnabled(URI location)
      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.

      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.

      Parameters:
      location - The absolute location of the repository whose enablement is requested
      Returns:
      true if the repository is enabled, and false if it is not enabled, or if the repository location is not known to the repository manager.
      See Also:

    • removeRepository

      boolean removeRepository(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.
      Parameters:
      location - The absolute location of the repository to remove
      Returns:
      true if a repository was removed, and false otherwise.

    • setEnabled

      void setEnabled(URI location, boolean enablement)
      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.

      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.

      This method has no effect if the given repository location is not known to the repository manager.

      Parameters:
      location - The absolute location of the repository to enable or disable
      enablement - trueto enable the repository, and false to disable the repository
      See Also:

    • createRepository

      IRepository<T> createRepository(URI location, String name, String type, Map<String,String> properties) throws ProvisionException
      Creates and returns a new empty repository of the given type at the given location.

      The resulting repository is added to the list of repositories tracked by the repository manager. Clients must make a subsequent call to removeRepository(URI) if they do not want the repository manager to remember the repository for subsequent load attempts.

      Parameters:
      location - the absolute location for the new repository
      name - the name of the new repository
      type - the kind of repository to create
      properties - the properties to set on the repository
      Returns:
      the newly created repository
      Throws:
      ProvisionException - if the repository could not be created. Reasons include:
      • The repository type is unknown.
      • There was an error writing to the given repository location.
      • A repository already exists at that location.
      Since:
      2.8

    • loadRepository

      IRepository<T> loadRepository(URI location, IProgressMonitor monitor) throws ProvisionException
      Loads the repository at the given location. If a repository has previously been loaded at that location, the same cached repository may be returned.

      The resulting repository is added to the list of repositories tracked by the repository manager. Clients must make a subsequent call to removeRepository(URI) if they do not want the repository manager to remember the repository for subsequent load attempts.

      Parameters:
      location - the absolute location of the repository to load
      monitor - a progress monitor, or null if progress reporting is not desired
      Returns:
      the loaded repository
      Throws:
      ProvisionException - if the repository could not be created. Reasons include:
      • There is no existing repository at that location.
      • The repository at that location could not be read.
      Since:
      2.8

    • loadRepository

      IRepository<T> loadRepository(URI location, int flags, IProgressMonitor monitor) throws ProvisionException
      Loads the repository at the given location. If a repository has previously been loaded at that location, the same cached repository may be returned.

      The resulting repository is added to the list of repositories tracked by the repository manager. Clients must make a subsequent call to removeRepository(URI) if they do not want the repository manager to remember the repository for subsequent load attempts.

      The flags passed in should be taken as a hint for the type of repository to load. If the manager cannot load a repository that satisfies these hints, it can fail fast.

      Parameters:
      location - the absolute location of the repository to load
      flags - bit-wise or of flags to consider when loading the repository (currently only REPOSITORY_HINT_MODIFIABLE is supported)
      monitor - a progress monitor, or null if progress reporting is not desired
      Returns:
      the loaded repository
      Throws:
      ProvisionException - if the repository could not be created. Reasons include:
      • There is no existing repository at that location.
      • The repository at that location could not be read.
      Since:
      2.8
      See Also:

    • refreshRepository

      IRepository<T> refreshRepository(URI location, IProgressMonitor monitor) throws ProvisionException
      Refreshes the repository corresponding to the given URL. This method discards any cached state held by the repository manager and reloads the repository contents. The provided repository location must already be known to the repository manager.
      Parameters:
      location - The absolute location of the repository to refresh
      monitor - a progress monitor, or null if progress reporting is not desired
      Returns:
      The refreshed repository
      Throws:
      ProvisionException - if the repository could not be refreshed. Reasons include:
      • The location is not known to the repository manager.
      • There is no existing repository at that location.
      • The repository at that location could not be read.
      Since:
      2.8