001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *   http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied.  See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019package org.eclipse.aether;
020
021import java.io.Closeable;
022import java.util.Collection;
023import java.util.List;
024
025import org.eclipse.aether.artifact.Artifact;
026import org.eclipse.aether.collection.CollectRequest;
027import org.eclipse.aether.collection.CollectResult;
028import org.eclipse.aether.collection.DependencyCollectionException;
029import org.eclipse.aether.deployment.DeployRequest;
030import org.eclipse.aether.deployment.DeployResult;
031import org.eclipse.aether.deployment.DeploymentException;
032import org.eclipse.aether.graph.DependencyNode;
033import org.eclipse.aether.installation.InstallRequest;
034import org.eclipse.aether.installation.InstallResult;
035import org.eclipse.aether.installation.InstallationException;
036import org.eclipse.aether.metadata.Metadata;
037import org.eclipse.aether.repository.LocalRepository;
038import org.eclipse.aether.repository.LocalRepositoryManager;
039import org.eclipse.aether.repository.RemoteRepository;
040import org.eclipse.aether.resolution.ArtifactDescriptorException;
041import org.eclipse.aether.resolution.ArtifactDescriptorRequest;
042import org.eclipse.aether.resolution.ArtifactDescriptorResult;
043import org.eclipse.aether.resolution.ArtifactRequest;
044import org.eclipse.aether.resolution.ArtifactResolutionException;
045import org.eclipse.aether.resolution.ArtifactResult;
046import org.eclipse.aether.resolution.DependencyRequest;
047import org.eclipse.aether.resolution.DependencyResolutionException;
048import org.eclipse.aether.resolution.DependencyResult;
049import org.eclipse.aether.resolution.MetadataRequest;
050import org.eclipse.aether.resolution.MetadataResult;
051import org.eclipse.aether.resolution.VersionRangeRequest;
052import org.eclipse.aether.resolution.VersionRangeResolutionException;
053import org.eclipse.aether.resolution.VersionRangeResult;
054import org.eclipse.aether.resolution.VersionRequest;
055import org.eclipse.aether.resolution.VersionResolutionException;
056import org.eclipse.aether.resolution.VersionResult;
057
058/**
059 * The main entry point to the repository system and its functionality. Note that obtaining a concrete implementation of
060 * this interface (e.g. via dependency injection, service locator, etc.) is dependent on the application and its
061 * specific needs, please consult the online documentation for examples and directions on booting the system.
062 * <p>
063 * When the repository system or the application integrating it is about to exit, invoke the {@link #shutdown()} to let
064 * resolver system perform possible resource cleanups.
065 *
066 * @noimplement This interface is not intended to be implemented by clients.
067 * @noextend This interface is not intended to be extended by clients.
068 */
069public interface RepositorySystem extends Closeable {
070
071    /**
072     * Expands a version range to a list of matching versions, in ascending order. For example, resolves "[3.8,4.0)" to
073     * "3.8", "3.8.1", "3.8.2". Note that the returned list of versions is only dependent on the configured repositories
074     * and their contents, the list is not processed by the {@link RepositorySystemSession#getVersionFilter() session's
075     * version filter}.
076     * <p>
077     * The supplied request may also refer to a single concrete version rather than a version range. In this case
078     * though, the result contains simply the (parsed) input version, regardless of the repositories and their contents.
079     *
080     * @param session The repository session, must not be {@code null}.
081     * @param request The version range request, must not be {@code null}.
082     * @return The version range result, never {@code null}.
083     * @throws VersionRangeResolutionException If the requested range could not be parsed. Note that an empty range does
084     *                                         not raise an exception.
085     * @see #newResolutionRepositories(RepositorySystemSession, List)
086     */
087    VersionRangeResult resolveVersionRange(RepositorySystemSession session, VersionRangeRequest request)
088            throws VersionRangeResolutionException;
089
090    /**
091     * Resolves an artifact's meta version (if any) to a concrete version. For example, resolves "1.0-SNAPSHOT" to
092     * "1.0-20090208.132618-23".
093     *
094     * @param session The repository session, must not be {@code null}.
095     * @param request The version request, must not be {@code null}.
096     * @return The version result, never {@code null}.
097     * @throws VersionResolutionException If the metaversion could not be resolved.
098     * @see #newResolutionRepositories(RepositorySystemSession, List)
099     */
100    VersionResult resolveVersion(RepositorySystemSession session, VersionRequest request)
101            throws VersionResolutionException;
102
103    /**
104     * Gets information about an artifact like its direct dependencies and potential relocations.
105     *
106     * @param session The repository session, must not be {@code null}.
107     * @param request The descriptor request, must not be {@code null}.
108     * @return The descriptor result, never {@code null}.
109     * @throws ArtifactDescriptorException If the artifact descriptor could not be read.
110     * @see RepositorySystemSession#getArtifactDescriptorPolicy()
111     * @see #newResolutionRepositories(RepositorySystemSession, List)
112     */
113    ArtifactDescriptorResult readArtifactDescriptor(RepositorySystemSession session, ArtifactDescriptorRequest request)
114            throws ArtifactDescriptorException;
115
116    /**
117     * Collects the transitive dependencies of an artifact and builds a dependency graph. Note that this operation is
118     * only concerned about determining the coordinates of the transitive dependencies. To also resolve the actual
119     * artifact files, use {@link #resolveDependencies(RepositorySystemSession, DependencyRequest)}.
120     *
121     * @param session The repository session, must not be {@code null}.
122     * @param request The collection request, must not be {@code null}.
123     * @return The collection result, never {@code null}.
124     * @throws DependencyCollectionException If the dependency tree could not be built.
125     * @see RepositorySystemSession#getDependencyTraverser()
126     * @see RepositorySystemSession#getDependencyManager()
127     * @see RepositorySystemSession#getDependencySelector()
128     * @see RepositorySystemSession#getVersionFilter()
129     * @see RepositorySystemSession#getDependencyGraphTransformer()
130     * @see #newResolutionRepositories(RepositorySystemSession, List)
131     */
132    CollectResult collectDependencies(RepositorySystemSession session, CollectRequest request)
133            throws DependencyCollectionException;
134
135    /**
136     * Collects and resolves the transitive dependencies of an artifact. This operation is essentially a combination of
137     * {@link #collectDependencies(RepositorySystemSession, CollectRequest)} and
138     * {@link #resolveArtifacts(RepositorySystemSession, Collection)}.
139     *
140     * @param session The repository session, must not be {@code null}.
141     * @param request The dependency request, must not be {@code null}.
142     * @return The dependency result, never {@code null}.
143     * @throws DependencyResolutionException If the dependency tree could not be built or any dependency artifact could
144     *                                       not be resolved.
145     * @see #newResolutionRepositories(RepositorySystemSession, List)
146     */
147    DependencyResult resolveDependencies(RepositorySystemSession session, DependencyRequest request)
148            throws DependencyResolutionException;
149
150    /**
151     * Flattens the provided graph as {@link DependencyNode} into a {@link List}{@code <DependencyNode>} according to session
152     * configuration.
153     *
154     * @param session The repository session, must not be {@code null}.
155     * @param root The dependency node root of the graph, must not be {@code null}.
156     * @return The flattened list of dependency nodes, never {@code null}.
157     * @since 2.0.0
158     */
159    List<DependencyNode> flattenDependencyNodes(RepositorySystemSession session, DependencyNode root);
160
161    /**
162     * Resolves the path for an artifact. The artifact will be downloaded to the local repository if necessary. An
163     * artifact that is already resolved will be skipped and is not re-resolved. In general, callers must not assume any
164     * relationship between an artifact's resolved filename and its coordinates. Note that this method assumes that any
165     * relocations have already been processed.
166     *
167     * @param session The repository session, must not be {@code null}.
168     * @param request The resolution request, must not be {@code null}.
169     * @return The resolution result, never {@code null}.
170     * @throws ArtifactResolutionException If the artifact could not be resolved.
171     * @see Artifact#getFile()
172     * @see #newResolutionRepositories(RepositorySystemSession, List)
173     */
174    ArtifactResult resolveArtifact(RepositorySystemSession session, ArtifactRequest request)
175            throws ArtifactResolutionException;
176
177    /**
178     * Resolves the paths for a collection of artifacts. Artifacts will be downloaded to the local repository if
179     * necessary. Artifacts that are already resolved will be skipped and are not re-resolved. In general, callers must
180     * not assume any relationship between an artifact's filename and its coordinates. Note that this method assumes
181     * that any relocations have already been processed.
182     *
183     * @param session  The repository session, must not be {@code null}.
184     * @param requests The resolution requests, must not be {@code null}.
185     * @return The resolution results (in request order), never {@code null}.
186     * @throws ArtifactResolutionException If any artifact could not be resolved.
187     * @see Artifact#getFile()
188     * @see #newResolutionRepositories(RepositorySystemSession, List)
189     */
190    List<ArtifactResult> resolveArtifacts(
191            RepositorySystemSession session, Collection<? extends ArtifactRequest> requests)
192            throws ArtifactResolutionException;
193
194    /**
195     * Resolves the paths for a collection of metadata. Metadata will be downloaded to the local repository if
196     * necessary, e.g. because it hasn't been cached yet or the cache is deemed outdated.
197     *
198     * @param session  The repository session, must not be {@code null}.
199     * @param requests The resolution requests, must not be {@code null}.
200     * @return The resolution results (in request order), never {@code null}.
201     * @see Metadata#getFile()
202     * @see #newResolutionRepositories(RepositorySystemSession, List)
203     */
204    List<MetadataResult> resolveMetadata(
205            RepositorySystemSession session, Collection<? extends MetadataRequest> requests);
206
207    /**
208     * Installs a collection of artifacts and their accompanying metadata to the local repository.
209     *
210     * @param session The repository session, must not be {@code null}.
211     * @param request The installation request, must not be {@code null}.
212     * @return The installation result, never {@code null}.
213     * @throws InstallationException If any artifact/metadata from the request could not be installed.
214     */
215    InstallResult install(RepositorySystemSession session, InstallRequest request) throws InstallationException;
216
217    /**
218     * Uploads a collection of artifacts and their accompanying metadata to a remote repository.
219     *
220     * @param session The repository session, must not be {@code null}.
221     * @param request The deployment request, must not be {@code null}.
222     * @return The deployment result, never {@code null}.
223     * @throws DeploymentException If any artifact/metadata from the request could not be deployed.
224     * @see #newDeploymentRepository(RepositorySystemSession, RemoteRepository)
225     */
226    DeployResult deploy(RepositorySystemSession session, DeployRequest request) throws DeploymentException;
227
228    /**
229     * Creates a new manager for the specified local repository. If the specified local repository has no type, the
230     * default local repository type of the system will be used. <em>Note:</em> It is expected that this method
231     * invocation is one of the last steps of setting up a new session, in particular any configuration properties
232     * should have been set already.
233     *
234     * @param session         The repository system session from which to configure the manager, must not be
235     *                        {@code null}.
236     * @param localRepository The local repository to create a manager for, must not be {@code null}.
237     * @return The local repository manager, never {@code null}.
238     * @throws IllegalArgumentException If the specified repository type is not recognized or no base directory is
239     *                                  given.
240     */
241    LocalRepositoryManager newLocalRepositoryManager(RepositorySystemSession session, LocalRepository localRepository);
242
243    /**
244     * Creates a new synchronization context.
245     *
246     * @param session The repository session during which the context will be used, must not be {@code null}.
247     * @param shared  A flag indicating whether access to the artifacts/metadata associated with the new context can be
248     *                shared among concurrent readers or whether access needs to be exclusive to the calling thread.
249     * @return The synchronization context, never {@code null}.
250     */
251    SyncContext newSyncContext(RepositorySystemSession session, boolean shared);
252
253    /**
254     * Forms remote repositories suitable for artifact resolution by applying the session's authentication selector and
255     * similar network configuration to the given repository prototypes. As noted for
256     * {@link RepositorySystemSession#getAuthenticationSelector()} etc. the remote repositories passed to e.g.
257     * {@link #resolveArtifact(RepositorySystemSession, ArtifactRequest) resolveArtifact()} are used as is and expected
258     * to already carry any required authentication or proxy configuration. This method can be used to apply the
259     * authentication/proxy configuration from a session to a bare repository definition to obtain the complete
260     * repository definition for use in the resolution request.
261     *
262     * @param session      The repository system session from which to configure the repositories, must not be
263     *                     {@code null}.
264     * @param repositories The repository prototypes from which to derive the resolution repositories, must not be
265     *                     {@code null} or contain {@code null} elements.
266     * @return The resolution repositories, never {@code null}. Note that there is generally no 1:1 relationship of the
267     * obtained repositories to the original inputs due to mirror selection potentially aggregating multiple
268     * repositories.
269     * @see #newDeploymentRepository(RepositorySystemSession, RemoteRepository)
270     */
271    List<RemoteRepository> newResolutionRepositories(
272            RepositorySystemSession session, List<RemoteRepository> repositories);
273
274    /**
275     * Forms a remote repository suitable for artifact deployment by applying the session's authentication selector and
276     * similar network configuration to the given repository prototype. As noted for
277     * {@link RepositorySystemSession#getAuthenticationSelector()} etc. the remote repository passed to
278     * {@link #deploy(RepositorySystemSession, DeployRequest) deploy()} is used as is and expected to already carry any
279     * required authentication or proxy configuration. This method can be used to apply the authentication/proxy
280     * configuration from a session to a bare repository definition to obtain the complete repository definition for use
281     * in the deployment request.
282     *
283     * @param session    The repository system session from which to configure the repository, must not be {@code null}.
284     * @param repository The repository prototype from which to derive the deployment repository, must not be
285     *                   {@code null}.
286     * @return The deployment repository, never {@code null}.
287     * @see #newResolutionRepositories(RepositorySystemSession, List)
288     */
289    RemoteRepository newDeploymentRepository(RepositorySystemSession session, RemoteRepository repository);
290
291    /**
292     * Registers an "on repository system end" handler, executed after repository system is shut down.
293     *
294     * @param handler The handler, must not be {@code null}.
295     * @since 1.9.0
296     */
297    void addOnSystemEndedHandler(Runnable handler);
298
299    /**
300     * Creates a brand-new session builder instance that produces "top level" (root) session. Top level sessions are
301     * associated with its creator {@link RepositorySystem} instance, and may be used only with that given instance and
302     * only within the lifespan of it, and after use should be closed.
303     *
304     * @since 2.0.0
305     */
306    RepositorySystemSession.SessionBuilder createSessionBuilder();
307
308    /**
309     * Signals to repository system to shut down. Shut down instance is not usable anymore.
310     * <p>
311     * Repository system may perform some resource cleanup, if applicable. Not using this method may cause leaks or
312     * unclean shutdown of some subsystem.
313     * <p>
314     * When shutdown happens, all the registered on-close handlers will be invoked (even if some throws), and at end
315     * of operation a {@link MultiRuntimeException} may be thrown, signaling that some handler(s) failed. This exception
316     * may be ignored, is at the discretion of caller.
317     *
318     * @since 1.9.0
319     */
320    void shutdown();
321
322    /**
323     * Closes this instance, invokes {@link #shutdown()}.
324     *
325     * @since 2.0.0
326     */
327    @Override
328    default void close() {
329        shutdown();
330    }
331}