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 }