com.opencloud.slee.resources.http

Interface HttpMessage

All Superinterfaces:

Cloneable

All Known Subinterfaces:

HttpRequest, HttpResponse

public interface HttpMessage
extends Cloneable

An HTTP message consisting of some headers and a body.

An instance of HttpMessage consists of a set of HTTP headers, and an optional content body. The headers are specific to the message instance, and modifications to them do not affect any other message instance.

The content body is conceptually held in a backing store. When content is initially provided to a message, the message holds a reference to the ByteBuffer or byte[] provided, and uses that as the backing store directly. Such a message is a shared message -- the backing store may be modified via other objects unexpectedly.

Usually, shared messages work fine. There are some cases where it is necessary to ensure that a message does not share a backing store, for example when the source of the content is actually an I/O buffer that will be reused. In this case, call unshare(), which forces a shared message to take its own copy of the content, becoming unshared.

Messages may be cloned via clone(). This does a deep copy of the headers, but the cloned message shares the content body of the original message. (unless the original message is immutable -- see below).

Messages may also be made immutable by calling setImmutable(). An immutable message will refuse to modify headers, returned content ByteBuffers will be read-only, and returned content bytearrays will take a fresh copy of the content to a new array each time. Once made immutable, messages cannot be made mutable again. Immutable messages may be cloned, producing a new mutable message that does not share the same backing store and may be modified safely.

In general, calling setImmutable() on a message is not in itself sufficient to make a truely immutable message. Callers must also ensure that the backing store of the message cannot be modified, either by providing that guarantee themselves, or by calling unshare() to force a shared message to take a copy of the content.

Method Summary

Modifier and Type	Method and Description
Object	clone() Return a copy of this message.
byte[]	getContent() Get the message's content, as a byte array.
String	getContentAsString() Get the message's content as a Java String.
ByteBuffer	getContentBuffer() Get the content of this message as a ByteBuffer.
int	getContentLength() Get the message's Content-Length.
String	getContentType() Get the message's Content-Type header.
String	getHeader(String name) Get the value of a HTTP header.
Iterator<String>	getHeaderNames() Get an iterator returning a String for each header present in this message.
HttpVersion	getVersion() Gets the HTTP version of this message
void	removeHeader(String name) Remove a HTTP header.
void	setContent(byte[] contentArray) Set the content of this message.
void	setContent(byte[] contentArray, int offset, int length) Set the content of this message.
void	setContent(ByteBuffer content) Set the content of this message to the active region of a ByteBuffer (that is, the bytes between content.position() and content.limit()).
void	setContent(String contentType, byte[] content) Set the message's content and content type.
void	setContentAsString(String contentType, String content) Encode a String using the charset of the given Content-Type, and set the content to the resulting bytes.
void	setContentType(String contentType) Set the message's Content-Type header.
void	setHeader(String name, String value) Set the value of a HTTP header.
void	setImmutable() Make this message immutable.
void	setVersion(HttpVersion version) Sets the HTTP version of this message
void	unshare() Make this message unshared.

Method Detail

getVersion

HttpVersion getVersion()

Gets the HTTP version of this message

Returns:

a HttpVersion instance

setVersion

void setVersion(HttpVersion version)
         throws IllegalStateException,
                NullPointerException

Sets the HTTP version of this message

Parameters:

version - a HttpVersion instance

Throws:

NullPointerException - if version is null.

IllegalStateException - if this message is immutable

getHeader

String getHeader(String name)

Get the value of a HTTP header.

Parameters:

name - the header name (case insensitive)

Returns:

the header's value, or null if the header is not present

setHeader

void setHeader(String name,
               String value)
        throws IllegalStateException,
               NullPointerException

Set the value of a HTTP header.

Parameters:

name - the header name

value - the value to set, or null to remove the header

Throws:

NullPointerException - if name is null

IllegalStateException - if this message is immutable

removeHeader

void removeHeader(String name)

Remove a HTTP header. This is equivalent to setHeader(name, null).

Parameters:

name - the header name to remove

Throws:

NullPointerException - if name is null

IllegalStateException - if this message is immutable

getHeaderNames

Iterator<String> getHeaderNames()

Get an iterator returning a String for each header present in this message. The returned iterator may be invalidated if the message's headers are modified.

Returns:

an Iterator instance

getContentType

String getContentType()

Get the message's Content-Type header. Equivalent to: getHeader("Content-Type")

Returns:

the Content-Type header's value, or null if not present

setContentType

void setContentType(String contentType)

Set the message's Content-Type header. Equivalent to: setHeader("Content-Type", contentType)

Parameters:

contentType - the Content-Type header's value, or null to remove the header

getContentLength

int getContentLength()

Get the message's Content-Length. This is not necessarily the same as the Content-Length header, as the message may omitted a Content-Length header and instead been terminated by client EOF.

Returns:

the number of bytes in this message's content

getContent

byte[] getContent()

Get the message's content, as a byte array. If this message is immutable, a new copy of the content is returned; otherwise, the returned array may optionally be backed by the actual content. Calling this method may cause a shared message to become unshared.

Returns:

a byte array containing the message's contents

getContentAsString

String getContentAsString()
                   throws IOException

Get the message's content as a Java String. The message's Content-Type field is parsed for a 'charset' parameter; if missing, ISO-8859-1 is assumed.

Returns:

the message content as a String

Throws:

IOException - if the content could not be converted

setContent

void setContent(String contentType,
                byte[] content)

Set the message's content and content type. Equivalent to:

     setHeader("Content-Type", contentType);
     setContent(content);
 

clone

Object clone()

Return a copy of this message. The copy has its own independent set of headers and is mutable. If the message being cloned is mutable, the copied message shares the same underlying content storage. To get a full deep copy, call unshare() on the newly copied message.

Returns:

a copy of this message

setContent

void setContent(byte[] contentArray,
                int offset,
                int length)

Set the content of this message. Copy of the array is taken.

Parameters:

contentArray - the content array; may be null

offset - the first byte of the content

length - the number of bytes of content

Throws:

IndexOutOfBoundsException - if offset/length point outside the bounds of contentArray

setContent

void setContent(byte[] contentArray)

Set the content of this message. The given array is used as the backing store for the content; call unshare() to force the message to take a copy.

Parameters:

contentArray - the content array; may be null

setContent

void setContent(ByteBuffer content)

Set the content of this message to the active region of a ByteBuffer (that is, the bytes between content.position() and content.limit()). The given buffer is used as the backing store for the content; call unshare() to force the message to take a copy.

Parameters:

content - the content buffer, or null if there is no content body

setContentAsString

void setContentAsString(String contentType,
                        String content)
                 throws IOException

Encode a String using the charset of the given Content-Type, and set the content to the resulting bytes. This is the corresponding method to getContentAsString().

Parameters:

contentType - the Content-Type to ise

content - the content, as a String

Throws:

IOException - if the content cannot be encoded as the given Content-Type

getContentBuffer

ByteBuffer getContentBuffer()

Get the content of this message as a ByteBuffer. If the message is immutable, this will be a read-only buffer. The returned buffer is backed by this message's content, but has its own position/mark/limit state.

Returns:

the content as a ByteBuffer, or null if there is no content body

unshare

void unshare()

Make this message unshared. If the message is currently shared, creates a new backing store that has a copy of the current content. Calling this method on an unshared message is a no-op.

setImmutable

void setImmutable()

Make this message immutable. This does not affect whether a message is shared or not, so it may also be necessary to call unshare() to get a truely immutable message. Calling this on an immutable message is a no-op.