HttpConnection (cloudant-http 2.4.3 API)

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.HttpUrlConnectionFactory` Factory used by HttpConnection to produce HttpUrlConnections.
`static interface`	`HttpConnection.InputStreamGenerator` An InputStreamGenerator has a single method getInputStream.

Field Summary

Fields
Modifier and Type	Field and Description
`HttpConnection.HttpUrlConnectionFactory`	`connectionFactory` A connectionFactory for opening the URLs, can be set, but configured with a default
`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)

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

Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
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 an InputStreamGenerator for an InputStream of request body data to be sent to the server.
`HttpConnection`	`setRequestBody(HttpConnection.InputStreamGenerator input, long inputLength)` Set an InputStreamGenerator for an InputStream, of known length, of request body data to be sent to the server.
`HttpConnection`	`setRequestBody(java.io.InputStream input)` Deprecated. Use `setRequestBody(InputStreamGenerator)`
`HttpConnection`	`setRequestBody(java.io.InputStream input, long inputLength)` Deprecated. Use `setRequestBody(InputStreamGenerator, long)`
`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
clone, equals, finalize, 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
```
  - connectionFactory
```
public HttpConnection.HttpUrlConnectionFactory connectionFactory
```
    A connectionFactory for opening the URLs, can be set, but configured with a default
- 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
    
    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(java.io.InputStream input)
```
    Deprecated. Use setRequestBody(InputStreamGenerator)
    
    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(java.io.InputStream input,
                                     long inputLength)
```
    Deprecated. Use setRequestBody(InputStreamGenerator, long)
    
    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
  - setRequestBody
```
public HttpConnection setRequestBody(HttpConnection.InputStreamGenerator input)
```
    Set an InputStreamGenerator for an 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
    
    Since:
    
    2.4.0
  - setRequestBody
```
public HttpConnection setRequestBody(HttpConnection.InputStreamGenerator input,
                                     long inputLength)
```
    Set an InputStreamGenerator for an InputStream, of known length, of request body data to be sent to the server.
    
    Parameters:
    
    input - InputStreamGenerator that returns an 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
    
    Since:
    
    2.4.0
  - 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.
    
    Note if the URL contains user information it will be encoded in a BasicAuth header.
    
    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()

Class HttpConnection

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

url

requestProperties

requestInterceptors

responseInterceptors

connectionFactory

Constructor Detail

HttpConnection

Method Detail

setNumberOfRetries

setRequestBody

setRequestBody

setRequestBody

setRequestBody

setRequestBody

setRequestBody

execute

responseAsString

responseAsBytes

responseAsInputStream

getConnection

disconnect