1 /******************************************************************************* 2 * Copyright (c) 2010, 2014 Sonatype, Inc. 3 * All rights reserved. This program and the accompanying materials 4 * are made available under the terms of the Eclipse Public License v1.0 5 * which accompanies this distribution, and is available at 6 * http://www.eclipse.org/legal/epl-v10.html 7 * 8 * Contributors: 9 * Sonatype, Inc. - initial API and implementation 10 *******************************************************************************/ 11 package org.eclipse.aether; 12 13 import java.util.Collection; 14 import java.util.List; 15 16 import org.eclipse.aether.artifact.Artifact; 17 import org.eclipse.aether.collection.CollectRequest; 18 import org.eclipse.aether.collection.CollectResult; 19 import org.eclipse.aether.collection.DependencyCollectionException; 20 import org.eclipse.aether.deployment.DeployRequest; 21 import org.eclipse.aether.deployment.DeployResult; 22 import org.eclipse.aether.deployment.DeploymentException; 23 import org.eclipse.aether.installation.InstallRequest; 24 import org.eclipse.aether.installation.InstallResult; 25 import org.eclipse.aether.installation.InstallationException; 26 import org.eclipse.aether.metadata.Metadata; 27 import org.eclipse.aether.repository.LocalRepository; 28 import org.eclipse.aether.repository.LocalRepositoryManager; 29 import org.eclipse.aether.repository.RemoteRepository; 30 import org.eclipse.aether.resolution.ArtifactDescriptorException; 31 import org.eclipse.aether.resolution.ArtifactDescriptorRequest; 32 import org.eclipse.aether.resolution.ArtifactDescriptorResult; 33 import org.eclipse.aether.resolution.ArtifactRequest; 34 import org.eclipse.aether.resolution.ArtifactResolutionException; 35 import org.eclipse.aether.resolution.ArtifactResult; 36 import org.eclipse.aether.resolution.DependencyRequest; 37 import org.eclipse.aether.resolution.DependencyResolutionException; 38 import org.eclipse.aether.resolution.DependencyResult; 39 import org.eclipse.aether.resolution.MetadataRequest; 40 import org.eclipse.aether.resolution.MetadataResult; 41 import org.eclipse.aether.resolution.VersionRangeRequest; 42 import org.eclipse.aether.resolution.VersionRangeResolutionException; 43 import org.eclipse.aether.resolution.VersionRangeResult; 44 import org.eclipse.aether.resolution.VersionRequest; 45 import org.eclipse.aether.resolution.VersionResolutionException; 46 import org.eclipse.aether.resolution.VersionResult; 47 48 /** 49 * The main entry point to the repository system and its functionality. Note that obtaining a concrete implementation of 50 * this interface (e.g. via dependency injection, service locator, etc.) is dependent on the application and its 51 * specific needs, please consult the online documentation for examples and directions on booting the system. 52 * 53 * @noimplement This interface is not intended to be implemented by clients. 54 * @noextend This interface is not intended to be extended by clients. 55 */ 56 public interface RepositorySystem 57 { 58 59 /** 60 * Expands a version range to a list of matching versions, in ascending order. For example, resolves "[3.8,4.0)" to 61 * "3.8", "3.8.1", "3.8.2". Note that the returned list of versions is only dependent on the configured repositories 62 * and their contents, the list is not processed by the {@link RepositorySystemSession#getVersionFilter() session's 63 * version filter}. 64 * <p> 65 * The supplied request may also refer to a single concrete version rather than a version range. In this case 66 * though, the result contains simply the (parsed) input version, regardless of the repositories and their contents. 67 * 68 * @param session The repository session, must not be {@code null}. 69 * @param request The version range request, must not be {@code null}. 70 * @return The version range result, never {@code null}. 71 * @throws VersionRangeResolutionException If the requested range could not be parsed. Note that an empty range does 72 * not raise an exception. 73 * @see #newResolutionRepositories(RepositorySystemSession, List) 74 */ 75 VersionRangeResult resolveVersionRange( RepositorySystemSession session, VersionRangeRequest request ) 76 throws VersionRangeResolutionException; 77 78 /** 79 * Resolves an artifact's meta version (if any) to a concrete version. For example, resolves "1.0-SNAPSHOT" to 80 * "1.0-20090208.132618-23". 81 * 82 * @param session The repository session, must not be {@code null}. 83 * @param request The version request, must not be {@code null}. 84 * @return The version result, never {@code null}. 85 * @throws VersionResolutionException If the metaversion could not be resolved. 86 * @see #newResolutionRepositories(RepositorySystemSession, List) 87 */ 88 VersionResult resolveVersion( RepositorySystemSession session, VersionRequest request ) 89 throws VersionResolutionException; 90 91 /** 92 * Gets information about an artifact like its direct dependencies and potential relocations. 93 * 94 * @param session The repository session, must not be {@code null}. 95 * @param request The descriptor request, must not be {@code null}. 96 * @return The descriptor result, never {@code null}. 97 * @throws ArtifactDescriptorException If the artifact descriptor could not be read. 98 * @see RepositorySystemSession#getArtifactDescriptorPolicy() 99 * @see #newResolutionRepositories(RepositorySystemSession, List) 100 */ 101 ArtifactDescriptorResult readArtifactDescriptor( RepositorySystemSession session, ArtifactDescriptorRequest request ) 102 throws ArtifactDescriptorException; 103 104 /** 105 * Collects the transitive dependencies of an artifact and builds a dependency graph. Note that this operation is 106 * only concerned about determining the coordinates of the transitive dependencies. To also resolve the actual 107 * artifact files, use {@link #resolveDependencies(RepositorySystemSession, DependencyRequest)}. 108 * 109 * @param session The repository session, must not be {@code null}. 110 * @param request The collection request, must not be {@code null}. 111 * @return The collection result, never {@code null}. 112 * @throws DependencyCollectionException If the dependency tree could not be built. 113 * @see RepositorySystemSession#getDependencyTraverser() 114 * @see RepositorySystemSession#getDependencyManager() 115 * @see RepositorySystemSession#getDependencySelector() 116 * @see RepositorySystemSession#getVersionFilter() 117 * @see RepositorySystemSession#getDependencyGraphTransformer() 118 * @see #newResolutionRepositories(RepositorySystemSession, List) 119 */ 120 CollectResult collectDependencies( RepositorySystemSession session, CollectRequest request ) 121 throws DependencyCollectionException; 122 123 /** 124 * Collects and resolves the transitive dependencies of an artifact. This operation is essentially a combination of 125 * {@link #collectDependencies(RepositorySystemSession, CollectRequest)} and 126 * {@link #resolveArtifacts(RepositorySystemSession, Collection)}. 127 * 128 * @param session The repository session, must not be {@code null}. 129 * @param request The dependency request, must not be {@code null}. 130 * @return The dependency result, never {@code null}. 131 * @throws DependencyResolutionException If the dependency tree could not be built or any dependency artifact could 132 * not be resolved. 133 * @see #newResolutionRepositories(RepositorySystemSession, List) 134 */ 135 DependencyResult resolveDependencies( RepositorySystemSession session, DependencyRequest request ) 136 throws DependencyResolutionException; 137 138 /** 139 * Resolves the path for an artifact. The artifact will be downloaded to the local repository if necessary. An 140 * artifact that is already resolved will be skipped and is not re-resolved. In general, callers must not assume any 141 * relationship between an artifact's resolved filename and its coordinates. Note that this method assumes that any 142 * relocations have already been processed. 143 * 144 * @param session The repository session, must not be {@code null}. 145 * @param request The resolution request, must not be {@code null}. 146 * @return The resolution result, never {@code null}. 147 * @throws ArtifactResolutionException If the artifact could not be resolved. 148 * @see Artifact#getFile() 149 * @see #newResolutionRepositories(RepositorySystemSession, List) 150 */ 151 ArtifactResult resolveArtifact( RepositorySystemSession session, ArtifactRequest request ) 152 throws ArtifactResolutionException; 153 154 /** 155 * Resolves the paths for a collection of artifacts. Artifacts will be downloaded to the local repository if 156 * necessary. Artifacts that are already resolved will be skipped and are not re-resolved. In general, callers must 157 * not assume any relationship between an artifact's filename and its coordinates. Note that this method assumes 158 * that any relocations have already been processed. 159 * 160 * @param session The repository session, must not be {@code null}. 161 * @param requests The resolution requests, must not be {@code null}. 162 * @return The resolution results (in request order), never {@code null}. 163 * @throws ArtifactResolutionException If any artifact could not be resolved. 164 * @see Artifact#getFile() 165 * @see #newResolutionRepositories(RepositorySystemSession, List) 166 */ 167 List<ArtifactResult> resolveArtifacts( RepositorySystemSession session, 168 Collection<? extends ArtifactRequest> requests ) 169 throws ArtifactResolutionException; 170 171 /** 172 * Resolves the paths for a collection of metadata. Metadata will be downloaded to the local repository if 173 * necessary, e.g. because it hasn't been cached yet or the cache is deemed outdated. 174 * 175 * @param session The repository session, must not be {@code null}. 176 * @param requests The resolution requests, must not be {@code null}. 177 * @return The resolution results (in request order), never {@code null}. 178 * @see Metadata#getFile() 179 * @see #newResolutionRepositories(RepositorySystemSession, List) 180 */ 181 List<MetadataResult> resolveMetadata( RepositorySystemSession session, 182 Collection<? extends MetadataRequest> requests ); 183 184 /** 185 * Installs a collection of artifacts and their accompanying metadata to the local repository. 186 * 187 * @param session The repository session, must not be {@code null}. 188 * @param request The installation request, must not be {@code null}. 189 * @return The installation result, never {@code null}. 190 * @throws InstallationException If any artifact/metadata from the request could not be installed. 191 */ 192 InstallResult install( RepositorySystemSession session, InstallRequest request ) 193 throws InstallationException; 194 195 /** 196 * Uploads a collection of artifacts and their accompanying metadata to a remote repository. 197 * 198 * @param session The repository session, must not be {@code null}. 199 * @param request The deployment request, must not be {@code null}. 200 * @return The deployment result, never {@code null}. 201 * @throws DeploymentException If any artifact/metadata from the request could not be deployed. 202 * @see #newDeploymentRepository(RepositorySystemSession, RemoteRepository) 203 */ 204 DeployResult deploy( RepositorySystemSession session, DeployRequest request ) 205 throws DeploymentException; 206 207 /** 208 * Creates a new manager for the specified local repository. If the specified local repository has no type, the 209 * default local repository type of the system will be used. <em>Note:</em> It is expected that this method 210 * invocation is one of the last steps of setting up a new session, in particular any configuration properties 211 * should have been set already. 212 * 213 * @param session The repository system session from which to configure the manager, must not be {@code null}. 214 * @param localRepository The local repository to create a manager for, must not be {@code null}. 215 * @return The local repository manager, never {@code null}. 216 * @throws IllegalArgumentException If the specified repository type is not recognized or no base directory is 217 * given. 218 */ 219 LocalRepositoryManager newLocalRepositoryManager( RepositorySystemSession session, LocalRepository localRepository ); 220 221 /** 222 * Creates a new synchronization context. 223 * 224 * @param session The repository session during which the context will be used, must not be {@code null}. 225 * @param shared A flag indicating whether access to the artifacts/metadata associated with the new context can be 226 * shared among concurrent readers or whether access needs to be exclusive to the calling thread. 227 * @return The synchronization context, never {@code null}. 228 */ 229 SyncContext newSyncContext( RepositorySystemSession session, boolean shared ); 230 231 /** 232 * Forms remote repositories suitable for artifact resolution by applying the session's authentication selector and 233 * similar network configuration to the given repository prototypes. As noted for 234 * {@link RepositorySystemSession#getAuthenticationSelector()} etc. the remote repositories passed to e.g. 235 * {@link #resolveArtifact(RepositorySystemSession, ArtifactRequest) resolveArtifact()} are used as is and expected 236 * to already carry any required authentication or proxy configuration. This method can be used to apply the 237 * authentication/proxy configuration from a session to a bare repository definition to obtain the complete 238 * repository definition for use in the resolution request. 239 * 240 * @param session The repository system session from which to configure the repositories, must not be {@code null}. 241 * @param repositories The repository prototypes from which to derive the resolution repositories, must not be 242 * {@code null} or contain {@code null} elements. 243 * @return The resolution repositories, never {@code null}. Note that there is generally no 1:1 relationship of the 244 * obtained repositories to the original inputs due to mirror selection potentially aggregating multiple 245 * repositories. 246 * @see #newDeploymentRepository(RepositorySystemSession, RemoteRepository) 247 */ 248 List<RemoteRepository> newResolutionRepositories( RepositorySystemSession session, 249 List<RemoteRepository> repositories ); 250 251 /** 252 * Forms a remote repository suitable for artifact deployment by applying the session's authentication selector and 253 * similar network configuration to the given repository prototype. As noted for 254 * {@link RepositorySystemSession#getAuthenticationSelector()} etc. the remote repository passed to 255 * {@link #deploy(RepositorySystemSession, DeployRequest) deploy()} is used as is and expected to already carry any 256 * required authentication or proxy configuration. This method can be used to apply the authentication/proxy 257 * configuration from a session to a bare repository definition to obtain the complete repository definition for use 258 * in the deploy request. 259 * 260 * @param session The repository system session from which to configure the repository, must not be {@code null}. 261 * @param repository The repository prototype from which to derive the deployment repository, must not be 262 * {@code null}. 263 * @return The deployment repository, never {@code null}. 264 * @see #newResolutionRepositories(RepositorySystemSession, List) 265 */ 266 RemoteRepository newDeploymentRepository( RepositorySystemSession session, RemoteRepository repository ); 267 268 }