com.cloudant.http

Class HttpConnection

java.lang.Object

com.cloudant.http.HttpConnection

public class HttpConnection
extends java.lang.Object

A wrapper for HttpURLConnections.

Provides some convenience methods for making requests and sending/receiving data as streams, strings, or byte arrays.

Typical usage:

 HttpConnection hc = new HttpConnection("POST", "application/json", new URL("http://somewhere"));
 hc.requestProperties.put("x-some-header", "some-value");
 hc.setRequestBody("{\"hello\": \"world\"});
 String result = hc.execute().responseAsString();
 // get the underlying HttpURLConnection if you need to do something a bit more advanced:
 int response = hc.getConnection().getResponseCode();
 hc.disconnect();
 

Important: this class is not thread-safe and HttpConnections should not be shared across threads.

See Also:

HttpURLConnection

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	HttpConnection.InputStreamGenerator

Field Summary

Fields

Modifier and Type	Field and Description
java.util.List<HttpConnectionRequestInterceptor>	requestInterceptors
java.util.HashMap<java.lang.String,java.lang.String>	requestProperties
java.util.List<HttpConnectionResponseInterceptor>	responseInterceptors
java.net.URL	url

Constructor Summary

Constructors

Constructor and Description
HttpConnection(java.lang.String requestMethod, java.net.URL url, java.lang.String contentType)

Method Summary

Modifier and Type	Method and Description
void	disconnect() Disconnect the underlying HttpURLConnection.
HttpConnection	execute() Execute request without returning data from server.
java.net.HttpURLConnection	getConnection() Get the underlying HttpURLConnection object, allowing clients to set/get properties not exposed here.
byte[]	responseAsBytes() Return response body data from server as a byte array.
java.io.InputStream	responseAsInputStream() Return response body data from server as an InputStream.
java.lang.String	responseAsString() Return response body data from server as a String.
HttpConnection	setNumberOfRetries(int numberOfRetries) Sets the number of times this request can be retried.
HttpConnection	setRequestBody(byte[] input) Set the byte array of request body data to be sent to the server.
HttpConnection	setRequestBody(HttpConnection.InputStreamGenerator input) Set the InputStream of request body data to be sent to the server.
HttpConnection	setRequestBody(HttpConnection.InputStreamGenerator input, long inputLength) Set the InputStream of request body data, of known length, to be sent to the server.
HttpConnection	setRequestBody(java.lang.String input) Set the String of request body data to be sent to the server.

Methods inherited from class java.lang.Object

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

Field Detail

url

public final java.net.URL url

requestProperties

public final java.util.HashMap<java.lang.String,java.lang.String> requestProperties

requestInterceptors

public final java.util.List<HttpConnectionRequestInterceptor> requestInterceptors

responseInterceptors

public final java.util.List<HttpConnectionResponseInterceptor> responseInterceptors

Constructor Detail

HttpConnection

public HttpConnection(java.lang.String requestMethod,
                      java.net.URL url,
                      java.lang.String contentType)

Method Detail

setNumberOfRetries

public HttpConnection setNumberOfRetries(int numberOfRetries)

Sets the number of times this request can be retried. This method must be called before execute()

Parameters:

numberOfRetries - the number of times this request can be retried.

Returns:

an HttpConnection for method chaining

setRequestBody

public HttpConnection setRequestBody(java.lang.String input)

Set the String of request body data to be sent to the server.

Parameters:

input - String of request body data to be sent to the server. The input is assumed to be UTF-8 encoded.

Returns:

an HttpConnection for method chaining

setRequestBody

public HttpConnection setRequestBody(byte[] input)

Set the byte array of request body data to be sent to the server.

Parameters:

input - byte array of request body data to be sent to the server

Returns:

an HttpConnection for method chaining

setRequestBody

public HttpConnection setRequestBody(HttpConnection.InputStreamGenerator input)

Set the InputStream of request body data to be sent to the server.

Parameters:

input - InputStream of request body data to be sent to the server

Returns:

an HttpConnection for method chaining

setRequestBody

public HttpConnection setRequestBody(HttpConnection.InputStreamGenerator input,
                                     long inputLength)

Set the InputStream of request body data, of known length, to be sent to the server.

Parameters:

input - InputStream of request body data to be sent to the server

inputLength - Length of request body data to be sent to the server, in bytes

Returns:

an HttpConnection for method chaining

execute

public HttpConnection execute()
                       throws java.io.IOException

Execute request without returning data from server.

Call responseAsString, responseAsBytes, or responseAsInputStream after execute if the response body is required.

Returns:

An HttpConnection which can be used to obtain the response body

Throws:

java.io.IOException - if there was a problem writing data to the server

responseAsString

public java.lang.String responseAsString()
                                  throws java.io.IOException

Return response body data from server as a String.

Important: you must call execute() before calling this method.

Returns:

String of response body data from server, if any

Throws:

java.io.IOException - if there was a problem reading data from the server

responseAsBytes

public byte[] responseAsBytes()
                       throws java.io.IOException

Return response body data from server as a byte array.

Important: you must call execute() before calling this method.

Returns:

Byte array of response body data from server, if any

Throws:

java.io.IOException - if there was a problem reading data from the server

responseAsInputStream

public java.io.InputStream responseAsInputStream()
                                          throws java.io.IOException

Return response body data from server as an InputStream.

Important: you must call execute() before calling this method.

Returns:

InputStream of response body data from server, if any

Throws:

java.io.IOException - if there was a problem reading data from the server

getConnection

public java.net.HttpURLConnection getConnection()

Get the underlying HttpURLConnection object, allowing clients to set/get properties not exposed here.

Returns:

HttpURLConnection the underlying HttpURLConnection object

disconnect

public void disconnect()

Disconnect the underlying HttpURLConnection. Equivalent to calling: getConnection.disconnect()