001package org.eclipse.aether.spi.connector.transport;
002
003/*
004 * Licensed to the Apache Software Foundation (ASF) under one
005 * or more contributor license agreements.  See the NOTICE file
006 * distributed with this work for additional information
007 * regarding copyright ownership.  The ASF licenses this file
008 * to you under the Apache License, Version 2.0 (the
009 * "License"); you may not use this file except in compliance
010 * with the License.  You may obtain a copy of the License at
011 * 
012 *  http://www.apache.org/licenses/LICENSE-2.0
013 * 
014 * Unless required by applicable law or agreed to in writing,
015 * software distributed under the License is distributed on an
016 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017 * KIND, either express or implied.  See the License for the
018 * specific language governing permissions and limitations
019 * under the License.
020 */
021
022import java.io.Closeable;
023
024/**
025 * A transporter for a remote repository. A transporter is responsible for transferring resources between the remote
026 * repository and the local system. During its operation, the transporter must provide progress feedback via the
027 * {@link TransportListener} configured on the underlying task.
028 * <p>
029 * If applicable, a transporter should obey connect/request timeouts and other relevant settings from the
030 * {@link org.eclipse.aether.RepositorySystemSession#getConfigProperties() configuration properties} of the repository
031 * system session.
032 * <p>
033 * <strong>Note:</strong> Implementations must be thread-safe such that a given transporter instance can safely be used
034 * for concurrent requests.
035 */
036public interface Transporter
037    extends Closeable
038{
039
040    /**
041     * Classification for exceptions that denote connectivity or authentication issues and any other kind of error that
042     * is not mapped to another classification code.
043     * 
044     * @see #classify(Throwable)
045     */
046    int ERROR_OTHER = 0;
047
048    /**
049     * Classification for exceptions that denote a requested resource does not exist in the remote repository. Note that
050     * cases where a remote repository is completely inaccessible should be classified as {@link #ERROR_OTHER}.
051     * 
052     * @see #classify(Throwable)
053     */
054    int ERROR_NOT_FOUND = 1;
055
056    /**
057     * Classifies the type of exception that has been thrown from a previous request to the transporter. The exception
058     * types employed by a transporter are generally unknown to its caller. Where a caller needs to distinguish between
059     * certain error cases, it employs this method to detect which error case corresponds to the exception.
060     * 
061     * @param error The exception to classify, must not be {@code null}.
062     * @return The classification of the error, either {@link #ERROR_NOT_FOUND} or {@link #ERROR_OTHER}.
063     */
064    int classify( Throwable error );
065
066    /**
067     * Checks the existence of a resource in the repository. If the remote repository can be contacted successfully but
068     * indicates the resource specified in the request does not exist, an exception is thrown such that invoking
069     * {@link #classify(Throwable)} with that exception yields {@link #ERROR_NOT_FOUND}.
070     * 
071     * @param task The existence check to perform, must not be {@code null}.
072     * @throws Exception If the existence of the specified resource could not be confirmed.
073     */
074    void peek( PeekTask task )
075        throws Exception;
076
077    /**
078     * Downloads a resource from the repository. If the resource is downloaded to a file as given by
079     * {@link GetTask#getDataFile()} and the operation fails midway, the transporter should not delete the partial file
080     * but leave its management to the caller.
081     * 
082     * @param task The download to perform, must not be {@code null}.
083     * @throws Exception If the transfer failed.
084     */
085    void get( GetTask task )
086        throws Exception;
087
088    /**
089     * Uploads a resource to the repository.
090     * 
091     * @param task The upload to perform, must not be {@code null}.
092     * @throws Exception If the transfer failed.
093     */
094    void put( PutTask task )
095        throws Exception;
096
097    /**
098     * Closes this transporter and frees any network resources associated with it. Once closed, a transporter must not
099     * 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}