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