it.could.util.http
Class HttpClient

java.lang.Object
  extended byit.could.util.http.HttpClient

public class HttpClient
extends Object

A class implementing an extremely simple HTTP 1.0 connector with basic authentication support.

Author:
Pier Fumagalli

Field Summary
static String DEFAULT_METHOD
          The default HTTP method to use.
 
Constructor Summary
HttpClient(Location location)
          Create a new HttpClient instance associated with the specified Location.
HttpClient(String location)
          Create a new HttpClient instance associated with the specified location in string format.
HttpClient(String location, String encoding)
          Create a new HttpClient instance associated with the specified location in string format.
 
Method Summary
 HttpClient addRequestHeader(String name, String value)
          Add a new header that will be sent with the HTTP request.
 HttpClient addRequestHeader(String name, String value, boolean appendValue)
          Add a new header that will be sent with the HTTP request.
 HttpClient connect()
          Connect to the Location specified at construction using the default method GET.
 HttpClient connect(boolean followRedirects)
          Connect to the Location specified at construction using the default method GET and optionally following redirects.
 HttpClient connect(long contentLength)
          Connect to the Location specified at construction using the default method GET allowing for a specified amount of content to be written into the request.
 HttpClient connect(String method)
          Connect to the Location specified at construction with the specified method.
 HttpClient connect(String method, boolean followRedirects)
          Connect to the Location specified at construction with the specified method and optionally following redirects.
 HttpClient connect(String method, long contentLength)
          Connect to the Location specified at construction with the specified method allowing for a specified amount of content to be written into the request.
 HttpClient disconnect()
          Disconnect from the remote endpoint and terminate the request.
 HttpClient disconnect(boolean reset)
          Disconnect from the remote endpoint and terminate the request.
 Location getLocation()
          Return the Location of this connection.
 OutputStream getRequestStream()
          Return an OutputStream where the content of the HTTP request can be written to.
 String getResponseHeader(String name)
          Return the first value for the specified response header.
 Iterator getResponseHeaderNames()
          Return an Iterator over all response header names.
 List getResponseHeaderValues(String name)
          Return all the values for the specified response header.
 String getResponseMessage()
          Return the status message returned by the remote HTTP server.
 String getResponseProtocol()
          Return the protocol returned by the remote HTTP server.
 int getResponseStatus()
          Return the status returned by the remote HTTP server.
 InputStream getResponseStream()
          Return an InputStream where the content of the HTTP response can be read from.
static void main(String[] args)
          Utility method: fetch the location specified on the command line following redirects if necessary.
 HttpClient removeRequestHeader(String name)
          Remove the named header from the current HTTP request.
 HttpClient removeRequestHeaders()
          Remove all headers from the current HTTP request.
 HttpClient setAcceptableStatus(int status)
          Set an HTTP response status code considered to be acceptable when verifying the connection.
 HttpClient setAcceptableStatuses(int[] statuses)
          Set an array of HTTP response status codes considered to be acceptable when verifying the connection.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_METHOD

public static final String DEFAULT_METHOD

The default HTTP method to use.

See Also:
Constant Field Values
Constructor Detail

HttpClient

public HttpClient(String location)
           throws MalformedURLException

Create a new HttpClient instance associated with the specified location in string format.

Throws:
MalformedURLException - if the location couldn't be parsed.

HttpClient

public HttpClient(String location,
                  String encoding)
           throws MalformedURLException,
                  UnsupportedEncodingException

Create a new HttpClient instance associated with the specified location in string format.

Throws:
MalformedURLException - if the location couldn't be parsed.
UnsupportedEncodingException

HttpClient

public HttpClient(Location location)

Create a new HttpClient instance associated with the specified Location.

Method Detail

setAcceptableStatus

public HttpClient setAcceptableStatus(int status)

Set an HTTP response status code considered to be acceptable when verifying the connection.


setAcceptableStatuses

public HttpClient setAcceptableStatuses(int[] statuses)

Set an array of HTTP response status codes considered to be acceptable when verifying the connection.

If the array is null status code checking is disabled.


connect

public HttpClient connect()
                   throws IOException

Connect to the Location specified at construction using the default method GET.

This is equivalent to connect(true).

Returns:
this HttpClient instance.
Throws:
IOException - if an I/O or a network error occurred.

connect

public HttpClient connect(long contentLength)
                   throws IOException

Connect to the Location specified at construction using the default method GET allowing for a specified amount of content to be written into the request.

Returns:
this HttpClient instance.
Throws:
IOException - if an I/O or a network error occurred.

connect

public HttpClient connect(boolean followRedirects)
                   throws IOException

Connect to the Location specified at construction using the default method GET and optionally following redirects.

