001package org.eclipse.aether;
002
003/*
004 * Licensed to the Apache Software Foundation (ASF) under one
005 * or more contributor license agreements.  See the NOTICE file
006 * distributed with this work for additional information
007 * regarding copyright ownership.  The ASF licenses this file
008 * to you under the Apache License, Version 2.0 (the
009 * "License"); you may not use this file except in compliance
010 * with the License.  You may obtain a copy of the License at
011 * 
012 *  http://www.apache.org/licenses/LICENSE-2.0
013 * 
014 * Unless required by applicable law or agreed to in writing,
015 * software distributed under the License is distributed on an
016 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017 * KIND, either express or implied.  See the License for the
018 * specific language governing permissions and limitations
019 * under the License.
020 */
021
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.installation.InstallRequest;
033import org.eclipse.aether.installation.InstallResult;
034import org.eclipse.aether.installation.InstallationException;
035import org.eclipse.aether.metadata.Metadata;
036import org.eclipse.aether.repository.LocalRepository;
037import org.eclipse.aether.repository.LocalRepositoryManager;
038import org.eclipse.aether.repository.RemoteRepository;
039import org.eclipse.aether.resolution.ArtifactDescriptorException;
040import org.eclipse.aether.resolution.ArtifactDescriptorRequest;
041import org.eclipse.aether.resolution.ArtifactDescriptorResult;
042import org.eclipse.aether.resolution.ArtifactRequest;
043import org.eclipse.aether.resolution.ArtifactResolutionException;
044import org.eclipse.aether.resolution.ArtifactResult;
045import org.eclipse.aether.resolution.DependencyRequest;
046import org.eclipse.aether.resolution.DependencyResolutionException;
047import org.eclipse.aether.resolution.DependencyResult;
048import org.eclipse.aether.resolution.MetadataRequest;
049import org.eclipse.aether.resolution.MetadataResult;
050import org.eclipse.aether.resolution.VersionRangeRequest;
051import org.eclipse.aether.resolution.VersionRangeResolutionException;
052import org.eclipse.aether.resolution.VersionRangeResult;
053import org.eclipse.aether.resolution.VersionRequest;
054import org.eclipse.aether.resolution.VersionResolutionException;
055import org.eclipse.aether.resolution.VersionResult;
056
057/**
058 * The main entry point to the repository system and its functionality. Note that obtaining a concrete implementation of
059 * this interface (e.g. via dependency injection, service locator, etc.) is dependent on the application and its
060 * specific needs, please consult the online documentation for examples and directions on booting the system.
061 * 
062 * @noimplement This interface is not intended to be implemented by clients.
063 * @noextend This interface is not intended to be extended by clients.
064 */
065public interface RepositorySystem
066{
067
068    /**
069     * Expands a version range to a list of matching versions, in ascending order. For example, resolves "[3.8,4.0)" to
070     * "3.8", "3.8.1", "3.8.2". Note that the returned list of versions is only dependent on the configured repositories
071     * and their contents, the list is not processed by the {@link RepositorySystemSession#getVersionFilter() session's
072     * version filter}.
073     * <p>
074     * The supplied request may also refer to a single concrete version rather than a version range. In this case
075     * though, the result contains simply the (parsed) input version, regardless of the repositories and their contents.
076     * 
077     * @param session The repository session, must not be {@code null}.
078     * @param request The version range request, must not be {@code null}.
079     * @return The version range result, never {@code null}.
080     * @throws VersionRangeResolutionException If the requested range could not be parsed. Note that an empty range does
081     *             not raise an exception.
082     * @see #newResolutionRepositories(RepositorySystemSession, List)
083     */
084    VersionRangeResult resolveVersionRange( RepositorySystemSession session, VersionRangeRequest request )
085        throws VersionRangeResolutionException;
086
087    /**
088     * Resolves an artifact's meta version (if any) to a concrete version. For example, resolves "1.0-SNAPSHOT" to
089     * "1.0-20090208.132618-23".
090     * 
091     * @param session The repository session, must not be {@code null}.
092     * @param request The version request, must not be {@code null}.
093     * @return The version result, never {@code null}.
094     * @throws VersionResolutionException If the metaversion could not be resolved.
095     * @see #newResolutionRepositories(RepositorySystemSession, List)
096     */
097    VersionResult resolveVersion( RepositorySystemSession session, VersionRequest request )
098        throws VersionResolutionException;
099
100    /**
101     * Gets information about an artifact like its direct dependencies and potential relocations.
102     * 
103     * @param session The repository session, must not be {@code null}.
104     * @param request The descriptor request, must not be {@code null}.
105     * @return The descriptor result, never {@code null}.
106     * @throws ArtifactDescriptorException If the artifact descriptor could not be read.
107     * @see RepositorySystemSession#getArtifactDescriptorPolicy()
108     * @see #newResolutionRepositories(RepositorySystemSession, List)
109     */
110    ArtifactDescriptorResult readArtifactDescriptor( RepositorySystemSession session,
111                                                     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( RepositorySystemSession session,
178                                           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( RepositorySystemSession session,
192                                          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 )
203        throws InstallationException;
204
205    /**
206     * Uploads a collection of artifacts and their accompanying metadata to a remote repository.
207     * 
208     * @param session The repository session, must not be {@code null}.
209     * @param request The deployment request, must not be {@code null}.
210     * @return The deployment result, never {@code null}.
211     * @throws DeploymentException If any artifact/metadata from the request could not be deployed.
212     * @see #newDeploymentRepository(RepositorySystemSession, RemoteRepository)
213     */
214    DeployResult deploy( RepositorySystemSession session, DeployRequest request )
215        throws DeploymentException;
216
217    /**
218     * Creates a new manager for the specified local repository. If the specified local repository has no type, the
219     * default local repository type of the system will be used. <em>Note:</em> It is expected that this method
220     * invocation is one of the last steps of setting up a new session, in particular any configuration properties
221     * should have been set already.
222     * 
223     * @param session The repository system session from which to configure the manager, must not be {@code null}.
224     * @param localRepository The local repository to create a manager for, must not be {@code null}.
225     * @return The local repository manager, never {@code null}.
226     * @throws IllegalArgumentException If the specified repository type is not recognized or no base directory is
227     *             given.
228     */
229    LocalRepositoryManager newLocalRepositoryManager( RepositorySystemSession session,
230                                                      LocalRepository localRepository );
231
232    /**
233     * Creates a new synchronization context.
234     * 
235     * @param session The repository session during which the context will be used, must not be {@code null}.
236     * @param shared A flag indicating whether access to the artifacts/metadata associated with the new context can be
237     *            shared among concurrent readers or whether access needs to be exclusive to the calling thread.
238     * @return The synchronization context, never {@code null}.
239     */
240    SyncContext newSyncContext( RepositorySystemSession session, boolean shared );
241
242    /**
243     * Forms remote repositories suitable for artifact resolution by applying the session's authentication selector and
244     * similar network configuration to the given repository prototypes. As noted for
245     * {@link RepositorySystemSession#getAuthenticationSelector()} etc. the remote repositories passed to e.g.
246     * {@link #resolveArtifact(RepositorySystemSession, ArtifactRequest) resolveArtifact()} are used as is and expected
247     * to already carry any required authentication or proxy configuration. This method can be used to apply the
248     * authentication/proxy configuration from a session to a bare repository definition to obtain the complete
249     * repository definition for use in the resolution request.
250     * 
251     * @param session The repository system session from which to configure the repositories, must not be {@code null}.
252     * @param repositories The repository prototypes from which to derive the resolution repositories, must not be
253     *            {@code null} or contain {@code null} elements.
254     * @return The resolution repositories, never {@code null}. Note that there is generally no 1:1 relationship of the
255     *         obtained repositories to the original inputs due to mirror selection potentially aggregating multiple
256     *         repositories.
257     * @see #newDeploymentRepository(RepositorySystemSession, RemoteRepository)
258     */
259    List<RemoteRepository> newResolutionRepositories( RepositorySystemSession session,
260                                                      List<RemoteRepository> repositories );
261
262    /**
263     * Forms a remote repository suitable for artifact deployment by applying the session's authentication selector and
264     * similar network configuration to the given repository prototype. As noted for
265     * {@link RepositorySystemSession#getAuthenticationSelector()} etc. the remote repository passed to
266     * {@link #deploy(RepositorySystemSession, DeployRequest) deploy()} is used as is and expected to already carry any
267     * required authentication or proxy configuration. This method can be used to apply the authentication/proxy
268     * configuration from a session to a bare repository definition to obtain the complete repository definition for use
269     * in the deploy request.
270     * 
271     * @param session The repository system session from which to configure the repository, must not be {@code null}.
272     * @param repository The repository prototype from which to derive the deployment repository, must not be
273     *            {@code null}.
274     * @return The deployment repository, never {@code null}.
275     * @see #newResolutionRepositories(RepositorySystemSession, List)
276     */
277    RemoteRepository newDeploymentRepository( RepositorySystemSession session, RemoteRepository repository );
278
279}