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.transport;
020
021import java.io.Closeable;
022
023/**
024 * A transporter for a remote repository. A transporter is responsible for transferring resources between the remote
025 * repository and the local system. During its operation, the transporter must provide progress feedback via the
026 * {@link TransportListener} configured on the underlying task.
027 * <p>
028 * If applicable, a transporter should obey connect/request timeouts and other relevant settings from the
029 * {@link org.eclipse.aether.RepositorySystemSession#getConfigProperties() configuration properties} of the repository
030 * system session.
031 * <p>
032 * <strong>Note:</strong> Implementations must be thread-safe such that a given transporter instance can safely be used
033 * for concurrent requests.
034 */
035public interface Transporter extends Closeable {
036
037    /**
038     * Classification for exceptions that denote connectivity or authentication issues and any other kind of error that
039     * is not mapped to another classification code.
040     *
041     * @see #classify(Throwable)
042     */
043    int ERROR_OTHER = 0;
044
045    /**
046     * Classification for exceptions that denote a requested resource does not exist in the remote repository. Note that
047     * cases where a remote repository is completely inaccessible should be classified as {@link #ERROR_OTHER}.
048     *
049     * @see #classify(Throwable)
050     */
051    int ERROR_NOT_FOUND = 1;
052
053    /**
054     * Classifies the type of exception that has been thrown from a previous request to the transporter. The exception
055     * types employed by a transporter are generally unknown to its caller. Where a caller needs to distinguish between
056     * certain error cases, it employs this method to detect which error case corresponds to the exception.
057     *
058     * @param error The exception to classify, must not be {@code null}.
059     * @return The classification of the error, either {@link #ERROR_NOT_FOUND} or {@link #ERROR_OTHER}.
060     */
061    int classify(Throwable error);
062
063    /**
064     * Checks the existence of a resource in the repository. If the remote repository can be contacted successfully but
065     * indicates the resource specified in the request does not exist, an exception is thrown such that invoking
066     * {@link #classify(Throwable)} with that exception yields {@link #ERROR_NOT_FOUND}.
067     *
068     * @param task The existence check to perform, must not be {@code null}.
069     * @throws Exception If the existence of the specified resource could not be confirmed.
070     */
071    void peek(PeekTask task) throws Exception;
072
073    /**
074     * Downloads a resource from the repository. If the resource is downloaded to a file as given by
075     * {@link GetTask#getDataFile()} and the operation fails midway, the transporter should not delete the partial file
076     * but leave its management to the caller.
077     *
078     * @param task The download to perform, must not be {@code null}.
079     * @throws Exception If the transfer failed.
080     */
081    void get(GetTask task) throws Exception;
082
083    /**
084     * Uploads a resource to the repository.
085     *
086     * @param task The upload to perform, must not be {@code null}.
087     * @throws Exception If the transfer failed.
088     */
089    void put(PutTask task) throws Exception;
090
091    /**
092     * Closes this transporter and frees any network resources associated with it. Once closed, a transporter must not
093     * be used for further transfers, any attempt to do so would yield a {@link IllegalStateException} or similar.
094     * Closing an already closed transporter is harmless and has no effect.
095     */
096    void close();
097}