HttpEasy (inedo-proget-plugin 0.7 API)

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

Constructors
Constructor and Description
`HttpEasy()`

Method Summary

All Methods Static Methods Instance Methods Concrete 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()
```

Class HttpEasy

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

HttpEasy

Method Detail

withDefaults

request

header

authorization

setTimeout

baseURI

path

query

queryParam

logRequestDetails

parameterTokens

urlParameters

dataForm

urlEncodedForm

field

field

field

field

field

data

data

doNotFailOn

doNotFailOn

withLogListener

get

head

post

put

delete

getEventManager