com.github.kevinsawicki.http
Class HttpRequest

java.lang.Object
  extended by com.github.kevinsawicki.http.HttpRequest

public class HttpRequest
extends java.lang.Object

A fluid interface for making HTTP requests using an underlying HttpURLConnection (or sub-class).

Each instance supports making a single request and cannot be reused for further requests.


Nested Class Summary
static class HttpRequest.Base64
           Encodes and decodes to and from Base64 notation.
static class HttpRequest.HttpRequestException
          HTTP request exception whose cause is always an IOException
static class HttpRequest.RequestOutputStream
          Request output stream
 
Field Summary
static java.lang.String CHARSET_UTF8
          'UTF-8' charset name
static java.lang.String CONTENT_TYPE_FORM
          'application/x-www-form-urlencoded' content type header value
static java.lang.String CONTENT_TYPE_JSON
          'application/json' content type header value
static java.lang.String ENCODING_GZIP
          'gzip' encoding header value
static java.lang.String HEADER_ACCEPT
          'Accept' header name
static java.lang.String HEADER_ACCEPT_CHARSET
          'Accept-Charset' header name
static java.lang.String HEADER_ACCEPT_ENCODING
          'Accept-Encoding' header name
static java.lang.String HEADER_AUTHORIZATION
          'Authorization' header name
static java.lang.String HEADER_CACHE_CONTROL
          'Cache-Control' header name
static java.lang.String HEADER_CONTENT_ENCODING
          'Content-Encoding' header name
static java.lang.String HEADER_CONTENT_LENGTH
          'Content-Length' header name
static java.lang.String HEADER_CONTENT_TYPE
          'Content-Type' header name
static java.lang.String HEADER_DATE
          'Date' header name
static java.lang.String HEADER_ETAG
          'ETag' header name
static java.lang.String HEADER_EXPIRES
          'Expires' header name
static java.lang.String HEADER_IF_NONE_MATCH
          'If-None-Match' header name
static java.lang.String HEADER_LAST_MODIFIED
          'Last-Modified' header name
static java.lang.String HEADER_LOCATION
          'Location' header name
static java.lang.String HEADER_SERVER
          'Server' header name
static java.lang.String HEADER_USER_AGENT
          'User-Agent' header name
static java.lang.String METHOD_DELETE
          'DELETE' request method
static java.lang.String METHOD_GET
          'GET' request method
static java.lang.String METHOD_HEAD
          'HEAD' request method
static java.lang.String METHOD_OPTIONS
          'OPTIONS' options method
static java.lang.String METHOD_POST
          'POST' request method
static java.lang.String METHOD_PUT
          'PUT' request method
static java.lang.String METHOD_TRACE
          'TRACE' request method
static java.lang.String PARAM_CHARSET
          'charset' header value parameter
 
Constructor Summary
HttpRequest(java.lang.CharSequence url, java.lang.String method)
          Create HTTP connection wrapper
HttpRequest(java.net.URL url, java.lang.String method)
          Create HTTP connection wrapper
 
Method Summary
 HttpRequest accept(java.lang.String value)
          Set the 'Accept' header to given value
 HttpRequest acceptCharset(java.lang.String value)
          Set the 'Accept-Charset' header to given value
 HttpRequest acceptEncoding(java.lang.String value)
          Set the 'Accept-Encoding' header to given value
 HttpRequest acceptGzipEncoding()
          Set the 'Accept-Encoding' header to 'gzip'
 HttpRequest acceptJson()
          Set the 'Accept' header to 'application/json'
static java.lang.String append(java.lang.CharSequence url, java.util.Map<?,?> params)
          Append given map as query parameters to the base URL
static java.lang.String append(java.lang.CharSequence url, java.lang.Object... params)
          Append given name/value pairs as query parameters to the base URL
 HttpRequest authorization(java.lang.String value)
          Set the 'Authorization' header to given value
 boolean badRequest()
          Is the response code a 400 Bad Request?
 HttpRequest basic(java.lang.String name, java.lang.String password)
          Set the 'Authorization' header to given values in Basic authentication format
 java.lang.String body()
          Get response as String using character set returned from charset()
 java.lang.String body(java.lang.String charset)
          Get response as String in given character set
 java.io.BufferedInputStream buffer()
          Get response in a buffered stream
 java.io.BufferedReader bufferedReader()
          Get buffered reader to response body using the character set returned from charset() and the configured buffer size
 java.io.BufferedReader bufferedReader(java.lang.String charset)
          Get buffered reader to response body using the given character set r and the configured buffer size
 int bufferSize()
          Get the configured buffer size
 HttpRequest bufferSize(int size)
          Set the size used when buffering and copying between streams
 byte[] bytes()
          Get response as byte array
 java.lang.String cacheControl()
          Get the 'Cache-Control' header from the response
 java.lang.String charset()
          Get 'charset' parameter from 'Content-Type' response header
 HttpRequest chunk(int size)
          Set chunked streaming mode to the given size
 int code()
          Get the status code of the response
 HttpRequest code(java.util.concurrent.atomic.AtomicInteger output)
          Set the value of the given AtomicInteger to the status code of the response
 HttpRequest connectTimeout(int timeout)
          Set connect timeout on connection to given value
 java.lang.String contentEncoding()
          Get the 'Content-Encoding' header from the response
 int contentLength()
          Get the 'Content-Length' header from the response
 HttpRequest contentLength(int value)
          Set the 'Content-Length' request header to the given value
 HttpRequest contentLength(java.lang.String value)
          Set the 'Content-Length' request header to the given value
 java.lang.String contentType()
          Get the 'Content-Type' header from the response
 HttpRequest contentType(java.lang.String value)
          Set the 'Content-Type' request header to the given value
 HttpRequest contentType(java.lang.String value, java.lang.String charset)
          Set the 'Content-Type' request header to the given value and charset
 boolean created()
          Is the response code a 201 Created?
 long date()
          Get the 'Date' header from the response
 long dateHeader(java.lang.String name)
          Get a date header from the response falling back to returning -1 if the header is missing or parsing fails
 long dateHeader(java.lang.String name, long defaultValue)
          Get a date header from the response falling back to returning the given default value if the header is missing or parsing fails
static HttpRequest delete(java.lang.CharSequence url)
          Start a 'DELETE' request to the given URL
