View Javadoc
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 }