Returns:
this HttpClient instance.
Throws:
IOException - if an I/O or a network error occurred.

connect

public HttpClient connect(String method)
                   throws IOException

Connect to the Location specified at construction with the specified method.

This is equivalent to connect(method, true).

Returns:
this HttpClient instance.
Throws:
IOException - if an I/O or a network error occurred.

connect

public HttpClient connect(String method,
                          long contentLength)
                   throws IOException

Connect to the Location specified at construction with the specified method allowing for a specified amount of content to be written into the request.

Returns:
this HttpClient instance.
Throws:
IOException - if an I/O or a network error occurred.

connect

public HttpClient connect(String method,
                          boolean followRedirects)
                   throws IOException

Connect to the Location specified at construction with the specified method and optionally following redirects.

Returns:
this HttpClient instance.
Throws:
IOException - if an I/O or a network error occurred.

disconnect

public HttpClient disconnect()
                      throws IOException

Disconnect from the remote endpoint and terminate the request.

Note that request and response headers, the resultin status and acceptable statuses are not cleared by this method.

Returns:
this HttpClient instance.
Throws:
IOException - if an I/O or a network error occurred.

disconnect

public HttpClient disconnect(boolean reset)
                      throws IOException

Disconnect from the remote endpoint and terminate the request.

Parameters:
reset - whether to reset all headers, status and acceptable response status codes or not.
Returns:
this HttpClient instance.
Throws:
IOException - if an I/O or a network error occurred.

getResponseStream

public InputStream getResponseStream()
                              throws IllegalStateException

Return an InputStream where the content of the HTTP response can be read from.

Throws:
IllegalStateException - if this instance is not connected yet, or the request body was not fully written yet.

getRequestStream

public OutputStream getRequestStream()
                              throws IllegalStateException

Return an OutputStream where the content of the HTTP request can be written to.

Throws:
IllegalStateException - if this instance is not connected yet or if upon connection the size of the request was not specifed or zero.

getLocation

public Location getLocation()

Return the Location of this connection.

This might be different from the Location specified at construction time if upon connecting HTTP redirections were followed.


addRequestHeader

public HttpClient addRequestHeader(String name,
                                   String value)

Add a new header that will be sent with the HTTP request.

This method will remove any header value previously associated with the specified name, in other words this method is equivalent to addRequestHeader(name, value, false).

Parameters:
name - the name of the request header to add.
value - the value of the request header to add.
Returns:
this HttpClient instance.
Throws:
NullPointerException - the name or value were null.

addRequestHeader

public HttpClient addRequestHeader(String name,
                                   String value,
                                   boolean appendValue)

Add a new header that will be sent with the HTTP request.

Parameters:
name - the name of the request header to add.
value - the value of the request header to add.
appendValue - if the current value should be appended, or in other words, that two headers with the same can coexist.
Returns:
this HttpClient instance.
Throws:
NullPointerException - the name or value were null.

removeRequestHeader

public HttpClient removeRequestHeader(String name)

Remove the named header from the current HTTP request.

Parameters:
name - the name of the request header to add.
Returns:
this HttpClient instance.
Throws:
NullPointerException - the name was null.

removeRequestHeaders

public HttpClient removeRequestHeaders()

Remove all headers from the current HTTP request.

Returns:
this HttpClient instance.

getResponseHeader

public String getResponseHeader(String name)

Return the first value for the specified response header.

Parameters:
name - the name of the header whose value needs to be returned.
Returns:
a String or null if no such header exists.

getResponseHeaderValues

public List getResponseHeaderValues(String name)

Return all the values for the specified response header.

Parameters:
name - the name of the header whose values needs to be returned.
Returns:
a List or null if no such header exists.

getResponseHeaderNames

public Iterator getResponseHeaderNames()

Return an Iterator over all response header names.

Returns:
a non-null Iterator.

getResponseProtocol

public String getResponseProtocol()

Return the protocol returned by the remote HTTP server.

Returns:
a non-null String like HTTP/1.0.
Throws:
IllegalStateException - if the connection was never connected.

getResponseStatus

public int getResponseStatus()

Return the status returned by the remote HTTP server.

Returns:
a number representing the HTTP status of the response.
Throws:
IllegalStateException - if the connection was never connected.

getResponseMessage

public String getResponseMessage()

Return the status message returned by the remote HTTP server.

Returns:
a non-null String like OK.
Throws:
IllegalStateException - if the connection was never connected.

main

public static final void main(String[] args)

Utility method: fetch the location specified on the command line following redirects if necessary.

The final location fetched (in case of redirections it might change) will be reported on the system error stream alongside with any errors encountered while processing.