org.w3c.mwi.mobileok.basic
Class HttpRetrievalElement

java.lang.Object
  org.w3c.mwi.mobileok.basic.HttpRetrievalElement

All Implemented Interfaces:

RetrievalElement

public class HttpRetrievalElement
extends java.lang.Object
implements RetrievalElement

An instance of the class represents an HTTP client/server exchange, i.e. an HTTP request and an HTTP response.

Version:

$Revision: 1.1 $

Author:

Francois Daoust

Field Summary

private HTTPErrorsType	httpsOutcome The HTTPS outcome, as defined in the HTTPS section of the W3C mobileOK Basic Tests 1.0 standard.
private static int	MAX_BODY_SIZE_BYTES Maximum size of an HTTP response before giving up retrieval.
static int	NETWORK_ERROR Specific HTTP status code that indicates that a network error occurred.
private static org.apache.commons.httpclient.Header[]	NO_HEADERS Empty list of HTTP headers
private byte[]	rawBody HTTP Response body, null when reponse is too large.
private int	rawBodySize HTTP Response body size.
private org.apache.commons.httpclient.Header[]	rawRequestHeaders The list of HTTP request headers that were sent.
private org.apache.commons.httpclient.Header[]	rawResponseHeaders The list of HTTP response headers that were received.
private java.util.Map<java.lang.String,java.lang.String>	requestHeaders The list of HTTP request headers that were sent.
private java.util.Map<java.lang.String,java.lang.String>	responseHeaders The list of HTTP response headers that were received.
private java.lang.String	responseProtocol HTTP protocol of the response.
private java.lang.String	responseReason Error message that details the network error that may have occurred.
private int	statusCode HTTP Response status code.
private java.net.URI	uri URI of the retrieved resource.

Constructor Summary

HttpRetrievalElement(org.apache.commons.httpclient.HttpMethod httpMethod)
Creates a class instance bound to an HTTP exchange.

HttpRetrievalElement(org.apache.commons.httpclient.HttpMethod httpMethod, HTTPErrorsType httpsErrorCode)
Creates a class instance bound to an HTTP exchange and initializes the HTTPS outcome to the given one.

HttpRetrievalElement(java.net.URI uri, java.lang.String errorReason)
Creates a "fake" class instance bound to a URI with a message that explains why it could not be retrieved.

Method Summary

private static void	addHeaderElements(java.util.Map<java.lang.String,java.lang.String> headers, org.w3c.dom.Node request, org.w3c.dom.Document document) Adds a representation of the given list of HTTP header fields to the given Node.
private void	addHTTPResponseError(org.w3c.dom.Document document, org.w3c.dom.Node parent, ResourceContext context) Adds information about the HTTP error that may have been received if the resource could not be retrieved.
java.lang.String	getContentType() Returns the content-type of the retrieved resource, as defined in the Content-Type HTTP header.
java.lang.String	getContentTypeEncoding() Extracts the encoding from the Content-Type HTTP header received in the HTTP Response.
HTTPErrorsType	getHttpsError() Returns the outcome of running the HTTPS tests defined in the HTTPS section of the W3C mobileOK Basic Tests 1.0 standard.
byte[]	getRawBody() Returns the HTTP response body.
int	getRawBodySize() Returns the size of the HTTP response body.
(package private) org.apache.commons.httpclient.Header[]	getRawRequestHeaders() Returns the list of HTTP request headers that were sent to retrieve the final resource.
(package private) org.apache.commons.httpclient.Header[]	getRawResponseHeaders() Returns the list of HTTP response headers that were received with the final resource.
(package private) java.util.Map<java.lang.String,java.lang.String>	getRequestHeaders() Returns the list of HTTP request headers that were sent to retrieve the final resource.
(package private) java.util.Map<java.lang.String,java.lang.String>	getResponseHeaders() Returns the list of HTTP response headers that were received with the final resource.
(package private) java.lang.String	getResponseProtocol() Returns the HTTP protocol of the response.
(package private) java.lang.String	getResponseReason() When a network error occurred and getResponseStatus() returns NETWORK_ERROR, this method returns the exception error message.
(package private) int	getResponseStatus() Returns the HTTP Response status code.
java.net.URI	getUri() Returns the absolute URI of the retrieved resource.
private static void	parameterize(java.lang.String parameters, org.w3c.dom.Node parent, org.w3c.dom.Document document, HeaderParseMethod parseMethod)
private static java.util.Map<java.lang.String,java.lang.String>	parseHTTPHeaders(org.apache.commons.httpclient.Header[] headers) Converts a list of HTTP headers to a (name, value) map.
private static java.lang.String	serializeHTTPHeaders(org.apache.commons.httpclient.Header[] headers) Static helper method that serializes a list of HTTP Header fields.
org.w3c.dom.Node	toMokiNode(org.w3c.dom.Document document, org.w3c.dom.Node parent, ResourceContext context) Serializes the retrieval element to its moki representation as a DOM node.