static HttpRequest delete(java.lang.CharSequence baseUrl, boolean encode, java.lang.Object... params)
          Start a 'DELETE' request to the given URL along with the query params
static HttpRequest delete(java.lang.CharSequence baseUrl, java.util.Map<?,?> params, boolean encode)
          Start a 'DELETE' request to the given URL along with the query params
static HttpRequest delete(java.net.URL url)
          Start a 'DELETE' request to the given URL
 HttpRequest disconnect()
          Disconnect the connection
static java.lang.String encode(java.lang.CharSequence url)
          Encode the given URL as an ASCII String
 java.lang.String eTag()
          Get the 'ETag' header from the response
 long expires()
          Get the 'Expires' header from the response
 HttpRequest form(java.util.Map.Entry<?,?> entry)
          Write the key and value in the entry as form data to the request body
 HttpRequest form(java.util.Map.Entry<?,?> entry, java.lang.String charset)
          Write the key and value in the entry as form data to the request body
 HttpRequest form(java.util.Map<?,?> values)
          Write the values in the map as form data to the request body
 HttpRequest form(java.util.Map<?,?> values, java.lang.String charset)
          Write the values in the map as encoded form data to the request body
 HttpRequest form(java.lang.Object name, java.lang.Object value)
          Write the name/value pair as form data to the request body
 HttpRequest form(java.lang.Object name, java.lang.Object value, java.lang.String charset)
          Write the name/value pair as form data to the request body
static HttpRequest get(java.lang.CharSequence url)
          Start a 'GET' request to the given URL
static HttpRequest get(java.lang.CharSequence baseUrl, boolean encode, java.lang.Object... params)
          Start a 'GET' request to the given URL along with the query params
static HttpRequest get(java.lang.CharSequence baseUrl, java.util.Map<?,?> params, boolean encode)
          Start a 'GET' request to the given URL along with the query params
static HttpRequest get(java.net.URL url)
          Start a 'GET' request to the given URL
 java.net.HttpURLConnection getConnection()
          Get underlying connection
static HttpRequest head(java.lang.CharSequence url)
          Start a 'HEAD' request to the given URL
static HttpRequest head(java.lang.CharSequence baseUrl, boolean encode, java.lang.Object... params)
          Start a 'GET' request to the given URL along with the query params
static HttpRequest head(java.lang.CharSequence baseUrl, java.util.Map<?,?> params, boolean encode)
          Start a 'HEAD' request to the given URL along with the query params
static HttpRequest head(java.net.URL url)
          Start a 'HEAD' request to the given URL
 HttpRequest header(java.util.Map.Entry<java.lang.String,java.lang.String> header)
          Set header to have given entry's key as the name and value as the value
 java.lang.String header(java.lang.String name)
          Get a response header
 HttpRequest header(java.lang.String name, java.lang.Number value)
          Set header name to given value
 HttpRequest header(java.lang.String name, java.lang.String value)
          Set header name to given value
 java.util.Map<java.lang.String,java.util.List<java.lang.String>> headers()
          Get all the response headers
 HttpRequest headers(java.util.Map<java.lang.String,java.lang.String> headers)
          Set all headers found in given map where the keys are the header names and the values are the header values
 java.lang.String[] headers(java.lang.String name)
          Get all values of the given header from the response
 HttpRequest ifModifiedSince(long value)
          Set the 'If-Modified-Since' request header to the given value
 HttpRequest ifNoneMatch(java.lang.String value)
          Set the 'If-None-Match' request header to the given value
 boolean ignoreCloseExceptions()
          Get whether or not exceptions thrown by Closeable.close() are ignored
 HttpRequest ignoreCloseExceptions(boolean ignore)
          Set whether or not to ignore exceptions that occur from calling Closeable.close()
 int intHeader(java.lang.String name)
          Get an integer header from the response falling back to returning -1 if the header is missing or parsing fails
 int intHeader(java.lang.String name, int defaultValue)
          Get an integer header value from the response falling back to the given default value if the header is missing or if parsing fails
 boolean isBodyEmpty()
          Is the response body empty?
static void keepAlive(boolean keepAlive)
          Set the 'http.keepAlive' property to the given value.
 long lastModified()
          Get the 'Last-Modified' header from the response
 java.lang.String location()
          Get the 'Location' header from the response
 java.lang.String message()
          Get status message of the response
static void nonProxyHosts(java.lang.String... hosts)
          Set the 'http.nonProxyHosts' property to the given host values.
 boolean notFound()
          Is the response code a 404 Not Found?
 boolean notModified()
          Is the response code a 304 Not Modified?
 boolean ok()
          Is the response code a 200 OK?
static HttpRequest options(java.lang.CharSequence url)
          Start an 'OPTIONS' request to the given URL
static HttpRequest options(java.net.URL url)
          Start an 'OPTIONS' request to the given URL
 java.lang.String parameter(java.lang.String headerName, java.lang.String paramName)
          Get parameter with given name from header value in response
 java.util.Map<java.lang.String,java.lang.String> parameters(java.lang.String headerName)
          Get all parameters from header value in response
 HttpRequest part(java.lang.String name, java.io.File part)
          Write part of a multipart request to the request body
 HttpRequest part(java.lang.String name, java.io.InputStream part)
          Write part of a multipart request to the request body
 HttpRequest part(java.lang.String name, java.lang.Number part)
          Write part of a multipart request to the request body
 HttpRequest part(java.lang.String name, java.lang.String part)
          Write part of a multipart request to the request body
 HttpRequest part(java.lang.String name, java.lang.String filename, java.io.File part)
          Write part of a multipart request to the request body
 HttpRequest part(java.lang.String name, java.lang.String filename, java.lang.Number part)
          Write part of a multipart request to the request body
 HttpRequest part(java.lang.String name, java.lang.String filename, java.lang.String part)
          Write part of a multipart request to the request body
 HttpRequest part(java.lang.String name, java.lang.String filename, java.lang.String contentType, java.io.File part)
          Write part of a multipart request to the request body
 HttpRequest part(java.lang.String name, java.lang.String filename, java.lang.String contentType, java.io.InputStream part)
          Write part of a multipart request to the request body
 HttpRequest part(java.lang.String name, java.lang.String filename, java.lang.String contentType, java.lang.String part)
          Write part of a multipart request to the request body
 HttpRequest partHeader(java.lang.String name, java.lang.String value)
          Write a multipart header to the response body
