View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one
3    * or more contributor license agreements.  See the NOTICE file
4    * distributed with this work for additional information
5    * regarding copyright ownership.  The ASF licenses this file
6    * to you under the Apache License, Version 2.0 (the
7    * "License"); you may not use this file except in compliance
8    * with the License.  You may obtain a copy of the License at
9    *
10   *   http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing,
13   * software distributed under the License is distributed on an
14   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15   * KIND, either express or implied.  See the License for the
16   * specific language governing permissions and limitations
17   * under the License.
18   */
19  package org.eclipse.aether.spi.connector;
20  
21  import java.io.Closeable;
22  import java.util.Collection;
23  
24  /**
25   * A connector for a remote repository. The connector is responsible for downloading/uploading of artifacts and metadata
26   * from/to a remote repository.
27   * <p>
28   * If applicable, a connector should obey connect/request timeouts and other relevant settings from the
29   * {@link org.eclipse.aether.RepositorySystemSession#getConfigProperties() configuration properties} of the repository
30   * session it has been obtained for. However, a connector must not emit any events to the transfer listener configured
31   * for the session. Instead, transfer events must be emitted only to the listener (if any) specified for a given
32   * download/upload request.
33   * <p>
34   * <strong>Note:</strong> While a connector itself can use multiple threads internally to performs the transfers,
35   * clients must not call a connector concurrently, i.e. connectors are generally not thread-safe.
36   *
37   * @see org.eclipse.aether.spi.connector.transport.TransporterProvider
38   * @see org.eclipse.aether.spi.connector.layout.RepositoryLayoutProvider
39   * @see org.eclipse.aether.spi.connector.checksum.ChecksumPolicyProvider
40   */
41  public interface RepositoryConnector extends Closeable {
42  
43      /**
44       * Performs the specified downloads. If a download fails, the connector stores the underlying exception in the
45       * download object such that callers can inspect the result via {@link ArtifactDownload#getException()} and
46       * {@link MetadataDownload#getException()}, respectively. If reasonable, a connector should continue to process the
47       * remaining downloads after an error to retrieve as many items as possible. The connector may perform the transfers
48       * concurrently and in any order.
49       *
50       * @param artifactDownloads The artifact downloads to perform, may be {@code null} or empty.
51       * @param metadataDownloads The metadata downloads to perform, may be {@code null} or empty.
52       */
53      void get(
54              Collection<? extends ArtifactDownload> artifactDownloads,
55              Collection<? extends MetadataDownload> metadataDownloads);
56  
57      /**
58       * Performs the specified uploads. If an upload fails, the connector stores the underlying exception in the upload
59       * object such that callers can inspect the result via {@link ArtifactUpload#getException()} and
60       * {@link MetadataUpload#getException()}, respectively. The connector may perform the transfers concurrently and in
61       * any order.
62       *
63       * @param artifactUploads The artifact uploads to perform, may be {@code null} or empty.
64       * @param metadataUploads The metadata uploads to perform, may be {@code null} or empty.
65       */
66      void put(
67              Collection<? extends ArtifactUpload> artifactUploads, Collection<? extends MetadataUpload> metadataUploads);
68  
69      /**
70       * Closes this connector and frees any network resources associated with it. Once closed, a connector must not be
71       * used for further transfers, any attempt to do so would yield a {@link IllegalStateException} or similar. Closing
72       * an already closed connector is harmless and has no effect.
73       */
74      void close();
75  }