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}