static HttpRequest post(java.lang.CharSequence url)
          Start a 'POST' request to the given URL
static HttpRequest post(java.lang.CharSequence baseUrl, boolean encode, java.lang.Object... params)
          Start a 'POST' request to the given URL along with the query params
static HttpRequest post(java.lang.CharSequence baseUrl, java.util.Map<?,?> params, boolean encode)
          Start a 'POST' request to the given URL along with the query params
static HttpRequest post(java.net.URL url)
          Start a 'POST' request to the given URL
static void proxyHost(java.lang.String host)
          Set the 'http.proxyHost' & 'https.proxyHost' properties to the given host value.
static void proxyPort(int port)
          Set the 'http.proxyPort' & 'https.proxyPort' properties to the given port number.
static HttpRequest put(java.lang.CharSequence url)
          Start a 'PUT' request to the given URL
static HttpRequest put(java.lang.CharSequence baseUrl, boolean encode, java.lang.Object... params)
          Start a 'PUT' request to the given URL along with the query params
static HttpRequest put(java.lang.CharSequence baseUrl, java.util.Map<?,?> params, boolean encode)
          Start a 'PUT' request to the given URL along with the query params
static HttpRequest put(java.net.URL url)
          Start a 'PUT' request to the given URL
 java.io.InputStreamReader reader()
          Get reader to response body using the character set returned from charset()
 java.io.InputStreamReader reader(java.lang.String charset)
          Get reader to response body using given character set.
 HttpRequest readTimeout(int timeout)
          Set read timeout on connection to given value
 HttpRequest receive(java.lang.Appendable appendable)
          Receive response into the given appendable
 HttpRequest receive(java.io.File file)
          Stream response body to file
 HttpRequest receive(java.io.OutputStream output)
          Stream response to given output stream
 HttpRequest receive(java.io.PrintStream output)
          Stream response to given print stream
 HttpRequest receive(java.io.Writer writer)
          Receive response into the given writer
 HttpRequest send(byte[] input)
          Write byte array to request body
 HttpRequest send(java.lang.CharSequence value)
          Write char sequence to request body
 HttpRequest send(java.io.File input)
          Write contents of file to request body
 HttpRequest send(java.io.InputStream input)
          Write stream to request body
 HttpRequest send(java.io.Reader input)
          Write reader to request body
 java.lang.String server()
          Get the 'Server' header from the response
 boolean serverError()
          Is the response code a 500 Internal Server Error?
 java.io.InputStream stream()
          Get stream to response body
 java.lang.String toString()
           
static HttpRequest trace(java.lang.CharSequence url)
          Start a 'TRACE' request to the given URL
static HttpRequest trace(java.net.URL url)
          Start a 'TRACE' request to the given URL
 HttpRequest trustAllCerts()
          Configure HTTPS connection to trust all certificates
 HttpRequest trustAllHosts()
          Configure HTTPS connection to trust all hosts using a custom HostnameVerifier that always returns true for each host verified
 HttpRequest uncompress(boolean uncompress)
          Set whether or not the response body should be automatically uncompressed when read from.
 HttpRequest useCaches(boolean useCaches)
          Set value of URLConnection.setUseCaches(boolean)
 HttpRequest userAgent(java.lang.String value)
          Set the 'User-Agent' header to given value
 java.io.OutputStreamWriter writer()
          Create writer to request output stream
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

CHARSET_UTF8

public static final java.lang.String CHARSET_UTF8
'UTF-8' charset name

See Also:
Constant Field Values

CONTENT_TYPE_FORM

public static final java.lang.String CONTENT_TYPE_FORM
'application/x-www-form-urlencoded' content type header value

See Also:
Constant Field Values

CONTENT_TYPE_JSON

public static final java.lang.String CONTENT_TYPE_JSON
'application/json' content type header value

See Also:
Constant Field Values

ENCODING_GZIP

public static final java.lang.String ENCODING_GZIP
'gzip' encoding header value

See Also:
Constant Field Values

HEADER_ACCEPT

public static final java.lang.String HEADER_ACCEPT
'Accept' header name

See Also:
Constant Field Values

HEADER_ACCEPT_CHARSET

public static final java.lang.String HEADER_ACCEPT_CHARSET
'Accept-Charset' header name

See Also:
Constant Field Values

HEADER_ACCEPT_ENCODING

public static final java.lang.String HEADER_ACCEPT_ENCODING
'Accept-Encoding' header name

See Also:
Constant Field Values

HEADER_AUTHORIZATION

public static final java.lang.String HEADER_AUTHORIZATION
'Authorization' header name

See Also:
Constant Field Values

HEADER_CACHE_CONTROL

public static final java.lang.String HEADER_CACHE_CONTROL
'Cache-Control' header name

See Also:
Constant Field Values

HEADER_CONTENT_ENCODING

public static final java.lang.String HEADER_CONTENT_ENCODING
'Content-Encoding' header name

See Also:
Constant Field Values

HEADER_CONTENT_LENGTH

public static final java.lang.String HEADER_CONTENT_LENGTH
'Content-Length' header name

See Also:
Constant Field Values

HEADER_CONTENT_TYPE

public static final java.lang.String HEADER_CONTENT_TYPE
'Content-Type' header name

See Also:
Constant Field Values

HEADER_DATE

public static final java.lang.String HEADER_DATE
'Date' header name

See Also:
Constant Field Values

HEADER_ETAG

public static final java.lang.String HEADER_ETAG
'ETag' header name

See Also:
Constant Field Values

HEADER_EXPIRES

public static final java.lang.String HEADER_EXPIRES
'Expires' header name

See Also:
Constant Field Values

HEADER_IF_NONE_MATCH

public static final java.lang.String HEADER_IF_NONE_MATCH
'If-None-Match' header name

See Also:
Constant Field Values

HEADER_LAST_MODIFIED

public static final java.lang.String HEADER_LAST_MODIFIED
'Last-Modified' header name

See Also:
Constant Field Values

HEADER_LOCATION

public static final java.lang.String HEADER_LOCATION
'Location' header name

See Also:
Constant Field Values

HEADER_SERVER

public static final java.lang.String HEADER_SERVER
'Server' header name

See Also:
Constant Field Values

HEADER_USER_AGENT

public static final java.lang.String HEADER_USER_AGENT
'User-Agent' header name

See Also:
Constant Field Values

METHOD_DELETE

public static final java.lang.String METHOD_DELETE
'DELETE' request method

