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 public interface Wagon
35 {
36 String ROLE = Wagon.class.getName();
37
38 /**
39 * default 60s approximately 1 minute
40 */
41 public static final int DEFAULT_CONNECTION_TIMEOUT = 60000;
42
43 /**
44 * default 1800s approximately 30 minutes
45 *
46 * @since 2.2
47 */
48 public static final int DEFAULT_READ_TIMEOUT = 1800000;
49
50 // ----------------------------------------------------------------------
51 // File/File handling
52 // ----------------------------------------------------------------------
53
54 /**
55 * Downloads specified resource from the repository to given file.
56 *
57 * @param resourceName
58 * @param destination
59 * @throws TransferFailedException
60 * @throws ResourceDoesNotExistException
61 * @throws AuthorizationException
62 */
63 void get( String resourceName, File destination )
64 throws TransferFailedException, ResourceDoesNotExistException, AuthorizationException;
65
66 /**
67 * Downloads specified resource from the repository
68 * if it was modified since specified date.
69 * The date is measured in milliseconds, between the current time and midnight, January 1, 1970 UTC
70 * and aligned to GMT timezone.
71 *
72 * @param resourceName
73 * @param destination
74 * @param timestamp
75 * @return <code>true</code> if newer resource has been downloaded, <code>false</code> if resource
76 * in the repository is older or has the same age.
77 * @throws TransferFailedException
78 * @throws ResourceDoesNotExistException
79 * @throws AuthorizationException
80 */
81 boolean getIfNewer( String resourceName, File destination, long timestamp )
82 throws TransferFailedException, ResourceDoesNotExistException, AuthorizationException;
83
84 /**
85 * Copy a file from local system to remote
86 *
87 * @param source the local file
88 * @param destination the remote destination
89 * @throws TransferFailedException
90 * @throws ResourceDoesNotExistException
91 * @throws AuthorizationException
92 */
93 void put( File source, String destination )
94 throws TransferFailedException, ResourceDoesNotExistException, AuthorizationException;
95
96 /**
97 * Copy a directory from local system to remote
98 *
99 * @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 }