1 package org.eclipse.aether;
2
3 /*
4 * Licensed to the Apache Software Foundation (ASF) under one
5 * or more contributor license agreements. See the NOTICE file
6 * distributed with this work for additional information
7 * regarding copyright ownership. The ASF licenses this file
8 * to you under the Apache License, Version 2.0 (the
9 * "License"); you may not use this file except in compliance
10 * with the License. You may obtain a copy of the License at
11 *
12 * http://www.apache.org/licenses/LICENSE-2.0
13 *
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17 * KIND, either express or implied. See the License for the
18 * specific language governing permissions and limitations
19 * under the License.
20 */
21
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.installation.InstallRequest;
33 import org.eclipse.aether.installation.InstallResult;
34 import org.eclipse.aether.installation.InstallationException;
35 import org.eclipse.aether.metadata.Metadata;
36 import org.eclipse.aether.repository.LocalRepository;
37 import org.eclipse.aether.repository.LocalRepositoryManager;
38 import org.eclipse.aether.repository.RemoteRepository;
39 import org.eclipse.aether.resolution.ArtifactDescriptorException;
40 import org.eclipse.aether.resolution.ArtifactDescriptorRequest;
41 import org.eclipse.aether.resolution.ArtifactDescriptorResult;
42 import org.eclipse.aether.resolution.ArtifactRequest;
43 import org.eclipse.aether.resolution.ArtifactResolutionException;
44 import org.eclipse.aether.resolution.ArtifactResult;
45 import org.eclipse.aether.resolution.DependencyRequest;
46 import org.eclipse.aether.resolution.DependencyResolutionException;
47 import org.eclipse.aether.resolution.DependencyResult;
48 import org.eclipse.aether.resolution.MetadataRequest;
49 import org.eclipse.aether.resolution.MetadataResult;
50 import org.eclipse.aether.resolution.VersionRangeRequest;
51 import org.eclipse.aether.resolution.VersionRangeResolutionException;
52 import org.eclipse.aether.resolution.VersionRangeResult;
53 import org.eclipse.aether.resolution.VersionRequest;
54 import org.eclipse.aether.resolution.VersionResolutionException;
55 import org.eclipse.aether.resolution.VersionResult;
56
57 /**
58 * The main entry point to the repository system and its functionality. Note that obtaining a concrete implementation of
59 * this interface (e.g. via dependency injection, service locator, etc.) is dependent on the application and its
60 * specific needs, please consult the online documentation for examples and directions on booting the system.
61 *
62 * @noimplement This interface is not intended to be implemented by clients.
63 * @noextend This interface is not intended to be extended by clients.
64 */
65 public interface RepositorySystem
66 {
67
68 /**
69 * Expands a version range to a list of matching versions, in ascending order. For example, resolves "[3.8,4.0)" to
70 * "3.8", "3.8.1", "3.8.2". Note that the returned list of versions is only dependent on the configured repositories
71 * and their contents, the list is not processed by the {@link RepositorySystemSession#getVersionFilter() session's
72 * version filter}.
73 * <p>
74 * The supplied request may also refer to a single concrete version rather than a version range. In this case
75 * though, the result contains simply the (parsed) input version, regardless of the repositories and their contents.
76 *
77 * @param session The repository session, must not be {@code null}.
78 * @param request The version range request, must not be {@code null}.
79 * @return The version range result, never {@code null}.
80 * @throws VersionRangeResolutionException If the requested range could not be parsed. Note that an empty range does
81 * not raise an exception.
82 * @see #newResolutionRepositories(RepositorySystemSession, List)
83 */
84 VersionRangeResult resolveVersionRange( RepositorySystemSession session, VersionRangeRequest request )
85 throws VersionRangeResolutionException;
86
87 /**
88 * Resolves an artifact's meta version (if any) to a concrete version. For example, resolves "1.0-SNAPSHOT" to
89 * "1.0-20090208.132618-23".
90 *
91 * @param session The repository session, must not be {@code null}.
92 * @param request The version request, must not be {@code null}.
93 * @return The version result, never {@code null}.
94 * @throws VersionResolutionException If the metaversion could not be resolved.
95 * @see #newResolutionRepositories(RepositorySystemSession, List)
96 */
97 VersionResult resolveVersion( RepositorySystemSession session, VersionRequest request )
98 throws VersionResolutionException;
99
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 }