See Also:
Constant Field Values

METHOD_GET

public static final java.lang.String METHOD_GET
'GET' request method

See Also:
Constant Field Values

METHOD_HEAD

public static final java.lang.String METHOD_HEAD
'HEAD' request method

See Also:
Constant Field Values

METHOD_OPTIONS

public static final java.lang.String METHOD_OPTIONS
'OPTIONS' options method

See Also:
Constant Field Values

METHOD_POST

public static final java.lang.String METHOD_POST
'POST' request method

See Also:
Constant Field Values

METHOD_PUT

public static final java.lang.String METHOD_PUT
'PUT' request method

See Also:
Constant Field Values

METHOD_TRACE

public static final java.lang.String METHOD_TRACE
'TRACE' request method

See Also:
Constant Field Values

PARAM_CHARSET

public static final java.lang.String PARAM_CHARSET
'charset' header value parameter

See Also:
Constant Field Values
Constructor Detail

HttpRequest

public HttpRequest(java.lang.CharSequence url,
                   java.lang.String method)
            throws HttpRequest.HttpRequestException
Create HTTP connection wrapper

Parameters:
url -
method -
Throws:
HttpRequest.HttpRequestException

HttpRequest

public HttpRequest(java.net.URL url,
                   java.lang.String method)
            throws HttpRequest.HttpRequestException
Create HTTP connection wrapper

Parameters:
url -
method -
Throws:
HttpRequest.HttpRequestException
Method Detail

accept

public HttpRequest accept(java.lang.String value)
Set the 'Accept' header to given value

Parameters:
value -
Returns:
this request

acceptCharset

public HttpRequest acceptCharset(java.lang.String value)
Set the 'Accept-Charset' header to given value

Parameters:
value -
Returns:
this request

acceptEncoding

public HttpRequest acceptEncoding(java.lang.String value)
Set the 'Accept-Encoding' header to given value

Parameters:
value -
Returns:
this request

acceptGzipEncoding

public HttpRequest acceptGzipEncoding()
Set the 'Accept-Encoding' header to 'gzip'

Returns:
this request
See Also:
uncompress(boolean)

acceptJson

public HttpRequest acceptJson()
Set the 'Accept' header to 'application/json'

Returns:
this request

append

public static java.lang.String append(java.lang.CharSequence url,
                                      java.util.Map<?,?> params)
Append given map as query parameters to the base URL

Each map entry's key will be a parameter name and the value's Object.toString() will be the parameter value.

Parameters:
url -
params -
Returns:
URL with appended query params

append

public static java.lang.String append(java.lang.CharSequence url,
                                      java.lang.Object... params)
Append given name/value pairs as query parameters to the base URL

The params argument is interpreted as a sequence of name/value pairs so the given number of params must be divisible by 2.

Parameters:
url -
params - name/value pairs
Returns:
URL with appended query params

authorization

public HttpRequest authorization(java.lang.String value)
Set the 'Authorization' header to given value

Parameters:
value -
Returns:
this request

badRequest

public boolean badRequest()
                   throws HttpRequest.HttpRequestException
Is the response code a 400 Bad Request?

Returns:
true if 400, false otherwise
Throws:
HttpRequest.HttpRequestException

basic

public HttpRequest basic(java.lang.String name,
                         java.lang.String password)
Set the 'Authorization' header to given values in Basic authentication format

Parameters:
name -
password -
Returns:
this request

body

public java.lang.String body()
                      throws HttpRequest.HttpRequestException
Get response as String using character set returned from charset()

Returns:
string
Throws:
HttpRequest.HttpRequestException

body

public java.lang.String body(java.lang.String charset)
                      throws HttpRequest.HttpRequestException
Get response as String in given character set

This will fall back to using the UTF-8 character set if the given charset is null

Parameters:
charset -
Returns:
string
Throws:
HttpRequest.HttpRequestException

buffer

public java.io.BufferedInputStream buffer()
                                   throws HttpRequest.HttpRequestException
Get response in a buffered stream

Returns:
stream
Throws:
HttpRequest.HttpRequestException
See Also:
bufferSize(int)

bufferedReader

public java.io.BufferedReader bufferedReader()
                                      throws HttpRequest.HttpRequestException
Get buffered reader to response body using the character set returned from charset() and the configured buffer size

Returns:
reader
Throws:
HttpRequest.HttpRequestException
See Also:
bufferSize(int)

bufferedReader

public java.io.BufferedReader bufferedReader(java.lang.String charset)
                                      throws HttpRequest.HttpRequestException
Get buffered reader to response body using the given character set r and the configured buffer size

Parameters:
charset -
Returns:
reader
Throws:
HttpRequest.HttpRequestException
See Also:
bufferSize(int)

bufferSize

public int bufferSize()
Get the configured buffer size

The default buffer size is 8,192 bytes

Returns:
buffer size

bufferSize

public HttpRequest bufferSize(int size)
Set the size used when buffering and copying between streams

This size is also used for send and receive buffers created for both char and byte arrays

The default buffer size is 8,192 bytes

Parameters:
size -
Returns:
this request

bytes

public byte[] bytes()
             throws HttpRequest.HttpRequestException
Get response as byte array

Returns:
byte array
Throws:
HttpRequest.HttpRequestException

cacheControl

public java.lang.String cacheControl()
Get the 'Cache-Control' header from the response

Returns:
cache control

charset

public java.lang.String charset()
Get 'charset' parameter from 'Content-Type' response header

Returns:
charset or null if none

chunk

public HttpRequest chunk(int size)
Set chunked streaming mode to the given size

Parameters:
size -
Returns:
this request

code

public int code()
         throws HttpRequest.HttpRequestException
Get the status code of the response

Returns:
the response code
Throws:
HttpRequest.HttpRequestException

code

public HttpRequest code(java.util.concurrent.atomic.AtomicInteger output)
                 throws HttpRequest.HttpRequestException
Set the value of the given AtomicInteger to the status code of the response

Parameters:
output -
Returns:
this request
Throws:
HttpRequest.HttpRequestException

connectTimeout

public HttpRequest connectTimeout(int timeout)
Set connect timeout on connection to given value

Parameters:
timeout -
Returns:
this request

contentEncoding

public java.lang.String contentEncoding()
Get the 'Content-Encoding' header from the response

Returns:
this request

contentLength

public int contentLength()
Get the 'Content-Length' header from the response

