package org.apache.maven.wagon;

/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */

import org.apache.maven.wagon.authentication.AuthenticationException;
import org.apache.maven.wagon.authentication.AuthenticationInfo;
import org.apache.maven.wagon.authorization.AuthorizationException;
import org.apache.maven.wagon.events.SessionListener;
import org.apache.maven.wagon.events.TransferListener;
import org.apache.maven.wagon.proxy.ProxyInfo;
import org.apache.maven.wagon.proxy.ProxyInfoProvider;
import org.apache.maven.wagon.repository.Repository;

import java.io.File;
import java.util.List;

/**
 * 
 */
public interface Wagon
{
    String ROLE = Wagon.class.getName();

    
default 60s approximately 1 minute
/**
     * default 60s approximately 1 minute
     */
    int DEFAULT_CONNECTION_TIMEOUT = 60000;

    
default 1800s approximately 30 minutes
Since:
2.2/**
     * default 1800s approximately 30 minutes
     *
     * @since 2.2
     */
    int DEFAULT_READ_TIMEOUT = 1800000;

    // ----------------------------------------------------------------------
    // File/File handling
    // ----------------------------------------------------------------------

    
Downloads specified resource from the repository to given file.
Params:
resourceName – 
destination – 
Throws:
TransferFailedException – 
ResourceDoesNotExistException – 
AuthorizationException – /**
     * Downloads specified resource from the repository to given file.
     *
     * @param resourceName
     * @param destination
     * @throws TransferFailedException
     * @throws ResourceDoesNotExistException
     * @throws AuthorizationException
     */
    void get( String resourceName, File destination )
        throws TransferFailedException, ResourceDoesNotExistException, AuthorizationException;

    
Downloads specified resource from the repository
if it was modified since specified date.
The date is measured in milliseconds, between the current time and midnight, January 1, 1970 UTC
and aligned to GMT timezone.
Params:
resourceName – 
destination – 
timestamp – 
Throws:
TransferFailedException – 
ResourceDoesNotExistException – 
AuthorizationException – 
Returns:
true if newer resource has been downloaded, false if resource
        in the repository is older or has the same age./**
     * Downloads specified resource from the repository
     * if it was modified since specified date.
     * The date is measured in milliseconds, between the current time and midnight, January 1, 1970 UTC
     * and aligned to GMT timezone.
     *
     * @param resourceName
     * @param destination
     * @param timestamp
     * @return <code>true</code> if newer resource has been downloaded, <code>false</code> if resource
     *         in the repository is older or has the same age.
     * @throws TransferFailedException
     * @throws ResourceDoesNotExistException
     * @throws AuthorizationException
     */
    boolean getIfNewer( String resourceName, File destination, long timestamp )
        throws TransferFailedException, ResourceDoesNotExistException, AuthorizationException;

    
Copy a file from local system to remote
Params:
source –      the local file
destination – the remote destination
Throws:
TransferFailedException – 
ResourceDoesNotExistException – 
AuthorizationException – /**
     * Copy a file from local system to remote
     *
     * @param source      the local file
     * @param destination the remote destination
     * @throws TransferFailedException
     * @throws ResourceDoesNotExistException
     * @throws AuthorizationException
     */
    void put( File source, String destination )
        throws TransferFailedException, ResourceDoesNotExistException, AuthorizationException;

    
Copy a directory from local system to remote
Params:
sourceDirectory –      the local directory
destinationDirectory – the remote destination
Throws:
TransferFailedException – 
ResourceDoesNotExistException – 
AuthorizationException – /**
     * Copy a directory from local system to remote
     *
     * @param sourceDirectory      the local directory
     * @param destinationDirectory the remote destination
     * @throws TransferFailedException
     * @throws ResourceDoesNotExistException
     * @throws AuthorizationException
     */
    void putDirectory( File sourceDirectory, String destinationDirectory )
        throws TransferFailedException, ResourceDoesNotExistException, AuthorizationException;

    
Check if a remote resource exists
Params:
resourceName – 
Throws:
TransferFailedException – if there's an error trying to access the remote side
AuthorizationException –  if not authorized to verify the existence of the resource
Returns:
whether the resource exists or not/**
     * Check if a remote resource exists
     *
     * @param resourceName
     * @return whether the resource exists or not
     * @throws TransferFailedException if there's an error trying to access the remote side
     * @throws AuthorizationException  if not authorized to verify the existence of the resource
     */
    boolean resourceExists( String resourceName )
        throws TransferFailedException, AuthorizationException;

    
 Returns a List of strings naming the files and directories in the directory denoted by this abstract pathname. 

