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