Methods inherited from class java.lang.Object

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

Field Detail

NETWORK_ERROR

public static final int NETWORK_ERROR

Specific HTTP status code that indicates that a network error occurred.

See Also:

Constant Field Values

MAX_BODY_SIZE_BYTES

private static final int MAX_BODY_SIZE_BYTES

Maximum size of an HTTP response before giving up retrieval.

See Also:

Constant Field Values

NO_HEADERS

private static final org.apache.commons.httpclient.Header[] NO_HEADERS

Empty list of HTTP headers

statusCode

private final int statusCode

HTTP Response status code.

responseProtocol

private final java.lang.String responseProtocol

HTTP protocol of the response.

responseReason

private final java.lang.String responseReason

Error message that details the network error that may have occurred.

uri

private java.net.URI uri

URI of the retrieved resource.

rawBody

private final byte[] rawBody

HTTP Response body, null when reponse is too large.

rawBodySize

private final int rawBodySize

HTTP Response body size.

rawRequestHeaders

private final org.apache.commons.httpclient.Header[] rawRequestHeaders

The list of HTTP request headers that were sent.

rawResponseHeaders

private final org.apache.commons.httpclient.Header[] rawResponseHeaders

The list of HTTP response headers that were received.

requestHeaders

private final java.util.Map<java.lang.String,java.lang.String> requestHeaders

The list of HTTP request headers that were sent.

responseHeaders

private final java.util.Map<java.lang.String,java.lang.String> responseHeaders

The list of HTTP response headers that were received.

httpsOutcome

private HTTPErrorsType httpsOutcome

The HTTPS outcome, as defined in the HTTPS section of the W3C mobileOK Basic Tests 1.0 standard.

Constructor Detail

HttpRetrievalElement

HttpRetrievalElement(org.apache.commons.httpclient.HttpMethod httpMethod)
               throws java.io.IOException

Creates a class instance bound to an HTTP exchange.

Note that the instantiation may take some time as the constructor retrieves information needed to create the instance on the network.

Parameters:

httpMethod - HTTP exchange to wrap in the created instance.

Throws:

java.io.IOException - a network error occurred.

HttpRetrievalElement

HttpRetrievalElement(org.apache.commons.httpclient.HttpMethod httpMethod,
                     HTTPErrorsType httpsErrorCode)
               throws java.io.IOException

Creates a class instance bound to an HTTP exchange and initializes the HTTPS outcome to the given one.

Parameters:

httpMethod - HTTP exchange to wrap in the created instance.

httpsErrorCode - outcome of running the HTTPS tests.

Throws:

java.io.IOException - a network error occurred.

HttpRetrievalElement

HttpRetrievalElement(java.net.URI uri,
                     java.lang.String errorReason)

Creates a "fake" class instance bound to a URI with a message that explains why it could not be retrieved.

This constructor should only be used when the HTTP request could not process at all due to some network error.

getResponseStatus() returns NETWORK_ERROR for the created instance.

Parameters:

uri - absolute URI of the resource that could not be retrieved.

errorReason - details of the network error that occurred.

Method Detail

getRawBody

public byte[] getRawBody()

Returns the HTTP response body.

Specified by:

getRawBody in interface RetrievalElement

Returns:

the HTTP response body. Returns null when the response was too large, or when a network error occurred.

getRawBodySize

public int getRawBodySize()

Returns the size of the HTTP response body.

The size is computed even when the response was too large.

Specified by:

getRawBodySize in interface RetrievalElement

Returns:

the size of the HTTP response body.

getRawRequestHeaders

org.apache.commons.httpclient.Header[] getRawRequestHeaders()

Returns the list of HTTP request headers that were sent to retrieve the final resource.

Returns:

the list of HTTP request headers sent in the last HTTP exchange.

getRawResponseHeaders

org.apache.commons.httpclient.Header[] getRawResponseHeaders()

Returns the list of HTTP response headers that were received with the final resource.

Returns:

the list of HTTP response headers received in the last HTTP exchange.

getRequestHeaders

java.util.Map<java.lang.String,java.lang.String> getRequestHeaders()

Returns the list of HTTP request headers that were sent to retrieve the final resource.