 If this abstract pathname does not denote a directory, or does not exist, then this method throws ResourceDoesNotExistException. Otherwise a List of strings is returned, one for each file or directory in the directory. Names denoting the directory itself and the directory's parent directory are not included in the result. Each string is a file name rather than a complete path. 


There is no guarantee that the name strings in the resulting list will appear in any specific
order; they are not, in particular, guaranteed to appear in alphabetical order.

Params:
destinationDirectory – directory to list contents of
Throws:
TransferFailedException –       if there's an error trying to access the remote side
ResourceDoesNotExistException – if destinationDirectory does not exist or is not a directory
AuthorizationException –        if not authorized to list the contents of the directory
Returns:
A List of strings naming the files and directories in the directory denoted by this abstract pathname. The List will be empty if the directory is empty./**
     * <p/>
     * Returns a {@link List} of strings naming the files and directories in the directory denoted by
     * this abstract pathname.
     * </p>
     * <p/>
     * If this abstract pathname does not denote a directory, or does not exist, then this method throws
     * {@link ResourceDoesNotExistException}.
     * Otherwise a {@link List} of strings is returned, one for each file or directory in the directory.
     * Names denoting the directory itself and the directory's parent directory are not included in
     * the result. Each string is a file name rather than a complete path.
     * </p>
     * <p/>
     * There is no guarantee that the name strings in the resulting list will appear in any specific
     * order; they are not, in particular, guaranteed to appear in alphabetical order.
     * </p>
     *
     * @param destinationDirectory directory to list contents of
     * @return A {@link List} of strings naming the files and directories in the directory denoted by
     *         this abstract pathname. The {@link List} will be empty if the directory is empty.
     * @throws TransferFailedException       if there's an error trying to access the remote side
     * @throws ResourceDoesNotExistException if destinationDirectory does not exist or is not a directory
     * @throws AuthorizationException        if not authorized to list the contents of the directory
     */
    List<String> getFileList( String destinationDirectory )
        throws TransferFailedException, ResourceDoesNotExistException, AuthorizationException;

    
Flag indicating if this wagon supports directory copy operations.
Returns:
whether if this wagon supports directory operations/**
     * Flag indicating if this wagon supports directory copy operations.
     *
     * @return whether if this wagon supports directory operations
     */
    boolean supportsDirectoryCopy();

    Repository getRepository();

