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 }