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.io.Closeable;
22  import java.util.Collection;
23  import java.util.List;
24  
25  import org.eclipse.aether.artifact.Artifact;
26  import org.eclipse.aether.collection.CollectRequest;
27  import org.eclipse.aether.collection.CollectResult;
28  import org.eclipse.aether.collection.DependencyCollectionException;
29  import org.eclipse.aether.deployment.DeployRequest;
30  import org.eclipse.aether.deployment.DeployResult;
31  import org.eclipse.aether.deployment.DeploymentException;
32  import org.eclipse.aether.graph.DependencyFilter;
33  import org.eclipse.aether.graph.DependencyNode;
34  import org.eclipse.aether.installation.InstallRequest;
35  import org.eclipse.aether.installation.InstallResult;
36  import org.eclipse.aether.installation.InstallationException;
37  import org.eclipse.aether.metadata.Metadata;
38  import org.eclipse.aether.repository.LocalRepository;
39  import org.eclipse.aether.repository.LocalRepositoryManager;
40  import org.eclipse.aether.repository.RemoteRepository;
41  import org.eclipse.aether.resolution.ArtifactDescriptorException;
42  import org.eclipse.aether.resolution.ArtifactDescriptorRequest;
43  import org.eclipse.aether.resolution.ArtifactDescriptorResult;
44  import org.eclipse.aether.resolution.ArtifactRequest;
45  import org.eclipse.aether.resolution.ArtifactResolutionException;
46  import org.eclipse.aether.resolution.ArtifactResult;
47  import org.eclipse.aether.resolution.DependencyRequest;
48  import org.eclipse.aether.resolution.DependencyResolutionException;
49  import org.eclipse.aether.resolution.DependencyResult;
50  import org.eclipse.aether.resolution.MetadataRequest;
51  import org.eclipse.aether.resolution.MetadataResult;
52  import org.eclipse.aether.resolution.VersionRangeRequest;
53  import org.eclipse.aether.resolution.VersionRangeResolutionException;
54  import org.eclipse.aether.resolution.VersionRangeResult;
55  import org.eclipse.aether.resolution.VersionRequest;
56  import org.eclipse.aether.resolution.VersionResolutionException;
57  import org.eclipse.aether.resolution.VersionResult;
58  
59  /**
60   * The main entry point to the repository system and its functionality. Note that obtaining a concrete implementation of
61   * this interface (e.g. via dependency injection, service locator, etc.) is dependent on the application and its
62   * specific needs, please consult the online documentation for examples and directions on booting the system.
63   * <p>
64   * When the repository system or the application integrating it is about to exit, invoke the {@link #shutdown()} to let
65   * resolver system perform possible resource cleanups.
66   *
67   * @noimplement This interface is not intended to be implemented by clients.
68   * @noextend This interface is not intended to be extended by clients.
69   */
70  public interface RepositorySystem extends Closeable {
71  
72      /**
73       * Expands a version range to a list of matching versions, in ascending order. For example, resolves "[3.8,4.0)" to
74       * "3.8", "3.8.1", "3.8.2". Note that the returned list of versions is only dependent on the configured repositories
75       * and their contents, the list is not processed by the {@link RepositorySystemSession#getVersionFilter() session's
76       * version filter}.
77       * <p>
78       * The supplied request may also refer to a single concrete version rather than a version range. In this case
79       * though, the result contains simply the (parsed) input version, regardless of the repositories and their contents.
80       *
81       * @param session The repository session, must not be {@code null}.
82       * @param request The version range request, must not be {@code null}.
83       * @return The version range result, never {@code null}.
84       * @throws VersionRangeResolutionException If the requested range could not be parsed. Note that an empty range does
85       *                                         not raise an exception.
86       * @see #newResolutionRepositories(RepositorySystemSession, List)
87       */
88      VersionRangeResult resolveVersionRange(RepositorySystemSession session, VersionRangeRequest request)
89              throws VersionRangeResolutionException;
90  
91      /**
92       * Resolves an artifact's meta version (if any) to a concrete version. For example, resolves "1.0-SNAPSHOT" to
93       * "1.0-20090208.132618-23".
94       *
95       * @param session The repository session, must not be {@code null}.
96       * @param request The version request, must not be {@code null}.
97       * @return The version result, never {@code null}.
98       * @throws VersionResolutionException If the metaversion could not be resolved.
99       * @see #newResolutionRepositories(RepositorySystemSession, List)
100      */
101     VersionResult resolveVersion(RepositorySystemSession session, VersionRequest request)
102             throws VersionResolutionException;
103 
104     /**
105      * Gets information about an artifact like its direct dependencies and potential relocations.
106      *
107      * @param session The repository session, must not be {@code null}.
108      * @param request The descriptor request, must not be {@code null}.
109      * @return The descriptor result, never {@code null}.
110      * @throws ArtifactDescriptorException If the artifact descriptor could not be read.
111      * @see RepositorySystemSession#getArtifactDescriptorPolicy()
112      * @see #newResolutionRepositories(RepositorySystemSession, List)
113      */
114     ArtifactDescriptorResult readArtifactDescriptor(RepositorySystemSession session, ArtifactDescriptorRequest request)
115             throws ArtifactDescriptorException;
116 
117     /**
118      * Collects the transitive dependencies of an artifact and builds a dependency graph. Note that this operation is
119      * only concerned about determining the coordinates of the transitive dependencies. To also resolve the actual
120      * artifact files, use {@link #resolveDependencies(RepositorySystemSession, DependencyRequest)}.
121      *
122      * @param session The repository session, must not be {@code null}.
123      * @param request The collection request, must not be {@code null}.
124      * @return The collection result, never {@code null}.
125      * @throws DependencyCollectionException If the dependency tree could not be built.
126      * @see RepositorySystemSession#getDependencyTraverser()
127      * @see RepositorySystemSession#getDependencyManager()
128      * @see RepositorySystemSession#getDependencySelector()
129      * @see RepositorySystemSession#getVersionFilter()
130      * @see RepositorySystemSession#getDependencyGraphTransformer()
131      * @see #newResolutionRepositories(RepositorySystemSession, List)
132      */
133     CollectResult collectDependencies(RepositorySystemSession session, CollectRequest request)
134             throws DependencyCollectionException;
135 
136     /**
137      * Collects and resolves the transitive dependencies of an artifact. This operation is essentially a combination of
138      * {@link #collectDependencies(RepositorySystemSession, CollectRequest)} and
139      * {@link #resolveArtifacts(RepositorySystemSession, Collection)}.
140      *
141      * @param session The repository session, must not be {@code null}.
142      * @param request The dependency request, must not be {@code null}.
143      * @return The dependency result, never {@code null}.
144      * @throws DependencyResolutionException If the dependency tree could not be built or any dependency artifact could
145      *                                       not be resolved.
146      * @see #newResolutionRepositories(RepositorySystemSession, List)
147      */
148     DependencyResult resolveDependencies(RepositorySystemSession session, DependencyRequest request)
149             throws DependencyResolutionException;
150 
151     /**
152      * Flattens the provided graph as {@link DependencyNode} into a {@link List}{@code <DependencyNode>} according to session
153      * configuration.
154      *
155      * @param session The repository session, must not be {@code null}.
156      * @param root The dependency node root of the graph, must not be {@code null}.
157      * @param filter The filter to apply, may be {@code null}.
158      * @return The flattened list of dependency nodes, never {@code null}.
159      * @since 2.0.0
160      */
161     List<DependencyNode> flattenDependencyNodes(
162             RepositorySystemSession session, DependencyNode root, DependencyFilter filter);
163 
164     /**
165      * Resolves the path for an artifact. The artifact will be downloaded to the local repository if necessary. An
166      * artifact that is already resolved will be skipped and is not re-resolved. In general, callers must not assume any
167      * relationship between an artifact's resolved filename and its coordinates. Note that this method assumes that any
168      * relocations have already been processed.
169      *
170      * @param session The repository session, must not be {@code null}.
171      * @param request The resolution request, must not be {@code null}.
172      * @return The resolution result, never {@code null}.
173      * @throws ArtifactResolutionException If the artifact could not be resolved.
174      * @see Artifact#getFile()
175      * @see #newResolutionRepositories(RepositorySystemSession, List)
176      */
177     ArtifactResult resolveArtifact(RepositorySystemSession session, ArtifactRequest request)
178             throws ArtifactResolutionException;
179 
180     /**
181      * Resolves the paths for a collection of artifacts. Artifacts will be downloaded to the local repository if
182      * necessary. Artifacts that are already resolved will be skipped and are not re-resolved. In general, callers must
183      * not assume any relationship between an artifact's filename and its coordinates. Note that this method assumes
184      * that any relocations have already been processed.
185      *
186      * @param session  The repository session, must not be {@code null}.
187      * @param requests The resolution requests, must not be {@code null}.
188      * @return The resolution results (in request order), never {@code null}.
189      * @throws ArtifactResolutionException If any artifact could not be resolved.
190      * @see Artifact#getFile()
191      * @see #newResolutionRepositories(RepositorySystemSession, List)
192      */
193     List<ArtifactResult> resolveArtifacts(
194             RepositorySystemSession session, Collection<? extends ArtifactRequest> requests)
195             throws ArtifactResolutionException;
196 
197     /**
198      * Resolves the paths for a collection of metadata. Metadata will be downloaded to the local repository if
199      * necessary, e.g. because it hasn't been cached yet or the cache is deemed outdated.
200      *
201      * @param session  The repository session, must not be {@code null}.
202      * @param requests The resolution requests, must not be {@code null}.
203      * @return The resolution results (in request order), never {@code null}.
204      * @see Metadata#getFile()
205      * @see #newResolutionRepositories(RepositorySystemSession, List)
206      */
207     List<MetadataResult> resolveMetadata(
208             RepositorySystemSession session, Collection<? extends MetadataRequest> requests);
209 
210     /**
211      * Installs a collection of artifacts and their accompanying metadata to the local repository.
212      *
213      * @param session The repository session, must not be {@code null}.
214      * @param request The installation request, must not be {@code null}.
215      * @return The installation result, never {@code null}.
216      * @throws InstallationException If any artifact/metadata from the request could not be installed.
217      */
218     InstallResult install(RepositorySystemSession session, InstallRequest request) throws InstallationException;
219 
220     /**
221      * Uploads a collection of artifacts and their accompanying metadata to a remote repository.
222      *
223      * @param session The repository session, must not be {@code null}.
224      * @param request The deployment request, must not be {@code null}.
225      * @return The deployment result, never {@code null}.
226      * @throws DeploymentException If any artifact/metadata from the request could not be deployed.
227      * @see #newDeploymentRepository(RepositorySystemSession, RemoteRepository)
228      */
229     DeployResult deploy(RepositorySystemSession session, DeployRequest request) throws DeploymentException;
230 
231     /**
232      * Creates a new manager for the specified local repository. If the specified local repository has no type, the
233      * default local repository type of the system will be used. <em>Note:</em> It is expected that this method
234      * invocation is one of the last steps of setting up a new session, in particular any configuration properties
235      * should have been set already.
236      *
237      * @param session         The repository system session from which to configure the manager, must not be
238      *                        {@code null}.
239      * @param localRepository The local repository to create a manager for, must not be {@code null}.
240      * @return The local repository manager, never {@code null}.
241      * @throws IllegalArgumentException If the specified repository type is not recognized or no base directory is
242      *                                  given.
243      */
244     LocalRepositoryManager newLocalRepositoryManager(RepositorySystemSession session, LocalRepository localRepository);
245 
246     /**
247      * Creates a new manager for the specified local repositories. If the specified local repository has no type, the
248      * default local repository type of the system will be used. <em>Note:</em> It is expected that this method
249      * invocation is one of the last steps of setting up a new session, in particular any configuration properties
250      * should have been set already. <em>Note:</em> this method accepts multiple local repositories, in which case
251      * it creates chained local repository.
252      *
253      * @param session         The repository system session from which to configure the manager, must not be
254      *                        {@code null}.
255      * @param localRepositories The local repositories to create a manager for, must not be {@code null} nor empty array.
256      * @return The local repository manager, never {@code null}.
257      * @throws IllegalArgumentException If the specified repository type is not recognized or no base directory is
258      *                                  given.
259      * @since 2.0.0
260      */
261     LocalRepositoryManager newLocalRepositoryManager(
262             RepositorySystemSession session, LocalRepository... localRepositories);
263 
264     /**
265      * Creates a new manager for the specified local repositories. If the specified local repository has no type, the
266      * default local repository type of the system will be used. <em>Note:</em> It is expected that this method
267      * invocation is one of the last steps of setting up a new session, in particular any configuration properties
268      * should have been set already. <em>Note:</em> this method accepts multiple local repositories, in which case
269      * it creates chained local repository.
270      *
271      * @param session         The repository system session from which to configure the manager, must not be
272      *                        {@code null}.
273      * @param localRepositories The local repositories to create a manager for, must not be {@code null} nor empty.
274      * @return The local repository manager, never {@code null}.
275      * @throws IllegalArgumentException If the specified repository type is not recognized or no base directory is
276      *                                  given.
277      * @since 2.0.0
278      */
279     LocalRepositoryManager newLocalRepositoryManager(
280             RepositorySystemSession session, List<LocalRepository> localRepositories);
281 
282     /**
283      * Creates a new synchronization context.
284      *
285      * @param session The repository session during which the context will be used, must not be {@code null}.
286      * @param shared  A flag indicating whether access to the artifacts/metadata associated with the new context can be
287      *                shared among concurrent readers or whether access needs to be exclusive to the calling thread.
288      * @return The synchronization context, never {@code null}.
289      */
290     SyncContext newSyncContext(RepositorySystemSession session, boolean shared);
291 
292     /**
293      * Forms remote repositories suitable for artifact resolution by applying the session's authentication selector and
294      * similar network configuration to the given repository prototypes. As noted for
295      * {@link RepositorySystemSession#getAuthenticationSelector()} etc. the remote repositories passed to e.g.
296      * {@link #resolveArtifact(RepositorySystemSession, ArtifactRequest) resolveArtifact()} are used as is and expected
297      * to already carry any required authentication or proxy configuration. This method can be used to apply the
298      * authentication/proxy configuration from a session to a bare repository definition to obtain the complete
299      * repository definition for use in the resolution request.
300      *
301      * @param session      The repository system session from which to configure the repositories, must not be
302      *                     {@code null}.
303      * @param repositories The repository prototypes from which to derive the resolution repositories, must not be
304      *                     {@code null} or contain {@code null} elements.
305      * @return The resolution repositories, never {@code null}. Note that there is generally no 1:1 relationship of the
306      * obtained repositories to the original inputs due to mirror selection potentially aggregating multiple
307      * repositories.
308      * @see #newDeploymentRepository(RepositorySystemSession, RemoteRepository)
309      */
310     List<RemoteRepository> newResolutionRepositories(
311             RepositorySystemSession session, List<RemoteRepository> repositories);
312 
313     /**
314      * Forms a remote repository suitable for artifact deployment by applying the session's authentication selector and
315      * similar network configuration to the given repository prototype. As noted for
316      * {@link RepositorySystemSession#getAuthenticationSelector()} etc. the remote repository passed to
317      * {@link #deploy(RepositorySystemSession, DeployRequest) deploy()} is used as is and expected to already carry any
318      * required authentication or proxy configuration. This method can be used to apply the authentication/proxy
319      * configuration from a session to a bare repository definition to obtain the complete repository definition for use
320      * in the deployment request.
321      *
322      * @param session    The repository system session from which to configure the repository, must not be {@code null}.
323      * @param repository The repository prototype from which to derive the deployment repository, must not be
324      *                   {@code null}.
325      * @return The deployment repository, never {@code null}.
326      * @see #newResolutionRepositories(RepositorySystemSession, List)
327      */
328     RemoteRepository newDeploymentRepository(RepositorySystemSession session, RemoteRepository repository);
329 
330     /**
331      * Registers an "on repository system end" handler, executed after repository system is shut down.
332      *
333      * @param handler The handler, must not be {@code null}.
334      * @since 1.9.0
335      */
336     void addOnSystemEndedHandler(Runnable handler);
337 
338     /**
339      * Creates a brand-new session builder instance that produces "top level" (root) session. Top level sessions are
340      * associated with its creator {@link RepositorySystem} instance, and may be used only with that given instance and
341      * only within the lifespan of it, and after use should be closed.
342      *
343      * @since 2.0.0
344      */
345     RepositorySystemSession.SessionBuilder createSessionBuilder();
346 
347     /**
348      * Signals to repository system to shut down. Shut down instance is not usable anymore.
349      * <p>
350      * Repository system may perform some resource cleanup, if applicable. Not using this method may cause leaks or
351      * unclean shutdown of some subsystem.
352      * <p>
353      * When shutdown happens, all the registered on-close handlers will be invoked (even if some throws), and at end
354      * of operation a {@link MultiRuntimeException} may be thrown, signaling that some handler(s) failed. This exception
355      * may be ignored, is at the discretion of caller.
356      *
357      * @since 1.9.0
358      */
359     void shutdown();
360 
361     /**
362      * Closes this instance, invokes {@link #shutdown()}.
363      *
364      * @since 2.0.0
365      */
366     @Override
367     default void close() {
368         shutdown();
369     }
370 }