Returns:

the list of HTTP request headers sent in the last HTTP exchange.

getResponseHeaders

java.util.Map<java.lang.String,java.lang.String> getResponseHeaders()

Returns the list of HTTP response headers that were received with the final resource.

Returns:

the list of HTTP response headers received in the last HTTP exchange.

getResponseStatus

int getResponseStatus()

Returns the HTTP Response status code.

Returns:

the HTTP Response status code. NETWORK_ERROR may be returned.

getResponseProtocol

java.lang.String getResponseProtocol()

Returns the HTTP protocol of the response.

Returns:

the HTTP protocol of the reponse, e.g. "HTTP/1.1".

getResponseReason

java.lang.String getResponseReason()

When a network error occurred and getResponseStatus() returns NETWORK_ERROR, this method returns the exception error message.

Returns:

the error message associated with the network error.

getUri

public java.net.URI getUri()

Returns the absolute URI of the retrieved resource.

Specified by:

getUri in interface RetrievalElement

Returns:

the absolute URI of the response.

parseHTTPHeaders

private static java.util.Map<java.lang.String,java.lang.String> parseHTTPHeaders(org.apache.commons.httpclient.Header[] headers)

Converts a list of HTTP headers to a (name, value) map.

Parameters:

headers - list of HTTP headers to convert

Returns:

a map of the HTTP headers

getHttpsError

public HTTPErrorsType getHttpsError()

Returns the outcome of running the HTTPS tests defined in the HTTPS section of the W3C mobileOK Basic Tests 1.0 standard.

Returns:

the HTTPS outcome when the resource uses HTTPS, the returned value is undefined when that's not the case.

getContentType

public java.lang.String getContentType()

Returns the content-type of the retrieved resource, as defined in the Content-Type HTTP header. If no Content-Type HTTP header was received, an empty string is returned.

Specified by:

getContentType in interface RetrievalElement

Returns:

the MIME media type of the resource.

getContentTypeEncoding

public java.lang.String getContentTypeEncoding()

Extracts the encoding from the Content-Type HTTP header received in the HTTP Response.

Specified by:

getContentTypeEncoding in interface RetrievalElement

Returns:

the encoding defined in the HTTP Content-Type header, null if not found.

toMokiNode

public org.w3c.dom.Node toMokiNode(org.w3c.dom.Document document,
                                   org.w3c.dom.Node parent,
                                   ResourceContext context)

Description copied from interface: RetrievalElement

Serializes the retrieval element to its moki representation as a DOM node.

Note that in an ideal world, there should be no need to pass the context that gave birth to the creation of the retrieval element as an argument, but HTTP error codes defined in mobileOK depend on the context, so it seems easier to issue the appropriate error code in the serialization rather than having to compute it afterwards depending on the location of the error code in the moki representation.

Specified by:

toMokiNode in interface RetrievalElement

Parameters:

document - DOM document the created node should belong to

parent - DOM node to which the representation should be appended.

context - context under which the retrieval element was created. The context is needed to return the appropriate error messages when the resource could not be retrieved.

Returns:

the moki representation of the element as a DOM node.

addHTTPResponseError

private void addHTTPResponseError(org.w3c.dom.Document document,
                                  org.w3c.dom.Node parent,
                                  ResourceContext context)

Adds information about the HTTP error that may have been received if the resource could not be retrieved.

The context under which the resource that contains the retrieval element is required because mobileOK defines specific error codes that depend on whether the error occurred for the primary resource, an image, a linked resource, ...

Parameters:

document - the document containing the Node to complete

parent - the Node that is to contain the description of the error.

context - the context that gave birth to the resource.

addHeaderElements

private static void addHeaderElements(java.util.Map<java.lang.String,java.lang.String> headers,
                                      org.w3c.dom.Node request,
                                      org.w3c.dom.Document document)

Adds a representation of the given list of HTTP header fields to the given Node.

Parameters:

headers - the list of HTTP header fields to represent as a DOM tree.

request - the Node that is to contain the representation of the list.

document - the document containing the Node to complete

serializeHTTPHeaders

private static java.lang.String serializeHTTPHeaders(org.apache.commons.httpclient.Header[] headers)

Static helper method that serializes a list of HTTP Header fields.

Parameters:

headers - list of HTTP header fields to serialize.

Returns:

the list of HTTP header field names and values as a string.

parameterize

private static void parameterize(java.lang.String parameters,
                                 org.w3c.dom.Node parent,
                                 org.w3c.dom.Document document,
                                 HeaderParseMethod parseMethod)