View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one
3    * or more contributor license agreements.  See the NOTICE file
4    * distributed with this work for additional information
5    * regarding copyright ownership.  The ASF licenses this file
6    * to you under the Apache License, Version 2.0 (the
7    * "License"); you may not use this file except in compliance
8    * with the License.  You may obtain a copy of the License at
9    *
10   *   http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing,
13   * software distributed under the License is distributed on an
14   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15   * KIND, either express or implied.  See the License for the
16   * specific language governing permissions and limitations
17   * under the License.
18   */
19  package org.eclipse.aether;
20  
21  import java.util.Collection;
22  import java.util.List;
23  
24  import org.eclipse.aether.artifact.Artifact;
25  import org.eclipse.aether.collection.CollectRequest;
26  import org.eclipse.aether.collection.CollectResult;
27  import org.eclipse.aether.collection.DependencyCollectionException;
28  import org.eclipse.aether.deployment.DeployRequest;
29  import org.eclipse.aether.deployment.DeployResult;
30  import org.eclipse.aether.deployment.DeploymentException;
31  import org.eclipse.aether.installation.InstallRequest;
32  import org.eclipse.aether.installation.InstallResult;
33  import org.eclipse.aether.installation.InstallationException;
34  import org.eclipse.aether.metadata.Metadata;
35  import org.eclipse.aether.repository.LocalRepository;
36  import org.eclipse.aether.repository.LocalRepositoryManager;
37  import org.eclipse.aether.repository.RemoteRepository;
38  import org.eclipse.aether.resolution.ArtifactDescriptorException;
39  import org.eclipse.aether.resolution.ArtifactDescriptorRequest;
40  import org.eclipse.aether.resolution.ArtifactDescriptorResult;
41  import org.eclipse.aether.resolution.ArtifactRequest;
42  import org.eclipse.aether.resolution.ArtifactResolutionException;
43  import org.eclipse.aether.resolution.ArtifactResult;
44  import org.eclipse.aether.resolution.DependencyRequest;
45  import org.eclipse.aether.resolution.DependencyResolutionException;
46  import org.eclipse.aether.resolution.DependencyResult;
47  import org.eclipse.aether.resolution.MetadataRequest;
48  import org.eclipse.aether.resolution.MetadataResult;
49  import org.eclipse.aether.resolution.VersionRangeRequest;
50  import org.eclipse.aether.resolution.VersionRangeResolutionException;
51  import org.eclipse.aether.resolution.VersionRangeResult;
52  import org.eclipse.aether.resolution.VersionRequest;
53  import org.eclipse.aether.resolution.VersionResolutionException;
54  import org.eclipse.aether.resolution.VersionResult;
55  
56  /**
57   * The main entry point to the repository system and its functionality. Note that obtaining a concrete implementation of
58   * this interface (e.g. via dependency injection, service locator, etc.) is dependent on the application and its
59   * specific needs, please consult the online documentation for examples and directions on booting the system.
60   * <p>
61   * When the repository system or the application integrating it is about to exit, invoke the {@link #shutdown()} to let
62   * resolver system perform possible resource cleanups.
63   *
64   * @noimplement This interface is not intended to be implemented by clients.
65   * @noextend This interface is not intended to be extended by clients.
66   */
67  public interface RepositorySystem {
68  
69      /**
70       * Expands a version range to a list of matching versions, in ascending order. For example, resolves "[3.8,4.0)" to
71       * "3.8", "3.8.1", "3.8.2". Note that the returned list of versions is only dependent on the configured repositories
72       * and their contents, the list is not processed by the {@link RepositorySystemSession#getVersionFilter() session's
73       * version filter}.
74       * <p>
75       * The supplied request may also refer to a single concrete version rather than a version range. In this case
76       * though, the result contains simply the (parsed) input version, regardless of the repositories and their contents.
77       *
78       * @param session The repository session, must not be {@code null}.
79       * @param request The version range request, must not be {@code null}.
80       * @return The version range result, never {@code null}.
81       * @throws VersionRangeResolutionException If the requested range could not be parsed. Note that an empty range does
82       *                                         not raise an exception.
83       * @see #newResolutionRepositories(RepositorySystemSession, List)
84       */
85      VersionRangeResult resolveVersionRange(RepositorySystemSession session, VersionRangeRequest request)
86              throws VersionRangeResolutionException;
87  
88      /**
89       * Resolves an artifact's meta version (if any) to a concrete version. For example, resolves "1.0-SNAPSHOT" to
90       * "1.0-20090208.132618-23".
91       *
92       * @param session The repository session, must not be {@code null}.
93       * @param request The version request, must not be {@code null}.
94       * @return The version result, never {@code null}.
95       * @throws VersionResolutionException If the metaversion could not be resolved.
96       * @see #newResolutionRepositories(RepositorySystemSession, List)
97       */
98      VersionResult resolveVersion(RepositorySystemSession session, VersionRequest request)
99              throws VersionResolutionException;
100 
101     /**
102      * Gets information about an artifact like its direct dependencies and potential relocations.
103      *
104      * @param session The repository session, must not be {@code null}.
105      * @param request The descriptor request, must not be {@code null}.
106      * @return The descriptor result, never {@code null}.
107      * @throws ArtifactDescriptorException If the artifact descriptor could not be read.
108      * @see RepositorySystemSession#getArtifactDescriptorPolicy()
109      * @see #newResolutionRepositories(RepositorySystemSession, List)
110      */
111     ArtifactDescriptorResult readArtifactDescriptor(RepositorySystemSession session, ArtifactDescriptorRequest request)
112             throws ArtifactDescriptorException;
113 
114     /**
115      * Collects the transitive dependencies of an artifact and builds a dependency graph. Note that this operation is
116      * only concerned about determining the coordinates of the transitive dependencies. To also resolve the actual
117      * artifact files, use {@link #resolveDependencies(RepositorySystemSession, DependencyRequest)}.
118      *
119      * @param session The repository session, must not be {@code null}.
120      * @param request The collection request, must not be {@code null}.
121      * @return The collection result, never {@code null}.
122      * @throws DependencyCollectionException If the dependency tree could not be built.
123      * @see RepositorySystemSession#getDependencyTraverser()
124      * @see RepositorySystemSession#getDependencyManager()
125      * @see RepositorySystemSession#getDependencySelector()
126      * @see RepositorySystemSession#getVersionFilter()
127      * @see RepositorySystemSession#getDependencyGraphTransformer()
128      * @see #newResolutionRepositories(RepositorySystemSession, List)
129      */
130     CollectResult collectDependencies(RepositorySystemSession session, CollectRequest request)
131             throws DependencyCollectionException;
132 
133     /**
134      * Collects and resolves the transitive dependencies of an artifact. This operation is essentially a combination of
135      * {@link #collectDependencies(RepositorySystemSession, CollectRequest)} and
136      * {@link #resolveArtifacts(RepositorySystemSession, Collection)}.
137      *
138      * @param session The repository session, must not be {@code null}.
139      * @param request The dependency request, must not be {@code null}.
140      * @return The dependency result, never {@code null}.
141      * @throws DependencyResolutionException If the dependency tree could not be built or any dependency artifact could
142      *                                       not be resolved.
143      * @see #newResolutionRepositories(RepositorySystemSession, List)
144      */
145     DependencyResult resolveDependencies(RepositorySystemSession session, DependencyRequest request)
146             throws DependencyResolutionException;
147 
148     /**
149      * Resolves the path for an artifact. The artifact will be downloaded to the local repository if necessary. An
150      * artifact that is already resolved will be skipped and is not re-resolved. In general, callers must not assume any
151      * relationship between an artifact's resolved filename and its coordinates. Note that this method assumes that any
152      * relocations have already been processed.
153      *
154      * @param session The repository session, must not be {@code null}.
155      * @param request The resolution request, must not be {@code null}.
156      * @return The resolution result, never {@code null}.
157      * @throws ArtifactResolutionException If the artifact could not be resolved.
158      * @see Artifact#getFile()
159      * @see #newResolutionRepositories(RepositorySystemSession, List)
160      */
161     ArtifactResult resolveArtifact(RepositorySystemSession session, ArtifactRequest request)
162             throws ArtifactResolutionException;
163 
164     /**
165      * Resolves the paths for a collection of artifacts. Artifacts will be downloaded to the local repository if
166      * necessary. Artifacts that are already resolved will be skipped and are not re-resolved. In general, callers must
167      * not assume any relationship between an artifact's filename and its coordinates. Note that this method assumes
168      * that any relocations have already been processed.
169      *
170      * @param session  The repository session, must not be {@code null}.
171      * @param requests The resolution requests, must not be {@code null}.
172      * @return The resolution results (in request order), never {@code null}.
173      * @throws ArtifactResolutionException If any artifact could not be resolved.
174      * @see Artifact#getFile()
175      * @see #newResolutionRepositories(RepositorySystemSession, List)
176      */
177     List<ArtifactResult> resolveArtifacts(
178             RepositorySystemSession session, Collection<? extends ArtifactRequest> requests)
179             throws ArtifactResolutionException;
180 
181     /**
182      * Resolves the paths for a collection of metadata. Metadata will be downloaded to the local repository if
183      * necessary, e.g. because it hasn't been cached yet or the cache is deemed outdated.
184      *
185      * @param session  The repository session, must not be {@code null}.
186      * @param requests The resolution requests, must not be {@code null}.
187      * @return The resolution results (in request order), never {@code null}.
188      * @see Metadata#getFile()
189      * @see #newResolutionRepositories(RepositorySystemSession, List)
190      */
191     List<MetadataResult> resolveMetadata(
192             RepositorySystemSession session, Collection<? extends MetadataRequest> requests);
193 
194     /**
195      * Installs a collection of artifacts and their accompanying metadata to the local repository.
196      *
197      * @param session The repository session, must not be {@code null}.
198      * @param request The installation request, must not be {@code null}.
199      * @return The installation result, never {@code null}.
200      * @throws InstallationException If any artifact/metadata from the request could not be installed.
201      */
202     InstallResult install(RepositorySystemSession session, InstallRequest request) throws InstallationException;
203 
204     /**
205      * Uploads a collection of artifacts and their accompanying metadata to a remote repository.
206      *
207      * @param session The repository session, must not be {@code null}.
208      * @param request The deployment request, must not be {@code null}.
209      * @return The deployment result, never {@code null}.
210      * @throws DeploymentException If any artifact/metadata from the request could not be deployed.
211      * @see #newDeploymentRepository(RepositorySystemSession, RemoteRepository)
212      */
213     DeployResult deploy(RepositorySystemSession session, DeployRequest request) throws DeploymentException;
214 
215     /**
216      * Creates a new manager for the specified local repository. If the specified local repository has no type, the
217      * default local repository type of the system will be used. <em>Note:</em> It is expected that this method
218      * invocation is one of the last steps of setting up a new session, in particular any configuration properties
219      * should have been set already.
220      *
221      * @param session         The repository system session from which to configure the manager, must not be
222      *                        {@code null}.
223      * @param localRepository The local repository to create a manager for, must not be {@code null}.
224      * @return The local repository manager, never {@code null}.
225      * @throws IllegalArgumentException If the specified repository type is not recognized or no base directory is
226      *                                  given.
227      */
228     LocalRepositoryManager newLocalRepositoryManager(RepositorySystemSession session, LocalRepository localRepository);
229 
230     /**
231      * Creates a new synchronization context.
232      *
233      * @param session The repository session during which the context will be used, must not be {@code null}.
234      * @param shared  A flag indicating whether access to the artifacts/metadata associated with the new context can be
235      *                shared among concurrent readers or whether access needs to be exclusive to the calling thread.
236      * @return The synchronization context, never {@code null}.
237      */
238     SyncContext newSyncContext(RepositorySystemSession session, boolean shared);
239 
240     /**
241      * Forms remote repositories suitable for artifact resolution by applying the session's authentication selector and
242      * similar network configuration to the given repository prototypes. As noted for
243      * {@link RepositorySystemSession#getAuthenticationSelector()} etc. the remote repositories passed to e.g.
244      * {@link #resolveArtifact(RepositorySystemSession, ArtifactRequest) resolveArtifact()} are used as is and expected
245      * to already carry any required authentication or proxy configuration. This method can be used to apply the
246      * authentication/proxy configuration from a session to a bare repository definition to obtain the complete
247      * repository definition for use in the resolution request.
248      *
249      * @param session      The repository system session from which to configure the repositories, must not be
250      *                     {@code null}.
251      * @param repositories The repository prototypes from which to derive the resolution repositories, must not be
252      *                     {@code null} or contain {@code null} elements.
253      * @return The resolution repositories, never {@code null}. Note that there is generally no 1:1 relationship of the
254      * obtained repositories to the original inputs due to mirror selection potentially aggregating multiple
255      * repositories.
256      * @see #newDeploymentRepository(RepositorySystemSession, RemoteRepository)
257      */
258     List<RemoteRepository> newResolutionRepositories(
259             RepositorySystemSession session, List<RemoteRepository> repositories);
260 
261     /**
262      * Forms a remote repository suitable for artifact deployment by applying the session's authentication selector and
263      * similar network configuration to the given repository prototype. As noted for
264      * {@link RepositorySystemSession#getAuthenticationSelector()} etc. the remote repository passed to
265      * {@link #deploy(RepositorySystemSession, DeployRequest) deploy()} is used as is and expected to already carry any
266      * required authentication or proxy configuration. This method can be used to apply the authentication/proxy
267      * configuration from a session to a bare repository definition to obtain the complete repository definition for use
268      * in the deploy request.
269      *
270      * @param session    The repository system session from which to configure the repository, must not be {@code null}.
271      * @param repository The repository prototype from which to derive the deployment repository, must not be
272      *                   {@code null}.
273      * @return The deployment repository, never {@code null}.
274      * @see #newResolutionRepositories(RepositorySystemSession, List)
275      */
276     RemoteRepository newDeploymentRepository(RepositorySystemSession session, RemoteRepository repository);
277 
278     /**
279      * Registers an "on repository system end" handler, executed after repository system is shut down.
280      *
281      * @param handler The handler, must not be {@code null}.
282      * @since 1.9.0
283      */
284     void addOnSystemEndedHandler(Runnable handler);
285 
286     /**
287      * Signals to repository system to shut down. Shut down instance is not usable anymore.
288      * <p>
289      * Repository system may perform some resource cleanup, if applicable. Not using this method may cause leaks or
290      * unclean shutdown of some subsystem.
291      * <p>
292      * When shutdown happens, all the registered on-close handlers will be invoked (even if some throws), and at end
293      * of operation a {@link MultiRuntimeException} may be thrown, signaling that some handler(s) failed. This exception
294      * may be ignored, is at the discretion of caller.
295      *
296      * @since 1.9.0
297      */
298     void shutdown();
299 }