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 }