package org.eclipse.aether;

/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 * 
 *  http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */

import java.util.Collection;
import java.util.List;

import org.eclipse.aether.artifact.Artifact;
import org.eclipse.aether.collection.CollectRequest;
import org.eclipse.aether.collection.CollectResult;
import org.eclipse.aether.collection.DependencyCollectionException;
import org.eclipse.aether.deployment.DeployRequest;
import org.eclipse.aether.deployment.DeployResult;
import org.eclipse.aether.deployment.DeploymentException;
import org.eclipse.aether.installation.InstallRequest;
import org.eclipse.aether.installation.InstallResult;
import org.eclipse.aether.installation.InstallationException;
import org.eclipse.aether.metadata.Metadata;
import org.eclipse.aether.repository.LocalRepository;
import org.eclipse.aether.repository.LocalRepositoryManager;
import org.eclipse.aether.repository.RemoteRepository;
import org.eclipse.aether.resolution.ArtifactDescriptorException;
import org.eclipse.aether.resolution.ArtifactDescriptorRequest;
import org.eclipse.aether.resolution.ArtifactDescriptorResult;
import org.eclipse.aether.resolution.ArtifactRequest;
import org.eclipse.aether.resolution.ArtifactResolutionException;
import org.eclipse.aether.resolution.ArtifactResult;
import org.eclipse.aether.resolution.DependencyRequest;
import org.eclipse.aether.resolution.DependencyResolutionException;
import org.eclipse.aether.resolution.DependencyResult;
import org.eclipse.aether.resolution.MetadataRequest;
import org.eclipse.aether.resolution.MetadataResult;
import org.eclipse.aether.resolution.VersionRangeRequest;
import org.eclipse.aether.resolution.VersionRangeResolutionException;
import org.eclipse.aether.resolution.VersionRangeResult;
import org.eclipse.aether.resolution.VersionRequest;
import org.eclipse.aether.resolution.VersionResolutionException;
import org.eclipse.aether.resolution.VersionResult;

The main entry point to the repository system and its functionality. Note that obtaining a concrete implementation of
this interface (e.g. via dependency injection, service locator, etc.) is dependent on the application and its
specific needs, please consult the online documentation for examples and directions on booting the system.
@noimplement
This interface is not intended to be implemented by clients.
@noextend
This interface is not intended to be extended by clients./**
 * The main entry point to the repository system and its functionality. Note that obtaining a concrete implementation of
 * this interface (e.g. via dependency injection, service locator, etc.) is dependent on the application and its
 * specific needs, please consult the online documentation for examples and directions on booting the system.
 * 
 * @noimplement This interface is not intended to be implemented by clients.
 * @noextend This interface is not intended to be extended by clients.
 */
