org.sakaiproject.entitybroker.util.http
Class HttpRESTUtils

java.lang.Object
  org.sakaiproject.entitybroker.util.http.HttpRESTUtils

public class HttpRESTUtils
extends Object

Utilities for generating and processing http requests, allows the developer to fire off a request and get back information about the response
All encoding is automatically UTF-8

Author:

Aaron Zeckoski (azeckoski @ gmail.com)

Nested Class Summary

static class	HttpRESTUtils.HttpIOException Indicates an IO failure
static class	HttpRESTUtils.HttpRequestException Indicates a general failure
static class	HttpRESTUtils.Method

Field Summary

static String	CONTENT_TYPE_UTF8
static String	ENCODING_UTF8
static int	MAX_RESPONSE_SIZE_CHARS

Constructor Summary

HttpRESTUtils()

Method Summary

static String	encodeDateHttp(Date date) Encode a date into an http date string
static HttpResponse	fireRequest(HttpClientWrapper httpClientWrapper, String URL, HttpRESTUtils.Method method, Map<String,String> params, Map<String,String> headers, Object data, boolean guaranteeSSL) Fire off a request to a URL using the specified method but reuse the client for efficiency, include optional params and data in the request, the response data will be returned in the object if the request can be carried out
static HttpResponse	fireRequest(HttpClientWrapper httpClientWrapper, String URL, HttpRESTUtils.Method method, Map<String,String> params, Object data, boolean guaranteeSSL) Fire off a request to a URL using the specified method but reuse the client for efficiency, include optional params and data in the request, the response data will be returned in the object if the request can be carried out
static HttpResponse	fireRequest(String URL, HttpRESTUtils.Method method) Fire off a request to a URL using the specified method, include optional params and data in the request, the response data will be returned in the object if the request can be carried out
static HttpResponse	fireRequest(String URL, HttpRESTUtils.Method method, Map<String,String> params) Fire off a request to a URL using the specified method, include optional params and data in the request, the response data will be returned in the object if the request can be carried out
static HttpResponse	fireRequest(String URL, HttpRESTUtils.Method method, Map<String,String> params, Map<String,String> headers, Object data, boolean guaranteeSSL) Fire off a request to a URL using the specified method, include optional params, headers, and data in the request, the response data will be returned in the object if the request can be carried out
static HttpResponse	fireRequest(String URL, HttpRESTUtils.Method method, Map<String,String> params, Object data, boolean guaranteeSSL) Fire off a request to a URL using the specified method, include optional params and data in the request, the response data will be returned in the object if the request can be carried out
protected static void	handleRequestData(org.apache.commons.httpclient.methods.EntityEnclosingMethod method, Object data)
static HttpRESTUtils.Method	makeMethodFromString(String method) Turns a method string ("get") into a HttpRESTUtils.Method enum object
static HttpClientWrapper	makeReusableHttpClient(boolean multiThreaded, int idleConnectionTimeout, javax.servlet.http.Cookie[] cookies) Generates a reusable http client wrapper which can be given to fireRequest(HttpClientWrapper, String, Method, Map, Object, boolean) as an efficiency mechanism
static String	mergeQueryStringWithParams(String queryString, Map<String,String> params) Merges an existing queryString with a set of params to create one queryString, this basically just adds the params to the end of the existing query string and will not insert a "?"
static URLData	parseURL(String urlString) Parses a url string into component pieces, unlike the java URL class, this will work with partial urls
static Map<String,String>	parseURLintoParams(String urlString) Get the query parameters out of a query string and return them as a map, this can be
protected static String	urlEncodeUTF8(String toEncode)

Methods inherited from class java.lang.Object

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

Field Detail

CONTENT_TYPE_UTF8

public static final String CONTENT_TYPE_UTF8

See Also:

Constant Field Values

ENCODING_UTF8

public static final String ENCODING_UTF8

See Also:

Constant Field Values

MAX_RESPONSE_SIZE_CHARS

public static final int MAX_RESPONSE_SIZE_CHARS

See Also:

Constant Field Values

