org.argeo.slc.repo/src/org/eclipse/aether/RepositorySystem.java

   1 /*******************************************************************************
   2  * Copyright (c) 2010, 2014 Sonatype, Inc.
   3  * All rights reserved. This program and the accompanying materials
   4  * are made available under the terms of the Eclipse Public License v1.0
   5  * which accompanies this distribution, and is available at
   6  * http://www.eclipse.org/legal/epl-v10.html
   7  *
   8  * Contributors:
   9  *    Sonatype, Inc. - initial API and implementation
  10  *******************************************************************************/
  11 package org.eclipse.aether;
  12
  13 import java.util.Collection;
  14 import java.util.List;
  15
  16 import org.eclipse.aether.artifact.Artifact;
  17 import org.eclipse.aether.collection.CollectRequest;
  18 import org.eclipse.aether.collection.CollectResult;
  19 import org.eclipse.aether.collection.DependencyCollectionException;
  20 import org.eclipse.aether.deployment.DeployRequest;
  21 import org.eclipse.aether.deployment.DeployResult;
  22 import org.eclipse.aether.deployment.DeploymentException;
  23 import org.eclipse.aether.installation.InstallRequest;
  24 import org.eclipse.aether.installation.InstallResult;
  25 import org.eclipse.aether.installation.InstallationException;
  26 import org.eclipse.aether.metadata.Metadata;
  27 import org.eclipse.aether.repository.LocalRepository;
  28 import org.eclipse.aether.repository.LocalRepositoryManager;
  29 import org.eclipse.aether.repository.RemoteRepository;
  30 import org.eclipse.aether.resolution.ArtifactDescriptorException;
  31 import org.eclipse.aether.resolution.ArtifactDescriptorRequest;
  32 import org.eclipse.aether.resolution.ArtifactDescriptorResult;
  33 import org.eclipse.aether.resolution.ArtifactRequest;
  34 import org.eclipse.aether.resolution.ArtifactResolutionException;
  35 import org.eclipse.aether.resolution.ArtifactResult;
  36 import org.eclipse.aether.resolution.DependencyRequest;
  37 import org.eclipse.aether.resolution.DependencyResolutionException;
  38 import org.eclipse.aether.resolution.DependencyResult;
  39 import org.eclipse.aether.resolution.MetadataRequest;
  40 import org.eclipse.aether.resolution.MetadataResult;
  41 import org.eclipse.aether.resolution.VersionRangeRequest;
  42 import org.eclipse.aether.resolution.VersionRangeResolutionException;
  43 import org.eclipse.aether.resolution.VersionRangeResult;
  44 import org.eclipse.aether.resolution.VersionRequest;
  45 import org.eclipse.aether.resolution.VersionResolutionException;
  46 import org.eclipse.aether.resolution.VersionResult;
  47
  48 /**
  49  * The main entry point to the repository system and its functionality. Note that obtaining a concrete implementation of
  50  * this interface (e.g. via dependency injection, service locator, etc.) is dependent on the application and its
  51  * specific needs, please consult the online documentation for examples and directions on booting the system.
  52  *
  53  * @noimplement This interface is not intended to be implemented by clients.
  54  * @noextend This interface is not intended to be extended by clients.
  55  */
  56 public interface RepositorySystem
  57 {
  58
  59     /**
  60      * Expands a version range to a list of matching versions, in ascending order. For example, resolves "[3.8,4.0)" to
  61      * "3.8", "3.8.1", "3.8.2". Note that the returned list of versions is only dependent on the configured repositories
  62      * and their contents, the list is not processed by the {@link RepositorySystemSession#getVersionFilter() session's
  63      * version filter}.
  64      * <p>
  65      * The supplied request may also refer to a single concrete version rather than a version range. In this case
  66      * though, the result contains simply the (parsed) input version, regardless of the repositories and their contents.
  67      *
  68      * @param session The repository session, must not be {@code null}.
  69      * @param request The version range request, must not be {@code null}.
  70      * @return The version range result, never {@code null}.
  71      * @throws VersionRangeResolutionException If the requested range could not be parsed. Note that an empty range does
  72      *             not raise an exception.
  73      * @see #newResolutionRepositories(RepositorySystemSession, List)
  74      */
  75     VersionRangeResult resolveVersionRange( RepositorySystemSession session, VersionRangeRequest request )
  76         throws VersionRangeResolutionException;
  77
  78     /**
  79      * Resolves an artifact's meta version (if any) to a concrete version. For example, resolves "1.0-SNAPSHOT" to
  80      * "1.0-20090208.132618-23".
  81      *
  82      * @param session The repository session, must not be {@code null}.
  83      * @param request The version request, must not be {@code null}.
  84      * @return The version result, never {@code null}.
  85      * @throws VersionResolutionException If the metaversion could not be resolved.
  86      * @see #newResolutionRepositories(RepositorySystemSession, List)
  87      */
  88     VersionResult resolveVersion( RepositorySystemSession session, VersionRequest request )
  89         throws VersionResolutionException;
  90
  91     /**
  92      * Gets information about an artifact like its direct dependencies and potential relocations.
  93      *
  94      * @param session The repository session, must not be {@code null}.
  95      * @param request The descriptor request, must not be {@code null}.
  96      * @return The descriptor result, never {@code null}.
  97      * @throws ArtifactDescriptorException If the artifact descriptor could not be read.
  98      * @see RepositorySystemSession#getArtifactDescriptorPolicy()
  99      * @see #newResolutionRepositories(RepositorySystemSession, List)
 100      */
 101     ArtifactDescriptorResult readArtifactDescriptor( RepositorySystemSession session, ArtifactDescriptorRequest request )
 102         throws ArtifactDescriptorException;
 103
 104     /**
 105      * Collects the transitive dependencies of an artifact and builds a dependency graph. Note that this operation is
 106      * only concerned about determining the coordinates of the transitive dependencies. To also resolve the actual
 107      * artifact files, use {@link #resolveDependencies(RepositorySystemSession, DependencyRequest)}.
 108      *
 109      * @param session The repository session, must not be {@code null}.
 110      * @param request The collection request, must not be {@code null}.
 111      * @return The collection result, never {@code null}.
 112      * @throws DependencyCollectionException If the dependency tree could not be built.
 113      * @see RepositorySystemSession#getDependencyTraverser()
 114      * @see RepositorySystemSession#getDependencyManager()
 115      * @see RepositorySystemSession#getDependencySelector()
 116      * @see RepositorySystemSession#getVersionFilter()
 117      * @see RepositorySystemSession#getDependencyGraphTransformer()
 118      * @see #newResolutionRepositories(RepositorySystemSession, List)
 119      */
 120     CollectResult collectDependencies( RepositorySystemSession session, CollectRequest request )
 121         throws DependencyCollectionException;
 122
 123     /**
 124      * Collects and resolves the transitive dependencies of an artifact. This operation is essentially a combination of
 125      * {@link #collectDependencies(RepositorySystemSession, CollectRequest)} and
 126      * {@link #resolveArtifacts(RepositorySystemSession, Collection)}.
 127      *
 128      * @param session The repository session, must not be {@code null}.
 129      * @param request The dependency request, must not be {@code null}.
 130      * @return The dependency result, never {@code null}.
 131      * @throws DependencyResolutionException If the dependency tree could not be built or any dependency artifact could
 132      *             not be resolved.
 133      * @see #newResolutionRepositories(RepositorySystemSession, List)
 134      */
 135     DependencyResult resolveDependencies( RepositorySystemSession session, DependencyRequest request )
 136         throws DependencyResolutionException;
 137
 138     /**
 139      * Resolves the path for an artifact. The artifact will be downloaded to the local repository if necessary. An
 140      * artifact that is already resolved will be skipped and is not re-resolved. In general, callers must not assume any
 141      * relationship between an artifact's resolved filename and its coordinates. Note that this method assumes that any
 142      * relocations have already been processed.
 143      *
 144      * @param session The repository session, must not be {@code null}.
 145      * @param request The resolution request, must not be {@code null}.
 146      * @return The resolution result, never {@code null}.
 147      * @throws ArtifactResolutionException If the artifact could not be resolved.
 148      * @see Artifact#getFile()
 149      * @see #newResolutionRepositories(RepositorySystemSession, List)
 150      */
 151     ArtifactResult resolveArtifact( RepositorySystemSession session, ArtifactRequest request )
 152         throws ArtifactResolutionException;
 153
 154     /**
 155      * Resolves the paths for a collection of artifacts. Artifacts will be downloaded to the local repository if
 156      * necessary. Artifacts that are already resolved will be skipped and are not re-resolved. In general, callers must
 157      * not assume any relationship between an artifact's filename and its coordinates. Note that this method assumes
 158      * that any relocations have already been processed.
 159      *
 160      * @param session The repository session, must not be {@code null}.
 161      * @param requests The resolution requests, must not be {@code null}.
 162      * @return The resolution results (in request order), never {@code null}.
 163      * @throws ArtifactResolutionException If any artifact could not be resolved.
 164      * @see Artifact#getFile()
 165      * @see #newResolutionRepositories(RepositorySystemSession, List)
 166      */
 167     List<ArtifactResult> resolveArtifacts( RepositorySystemSession session,
 168                                            Collection<? extends ArtifactRequest> requests )
 169         throws ArtifactResolutionException;
 170
 171     /**
 172      * Resolves the paths for a collection of metadata. Metadata will be downloaded to the local repository if
 173      * necessary, e.g. because it hasn't been cached yet or the cache is deemed outdated.
 174      *
 175      * @param session The repository session, must not be {@code null}.
 176      * @param requests The resolution requests, must not be {@code null}.
 177      * @return The resolution results (in request order), never {@code null}.
 178      * @see Metadata#getFile()
 179      * @see #newResolutionRepositories(RepositorySystemSession, List)
 180      */
 181     List<MetadataResult> resolveMetadata( RepositorySystemSession session,
 182                                           Collection<? extends MetadataRequest> requests );
 183
 184     /**
 185      * Installs a collection of artifacts and their accompanying metadata to the local repository.
 186      *
 187      * @param session The repository session, must not be {@code null}.
 188      * @param request The installation request, must not be {@code null}.
 189      * @return The installation result, never {@code null}.
 190      * @throws InstallationException If any artifact/metadata from the request could not be installed.
 191      */
 192     InstallResult install( RepositorySystemSession session, InstallRequest request )
 193         throws InstallationException;
 194
 195     /**
 196      * Uploads a collection of artifacts and their accompanying metadata to a remote repository.
 197      *
 198      * @param session The repository session, must not be {@code null}.
 199      * @param request The deployment request, must not be {@code null}.
 200      * @return The deployment result, never {@code null}.
 201      * @throws DeploymentException If any artifact/metadata from the request could not be deployed.
 202      * @see #newDeploymentRepository(RepositorySystemSession, RemoteRepository)
 203      */
 204     DeployResult deploy( RepositorySystemSession session, DeployRequest request )
 205         throws DeploymentException;
 206
 207     /**
 208      * Creates a new manager for the specified local repository. If the specified local repository has no type, the
 209      * default local repository type of the system will be used. <em>Note:</em> It is expected that this method
 210      * invocation is one of the last steps of setting up a new session, in particular any configuration properties
 211      * should have been set already.
 212      *
 213      * @param session The repository system session from which to configure the manager, must not be {@code null}.
 214      * @param localRepository The local repository to create a manager for, must not be {@code null}.
 215      * @return The local repository manager, never {@code null}.
 216      * @throws IllegalArgumentException If the specified repository type is not recognized or no base directory is
 217      *             given.
 218      */
 219     LocalRepositoryManager newLocalRepositoryManager( RepositorySystemSession session, LocalRepository localRepository );
 220
 221     /**
 222      * Creates a new synchronization context.
 223      *
 224      * @param session The repository session during which the context will be used, must not be {@code null}.
 225      * @param shared A flag indicating whether access to the artifacts/metadata associated with the new context can be
 226      *            shared among concurrent readers or whether access needs to be exclusive to the calling thread.
 227      * @return The synchronization context, never {@code null}.
 228      */
 229     SyncContext newSyncContext( RepositorySystemSession session, boolean shared );
 230
 231     /**
 232      * Forms remote repositories suitable for artifact resolution by applying the session's authentication selector and
 233      * similar network configuration to the given repository prototypes. As noted for
 234      * {@link RepositorySystemSession#getAuthenticationSelector()} etc. the remote repositories passed to e.g.
 235      * {@link #resolveArtifact(RepositorySystemSession, ArtifactRequest) resolveArtifact()} are used as is and expected
 236      * to already carry any required authentication or proxy configuration. This method can be used to apply the
 237      * authentication/proxy configuration from a session to a bare repository definition to obtain the complete
 238      * repository definition for use in the resolution request.
 239      *
 240      * @param session The repository system session from which to configure the repositories, must not be {@code null}.
 241      * @param repositories The repository prototypes from which to derive the resolution repositories, must not be
 242      *            {@code null} or contain {@code null} elements.
 243      * @return The resolution repositories, never {@code null}. Note that there is generally no 1:1 relationship of the
 244      *         obtained repositories to the original inputs due to mirror selection potentially aggregating multiple
 245      *         repositories.
 246      * @see #newDeploymentRepository(RepositorySystemSession, RemoteRepository)
 247      */
 248     List<RemoteRepository> newResolutionRepositories( RepositorySystemSession session,
 249                                                       List<RemoteRepository> repositories );
 250
 251     /**
 252      * Forms a remote repository suitable for artifact deployment by applying the session's authentication selector and
 253      * similar network configuration to the given repository prototype. As noted for
 254      * {@link RepositorySystemSession#getAuthenticationSelector()} etc. the remote repository passed to
 255      * {@link #deploy(RepositorySystemSession, DeployRequest) deploy()} is used as is and expected to already carry any
 256      * required authentication or proxy configuration. This method can be used to apply the authentication/proxy
 257      * configuration from a session to a bare repository definition to obtain the complete repository definition for use
 258      * in the deploy request.
 259      *
 260      * @param session The repository system session from which to configure the repository, must not be {@code null}.
 261      * @param repository The repository prototype from which to derive the deployment repository, must not be
 262      *            {@code null}.
 263      * @return The deployment repository, never {@code null}.
 264      * @see #newResolutionRepositories(RepositorySystemSession, List)
 265      */
 266     RemoteRepository newDeploymentRepository( RepositorySystemSession session, RemoteRepository repository );
 267
 268 }