Returns:
response header value

contentLength

public HttpRequest contentLength(int value)
Set the 'Content-Length' request header to the given value

Parameters:
value -
Returns:
this request

contentLength

public HttpRequest contentLength(java.lang.String value)
Set the 'Content-Length' request header to the given value

Parameters:
value -
Returns:
this request

contentType

public java.lang.String contentType()
Get the 'Content-Type' header from the response

Returns:
response header value

contentType

public HttpRequest contentType(java.lang.String value)
Set the 'Content-Type' request header to the given value

Parameters:
value -
Returns:
this request

contentType

public HttpRequest contentType(java.lang.String value,
                               java.lang.String charset)
Set the 'Content-Type' request header to the given value and charset

Parameters:
value -
charset -
Returns:
this request

created

public boolean created()
                throws HttpRequest.HttpRequestException
Is the response code a 201 Created?

Returns:
true if 201, false otherwise
Throws:
HttpRequest.HttpRequestException

date

public long date()
Get the 'Date' header from the response

Returns:
date value, -1 on failures

dateHeader

public long dateHeader(java.lang.String name)
                throws HttpRequest.HttpRequestException
Get a date header from the response falling back to returning -1 if the header is missing or parsing fails

Parameters:
name -
Returns:
date, -1 on failures
Throws:
HttpRequest.HttpRequestException

dateHeader

public long dateHeader(java.lang.String name,
                       long defaultValue)
                throws HttpRequest.HttpRequestException
Get a date header from the response falling back to returning the given default value if the header is missing or parsing fails

Parameters:
name -
defaultValue -
Returns:
date, default value on failures
Throws:
HttpRequest.HttpRequestException

delete

public static HttpRequest delete(java.lang.CharSequence url)
                          throws HttpRequest.HttpRequestException
Start a 'DELETE' request to the given URL

Parameters:
url -
Returns:
request
Throws:
HttpRequest.HttpRequestException

delete

public static HttpRequest delete(java.lang.CharSequence baseUrl,
                                 boolean encode,
                                 java.lang.Object... params)
Start a 'DELETE' request to the given URL along with the query params

Parameters:
baseUrl -
encode - true to encode the full URL
params - the name/value query parameter pairs to include as part of the baseUrl
Returns:
request
See Also:
#append(CharSequence, String...), encode(CharSequence)

delete

public static HttpRequest delete(java.lang.CharSequence baseUrl,
                                 java.util.Map<?,?> params,
                                 boolean encode)
Start a 'DELETE' request to the given URL along with the query params

Parameters:
baseUrl -
params - The query parameters to include as part of the baseUrl
encode - true to encode the full URL
Returns:
request
See Also:
append(CharSequence, Map), encode(CharSequence)

delete

public static HttpRequest delete(java.net.URL url)
                          throws HttpRequest.HttpRequestException
Start a 'DELETE' request to the given URL

Parameters:
url -
Returns:
request
Throws:
HttpRequest.HttpRequestException

disconnect

public HttpRequest disconnect()
Disconnect the connection

Returns:
this request

encode

public static java.lang.String encode(java.lang.CharSequence url)
                               throws HttpRequest.HttpRequestException
Encode the given URL as an ASCII String

This method ensures the path and query segments of the URL are properly encoded such as ' ' characters being encoded to '%20' or any UTF-8 characters that are non-ASCII. No encoding of URLs is done by default by the HttpRequest constructors and so if URL encoding is needed this method should be called before calling the HttpRequest constructor.

Parameters:
url -
Returns:
encoded URL
Throws:
HttpRequest.HttpRequestException

eTag

public java.lang.String eTag()
Get the 'ETag' header from the response

Returns:
entity tag

expires

public long expires()
Get the 'Expires' header from the response

Returns:
expires value, -1 on failures

form

public HttpRequest form(java.util.Map.Entry<?,?> entry)
                 throws HttpRequest.HttpRequestException
Write the key and value in the entry as form data to the request body

The pair specified will be URL-encoded in UTF-8 and sent with the 'application/x-www-form-urlencoded' content-type

Parameters:
entry -
Returns:
this request
Throws:
HttpRequest.HttpRequestException

form

public HttpRequest form(java.util.Map.Entry<?,?> entry,
                        java.lang.String charset)
                 throws HttpRequest.HttpRequestException
Write the key and value in the entry as form data to the request body

The pair specified will be URL-encoded and sent with the 'application/x-www-form-urlencoded' content-type

Parameters:
entry -
charset -
Returns:
this request
Throws:
HttpRequest.HttpRequestException

form

public HttpRequest form(java.util.Map<?,?> values)
                 throws HttpRequest.HttpRequestException
Write the values in the map as form data to the request body

The pairs specified will be URL-encoded in UTF-8 and sent with the 'application/x-www-form-urlencoded' content-type

Parameters:
values -
Returns:
this request
Throws:
HttpRequest.HttpRequestException

form

public HttpRequest form(java.util.Map<?,?> values,
                        java.lang.String charset)
                 throws HttpRequest.HttpRequestException
Write the values in the map as encoded form data to the request body

Parameters:
values -
charset -
Returns:
this request
Throws:
HttpRequest.HttpRequestException

form

public HttpRequest form(java.lang.Object name,
                        java.lang.Object value)
                 throws HttpRequest.HttpRequestException
Write the name/value pair as form data to the request body

The pair specified will be URL-encoded in UTF-8 and sent with the 'application/x-www-form-urlencoded' content-type

Parameters:
name -
value -
Returns:
this request
Throws:
HttpRequest.HttpRequestException

form

public HttpRequest form(java.lang.Object name,
                        java.lang.Object value,
                        java.lang.String charset)
                 throws HttpRequest.HttpRequestException
Write the name/value pair as form data to the request body

The values specified will be URL-encoded and sent with the 'application/x-www-form-urlencoded' content-type

Parameters:
name -
value -
charset -
Returns:
this request
Throws:
HttpRequest.HttpRequestException

get

public static HttpRequest get(java.lang.CharSequence url)
                       throws HttpRequest.HttpRequestException
Start a 'GET' request to the given URL

Parameters:
url -
Returns:
request
Throws:
HttpRequest.HttpRequestException

get

public static HttpRequest get(java.lang.CharSequence baseUrl,
                              boolean encode,
                              java.lang.Object... params)
Start a 'GET' request to the given URL along with the query params

