001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *   http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied.  See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019package org.eclipse.aether.spi.connector;
020
021import java.io.Closeable;
022import java.util.Collection;
023
024/**
025 * A connector for a remote repository. The connector is responsible for downloading/uploading of artifacts and metadata
026 * from/to a remote repository.
027 * <p>
028 * If applicable, a connector should obey connect/request timeouts and other relevant settings from the
029 * {@link org.eclipse.aether.RepositorySystemSession#getConfigProperties() configuration properties} of the repository
030 * session it has been obtained for. However, a connector must not emit any events to the transfer listener configured
031 * for the session. Instead, transfer events must be emitted only to the listener (if any) specified for a given
032 * download/upload request.
033 * <p>
034 * <strong>Note:</strong> While a connector itself can use multiple threads internally to performs the transfers,
035 * clients must not call a connector concurrently, i.e. connectors are generally not thread-safe.
036 *
037 * @see org.eclipse.aether.spi.connector.transport.TransporterProvider
038 * @see org.eclipse.aether.spi.connector.layout.RepositoryLayoutProvider
039 * @see org.eclipse.aether.spi.connector.checksum.ChecksumPolicyProvider
040 */
041public interface RepositoryConnector extends Closeable {
042
043    /**
044     * Performs the specified downloads. If a download fails, the connector stores the underlying exception in the
045     * download object such that callers can inspect the result via {@link ArtifactDownload#getException()} and
046     * {@link MetadataDownload#getException()}, respectively. If reasonable, a connector should continue to process the
047     * remaining downloads after an error to retrieve as many items as possible. The connector may perform the transfers
048     * concurrently and in any order.
049     *
050     * @param artifactDownloads The artifact downloads to perform, may be {@code null} or empty.
051     * @param metadataDownloads The metadata downloads to perform, may be {@code null} or empty.
052     */
053    void get(
054            Collection<? extends ArtifactDownload> artifactDownloads,
055            Collection<? extends MetadataDownload> metadataDownloads);
056
057    /**
058     * Performs the specified uploads. If an upload fails, the connector stores the underlying exception in the upload
059     * object such that callers can inspect the result via {@link ArtifactUpload#getException()} and
060     * {@link MetadataUpload#getException()}, respectively. The connector may perform the transfers concurrently and in
061     * any order.
062     *
063     * @param artifactUploads The artifact uploads to perform, may be {@code null} or empty.
064     * @param metadataUploads The metadata uploads to perform, may be {@code null} or empty.
065     */
066    void put(
067            Collection<? extends ArtifactUpload> artifactUploads, Collection<? extends MetadataUpload> metadataUploads);
068
069    /**
070     * Closes this connector and frees any network resources associated with it. Once closed, a connector must not be
071     * used for further transfers, any attempt to do so would yield a {@link IllegalStateException} or similar. Closing
072     * an already closed connector is harmless and has no effect.
073     */
074    void close();
075}