001package org.apache.maven.wagon;
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 org.apache.maven.wagon.authentication.AuthenticationException;
023import org.apache.maven.wagon.authentication.AuthenticationInfo;
024import org.apache.maven.wagon.authorization.AuthorizationException;
025import org.apache.maven.wagon.events.SessionListener;
026import org.apache.maven.wagon.events.TransferListener;
027import org.apache.maven.wagon.proxy.ProxyInfo;
028import org.apache.maven.wagon.proxy.ProxyInfoProvider;
029import org.apache.maven.wagon.repository.Repository;
030
031import java.io.File;
032import java.util.List;
033
034public interface Wagon
035{
036    String ROLE = Wagon.class.getName();
037
038    /**
039     * default 60s approximately 1 minute
040     */
041    public static final int DEFAULT_CONNECTION_TIMEOUT = 60000;
042
043    /**
044     * default 1800s approximately 30 minutes
045     *
046     * @since 2.2
047     */
048    public static final int DEFAULT_READ_TIMEOUT = 1800000;
049
050    // ----------------------------------------------------------------------
051    // File/File handling
052    // ----------------------------------------------------------------------
053
054    /**
055     * Downloads specified resource from the repository to given file.
056     *
057     * @param resourceName
058     * @param destination
059     * @throws TransferFailedException
060     * @throws ResourceDoesNotExistException
061     * @throws AuthorizationException
062     */
063    void get( String resourceName, File destination )
064        throws TransferFailedException, ResourceDoesNotExistException, AuthorizationException;
065
066    /**
067     * Downloads specified resource from the repository
068     * if it was modified since specified date.
069     * The date is measured in milliseconds, between the current time and midnight, January 1, 1970 UTC
070     * and aligned to GMT timezone.
071     *
072     * @param resourceName
073     * @param destination
074     * @param timestamp
075     * @return <code>true</code> if newer resource has been downloaded, <code>false</code> if resource
076     *         in the repository is older or has the same age.
077     * @throws TransferFailedException
078     * @throws ResourceDoesNotExistException
079     * @throws AuthorizationException
080     */
081    boolean getIfNewer( String resourceName, File destination, long timestamp )
082        throws TransferFailedException, ResourceDoesNotExistException, AuthorizationException;
083
084    /**
085     * Copy a file from local system to remote
086     *
087     * @param source      the local file
088     * @param destination the remote destination
089     * @throws TransferFailedException
090     * @throws ResourceDoesNotExistException
091     * @throws AuthorizationException
092     */
093    void put( File source, String destination )
094        throws TransferFailedException, ResourceDoesNotExistException, AuthorizationException;
095
096    /**
097     * Copy a directory from local system to remote
098     *
099     * @param sourceDirectory      the local directory
100     * @param destinationDirectory the remote destination
101     * @throws TransferFailedException
102     * @throws ResourceDoesNotExistException
103     * @throws AuthorizationException
104     */
105    void putDirectory( File sourceDirectory, String destinationDirectory )
106        throws TransferFailedException, ResourceDoesNotExistException, AuthorizationException;
107
108    /**
109     * Check if a remote resource exists
110     *
111     * @param resourceName
112     * @return whether the resource exists or not
113     * @throws TransferFailedException if there's an error trying to access the remote side
114     * @throws AuthorizationException  if not authorized to verify the existence of the resource
115     */
116    boolean resourceExists( String resourceName )
117        throws TransferFailedException, AuthorizationException;
118
119    /**
120     * <p/>
121     * Returns a {@link List} of strings naming the files and directories in the directory denoted by
122     * this abstract pathname.
123     * </p>
124     * <p/>
125     * If this abstract pathname does not denote a directory, or does not exist, then this method throws
126     * {@link ResourceDoesNotExistException}.
127     * Otherwise a {@link List} of strings is returned, one for each file or directory in the directory.
128     * Names denoting the directory itself and the directory's parent directory are not included in
129     * the result. Each string is a file name rather than a complete path.
130     * </p>
131     * <p/>
132     * There is no guarantee that the name strings in the resulting list will appear in any specific
133     * order; they are not, in particular, guaranteed to appear in alphabetical order.
134     * </p>
135     *
136     * @param destinationDirectory directory to list contents of
137     * @return A {@link List} of strings naming the files and directories in the directory denoted by
138     *         this abstract pathname. The {@link List} will be empty if the directory is empty.
139     * @throws TransferFailedException       if there's an error trying to access the remote side
140     * @throws ResourceDoesNotExistException if destinationDirectory does not exist or is not a directory
141     * @throws AuthorizationException        if not authorized to list the contents of the directory
142     */
143    List<String> getFileList( String destinationDirectory )
144        throws TransferFailedException, ResourceDoesNotExistException, AuthorizationException;
145
146    /**
147     * Flag indicating if this wagon supports directory copy operations.
148     *
149     * @return whether if this wagon supports directory operations
150     */
151    boolean supportsDirectoryCopy();
152
153    Repository getRepository();
154
155    // ----------------------------------------------------------------------
156    // Connection/Disconnection
157    // ----------------------------------------------------------------------
158
159    /**
160     * Initiate the connection to the repository.
161     *
162     * @param source the repository to connect to
163     * @throws ConnectionException if there is a problem connecting
164     * @throws org.apache.maven.wagon.authentication.AuthenticationException
165     *                             if the credentials for connecting are not sufficient
166     */
167    void connect( Repository source )
168        throws ConnectionException, AuthenticationException;
169
170    /**
171     * Initiate the connection to the repository.
172     *
173     * @param source the repository to connect to
174     * @throws ConnectionException if there is a problem connecting
175     * @throws org.apache.maven.wagon.authentication.AuthenticationException
176     *                             if the credentials for connecting are not sufficient
177     */
178    void connect( Repository source, ProxyInfo proxyInfo )
179        throws ConnectionException, AuthenticationException;
180
181    /**
182     * Initiate the connection to the repository.
183     *
184     * @param source the repository to connect to
185     * @param proxyInfoProvider  the provider to obtain a network proxy to use to connect to the remote repository
186     * @throws ConnectionException if there is a problem connecting
187     * @throws org.apache.maven.wagon.authentication.AuthenticationException
188     *                             if the credentials for connecting are not sufficient
189     */
190    void connect( Repository source, ProxyInfoProvider proxyInfoProvider )
191        throws ConnectionException, AuthenticationException;
192
193    /**
194     * Initiate the connection to the repository.
195     *
196     * @param source             the repository to connect to
197     * @param authenticationInfo authentication credentials for connecting
198     * @throws ConnectionException if there is a problem connecting
199     * @throws org.apache.maven.wagon.authentication.AuthenticationException
200     *                             if the credentials for connecting are not sufficient
201     */
202    void connect( Repository source, AuthenticationInfo authenticationInfo )
203        throws ConnectionException, AuthenticationException;
204
205    /**
206     * Initiate the connection to the repository.
207     *
208     * @param source             the repository to connect to
209     * @param authenticationInfo authentication credentials for connecting
210     * @param proxyInfo          the network proxy to use to connect to the remote repository
211     * @throws ConnectionException if there is a problem connecting
212     * @throws org.apache.maven.wagon.authentication.AuthenticationException
213     *                             if the credentials for connecting are not sufficient
214     */
215    void connect( Repository source, AuthenticationInfo authenticationInfo, ProxyInfo proxyInfo )
216        throws ConnectionException, AuthenticationException;
217
218    /**
219     * Initiate the connection to the repository.
220     *
221     * @param source             the repository to connect to
222     * @param authenticationInfo authentication credentials for connecting
223     * @param proxyInfoProvider  the provider to obtain a network proxy to use to connect to the remote repository
224     * @throws ConnectionException if there is a problem connecting
225     * @throws org.apache.maven.wagon.authentication.AuthenticationException
226     *                             if the credentials for connecting are not sufficient
227     */
228    void connect( Repository source, AuthenticationInfo authenticationInfo, ProxyInfoProvider proxyInfoProvider )
229        throws ConnectionException, AuthenticationException;
230
231    /**
232     * Initiate the connection to the repository.
233     *
234     * @throws ConnectionException if there is a problem connecting
235     * @throws org.apache.maven.wagon.authentication.AuthenticationException
236     *                             if ther credentials for connecting are not sufficient
237     * @todo delegate this to a truly internal connection method
238     * @deprecated connect using the {@link #connect(org.apache.maven.wagon.repository.Repository)} or related methods
239     *             - this is an internal method
240     */
241    void openConnection()
242        throws ConnectionException, AuthenticationException;
243
244    /**
245     * Disconnect from the repository.
246     *
247     * @throws ConnectionException if there is a problem disconnecting
248     */
249    void disconnect()
250        throws ConnectionException;
251    
252    /**
253     * Set the connection timeout limit in milliseconds
254     */
255    void setTimeout( int timeoutValue );
256    
257    /**
258     * Get the connection timeout limit in milliseconds
259     */
260    int getTimeout();
261
262    /**
263     * Set the read timeout limit in milliseconds
264     * @since 2.2
265     */
266    void setReadTimeout( int timeoutValue );
267
268    /**
269     * Get the read timeout limit in milliseconds
270     * @since 2.2
271     */
272    int getReadTimeout();
273
274    // ----------------------------------------------------------------------
275    //  Session listener
276    // ----------------------------------------------------------------------
277
278    void addSessionListener( SessionListener listener );
279
280    void removeSessionListener( SessionListener listener );
281
282    boolean hasSessionListener( SessionListener listener );
283
284    // ----------------------------------------------------------------------
285    // Transfer listener
286    // ----------------------------------------------------------------------
287
288    void addTransferListener( TransferListener listener );
289
290    void removeTransferListener( TransferListener listener );
291
292    boolean hasTransferListener( TransferListener listener );
293
294    boolean isInteractive();
295
296    void setInteractive( boolean interactive );
297}