    // ----------------------------------------------------------------------
    // Connection/Disconnection
    // ----------------------------------------------------------------------

    
Initiate the connection to the repository.
Params:
source – the repository to connect to
Throws:
ConnectionException – if there is a problem connecting
AuthenticationException – 
                            if the credentials for connecting are not sufficient/**
     * Initiate the connection to the repository.
     *
     * @param source the repository to connect to
     * @throws ConnectionException if there is a problem connecting
     * @throws org.apache.maven.wagon.authentication.AuthenticationException
     *                             if the credentials for connecting are not sufficient
     */
    void connect( Repository source )
        throws ConnectionException, AuthenticationException;

    
Initiate the connection to the repository.
Params:
source – the repository to connect to
Throws:
ConnectionException – if there is a problem connecting
AuthenticationException – 
                            if the credentials for connecting are not sufficient/**
     * Initiate the connection to the repository.
     *
     * @param source the repository to connect to
     * @throws ConnectionException if there is a problem connecting
     * @throws org.apache.maven.wagon.authentication.AuthenticationException
     *                             if the credentials for connecting are not sufficient
     */
    void connect( Repository source, ProxyInfo proxyInfo )
        throws ConnectionException, AuthenticationException;

    
Initiate the connection to the repository.
Params:
source – the repository to connect to
proxyInfoProvider –  the provider to obtain a network proxy to use to connect to the remote repository
Throws:
ConnectionException – if there is a problem connecting
AuthenticationException – 
                            if the credentials for connecting are not sufficient/**
     * Initiate the connection to the repository.
     *
     * @param source the repository to connect to
     * @param proxyInfoProvider  the provider to obtain a network proxy to use to connect to the remote repository
     * @throws ConnectionException if there is a problem connecting
     * @throws org.apache.maven.wagon.authentication.AuthenticationException
     *                             if the credentials for connecting are not sufficient
     */
    void connect( Repository source, ProxyInfoProvider proxyInfoProvider )
        throws ConnectionException, AuthenticationException;

    
Initiate the connection to the repository.
Params:
source –             the repository to connect to
authenticationInfo – authentication credentials for connecting
Throws:
ConnectionException – if there is a problem connecting
AuthenticationException – 
                            if the credentials for connecting are not sufficient/**
     * Initiate the connection to the repository.
     *
     * @param source             the repository to connect to
     * @param authenticationInfo authentication credentials for connecting
     * @throws ConnectionException if there is a problem connecting
     * @throws org.apache.maven.wagon.authentication.AuthenticationException
     *                             if the credentials for connecting are not sufficient
     */
    void connect( Repository source, AuthenticationInfo authenticationInfo )
        throws ConnectionException, AuthenticationException;

    
Initiate the connection to the repository.
Params:
source –             the repository to connect to
authenticationInfo – authentication credentials for connecting
proxyInfo –          the network proxy to use to connect to the remote repository
Throws:
ConnectionException – if there is a problem connecting
AuthenticationException – 
                            if the credentials for connecting are not sufficient/**
     * Initiate the connection to the repository.
     *
     * @param source             the repository to connect to
     * @param authenticationInfo authentication credentials for connecting
     * @param proxyInfo          the network proxy to use to connect to the remote repository
     * @throws ConnectionException if there is a problem connecting
     * @throws org.apache.maven.wagon.authentication.AuthenticationException
     *                             if the credentials for connecting are not sufficient
     */
    void connect( Repository source, AuthenticationInfo authenticationInfo, ProxyInfo proxyInfo )
        throws ConnectionException, AuthenticationException;

    
Initiate the connection to the repository.
Params:
source –             the repository to connect to
authenticationInfo – authentication credentials for connecting
proxyInfoProvider –  the provider to obtain a network proxy to use to connect to the remote repository
Throws:
ConnectionException – if there is a problem connecting
AuthenticationException – 
                            if the credentials for connecting are not sufficient/**
     * Initiate the connection to the repository.
     *
     * @param source             the repository to connect to
     * @param authenticationInfo authentication credentials for connecting
     * @param proxyInfoProvider  the provider to obtain a network proxy to use to connect to the remote repository
     * @throws ConnectionException if there is a problem connecting
     * @throws org.apache.maven.wagon.authentication.AuthenticationException
     *                             if the credentials for connecting are not sufficient
     */
    void connect( Repository source, AuthenticationInfo authenticationInfo, ProxyInfoProvider proxyInfoProvider )
        throws ConnectionException, AuthenticationException;

    
Initiate the connection to the repository.
Throws:
ConnectionException – if there is a problem connecting
AuthenticationException – 
                            if ther credentials for connecting are not sufficient
@todo
delegate this to a truly internal connection method
Deprecated:
connect using the connect(Repository) or related methods - this is an internal method/**
     * Initiate the connection to the repository.
     *
     * @throws ConnectionException if there is a problem connecting
     * @throws org.apache.maven.wagon.authentication.AuthenticationException
     *                             if ther credentials for connecting are not sufficient
     * @todo delegate this to a truly internal connection method
     * @deprecated connect using the {@link #connect(org.apache.maven.wagon.repository.Repository)} or related methods
     *             - this is an internal method
     */
    void openConnection()
        throws ConnectionException, AuthenticationException;

    
Disconnect from the repository.
Throws:
ConnectionException – if there is a problem disconnecting/**
     * Disconnect from the repository.
     *
     * @throws ConnectionException if there is a problem disconnecting
     */
    void disconnect()
        throws ConnectionException;
    
    
Set the connection timeout limit in milliseconds
/**
     * Set the connection timeout limit in milliseconds
     */
    void setTimeout( int timeoutValue );
    
    
Get the connection timeout limit in milliseconds
/**
     * Get the connection timeout limit in milliseconds
     */
    int getTimeout();

    
Set the read timeout limit in milliseconds
Since:
2.2/**
     * Set the read timeout limit in milliseconds
     * @since 2.2
     */
    void setReadTimeout( int timeoutValue );

    
Get the read timeout limit in milliseconds
Since:
2.2/**
     * Get the read timeout limit in milliseconds
     * @since 2.2
     */
    int getReadTimeout();

    // ----------------------------------------------------------------------
    //  Session listener
    // ----------------------------------------------------------------------

    void addSessionListener( SessionListener listener );

    void removeSessionListener( SessionListener listener );

    boolean hasSessionListener( SessionListener listener );

    // ----------------------------------------------------------------------
    // Transfer listener
    // ----------------------------------------------------------------------

    void addTransferListener( TransferListener listener );

    void removeTransferListener( TransferListener listener );

    boolean hasTransferListener( TransferListener listener );

    boolean isInteractive();

    void setInteractive( boolean interactive );
}