001package org.eclipse.aether.spi.connector;
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.io.Closeable;
023import java.util.Collection;
024
025/**
026 * A connector for a remote repository. The connector is responsible for downloading/uploading of artifacts and metadata
027 * from/to a remote repository.
028 * <p>
029 * If applicable, a connector should obey connect/request timeouts and other relevant settings from the
030 * {@link org.eclipse.aether.RepositorySystemSession#getConfigProperties() configuration properties} of the repository
031 * session it has been obtained for. However, a connector must not emit any events to the transfer listener configured
032 * for the session. Instead, transfer events must be emitted only to the listener (if any) specified for a given
033 * download/upload request.
034 * <p>
035 * <strong>Note:</strong> While a connector itself can use multiple threads internally to performs the transfers,
036 * clients must not call a connector concurrently, i.e. connectors are generally not thread-safe.
037 * 
038 * @see org.eclipse.aether.spi.connector.transport.TransporterProvider
039 * @see org.eclipse.aether.spi.connector.layout.RepositoryLayoutProvider
040 * @see org.eclipse.aether.spi.connector.checksum.ChecksumPolicyProvider
041 */
042public interface RepositoryConnector
043    extends Closeable
044{
045
046    /**
047     * Performs the specified downloads. If a download fails, the connector stores the underlying exception in the
048     * download object such that callers can inspect the result via {@link ArtifactDownload#getException()} and
049     * {@link MetadataDownload#getException()}, respectively. If reasonable, a connector should continue to process the
050     * remaining downloads after an error to retrieve as many items as possible. The connector may perform the transfers
051     * concurrently and in any order.
052     * 
053     * @param artifactDownloads The artifact downloads to perform, may be {@code null} or empty.
054     * @param metadataDownloads The metadata downloads to perform, may be {@code null} or empty.
055     */
056    void get( Collection<? extends ArtifactDownload> artifactDownloads,
057              Collection<? extends MetadataDownload> metadataDownloads );
058
059    /**
060     * Performs the specified uploads. If an upload fails, the connector stores the underlying exception in the upload
061     * object such that callers can inspect the result via {@link ArtifactUpload#getException()} and
062     * {@link MetadataUpload#getException()}, respectively. The connector may perform the transfers concurrently and in
063     * any order.
064     * 
065     * @param artifactUploads The artifact uploads to perform, may be {@code null} or empty.
066     * @param metadataUploads The metadata uploads to perform, may be {@code null} or empty.
067     */
068    void put( Collection<? extends ArtifactUpload> artifactUploads, Collection<? extends MetadataUpload> metadataUploads );
069
070    /**
071     * Closes this connector and frees any network resources associated with it. Once closed, a connector must not be
072     * used for further transfers, any attempt to do so would yield a {@link IllegalStateException} or similar. Closing
073     * an already closed connector is harmless and has no effect.
074     */
075    void close();
076
077}