mercury-plexus/src/main/java/org/apache/maven/mercury/plexus/PlexusMercury.java

/**
 *  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.
 */
package org.apache.maven.mercury.plexus;

import java.io.File;
import java.io.InputStream;
import java.net.URL;
import java.util.Collection;
import java.util.List;
import java.util.Map;
import java.util.Set;

import org.apache.maven.mercury.artifact.Artifact;
import org.apache.maven.mercury.artifact.ArtifactExclusionList;
import org.apache.maven.mercury.artifact.ArtifactInclusionList;
import org.apache.maven.mercury.artifact.ArtifactMetadata;
import org.apache.maven.mercury.artifact.ArtifactQueryList;
import org.apache.maven.mercury.artifact.ArtifactScopeEnum;
import org.apache.maven.mercury.artifact.MetadataTreeNode;
import org.apache.maven.mercury.builder.api.DependencyProcessor;
import org.apache.maven.mercury.crypto.api.StreamObserverFactory;
import org.apache.maven.mercury.crypto.api.StreamVerifierException;
import org.apache.maven.mercury.crypto.api.StreamVerifierFactory;
import org.apache.maven.mercury.crypto.pgp.PgpStreamVerifierFactory;
import org.apache.maven.mercury.repository.api.Repository;
import org.apache.maven.mercury.repository.api.RepositoryException;
import org.apache.maven.mercury.repository.local.m2.LocalRepositoryM2;
import org.apache.maven.mercury.repository.remote.m2.RemoteRepositoryM2;

/**
 * @author Oleg Gusakov
 */
public interface PlexusMercury
{
    /**
     * lookup dependency processor in plexus and return the "default" implementation
     * 
     * @return the dependency processor
     * @throws RepositoryException
     */
    DependencyProcessor findDependencyProcessor()
        throws RepositoryException;

    /**
     * lookup dependency processor in plexus and return the requested implementation
     * 
     * @param hint the plexus hint to lookup by
     * @return the dependency processor
     * @throws RepositoryException
     */
    DependencyProcessor findDependencyProcessor( String hint )
        throws RepositoryException;

    /**
     * create PGP factory to configure into repository reader for signature verification
     * 
     * @param lenient
     * @param sufficient
     * @param pubRing - keyring with all acceptable public keys
     * @return pgp verifier factory to be sent to Repository
     * @throws PlexusMercuryException
     */
    PgpStreamVerifierFactory createPgpReaderFactory( boolean lenient, boolean sufficient, InputStream pubRing )
        throws StreamVerifierException;

    /**
     * create PGP factory to configure into repository writer for signature generation
     * 
     * @param lenient
     * @param sufficient
     * @param secRing
     * @param keyId
     * @param keyPass
     * @return pgp verifier factory to be sent to Repository
     * @throws PlexusMercuryException
     */
    PgpStreamVerifierFactory createPgpWriterFactory( boolean lenient, boolean sufficient, InputStream secRing,
                                                            String keyId, String keyPass )
        throws StreamVerifierException;

    /**
     * construct remote M2 repository and configure it with supplied attributes
     * 
     * @param id
     * @param serverUrl
     * @param serverUser
     * @param serverPass
     * @param proxyUrl
     * @param proxyUser
     * @param proxyPass
     * @param readerStreamObservers
     * @param readerStreamVerifiers
     * @param writerStreamObservers
     * @param writerStreamVerifiers
     * @return repository instance
     * @throws PlexusMercuryException
     */
    RemoteRepositoryM2 constructRemoteRepositoryM2( String id, URL serverUrl, String serverUser,
                                                           String serverPass, URL proxyUrl, String proxyUser,
                                                           String proxyPass,
                                                           Set<StreamObserverFactory> readerStreamObservers,
                                                           Set<StreamVerifierFactory> readerStreamVerifiers,
                                                           Set<StreamObserverFactory> writerStreamObservers,
                                                           Set<StreamVerifierFactory> writerStreamVerifiers )
        throws RepositoryException;

