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. HttpEasy.withDefaults() - allows you to set some settings that apply to all requests such as configuring a proxy 1. HttpEasy.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

 HttpEasyReader r = HttpEasy.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:

 HttpEasy.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)

 HttpEasy.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...

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

Logging

Logging of requests and responses can be enabled by logRequestDetails() or, if using Eclipse, the TCP/IP Monitor utility.

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	data(java.lang.Object data, com.google.common.net.MediaType mediaType, java.lang.String fileName) 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(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.io.File value, com.google.common.net.MediaType type) Add a simple text field, if urlEncodedForm() has been used will try to guess the content type.
HttpEasy	field(java.lang.String name, java.io.InputStream value, com.google.common.net.MediaType type, java.lang.String fileName) Add a text field or attach file.
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 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, java.lang.String fileName) Add a text field or attach file.
HttpEasyReader	get() Performs an HTTP GET.
com.inedo.http.EventManager	getEventManager()
HttpEasyReader	head() Performs an HTTP HEAD.
HttpEasy	header(java.lang.String name, java.lang.String value) Add a header to request.
HttpEasy	logRequestDetails() If called will cause the request and response details to be logged.
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.
HttpEasy	queryParam(java.lang.String name, java.lang.Object value) Appends parameter to query portion of url.
static HttpEasy	request()
HttpEasy	setTimeout(int milliseconds) Sets a specified timeout value, in milliseconds, to be used when opening a communications link to the resource referenced by this URLConnection, and when reading from Input stream when a connection is established .
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	withLogListener(HttpEasyListener listener)

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

setTimeout

public HttpEasy setTimeout(int milliseconds)

Sets a specified timeout value, in milliseconds, to be used when opening a communications link to the resource referenced by this URLConnection, and when reading from Input stream when a connection is established . If the timeout expires a java.net.SocketTimeoutException is raised. A timeout of zero is interpreted as an infinite timeout.

Parameters:

milliseconds - Timeout value in milliseconds

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

queryParam

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

Appends parameter to query portion of url.

• If value is null then parameter will not be added
• If value is empty then parameter will be added as 'name='

Parameters:

name - Parameter name

value - Parameter value

Returns:

A self reference

logRequestDetails

public HttpEasy logRequestDetails()

If called will cause the request and response details to be logged.

An alternative to this if using Eclipse is to use the TCP/IP monitor

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.

See field(String, Object, MediaType, String)

Parameters:

name - Field name

value - Field value - this should not be URL Encoded!

Returns:

A self reference

field

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

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

See field(String, Object, MediaType, String)

Parameters:

name - Field name

value - Field value - this should not be URL Encoded!

type - Field's media type

Returns:

A self reference

field

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

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

See field(String, Object, MediaType, String)

Parameters:

name - Field name

value - File

type - File's media type

Returns:

A self reference

field

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

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

See field(String, Object, MediaType, String)

Parameters:

name - Field's name

value - Field's value - File, Inputstream, or object easily converted to a string

type - Field's media type

fileName - Field's file name - only required if field is an InputStream as this is assumed to be an attachment

Returns:

A self reference

field

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

Add a text field or attach file.

• If value is not a file then it must be easily converted to a string
• If value is an InputStream it is assumed to be a file attachment and the file name must be provided

If urlEncodedForm() or dataForm() have not been called then the form type will be auto selected: if field containing a file or input stream 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, if File or Inputstream will upload content as "multipart/form-data"

type - Field's media type

fileName - name of

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 object easily converted to a string

mediaType - Media type of the data

Returns:

A self reference

data

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

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, InputStream, or object easily converted to a string

mediaType - Media type of the data

fileName - name of file

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(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

withLogListener

public HttpEasy withLogListener(HttpEasyListener listener)

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

getEventManager

public com.inedo.http.EventManager getEventManager()