com.inedo.http

Class HttpEasy

java.lang.Object

com.inedo.http.HttpEasy

public class HttpEasy
extends java.lang.Object

Fluent wrapper around HttpURLConnection with full support for HTTP messages such as GET, POST, HEAD, etc and supports the REST and SOAP protocols and parsing JSON and XML responses.

This is been designed with as a fluent REST API similar to RestEasy and RestAssurred with the only real difference being that it has great proxy support.

There are two starting points for creating a rest request: 1. RestRequest.withDefaults() - allows you to set some settings that apply to all requests such as configuring a proxy 1. RestRequest.request() - performs the actual call, these HTTP methods are implemented: GET, HEAD, POST, PUT, DELETE

Note: if your url can contain weird characters you will want to encode it, something like this: myUrl = URLEncoder.encode(myUrl, "UTF-8");

Example

 RestResultReader r = RestRequest.request()
                          .baseURI(someUrl) 
                          .path(viewPath + "?startkey=\"{startkey}\"&endkey=\"{endkey}\") 
                          .urlParameters(startKey[0], endKey[0])
                          .get();
 
 String id = r.jsonPath("rows[0].doc._id").getAsString(); 
 String rev = r.jsonPath("rows[0].doc._rev").getAsString();
 

Error Handling

An IOException is thrown whenever a call returns a response code that is not part of the SUCCESS family (ie 200-299).

In order to prevent an exception being thrown for an expected response use one of the following methods: * request().doNotFailOn(Integer... reponseCodes) * request().doNotFailOn(Family... responseFamily)

Authentication

Supports two formats * http://username:password@where.ever * request().authorization(username, password)

Host and Certificate Verification

There is no fine grained control, its more of an all or nothing approach:

 RestRequest.withDefaults() 
     .allowAllHosts() 
     .trustAllCertificates();
 

Proxy

Only basic authentication is supported, although I believe the domain can be added by included "domain/" in front of the username (not tested)

 RestRequest.withDefaults() 
     .proxy(new Proxy(Proxy.Type.HTTP, new InetSocketAddress(user, password)))) 
     .proxyAuth(userName, password) 
     .bypassProxyForLocalAddresses(true);
 

Redirects

Redirects are NOT automatically followed - at least for REST base calls - even though the documentation for HttpURLConnection says that it should...

 RestResultReader response = RestRequest.request()
     .doNotFailOn(Family.REDIRECTION) 
     .path(url) 
     .head();
 
 if (response.getResponseCodeFamily() == Family.REDIRECTION) {
     url = response.getHeaderField("Location");
     ... 
 }
 

Constructor Summary

Constructors

Constructor and Description
HttpEasy()

Method Summary

Methods

Modifier and Type	Method and Description
HttpEasy	authorization(java.lang.String username, java.lang.String password) Add an authorization header to request.
HttpEasy	baseURI(java.lang.String uri) Set the host and port of the URL for the end-point.
HttpEasy	data(java.lang.Object data, com.google.common.net.MediaType mediaType) Sets the content type request property to the value of the supplied media type.
HttpEasy	dataForm() Sets the content type request property to "multipart/form-data" Any data that is required must be added via field(name, value, mediaType) method.
HttpEasyReader	delete() Performs an HTTP DELETE.
HttpEasy	doNotFailOn(HttpEasyReader.Family... responseFamily) Add a list of response family codes to ignore that would otherwise case a exception to be thrown.
HttpEasy	doNotFailOn(java.lang.Integer... reponseCodes) Add a list of response codes to ignore that would otherwise case a exception to be thrown.
HttpEasy	field(java.lang.String name, java.lang.Object value) Add a simple text field, if urlEncodedForm() has been used will try to guess the content type.
HttpEasy	field(java.lang.String name, java.lang.Object value, com.google.common.net.MediaType type) Add a text field or attach file.
HttpEasyReader	get() Performs an HTTP GET.
HttpEasyReader	head() Performs an HTTP HEAD.
HttpEasy	header(java.lang.String name, java.lang.String value) Add a header to request.
HttpEasy	parameterTokens(java.lang.String startToken, java.lang.String endToken) Override the default parameter start and end tokens.
HttpEasy	path(java.lang.String path) Set the path part of the URL for the end-point.
HttpEasyReader	post() Performs an HTTP POST.
HttpEasyReader	put() Performs an HTTP PUT.
HttpEasy	query(java.lang.String query) Set the query part of the URL for the end-point.
static HttpEasy	request()
HttpEasy	urlEncodedForm() Sets the content type request property to "application/x-www-form-urlencoded" Any data that is required must be added via field(name, value) method and the value must be easily converted to a string value.
HttpEasy	urlParameters(java.lang.Object... pathParams) Set the parameter values for the parameters in the URL.
static HttpEasyDefaults	withDefaults()
HttpEasy	withLogWriter(LogWriter logWriter)

Methods inherited from class java.lang.Object

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

Constructor Detail

HttpEasy

public HttpEasy()

Method Detail

withDefaults

public static HttpEasyDefaults withDefaults()

Returns:

Default settings object

request

public static HttpEasy request()

Returns:

Request object

