1 package org.eclipse.aether.spi.connector.transport;
2
3 /*
4 * Licensed to the Apache Software Foundation (ASF) under one
5 * or more contributor license agreements. See the NOTICE file
6 * distributed with this work for additional information
7 * regarding copyright ownership. The ASF licenses this file
8 * to you under the Apache License, Version 2.0 (the
9 * "License"); you may not use this file except in compliance
10 * with the License. You may obtain a copy of the License at
11 *
12 * http://www.apache.org/licenses/LICENSE-2.0
13 *
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17 * KIND, either express or implied. See the License for the
18 * specific language governing permissions and limitations
19 * under the License.
20 */
21
22 import java.io.Closeable;
23
24 /**
25 * A transporter for a remote repository. A transporter is responsible for transferring resources between the remote
26 * repository and the local system. During its operation, the transporter must provide progress feedback via the
27 * {@link TransportListener} configured on the underlying task.
28 * <p>
29 * If applicable, a transporter should obey connect/request timeouts and other relevant settings from the
30 * {@link org.eclipse.aether.RepositorySystemSession#getConfigProperties() configuration properties} of the repository
31 * system session.
32 * <p>
33 * <strong>Note:</strong> Implementations must be thread-safe such that a given transporter instance can safely be used
34 * for concurrent requests.
35 */
36 public interface Transporter
37 extends Closeable
38 {
39
40 /**
41 * Classification for exceptions that denote connectivity or authentication issues and any other kind of error that
42 * is not mapped to another classification code.
43 *
44 * @see #classify(Throwable)
45 */
46 int ERROR_OTHER = 0;
47
48 /**
49 * Classification for exceptions that denote a requested resource does not exist in the remote repository. Note that
50 * cases where a remote repository is completely inaccessible should be classified as {@link #ERROR_OTHER}.
51 *
52 * @see #classify(Throwable)
53 */
54 int ERROR_NOT_FOUND = 1;
55
56 /**
57 * Classifies the type of exception that has been thrown from a previous request to the transporter. The exception
58 * types employed by a transporter are generally unknown to its caller. Where a caller needs to distinguish between
59 * certain error cases, it employs this method to detect which error case corresponds to the exception.
60 *
61 * @param error The exception to classify, must not be {@code null}.
62 * @return The classification of the error, either {@link #ERROR_NOT_FOUND} or {@link #ERROR_OTHER}.
63 */
64 int classify( Throwable error );
65
66 /**
67 * Checks the existence of a resource in the repository. If the remote repository can be contacted successfully but
68 * indicates the resource specified in the request does not exist, an exception is thrown such that invoking
69 * {@link #classify(Throwable)} with that exception yields {@link #ERROR_NOT_FOUND}.
70 *
71 * @param task The existence check to perform, must not be {@code null}.
72 * @throws Exception If the existence of the specified resource could not be confirmed.
73 */
74 void peek( PeekTask task )
75 throws Exception;
76
77 /**
78 * Downloads a resource from the repository. If the resource is downloaded to a file as given by
79 * {@link GetTask#getDataFile()} and the operation fails midway, the transporter should not delete the partial file
80 * but leave its management to the caller.
81 *
82 * @param task The download to perform, must not be {@code null}.
83 * @throws Exception If the transfer failed.
84 */
85 void get( GetTask task )
86 throws Exception;
87
88 /**
89 * Uploads a resource to the repository.
90 *
91 * @param task The upload to perform, must not be {@code null}.
92 * @throws Exception If the transfer failed.
93 */
94 void put( PutTask task )
95 throws Exception;
96
97 /**
98 * Closes this transporter and frees any network resources associated with it. Once closed, a transporter must not
99 * be used for further transfers, any attempt to do so would yield a {@link IllegalStateException} or similar.
100 * Closing an already closed transporter is harmless and has no effect.
101 */
102 void close();
103
104 }