Constructor Detail

HttpRESTUtils

public HttpRESTUtils()

Method Detail

fireRequest

public static HttpResponse fireRequest(String URL,
                                       HttpRESTUtils.Method method)

Fire off a request to a URL using the specified method, include optional params and data in the request, the response data will be returned in the object if the request can be carried out

Parameters:

URL - the url to send the request to (absolute or relative, can include query params)

method - the method to use (e.g. GET, POST, etc.)

Returns:

an object representing the response, includes data about the response

Throws:

HttpRESTUtils.HttpRequestException - if the request cannot be processed for some reason (this is unrecoverable)

fireRequest

public static HttpResponse fireRequest(String URL,
                                       HttpRESTUtils.Method method,
                                       Map<String,String> params)

Fire off a request to a URL using the specified method, include optional params and data in the request, the response data will be returned in the object if the request can be carried out

Parameters:

URL - the url to send the request to (absolute or relative, can include query params)

method - the method to use (e.g. GET, POST, etc.)

params - (optional) params to send along with the request, will be encoded in the query string or in the body depending on the method

Returns:

an object representing the response, includes data about the response

Throws:

HttpRESTUtils.HttpRequestException - if the request cannot be processed for some reason (this is unrecoverable)

fireRequest

public static HttpResponse fireRequest(String URL,
                                       HttpRESTUtils.Method method,
                                       Map<String,String> params,
                                       Object data,
                                       boolean guaranteeSSL)

Fire off a request to a URL using the specified method, include optional params and data in the request, the response data will be returned in the object if the request can be carried out

Parameters:

URL - the url to send the request to (absolute or relative, can include query params)

method - the method to use (e.g. GET, POST, etc.)

params - (optional) params to send along with the request, will be encoded in the query string or in the body depending on the method

data - (optional) data to send along in the body of the request, this only works for POST and PUT requests, ignored for the other types

guaranteeSSL - if this is true then the request is sent in a mode which will allow self signed certs to work, otherwise https requests will fail if the certs cannot be centrally verified

Returns:

an object representing the response, includes data about the response

Throws:

HttpRESTUtils.HttpRequestException - if the request cannot be processed for some reason (this is unrecoverable)

fireRequest

public static HttpResponse fireRequest(String URL,
                                       HttpRESTUtils.Method method,
                                       Map<String,String> params,
                                       Map<String,String> headers,
                                       Object data,
                                       boolean guaranteeSSL)

Fire off a request to a URL using the specified method, include optional params, headers, and data in the request, the response data will be returned in the object if the request can be carried out

Parameters:

URL - the url to send the request to (absolute or relative, can include query params)

method - the method to use (e.g. GET, POST, etc.)

params - (optional) params to send along with the request, will be encoded in the query string or in the body depending on the method

params - (optional) headers to send along with the request, will be encoded in the headers

data - (optional) data to send along in the body of the request, this only works for POST and PUT requests, ignored for the other types

guaranteeSSL - if this is true then the request is sent in a mode which will allow self signed certs to work, otherwise https requests will fail if the certs cannot be centrally verified

Returns:

an object representing the response, includes data about the response

Throws:

HttpRESTUtils.HttpRequestException - if the request cannot be processed for some reason (this is unrecoverable)

fireRequest

public static HttpResponse fireRequest(HttpClientWrapper httpClientWrapper,
                                       String URL,
                                       HttpRESTUtils.Method method,
                                       Map<String,String> params,
                                       Object data,
                                       boolean guaranteeSSL)

Fire off a request to a URL using the specified method but reuse the client for efficiency, include optional params and data in the request, the response data will be returned in the object if the request can be carried out

Parameters:

httpClientWrapper - (optional) allows the http client to be reused for efficiency, if null a new one will be created each time, use #makeReusableHttpClient(boolean, int) to create a reusable instance

URL - the url to send the request to (absolute or relative, can include query params)

method - the method to use (e.g. GET, POST, etc.)

params - (optional) params to send along with the request, will be encoded in the query string or in the body depending on the method

