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