Parameters:
baseUrl -
encode - true to encode the full URL
params - the name/value query parameter pairs to include as part of the baseUrl
Returns:
request
See Also:
#append(CharSequence, String...), encode(CharSequence)

get

public static HttpRequest get(java.lang.CharSequence baseUrl,
                              java.util.Map<?,?> params,
                              boolean encode)
Start a 'GET' request to the given URL along with the query params

Parameters:
baseUrl -
params - The query parameters to include as part of the baseUrl
encode - true to encode the full URL
Returns:
request
See Also:
append(CharSequence, Map), encode(CharSequence)

get

public static HttpRequest get(java.net.URL url)
                       throws HttpRequest.HttpRequestException
Start a 'GET' request to the given URL

Parameters:
url -
Returns:
request
Throws:
HttpRequest.HttpRequestException

getConnection

public java.net.HttpURLConnection getConnection()
Get underlying connection

Returns:
connection

head

public static HttpRequest head(java.lang.CharSequence url)
                        throws HttpRequest.HttpRequestException
Start a 'HEAD' request to the given URL

Parameters:
url -
Returns:
request
Throws:
HttpRequest.HttpRequestException

head

public static HttpRequest head(java.lang.CharSequence baseUrl,
                               boolean encode,
                               java.lang.Object... params)
Start a 'GET' request to the given URL along with the query params

Parameters:
baseUrl -
encode - true to encode the full URL
params - the name/value query parameter pairs to include as part of the baseUrl
Returns:
request
See Also:
#append(CharSequence, String...), encode(CharSequence)

head

public static HttpRequest head(java.lang.CharSequence baseUrl,
                               java.util.Map<?,?> params,
                               boolean encode)
Start a 'HEAD' request to the given URL along with the query params

Parameters:
baseUrl -
params - The query parameters to include as part of the baseUrl
encode - true to encode the full URL
Returns:
request
See Also:
append(CharSequence, Map), encode(CharSequence)

head

public static HttpRequest head(java.net.URL url)
                        throws HttpRequest.HttpRequestException
Start a 'HEAD' request to the given URL

Parameters:
url -
Returns:
request
Throws:
HttpRequest.HttpRequestException

header

public HttpRequest header(java.util.Map.Entry<java.lang.String,java.lang.String> header)
Set header to have given entry's key as the name and value as the value

Parameters:
header -
Returns:
this request

header

public java.lang.String header(java.lang.String name)
                        throws HttpRequest.HttpRequestException
Get a response header

Parameters:
name -
Returns:
response header
Throws:
HttpRequest.HttpRequestException

header

public HttpRequest header(java.lang.String name,
                          java.lang.Number value)
Set header name to given value

Parameters:
name -
value -
Returns:
this request

header

public HttpRequest header(java.lang.String name,
                          java.lang.String value)
Set header name to given value

Parameters:
name -
value -
Returns:
this request

headers

public java.util.Map<java.lang.String,java.util.List<java.lang.String>> headers()
                                                                         throws HttpRequest.HttpRequestException
Get all the response headers

Returns:
map of response header names to their value(s)
Throws:
HttpRequest.HttpRequestException

headers

public HttpRequest headers(java.util.Map<java.lang.String,java.lang.String> headers)
Set all headers found in given map where the keys are the header names and the values are the header values

Parameters:
headers -
Returns:
this request

headers

public java.lang.String[] headers(java.lang.String name)
Get all values of the given header from the response

Parameters:
name -
Returns:
non-null but possibly empty array of String header values

ifModifiedSince

public HttpRequest ifModifiedSince(long value)
Set the 'If-Modified-Since' request header to the given value

Parameters:
value -
Returns:
this request

ifNoneMatch

public HttpRequest ifNoneMatch(java.lang.String value)
Set the 'If-None-Match' request header to the given value

Parameters:
value -
Returns:
this request

ignoreCloseExceptions

public boolean ignoreCloseExceptions()
Get whether or not exceptions thrown by Closeable.close() are ignored

Returns:
true if ignoring, false if throwing

ignoreCloseExceptions

public HttpRequest ignoreCloseExceptions(boolean ignore)
Set whether or not to ignore exceptions that occur from calling Closeable.close()

The default value of this setting is true

Parameters:
ignore -
Returns:
this request

intHeader

public int intHeader(java.lang.String name)
              throws HttpRequest.HttpRequestException
Get an integer header from the response falling back to returning -1 if the header is missing or parsing fails

Parameters:
name -
Returns:
header value as an integer, -1 when missing or parsing fails
Throws:
HttpRequest.HttpRequestException

intHeader

public int intHeader(java.lang.String name,
                     int defaultValue)
              throws HttpRequest.HttpRequestException
Get an integer header value from the response falling back to the given default value if the header is missing or if parsing fails

Parameters:
name -
defaultValue -
Returns:
header value as an integer, default value when missing or parsing fails
Throws:
HttpRequest.HttpRequestException

isBodyEmpty

public boolean isBodyEmpty()
                    throws HttpRequest.HttpRequestException
Is the response body empty?

Returns:
true if the Content-Length response header is 0, false otherwise
Throws:
HttpRequest.HttpRequestException

keepAlive

public static void keepAlive(boolean keepAlive)
Set the 'http.keepAlive' property to the given value.

This setting will apply to requests.

Parameters:
keepAlive -

lastModified

public long lastModified()
Get the 'Last-Modified' header from the response

Returns:
last modified value, -1 on failures

location

public java.lang.String location()
Get the 'Location' header from the response

Returns:
location

message

public java.lang.String message()
                         throws HttpRequest.HttpRequestException
Get status message of the response

Returns:
message
Throws:
HttpRequest.HttpRequestException

nonProxyHosts

public static void nonProxyHosts(java.lang.String... hosts)
Set the 'http.nonProxyHosts' property to the given host values.

Hosts will be separated by a '|' character.

This setting will apply to requests.

Parameters:
hosts -

notFound

public boolean notFound()
                 throws HttpRequest.HttpRequestException
Is the response code a 404 Not Found?

Returns:
true if 404, false otherwise
Throws:
HttpRequest.HttpRequestException

notModified

public boolean notModified()
                    throws HttpRequest.HttpRequestException
Is the response code a 304 Not Modified?

Returns:
true if 304, false otherwise
Throws:
HttpRequest.HttpRequestException

ok