data - (optional) data to send along in the body of the request, this only works for POST and PUT requests, ignored for the other types

guaranteeSSL - if this is true then the request is sent in a mode which will allow self signed certs to work, otherwise https requests will fail if the certs cannot be centrally verified

Returns:

an object representing the response, includes data about the response

Throws:

HttpRESTUtils.HttpRequestException - if the request cannot be processed for some reason (this is unrecoverable)

fireRequest

public static HttpResponse fireRequest(HttpClientWrapper httpClientWrapper,
                                       String URL,
                                       HttpRESTUtils.Method method,
                                       Map<String,String> params,
                                       Map<String,String> headers,
                                       Object data,
                                       boolean guaranteeSSL)

Fire off a request to a URL using the specified method but reuse the client for efficiency, include optional params and data in the request, the response data will be returned in the object if the request can be carried out

Parameters:

httpClientWrapper - (optional) allows the http client to be reused for efficiency, if null a new one will be created each time, use #makeReusableHttpClient(boolean, int) to create a reusable instance

URL - the url to send the request to (absolute or relative, can include query params)

method - the method to use (e.g. GET, POST, etc.)

params - (optional) params to send along with the request, will be encoded in the query string or in the body depending on the method

params - (optional) headers to send along with the request, will be encoded in the headers

data - (optional) data to send along in the body of the request, this only works for POST and PUT requests, ignored for the other types

guaranteeSSL - if this is true then the request is sent in a mode which will allow self signed certs to work, otherwise https requests will fail if the certs cannot be centrally verified

Returns:

an object representing the response, includes data about the response

Throws:

HttpRESTUtils.HttpRequestException - if the request cannot be processed for some reason (this is unrecoverable)

mergeQueryStringWithParams

public static String mergeQueryStringWithParams(String queryString,
                                                Map<String,String> params)

Merges an existing queryString with a set of params to create one queryString, this basically just adds the params to the end of the existing query string and will not insert a "?" but will take care of the "&"s

Parameters:

queryString - the query string in URL encoded form, without a leading '?'

params - a set of key->value strings to use as params for the request

Returns:

the merged queryString with the params included

parseURLintoParams

public static Map<String,String> parseURLintoParams(String urlString)

Get the query parameters out of a query string and return them as a map, this can be

Parameters:

urlString - a complete URL with query string at the end or a partial URL or just a query string only (e.g. /thing/stuff?blah=1&apple=fruit

Returns:

the map of all query string parameters (e.g. blah => 1, apple => fruit)

urlEncodeUTF8

protected static String urlEncodeUTF8(String toEncode)

handleRequestData

protected static void handleRequestData(org.apache.commons.httpclient.methods.EntityEnclosingMethod method,
                                        Object data)

parseURL

public static URLData parseURL(String urlString)

Parses a url string into component pieces, unlike the java URL class, this will work with partial urls

Parameters:

urlString - any URL string

Returns:

the URL data object

makeMethodFromString

public static HttpRESTUtils.Method makeMethodFromString(String method)

Turns a method string ("get") into a HttpRESTUtils.Method enum object

Parameters:

method - a method string (case is not important) e.g. GET, Post, put, DeLeTe

Returns:

the corresponding HttpRESTUtils.Method enum

makeReusableHttpClient

public static HttpClientWrapper makeReusableHttpClient(boolean multiThreaded,
                                                       int idleConnectionTimeout,
                                                       javax.servlet.http.Cookie[] cookies)

Generates a reusable http client wrapper which can be given to fireRequest(HttpClientWrapper, String, Method, Map, Object, boolean) as an efficiency mechanism

Parameters:

multiThreaded - true if you want to allow the client to run in multiple threads

idleConnectionTimeout - if this is 0 then it will use the defaults, otherwise connections will be timed out after this long (ms)

cookies - to send along with every request from this client

Returns:

the reusable http client wrapper

encodeDateHttp

public static String encodeDateHttp(Date date)

Encode a date into an http date string

Parameters:

date - the date

Returns:

the date string or an empty string if the date is null