header

public HttpEasy header(java.lang.String name,
              java.lang.String value)

Add a header to request.

Parameters:

name - Header name

value - Header value

Returns:

A self reference

authorization

public HttpEasy authorization(java.lang.String username,
                     java.lang.String password)

Add an authorization header to request.

Parameters:

username - username

password - password

Returns:

A self reference

baseURI

public HttpEasy baseURI(java.lang.String uri)

Set the host and port of the URL for the end-point. baseURI, path and query are helpers only and any of these can take full URL.

Parameters:

uri - The host and port of the URL

Returns:

A self reference

path

public HttpEasy path(java.lang.String path)

Set the path part of the URL for the end-point. baseURI, path and query are helpers only and any of these can take full URL.

Parameters:

path - The host and port of the URL

Returns:

A self reference

query

public HttpEasy query(java.lang.String query)

Set the query part of the URL for the end-point. baseURI, path and query are helpers only and any of these can take full URL.

Parameters:

query - The host and port of the URL

Returns:

A self reference

parameterTokens

public HttpEasy parameterTokens(java.lang.String startToken,
                       java.lang.String endToken)

Override the default parameter start and end tokens. By default any part of the url containing {...} is treated as a parameter and replaced by the values passed in by urlParameters(Object...).

Parameters:

startToken - Start token

endToken - End Token

Returns:

A self reference

urlParameters

public HttpEasy urlParameters(java.lang.Object... pathParams)

Set the parameter values for the parameters in the URL.

Parameters:

pathParams - A list of parameters to fill in any parameters required by the URL. These are replaced in the order they are found in the URL.

Returns:

A self reference

dataForm

public HttpEasy dataForm()

Sets the content type request property to "multipart/form-data" Any data that is required must be added via field(name, value, mediaType) method. Files are supported but any other objects must be easily converted to a string value.

Returns:

A self reference

urlEncodedForm

public HttpEasy urlEncodedForm()

Sets the content type request property to "application/x-www-form-urlencoded" Any data that is required must be added via field(name, value) method and the value must be easily converted to a string value.

Returns:

A self reference

field

public HttpEasy field(java.lang.String name,
             java.lang.Object value)

Add a simple text field, if urlEncodedForm() has been used will try to guess the content type.

If urlEncodedForm() or dataForm() have not been called then the form type will be auto selected: if field containing a file has been added then content type will be set to "multipart/form-data" else it will be set to "application/x-www-form-urlencoded"

Parameters:

name - Field name

value - Field value

Returns:

A self reference

field

public HttpEasy field(java.lang.String name,
             java.lang.Object value,
             com.google.common.net.MediaType type)

Add a text field or attach file. If value is not a file then it must be easily converted to a string.

If urlEncodedForm() or dataForm() have not been called then the form type will be auto selected: if field containing a file has been added then content type will be set to "multipart/form-data" else it will be set to "application/x-www-form-urlencoded"

Parameters:

name - Field's name

value - Field's value

type - Field's media type

Returns:

A self reference

data

public HttpEasy data(java.lang.Object data,
            com.google.common.net.MediaType mediaType)

Sets the content type request property to the value of the supplied media type. This can only be called once as passing raw data can only support one text block or binary file. With this in mind files are supported but any other objects must be easily converted to a string value.

Parameters:

data - File or String containing the data

mediaType - Media type of the data

Returns:

A self reference

doNotFailOn

public HttpEasy doNotFailOn(java.lang.Integer... reponseCodes)

Add a list of response codes to ignore that would otherwise case a exception to be thrown. Example: doNotFailOn(HttpURLConnection.HTTP_CONFLICT)

Parameters:

reponseCodes - A list of failing response codes

Returns:

A self reference

doNotFailOn

public HttpEasy doNotFailOn(HttpEasyReader.Family... responseFamily)

Add a list of response family codes to ignore that would otherwise case a exception to be thrown. Example: doNotFailOn(Family.REDIRECTION)

Parameters:

responseFamily - A list of failing response family codes

Returns:

A self reference

withLogWriter

public HttpEasy withLogWriter(LogWriter logWriter)

get

public HttpEasyReader get()
                   throws java.io.IOException

Performs an HTTP GET.

Returns:

The request response wrapped by HttpEasyReader

Throws:

java.io.IOException - If any connection or request errors

head

public HttpEasyReader head()
                    throws java.io.IOException

Performs an HTTP HEAD.

Returns:

The request response wrapped by HttpEasyReader

Throws:

java.io.IOException - If any connection or request errors

post

public HttpEasyReader post()
                    throws java.io.IOException

Performs an HTTP POST.

Returns:

The request response wrapped by HttpEasyReader

Throws:

java.io.IOException - If any connection or request errors

put

public HttpEasyReader put()
                   throws java.io.IOException

Performs an HTTP PUT.

Returns:

The request response wrapped by HttpEasyReader

Throws:

java.io.IOException - If any connection or request errors

delete

public HttpEasyReader delete()
                      throws java.io.IOException

Performs an HTTP DELETE.

Returns:

The request response wrapped by HttpEasyReader

Throws:

java.io.IOException - If any connection or request errors