public boolean ok()
           throws HttpRequest.HttpRequestException
Is the response code a 200 OK?

Returns:
true if 200, false otherwise
Throws:
HttpRequest.HttpRequestException

options

public static HttpRequest options(java.lang.CharSequence url)
                           throws HttpRequest.HttpRequestException
Start an 'OPTIONS' request to the given URL

Parameters:
url -
Returns:
request
Throws:
HttpRequest.HttpRequestException

options

public static HttpRequest options(java.net.URL url)
                           throws HttpRequest.HttpRequestException
Start an 'OPTIONS' request to the given URL

Parameters:
url -
Returns:
request
Throws:
HttpRequest.HttpRequestException

parameter

public java.lang.String parameter(java.lang.String headerName,
                                  java.lang.String paramName)
Get parameter with given name from header value in response

Parameters:
headerName -
paramName -
Returns:
parameter value or null if missing

parameters

public java.util.Map<java.lang.String,java.lang.String> parameters(java.lang.String headerName)
Get all parameters from header value in response

This will be all key=value pairs after the first ';' that are separated by a ';'

Parameters:
headerName -
Returns:
non-null but possibly empty map of parameter headers

part

public HttpRequest part(java.lang.String name,
                        java.io.File part)
                 throws HttpRequest.HttpRequestException
Write part of a multipart request to the request body

Parameters:
name -
part -
Returns:
this request
Throws:
HttpRequest.HttpRequestException

part

public HttpRequest part(java.lang.String name,
                        java.io.InputStream part)
                 throws HttpRequest.HttpRequestException
Write part of a multipart request to the request body

Parameters:
name -
part -
Returns:
this request
Throws:
HttpRequest.HttpRequestException

part

public HttpRequest part(java.lang.String name,
                        java.lang.Number part)
                 throws HttpRequest.HttpRequestException
Write part of a multipart request to the request body

Parameters:
name -
part -
Returns:
this request
Throws:
HttpRequest.HttpRequestException

part

public HttpRequest part(java.lang.String name,
                        java.lang.String part)
Write part of a multipart request to the request body

Parameters:
name -
part -
Returns:
this request

part

public HttpRequest part(java.lang.String name,
                        java.lang.String filename,
                        java.io.File part)
                 throws HttpRequest.HttpRequestException
Write part of a multipart request to the request body

Parameters:
name -
filename -
part -
Returns:
this request
Throws:
HttpRequest.HttpRequestException

part

public HttpRequest part(java.lang.String name,
                        java.lang.String filename,
                        java.lang.Number part)
                 throws HttpRequest.HttpRequestException
Write part of a multipart request to the request body

Parameters:
name -
filename -
part -
Returns:
this request
Throws:
HttpRequest.HttpRequestException

part

public HttpRequest part(java.lang.String name,
                        java.lang.String filename,
                        java.lang.String part)
                 throws HttpRequest.HttpRequestException
Write part of a multipart request to the request body

Parameters:
name -
filename -
part -
Returns:
this request
Throws:
HttpRequest.HttpRequestException

part

public HttpRequest part(java.lang.String name,
                        java.lang.String filename,
                        java.lang.String contentType,
                        java.io.File part)
                 throws HttpRequest.HttpRequestException
Write part of a multipart request to the request body

Parameters:
name -
filename -
contentType - value of the Content-Type part header
part -
Returns:
this request
Throws:
HttpRequest.HttpRequestException

part

public HttpRequest part(java.lang.String name,
                        java.lang.String filename,
                        java.lang.String contentType,
                        java.io.InputStream part)
                 throws HttpRequest.HttpRequestException
Write part of a multipart request to the request body

Parameters:
name -
filename -
contentType - value of the Content-Type part header
part -
Returns:
this request
Throws:
HttpRequest.HttpRequestException

part

public HttpRequest part(java.lang.String name,
                        java.lang.String filename,
                        java.lang.String contentType,
                        java.lang.String part)
                 throws HttpRequest.HttpRequestException
Write part of a multipart request to the request body

Parameters:
name -
filename -
contentType - value of the Content-Type part header
part -
Returns:
this request
Throws:
HttpRequest.HttpRequestException

partHeader

public HttpRequest partHeader(java.lang.String name,
                              java.lang.String value)
                       throws HttpRequest.HttpRequestException
Write a multipart header to the response body

Parameters:
name -
value -
Returns:
this request
Throws:
HttpRequest.HttpRequestException

post

public static HttpRequest post(java.lang.CharSequence url)
                        throws HttpRequest.HttpRequestException
Start a 'POST' request to the given URL

Parameters:
url -
Returns:
request
Throws:
HttpRequest.HttpRequestException

post

public static HttpRequest post(java.lang.CharSequence baseUrl,
                               boolean encode,
                               java.lang.Object... params)
Start a 'POST' request to the given URL along with the query params

Parameters:
baseUrl -
encode - true to encode the full URL
params - the name/value query parameter pairs to include as part of the baseUrl
Returns:
request
See Also:
#append(CharSequence, String...), encode(CharSequence)

post

public static HttpRequest post(java.lang.CharSequence baseUrl,
                               java.util.Map<?,?> params,
                               boolean encode)
Start a 'POST' request to the given URL along with the query params

Parameters:
baseUrl -
params - the query parameters to include as part of the baseUrl
encode - true to encode the full URL
Returns:
request
See Also:
append(CharSequence, Map), encode(CharSequence)

post

public static HttpRequest post(java.net.URL url)
                        throws HttpRequest.HttpRequestException
Start a 'POST' request to the given URL

Parameters:
url -
Returns:
request
Throws:
HttpRequest.HttpRequestException

proxyHost

public static void proxyHost(java.lang.String host)
Set the 'http.proxyHost' & 'https.proxyHost' properties to the given host value.

This setting will apply to requests.

Parameters:
host -

proxyPort

public static void proxyPort(int port)
Set the 'http.proxyPort' & 'https.proxyPort' properties to the given port number.

This setting will apply to requests.

Parameters:
port -

put

public static HttpRequest put(java.lang.CharSequence url)
                       throws HttpRequest.HttpRequestException
Start a 'PUT' request to the given URL

Parameters:
url -
Returns:
request
Throws:
HttpRequest.HttpRequestException

put

public static HttpRequest put(java.lang.CharSequence baseUrl,
                              boolean encode,
                              java.lang.Object... params)