public interface RepositorySystem
{

    
Expands a version range to a list of matching versions, in ascending order. For example, resolves "[3.8,4.0)" to "3.8", "3.8.1", "3.8.2". Note that the returned list of versions is only dependent on the configured repositories and their contents, the list is not processed by the session's
version filter. 

The supplied request may also refer to a single concrete version rather than a version range. In this case
though, the result contains simply the (parsed) input version, regardless of the repositories and their contents.
Params:
session – The repository session, must not be null.
request – The version range request, must not be null.
Throws:
VersionRangeResolutionException – If the requested range could not be parsed. Note that an empty range does
            not raise an exception.
See Also:
newResolutionRepositories(RepositorySystemSession, List<RemoteRepository>)
Returns:
The version range result, never null./**
     * Expands a version range to a list of matching versions, in ascending order. For example, resolves "[3.8,4.0)" to
     * "3.8", "3.8.1", "3.8.2". Note that the returned list of versions is only dependent on the configured repositories
     * and their contents, the list is not processed by the {@link RepositorySystemSession#getVersionFilter() session's
     * version filter}.
     * <p>
     * The supplied request may also refer to a single concrete version rather than a version range. In this case
     * though, the result contains simply the (parsed) input version, regardless of the repositories and their contents.
     * 
     * @param session The repository session, must not be {@code null}.
     * @param request The version range request, must not be {@code null}.
     * @return The version range result, never {@code null}.
     * @throws VersionRangeResolutionException If the requested range could not be parsed. Note that an empty range does
     *             not raise an exception.
     * @see #newResolutionRepositories(RepositorySystemSession, List)
     */
    VersionRangeResult resolveVersionRange( RepositorySystemSession session, VersionRangeRequest request )
        throws VersionRangeResolutionException;

    
Resolves an artifact's meta version (if any) to a concrete version. For example, resolves "1.0-SNAPSHOT" to
"1.0-20090208.132618-23".
Params:
session – The repository session, must not be null.
request – The version request, must not be null.
Throws:
VersionResolutionException – If the metaversion could not be resolved.
See Also:
newResolutionRepositories(RepositorySystemSession, List<RemoteRepository>)
Returns:
The version result, never null./**
     * Resolves an artifact's meta version (if any) to a concrete version. For example, resolves "1.0-SNAPSHOT" to
     * "1.0-20090208.132618-23".
     * 
     * @param session The repository session, must not be {@code null}.
     * @param request The version request, must not be {@code null}.
     * @return The version result, never {@code null}.
     * @throws VersionResolutionException If the metaversion could not be resolved.
     * @see #newResolutionRepositories(RepositorySystemSession, List)
     */
    VersionResult resolveVersion( RepositorySystemSession session, VersionRequest request )
        throws VersionResolutionException;

    
Gets information about an artifact like its direct dependencies and potential relocations.
Params:
session – The repository session, must not be null.
request – The descriptor request, must not be null.
Throws:
ArtifactDescriptorException – If the artifact descriptor could not be read.
See Also:
RepositorySystemSession.getArtifactDescriptorPolicy()
newResolutionRepositories(RepositorySystemSession, List<RemoteRepository>)
Returns:
The descriptor result, never null./**
     * Gets information about an artifact like its direct dependencies and potential relocations.
     * 
     * @param session The repository session, must not be {@code null}.
     * @param request The descriptor request, must not be {@code null}.
     * @return The descriptor result, never {@code null}.
     * @throws ArtifactDescriptorException If the artifact descriptor could not be read.
     * @see RepositorySystemSession#getArtifactDescriptorPolicy()
     * @see #newResolutionRepositories(RepositorySystemSession, List)
     */
    ArtifactDescriptorResult readArtifactDescriptor( RepositorySystemSession session,
                                                     ArtifactDescriptorRequest request )
        throws ArtifactDescriptorException;

    
Collects the transitive dependencies of an artifact and builds a dependency graph. Note that this operation is only concerned about determining the coordinates of the transitive dependencies. To also resolve the actual artifact files, use resolveDependencies(RepositorySystemSession, DependencyRequest). 
Params:
session – The repository session, must not be null.
request – The collection request, must not be null.
Throws:
DependencyCollectionException – If the dependency tree could not be built.
See Also:
RepositorySystemSession.getDependencyTraverser()
RepositorySystemSession.getDependencyManager()
RepositorySystemSession.getDependencySelector()
RepositorySystemSession.getVersionFilter()
RepositorySystemSession.getDependencyGraphTransformer()
newResolutionRepositories(RepositorySystemSession, List<RemoteRepository>)
Returns:
The collection result, never null./**
     * Collects the transitive dependencies of an artifact and builds a dependency graph. Note that this operation is
     * only concerned about determining the coordinates of the transitive dependencies. To also resolve the actual
     * artifact files, use {@link #resolveDependencies(RepositorySystemSession, DependencyRequest)}.
     * 
     * @param session The repository session, must not be {@code null}.
     * @param request The collection request, must not be {@code null}.
     * @return The collection result, never {@code null}.
     * @throws DependencyCollectionException If the dependency tree could not be built.
     * @see RepositorySystemSession#getDependencyTraverser()
     * @see RepositorySystemSession#getDependencyManager()
     * @see RepositorySystemSession#getDependencySelector()
     * @see RepositorySystemSession#getVersionFilter()
     * @see RepositorySystemSession#getDependencyGraphTransformer()
     * @see #newResolutionRepositories(RepositorySystemSession, List)
     */
    CollectResult collectDependencies( RepositorySystemSession session, CollectRequest request )
        throws DependencyCollectionException;

    
Collects and resolves the transitive dependencies of an artifact. This operation is essentially a combination of collectDependencies(RepositorySystemSession, CollectRequest) and resolveArtifacts(RepositorySystemSession, Collection<? extends ArtifactRequest>). 
Params:
session – The repository session, must not be null.
request – The dependency request, must not be null.
Throws:
DependencyResolutionException – If the dependency tree could not be built or any dependency artifact could
            not be resolved.
See Also:
newResolutionRepositories(RepositorySystemSession, List<RemoteRepository>)
Returns:
The dependency result, never null./**
     * Collects and resolves the transitive dependencies of an artifact. This operation is essentially a combination of
     * {@link #collectDependencies(RepositorySystemSession, CollectRequest)} and
     * {@link #resolveArtifacts(RepositorySystemSession, Collection)}.
     * 
     * @param session The repository session, must not be {@code null}.
     * @param request The dependency request, must not be {@code null}.
     * @return The dependency result, never {@code null}.
     * @throws DependencyResolutionException If the dependency tree could not be built or any dependency artifact could
     *             not be resolved.
     * @see #newResolutionRepositories(RepositorySystemSession, List)
     */
    DependencyResult resolveDependencies( RepositorySystemSession session, DependencyRequest request )
        throws DependencyResolutionException;

    
Resolves the path for an artifact. The artifact will be downloaded to the local repository if necessary. An
artifact that is already resolved will be skipped and is not re-resolved. In general, callers must not assume any
relationship between an artifact's resolved filename and its coordinates. Note that this method assumes that any
relocations have already been processed.
Params:
session – The repository session, must not be null.
request – The resolution request, must not be null.
Throws:
ArtifactResolutionException – If the artifact could not be resolved.
See Also:
Artifact.getFile()
newResolutionRepositories(RepositorySystemSession, List<RemoteRepository>)
Returns:
The resolution result, never null./**
     * Resolves the path for an artifact. The artifact will be downloaded to the local repository if necessary. An
     * artifact that is already resolved will be skipped and is not re-resolved. In general, callers must not assume any
     * relationship between an artifact's resolved filename and its coordinates. Note that this method assumes that any
     * relocations have already been processed.
     * 
     * @param session The repository session, must not be {@code null}.
     * @param request The resolution request, must not be {@code null}.
     * @return The resolution result, never {@code null}.
     * @throws ArtifactResolutionException If the artifact could not be resolved.
     * @see Artifact#getFile()
     * @see #newResolutionRepositories(RepositorySystemSession, List)
     */
    ArtifactResult resolveArtifact( RepositorySystemSession session, ArtifactRequest request )
        throws ArtifactResolutionException;

    
Resolves the paths for a collection of artifacts. Artifacts will be downloaded to the local repository if
necessary. Artifacts that are already resolved will be skipped and are not re-resolved. In general, callers must
not assume any relationship between an artifact's filename and its coordinates. Note that this method assumes
that any relocations have already been processed.
Params:
session – The repository session, must not be null.
requests – The resolution requests, must not be null.
Throws:
ArtifactResolutionException – If any artifact could not be resolved.
See Also:
Artifact.getFile()
newResolutionRepositories(RepositorySystemSession, List<RemoteRepository>)
Returns:
The resolution results (in request order), never null./**
     * Resolves the paths for a collection of artifacts. Artifacts will be downloaded to the local repository if
     * necessary. Artifacts that are already resolved will be skipped and are not re-resolved. In general, callers must
     * not assume any relationship between an artifact's filename and its coordinates. Note that this method assumes
     * that any relocations have already been processed.
     * 
     * @param session The repository session, must not be {@code null}.
     * @param requests The resolution requests, must not be {@code null}.
     * @return The resolution results (in request order), never {@code null}.
     * @throws ArtifactResolutionException If any artifact could not be resolved.
     * @see Artifact#getFile()
     * @see #newResolutionRepositories(RepositorySystemSession, List)
     */
    List<ArtifactResult> resolveArtifacts( RepositorySystemSession session,
                                           Collection<? extends ArtifactRequest> requests )
        throws ArtifactResolutionException;

    
Resolves the paths for a collection of metadata. Metadata will be downloaded to the local repository if
necessary, e.g. because it hasn't been cached yet or the cache is deemed outdated.
Params:
session – The repository session, must not be null.
requests – The resolution requests, must not be null.
See Also:
Metadata.getFile()
newResolutionRepositories(RepositorySystemSession, List<RemoteRepository>)
Returns:
The resolution results (in request order), never null./**
     * Resolves the paths for a collection of metadata. Metadata will be downloaded to the local repository if
     * necessary, e.g. because it hasn't been cached yet or the cache is deemed outdated.
     * 
     * @param session The repository session, must not be {@code null}.
     * @param requests The resolution requests, must not be {@code null}.
     * @return The resolution results (in request order), never {@code null}.
     * @see Metadata#getFile()
     * @see #newResolutionRepositories(RepositorySystemSession, List)
     */
    List<MetadataResult> resolveMetadata( RepositorySystemSession session,
                                          Collection<? extends MetadataRequest> requests );

    
Installs a collection of artifacts and their accompanying metadata to the local repository.
Params:
session – The repository session, must not be null.
request – The installation request, must not be null.
Throws:
InstallationException – If any artifact/metadata from the request could not be installed.
Returns:
The installation result, never null./**
     * Installs a collection of artifacts and their accompanying metadata to the local repository.
     * 
     * @param session The repository session, must not be {@code null}.
     * @param request The installation request, must not be {@code null}.
     * @return The installation result, never {@code null}.
     * @throws InstallationException If any artifact/metadata from the request could not be installed.
     */
    InstallResult install( RepositorySystemSession session, InstallRequest request )
        throws InstallationException;

    
Uploads a collection of artifacts and their accompanying metadata to a remote repository.
Params:
session – The repository session, must not be null.
request – The deployment request, must not be null.
Throws:
DeploymentException – If any artifact/metadata from the request could not be deployed.
See Also:
newDeploymentRepository(RepositorySystemSession, RemoteRepository)
Returns:
The deployment result, never null./**
     * Uploads a collection of artifacts and their accompanying metadata to a remote repository.
     * 
     * @param session The repository session, must not be {@code null}.
     * @param request The deployment request, must not be {@code null}.
     * @return The deployment result, never {@code null}.
     * @throws DeploymentException If any artifact/metadata from the request could not be deployed.
     * @see #newDeploymentRepository(RepositorySystemSession, RemoteRepository)
     */
    DeployResult deploy( RepositorySystemSession session, DeployRequest request )
        throws DeploymentException;

    
Creates a new manager for the specified local repository. If the specified local repository has no type, the
default local repository type of the system will be used. Note: It is expected that this method
invocation is one of the last steps of setting up a new session, in particular any configuration properties
should have been set already.
Params:
session – The repository system session from which to configure the manager, must not be null.
localRepository – The local repository to create a manager for, must not be null.
Throws:
IllegalArgumentException – If the specified repository type is not recognized or no base directory is
            given.
Returns:
The local repository manager, never null./**
     * Creates a new manager for the specified local repository. If the specified local repository has no type, the
     * default local repository type of the system will be used. <em>Note:</em> It is expected that this method
     * invocation is one of the last steps of setting up a new session, in particular any configuration properties
     * should have been set already.
     * 
     * @param session The repository system session from which to configure the manager, must not be {@code null}.
     * @param localRepository The local repository to create a manager for, must not be {@code null}.
     * @return The local repository manager, never {@code null}.
     * @throws IllegalArgumentException If the specified repository type is not recognized or no base directory is
     *             given.
     */
    LocalRepositoryManager newLocalRepositoryManager( RepositorySystemSession session,
                                                      LocalRepository localRepository );

    
Creates a new synchronization context.
Params:
session – The repository session during which the context will be used, must not be null.
shared – A flag indicating whether access to the artifacts/metadata associated with the new context can be
           shared among concurrent readers or whether access needs to be exclusive to the calling thread.
Returns:
The synchronization context, never null./**
     * Creates a new synchronization context.
     * 
     * @param session The repository session during which the context will be used, must not be {@code null}.
     * @param shared A flag indicating whether access to the artifacts/metadata associated with the new context can be
     *            shared among concurrent readers or whether access needs to be exclusive to the calling thread.
     * @return The synchronization context, never {@code null}.
     */
    SyncContext newSyncContext( RepositorySystemSession session, boolean shared );

    
Forms remote repositories suitable for artifact resolution by applying the session's authentication selector and similar network configuration to the given repository prototypes. As noted for RepositorySystemSession.getAuthenticationSelector() etc. the remote repositories passed to e.g. resolveArtifact() are used as is and expected to already carry any required authentication or proxy configuration. This method can be used to apply the authentication/proxy configuration from a session to a bare repository definition to obtain the complete repository definition for use in the resolution request. 
Params:
session – The repository system session from which to configure the repositories, must not be null.
repositories – The repository prototypes from which to derive the resolution repositories, must not be null or contain null elements.
See Also:
newDeploymentRepository(RepositorySystemSession, RemoteRepository)
Returns:
The resolution repositories, never null. Note that there is generally no 1:1 relationship of the obtained repositories to the original inputs due to mirror selection potentially aggregating multiple repositories./**
     * Forms remote repositories suitable for artifact resolution by applying the session's authentication selector and
     * similar network configuration to the given repository prototypes. As noted for
     * {@link RepositorySystemSession#getAuthenticationSelector()} etc. the remote repositories passed to e.g.
     * {@link #resolveArtifact(RepositorySystemSession, ArtifactRequest) resolveArtifact()} are used as is and expected
     * to already carry any required authentication or proxy configuration. This method can be used to apply the
     * authentication/proxy configuration from a session to a bare repository definition to obtain the complete
     * repository definition for use in the resolution request.
     * 
     * @param session The repository system session from which to configure the repositories, must not be {@code null}.
     * @param repositories The repository prototypes from which to derive the resolution repositories, must not be
     *            {@code null} or contain {@code null} elements.
     * @return The resolution repositories, never {@code null}. Note that there is generally no 1:1 relationship of the
     *         obtained repositories to the original inputs due to mirror selection potentially aggregating multiple
     *         repositories.
     * @see #newDeploymentRepository(RepositorySystemSession, RemoteRepository)
     */
    List<RemoteRepository> newResolutionRepositories( RepositorySystemSession session,
                                                      List<RemoteRepository> repositories );

    
Forms a remote repository suitable for artifact deployment by applying the session's authentication selector and similar network configuration to the given repository prototype. As noted for RepositorySystemSession.getAuthenticationSelector() etc. the remote repository passed to deploy() is used as is and expected to already carry any required authentication or proxy configuration. This method can be used to apply the authentication/proxy configuration from a session to a bare repository definition to obtain the complete repository definition for use in the deploy request. 
Params:
session – The repository system session from which to configure the repository, must not be null.
repository – The repository prototype from which to derive the deployment repository, must not be null.
See Also:
newResolutionRepositories(RepositorySystemSession, List<RemoteRepository>)
Returns:
The deployment repository, never null./**
     * Forms a remote repository suitable for artifact deployment by applying the session's authentication selector and
     * similar network configuration to the given repository prototype. As noted for
     * {@link RepositorySystemSession#getAuthenticationSelector()} etc. the remote repository passed to
     * {@link #deploy(RepositorySystemSession, DeployRequest) deploy()} is used as is and expected to already carry any
     * required authentication or proxy configuration. This method can be used to apply the authentication/proxy
     * configuration from a session to a bare repository definition to obtain the complete repository definition for use
     * in the deploy request.
     * 
     * @param session The repository system session from which to configure the repository, must not be {@code null}.
     * @param repository The repository prototype from which to derive the deployment repository, must not be
     *            {@code null}.
     * @return The deployment repository, never {@code null}.
     * @see #newResolutionRepositories(RepositorySystemSession, List)
     */
    RemoteRepository newDeploymentRepository( RepositorySystemSession session, RemoteRepository repository );

}