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.transport;
20
21 import java.io.Closeable;
22
23 /**
24 * A transporter for a remote repository. A transporter is responsible for transferring resources between the remote
25 * repository and the local system. During its operation, the transporter must provide progress feedback via the
26 * {@link TransportListener} configured on the underlying task.
27 * <p>
28 * If applicable, a transporter should obey connect/request timeouts and other relevant settings from the
29 * {@link org.eclipse.aether.RepositorySystemSession#getConfigProperties() configuration properties} of the repository
30 * system session.
31 * <p>
32 * <strong>Note:</strong> Implementations must be thread-safe such that a given transporter instance can safely be used
33 * for concurrent requests.
34 */
35 public interface Transporter extends Closeable {
36
37 /**
38 * Classification for exceptions that denote connectivity or authentication issues and any other kind of error that
39 * is not mapped to another classification code.
40 *
41 * @see #classify(Throwable)
42 */
43 int ERROR_OTHER = 0;
44
45 /**
46 * Classification for exceptions that denote a requested resource does not exist in the remote repository. Note that
47 * cases where a remote repository is completely inaccessible should be classified as {@link #ERROR_OTHER}.
48 *
49 * @see #classify(Throwable)
50 */
51 int ERROR_NOT_FOUND = 1;
52
53 /**
54 * Classifies the type of exception that has been thrown from a previous request to the transporter. The exception
55 * types employed by a transporter are generally unknown to its caller. Where a caller needs to distinguish between
56 * certain error cases, it employs this method to detect which error case corresponds to the exception.
57 *
58 * @param error The exception to classify, must not be {@code null}.
59 * @return The classification of the error, either {@link #ERROR_NOT_FOUND} or {@link #ERROR_OTHER}.
60 */
61 int classify(Throwable error);
62
63 /**
64 * Checks the existence of a resource in the repository. If the remote repository can be contacted successfully but
65 * indicates the resource specified in the request does not exist, an exception is thrown such that invoking
66 * {@link #classify(Throwable)} with that exception yields {@link #ERROR_NOT_FOUND}.
67 *
68 * @param task The existence check to perform, must not be {@code null}.
69 * @throws Exception If the existence of the specified resource could not be confirmed.
70 */
71 void peek(PeekTask task) throws Exception;
72
73 /**
74 * Downloads a resource from the repository. If the resource is downloaded to a file as given by
75 * {@link GetTask#getDataFile()} and the operation fails midway, the transporter should not delete the partial file
76 * but leave its management to the caller.
77 *
78 * @param task The download to perform, must not be {@code null}.
79 * @throws Exception If the transfer failed.
80 */
81 void get(GetTask task) throws Exception;
82
83 /**
84 * Uploads a resource to the repository.
85 *
86 * @param task The upload to perform, must not be {@code null}.
87 * @throws Exception If the transfer failed.
88 */
89 void put(PutTask task) throws Exception;
90
91 /**
92 * Closes this transporter and frees any network resources associated with it. Once closed, a transporter must not
93 * be used for further transfers, any attempt to do so would yield a {@link IllegalStateException} or similar.
94 * Closing an already closed transporter is harmless and has no effect.
95 */
96 void close();
97 }