Start a 'PUT' request to the given URL along with the query params

Parameters:
baseUrl -
encode - true to encode the full URL
params - the name/value query parameter pairs to include as part of the baseUrl
Returns:
request
See Also:
#append(CharSequence, String...), encode(CharSequence)

put

public static HttpRequest put(java.lang.CharSequence baseUrl,
                              java.util.Map<?,?> params,
                              boolean encode)
Start a 'PUT' request to the given URL along with the query params

Parameters:
baseUrl -
params - the query parameters to include as part of the baseUrl
encode - true to encode the full URL
Returns:
request
See Also:
append(CharSequence, Map), encode(CharSequence)

put

public static HttpRequest put(java.net.URL url)
                       throws HttpRequest.HttpRequestException
Start a 'PUT' request to the given URL

Parameters:
url -
Returns:
request
Throws:
HttpRequest.HttpRequestException

reader

public java.io.InputStreamReader reader()
                                 throws HttpRequest.HttpRequestException
Get reader to response body using the character set returned from charset()

Returns:
reader
Throws:
HttpRequest.HttpRequestException

reader

public java.io.InputStreamReader reader(java.lang.String charset)
                                 throws HttpRequest.HttpRequestException
Get reader to response body using given character set.

This will fall back to using the UTF-8 character set if the given charset is null

Parameters:
charset -
Returns:
reader
Throws:
HttpRequest.HttpRequestException

readTimeout

public HttpRequest readTimeout(int timeout)
Set read timeout on connection to given value

Parameters:
timeout -
Returns:
this request

receive

public HttpRequest receive(java.lang.Appendable appendable)
                    throws HttpRequest.HttpRequestException
Receive response into the given appendable

Parameters:
appendable -
Returns:
this request
Throws:
HttpRequest.HttpRequestException

receive

public HttpRequest receive(java.io.File file)
                    throws HttpRequest.HttpRequestException
Stream response body to file

Parameters:
file -
Returns:
this request
Throws:
HttpRequest.HttpRequestException

receive

public HttpRequest receive(java.io.OutputStream output)
                    throws HttpRequest.HttpRequestException
Stream response to given output stream

Parameters:
output -
Returns:
this request
Throws:
HttpRequest.HttpRequestException

receive

public HttpRequest receive(java.io.PrintStream output)
                    throws HttpRequest.HttpRequestException
Stream response to given print stream

Parameters:
output -
Returns:
this request
Throws:
HttpRequest.HttpRequestException

receive

public HttpRequest receive(java.io.Writer writer)
                    throws HttpRequest.HttpRequestException
Receive response into the given writer

Parameters:
writer -
Returns:
this request
Throws:
HttpRequest.HttpRequestException

send

public HttpRequest send(byte[] input)
                 throws HttpRequest.HttpRequestException
Write byte array to request body

Parameters:
input -
Returns:
this request
Throws:
HttpRequest.HttpRequestException

send

public HttpRequest send(java.lang.CharSequence value)
                 throws HttpRequest.HttpRequestException
Write char sequence to request body

The charset configured via contentType(String) will be used and UTF-8 will be used if it is unset.

Parameters:
value -
Returns:
this request
Throws:
HttpRequest.HttpRequestException

send

public HttpRequest send(java.io.File input)
                 throws HttpRequest.HttpRequestException
Write contents of file to request body

Parameters:
input -
Returns:
this request
Throws:
HttpRequest.HttpRequestException

send

public HttpRequest send(java.io.InputStream input)
                 throws HttpRequest.HttpRequestException
Write stream to request body

The given stream will be closed once sending completes

Parameters:
input -
Returns:
this request
Throws:
HttpRequest.HttpRequestException

send

public HttpRequest send(java.io.Reader input)
                 throws HttpRequest.HttpRequestException
Write reader to request body

The given reader will be closed once sending completes

Parameters:
input -
Returns:
this request
Throws:
HttpRequest.HttpRequestException

server

public java.lang.String server()
Get the 'Server' header from the response

Returns:
server

serverError

public boolean serverError()
                    throws HttpRequest.HttpRequestException
Is the response code a 500 Internal Server Error?

Returns:
true if 500, false otherwise
Throws:
HttpRequest.HttpRequestException

stream

public java.io.InputStream stream()
                           throws HttpRequest.HttpRequestException
Get stream to response body

Returns:
stream
Throws:
HttpRequest.HttpRequestException

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object

trace

public static HttpRequest trace(java.lang.CharSequence url)
                         throws HttpRequest.HttpRequestException
Start a 'TRACE' request to the given URL

Parameters:
url -
Returns:
request
Throws:
HttpRequest.HttpRequestException

trace

public static HttpRequest trace(java.net.URL url)
                         throws HttpRequest.HttpRequestException
Start a 'TRACE' request to the given URL

Parameters:
url -
Returns:
request
Throws:
HttpRequest.HttpRequestException

trustAllCerts

public HttpRequest trustAllCerts()
                          throws HttpRequest.HttpRequestException
Configure HTTPS connection to trust all certificates

This method does nothing if the current request is not a HTTPS request

Returns:
this request
Throws:
HttpRequest.HttpRequestException

trustAllHosts

public HttpRequest trustAllHosts()
Configure HTTPS connection to trust all hosts using a custom HostnameVerifier that always returns true for each host verified

This method does nothing if the current request is not a HTTPS request

Returns:
this request

uncompress

public HttpRequest uncompress(boolean uncompress)
Set whether or not the response body should be automatically uncompressed when read from.

This will only affect requests that have the 'Content-Encoding' response header set to 'gzip'.

This causes all receive methods to use a GZIPInputStream when applicable so that higher level streams and readers can read the data uncompressed.

Setting this option does not cause any request headers to be set automatically so acceptGzipEncoding() should be used in conjunction with this setting to tell the server to gzip the response.

Parameters:
uncompress -
Returns:
this request

useCaches

public HttpRequest useCaches(boolean useCaches)
Set value of URLConnection.setUseCaches(boolean)

Parameters:
useCaches -
Returns:
this request

userAgent

public HttpRequest userAgent(java.lang.String value)
Set the 'User-Agent' header to given value

Parameters:
value -
Returns:
this request

writer

public java.io.OutputStreamWriter writer()
                                  throws HttpRequest.HttpRequestException
Create writer to request output stream

Returns:
writer
Throws:
HttpRequest.HttpRequestException