    /**
     * construct local M2 repository and configure it with supplied attributes
     * 
     * @param id
     * @param rootDir
     * @param readerStreamObservers
     * @param readerStreamVerifiers
     * @param writerStreamObservers
     * @param writerStreamVerifiers
     * @return repository instance
     * @throws PlexusMercuryException
     */
    LocalRepositoryM2 constructLocalRepositoryM2( String id, File rootDir,
                                                         Set<StreamObserverFactory> readerStreamObservers,
                                                         Set<StreamVerifierFactory> readerStreamVerifiers,
                                                         Set<StreamObserverFactory> writerStreamObservers,
                                                         Set<StreamVerifierFactory> writerStreamVerifiers )
        throws RepositoryException;

    /**
     * construct a list of repositories from strings. First string is local dir, all others - remote URLs
     * 
     * @param localDir
     * @param urls varargs list of urls for remote repos
     * @return repository list
     * @throws PlexusMercuryException
     */
    List<Repository> constructRepositories( String localDir, String... urls )
        throws RepositoryException;

    /**
     * write (deploy) given Artifact(s) to the repository
     * 
     * @param repo repository instance to search
     * @param artfifacts to write
     * @return
     * @throws PlexusMercuryException
     */
    void write( Repository repo, Artifact... artifacts )
        throws RepositoryException;

    void write( Repository repo, Collection<Artifact> artifacts )
        throws RepositoryException;

    /**
     * read given Artifact(s) from the repository
     * 
     * @param repo repository instance to search
     * @param artfifacts to read
     * @return
     * @throws PlexusMercuryException
     */
    List<Artifact> read( List<Repository> repo, List<? extends ArtifactMetadata> artifacts )
        throws RepositoryException;

    List<Artifact> read( List<Repository> repo, ArtifactMetadata... artifacts )
        throws RepositoryException;

    /**
     * resolve Artifact dependencies. The inclusions and exclusions accept version ranges as parameters
     * 
     * @param repo repository instance to search
     * @param scope scope enumeration member indication the scope to resolve for
     * @param artfifacts list of artifact metadatas to resolve
     * @param inclusions list of artifact metadatas to include - only these will be in the resolved classpath
     * @param exclusions list of artifact metadatas to exclude - is applied after the inclusion, if one is present
     * @return
     * @throws PlexusMercuryException
     */
    List<ArtifactMetadata> resolve( List<Repository> repos, ArtifactScopeEnum scope,
                                           ArtifactQueryList artifacts, ArtifactInclusionList inclusions,
                                           ArtifactExclusionList exclusions )
        throws RepositoryException;

    List<ArtifactMetadata> resolve( List<Repository> repos, ArtifactScopeEnum scope,
                                           ArtifactQueryList artifacts, ArtifactInclusionList inclusions,
                                           ArtifactExclusionList exclusions, Map<String, ?> config )
        throws RepositoryException;

    MetadataTreeNode resolveAsTree( List<Repository> repos, ArtifactScopeEnum scope,
                                           ArtifactQueryList artifacts, ArtifactInclusionList inclusions,
                                           ArtifactExclusionList exclusions )
        throws RepositoryException;

    MetadataTreeNode resolveAsTree( List<Repository> repos, ArtifactScopeEnum scope,
                                           ArtifactQueryList artifacts, ArtifactInclusionList inclusions,
                                           ArtifactExclusionList exclusions, Map<String, ?> config )
        throws RepositoryException;

    List<ArtifactMetadata> resolve( List<Repository> repos, ArtifactScopeEnum scope, ArtifactMetadata metadata )
        throws RepositoryException;

    /**
     * get all available versions of for the artifact query.
     * 
     * @param repo repository instance to search
     * @param query metadata query to search by
     * @return list of found version metadatas
     * @throws PlexusMercuryException
     */
    List<ArtifactMetadata> readVersions( List<Repository> repos, ArtifactMetadata query )
        throws RepositoryException;
}