View Javadoc
1   package org.apache.maven.wagon;
2   
3   /*
4    * Licensed to the Apache Software Foundation (ASF) under one
5    * or more contributor license agreements.  See the NOTICE file
6    * distributed with this work for additional information
7    * regarding copyright ownership.  The ASF licenses this file
8    * to you under the Apache License, Version 2.0 (the
9    * "License"); you may not use this file except in compliance
10   * with the License.  You may obtain a copy of the License at
11   *
12   *   http://www.apache.org/licenses/LICENSE-2.0
13   *
14   * Unless required by applicable law or agreed to in writing,
15   * software distributed under the License is distributed on an
16   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17   * KIND, either express or implied.  See the License for the
18   * specific language governing permissions and limitations
19   * under the License.
20   */
21  
22  import org.apache.maven.wagon.authentication.AuthenticationException;
23  import org.apache.maven.wagon.authentication.AuthenticationInfo;
24  import org.apache.maven.wagon.authorization.AuthorizationException;
25  import org.apache.maven.wagon.events.SessionListener;
26  import org.apache.maven.wagon.events.TransferListener;
27  import org.apache.maven.wagon.proxy.ProxyInfo;
28  import org.apache.maven.wagon.proxy.ProxyInfoProvider;
29  import org.apache.maven.wagon.repository.Repository;
30  
31  import java.io.File;
32  import java.util.List;
33  
34  /**
35   * 
36   */
37  public interface Wagon
38  {
39      String ROLE = Wagon.class.getName();
40  
41      /**
42       * default 60s approximately 1 minute
43       */
44      int DEFAULT_CONNECTION_TIMEOUT = 60000;
45  
46      /**
47       * default 1800s approximately 30 minutes
48       *
49       * @since 2.2
50       */
51      int DEFAULT_READ_TIMEOUT = 1800000;
52  
53      // ----------------------------------------------------------------------
54      // File/File handling
55      // ----------------------------------------------------------------------
56  
57      /**
58       * Downloads specified resource from the repository to given file.
59       *
60       * @param resourceName
61       * @param destination
62       * @throws TransferFailedException
63       * @throws ResourceDoesNotExistException
64       * @throws AuthorizationException
65       */
66      void get( String resourceName, File destination )
67          throws TransferFailedException, ResourceDoesNotExistException, AuthorizationException;
68  
69      /**
70       * Downloads specified resource from the repository
71       * if it was modified since specified date.
72       * The date is measured in milliseconds, between the current time and midnight, January 1, 1970 UTC
73       * and aligned to GMT timezone.
74       *
75       * @param resourceName
76       * @param destination
77       * @param timestamp
78       * @return <code>true</code> if newer resource has been downloaded, <code>false</code> if resource
79       *         in the repository is older or has the same age.
80       * @throws TransferFailedException
81       * @throws ResourceDoesNotExistException
82       * @throws AuthorizationException
83       */
84      boolean getIfNewer( String resourceName, File destination, long timestamp )
85          throws TransferFailedException, ResourceDoesNotExistException, AuthorizationException;
86  
87      /**
88       * Copy a file from local system to remote
89       *
90       * @param source      the local file
91       * @param destination the remote destination
92       * @throws TransferFailedException
93       * @throws ResourceDoesNotExistException
94       * @throws AuthorizationException
95       */
96      void put( File source, String destination )
97          throws TransferFailedException, ResourceDoesNotExistException, AuthorizationException;
98  
99      /**
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 }