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
     */
    int DEFAULT_CONNECTION_TIMEOUT = 60000;

    /**
     * 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.
     *
     * @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.
     *
     * @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
     *
     * @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
     *
     * @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
     *
     * @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;

    /**
     * <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.
     *
     * @return whether if this wagon supports directory operations
     */
    boolean supportsDirectoryCopy();

    Repository getRepository();

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

    /**
     * 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.
     *
     * @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.
     *
     * @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.
     *
     * @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.
     *
     * @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.
     *
     * @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
     * @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
     */
    void disconnect()
        throws ConnectionException;
    
    /**
     * Set the connection timeout limit in milliseconds
     */
    void setTimeout( int timeoutValue );
    
    /**
     * Get the connection timeout limit in milliseconds
     */
    int getTimeout();

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

    /**
     * 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 );
}