Package io.jenkins.plugins.httpclient

Class RobustHTTPClient

java.lang.Object

io.jenkins.plugins.httpclient.RobustHTTPClient

All Implemented Interfaces:

Serializable

public final class RobustHTTPClient
extends Object
implements Serializable

Utility to make HTTP connections with protection against transient failures.

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	RobustHTTPClient.ConnectionCreator	How to initiate a connection.
static interface	RobustHTTPClient.ConnectionUser	What to do with a successful (2xx) connection.

Constructor Summary

Constructors

Constructor	Description
RobustHTTPClient()	Creates a client configured with reasonable defaults from system properties.

Method Summary

Modifier and Type	Method	Description
void	connect(String whatConcise, String whatVerbose, RobustHTTPClient.ConnectionCreator connectionCreator, RobustHTTPClient.ConnectionUser connectionUser, TaskListener listener)	Perform an HTTP network operation with appropriate timeouts and retries.
void	copyFromRemotely(FilePath f, URL url, TaskListener listener)	Like FilePath.copyFrom(URL) but using downloadFile(java.io.File, java.net.URL, hudson.model.TaskListener) and running remotely on the agent.
void	downloadFile(File f, URL url, TaskListener listener)	Download a file from a URL.
static String	sanitize(URL url)	Mask out query string or user info details in a URL.
void	setStopAfterAttemptNumber(int stopAfterAttemptNumber)	Number of upload/download attempts of nonfatal errors before giving up.
void	setTimeout(long timeout, TimeUnit unit)	Time to permit a single upload/download attempt to take.
void	setWaitMaximum(long waitMaximum, TimeUnit unit)	Maximum time between upload/download attempts.
void	setWaitMultiplier(long waitMultiplier, TimeUnit unit)	Initial time between first and second upload/download attempts.
void	uploadFile(File f, String contentType, URL url, TaskListener listener)	Upload a file to a URL with a specific content type.
void	uploadFile(File f, URL url, TaskListener listener)	Upload a file to a URL.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RobustHTTPClient

public RobustHTTPClient()

Creates a client configured with reasonable defaults from system properties.

This constructor should be run in the Jenkins controller. To make requests from an agent JVM, create a final field of this type in your MasterToSlaveCallable or similar; set it with a field initializer (run in the callable’s constructor on the controller), letting the agent deserialize the configuration.

Method Detail

setStopAfterAttemptNumber

public void setStopAfterAttemptNumber(int stopAfterAttemptNumber)

Number of upload/download attempts of nonfatal errors before giving up.

setWaitMultiplier

public void setWaitMultiplier(long waitMultiplier,
                              TimeUnit unit)

Initial time between first and second upload/download attempts. Subsequent ones increase exponentially. Note that this is not a randomized exponential backoff; and the base of the exponent is currently hard-coded to 2.

setWaitMaximum

public void setWaitMaximum(long waitMaximum,
                           TimeUnit unit)

Maximum time between upload/download attempts.

setTimeout

public void setTimeout(long timeout,
                       TimeUnit unit)

Time to permit a single upload/download attempt to take.

connect

public void connect(String whatConcise,
                    String whatVerbose,
                    @NonNull
                    RobustHTTPClient.ConnectionCreator connectionCreator,
                    @NonNull
                    RobustHTTPClient.ConnectionUser connectionUser,
                    @NonNull
                    TaskListener listener)
             throws IOException,
                    InterruptedException

Perform an HTTP network operation with appropriate timeouts and retries. 2xx status codes are considered successful. Low-level network errors (for example, DNS failures) and 5xx server responses are considered retryable, as are timeouts on individual attempts; other response codes (normally 3xx or 4xx) are treated as immediate failures.

Parameters:

whatConcise - a short description of the operation, like upload, used when retrying

whatVerbose - a longer description of the operation, like uploading … to …, used when retrying (see sanitize(java.net.URL))

connectionCreator - how to establish a connection prior to getting the server’s response

connectionUser - what to do, if anything, after a successful (2xx) server response

listener - a place to print messages

Throws:

IOException - if there is an unrecoverable error; AbortException will be used where appropriate

InterruptedException - if an operation, or a sleep between retries, is interrupted

sanitize

public static String sanitize(URL url)

Mask out query string or user info details in a URL. Useful in conjunction with VirtualFile#toExternalURL.

Parameters:

url - any URL

Returns:

the same, but with any URL.getQuery() and/or URL.getUserInfo() concealed

uploadFile

public void uploadFile(File f,
                       URL url,
                       TaskListener listener)
                throws IOException,
                       InterruptedException

Upload a file to a URL.

Throws:

IOException

InterruptedException

uploadFile

public void uploadFile(File f,
                       String contentType,
                       URL url,
                       TaskListener listener)
                throws IOException,
                       InterruptedException

Upload a file to a URL with a specific content type.

Parameters:

f - the file to upload

contentType - the content type for the specified file

Throws:

IOException

InterruptedException

downloadFile

public void downloadFile(File f,
                         URL url,
                         TaskListener listener)
                  throws IOException,
                         InterruptedException

Download a file from a URL.

Throws:

IOException

InterruptedException

copyFromRemotely

public void copyFromRemotely(FilePath f,
                             URL url,
                             TaskListener listener)
                      throws IOException,
                             InterruptedException

Like FilePath.copyFrom(URL) but using downloadFile(java.io.File, java.net.URL, hudson.model.TaskListener) and running remotely on the agent.

Throws:

IOException

InterruptedException