public interface HttpMessage extends Cloneable
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.
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.
|
HttpVersion getVersion()
void setVersion(HttpVersion version) throws IllegalStateException, NullPointerException
version
- a HttpVersion instanceNullPointerException
- if version is null.IllegalStateException
- if this message is immutableString getHeader(String name)
name
- the header name (case insensitive)void setHeader(String name, String value) throws IllegalStateException, NullPointerException
name
- the header namevalue
- the value to set, or null to remove the headerNullPointerException
- if name is nullIllegalStateException
- if this message is immutablevoid removeHeader(String name)
setHeader(name, null)
.name
- the header name to removeNullPointerException
- if name is nullIllegalStateException
- if this message is immutableIterator<String> getHeaderNames()
String getContentType()
getHeader("Content-Type")
void setContentType(String contentType)
setHeader("Content-Type", contentType)
contentType
- the Content-Type header's value, or null to remove the headerint getContentLength()
byte[] getContent()
String getContentAsString() throws IOException
IOException
- if the content could not be convertedvoid setContent(String contentType, byte[] content)
setHeader("Content-Type", contentType); setContent(content);
Object clone()
unshare()
on the newly copied
message.void setContent(byte[] contentArray, int offset, int length)
contentArray
- the content array; may be nulloffset
- the first byte of the contentlength
- the number of bytes of contentIndexOutOfBoundsException
- if offset/length point outside the bounds of contentArrayvoid setContent(byte[] contentArray)
unshare()
to force the message
to take a copy.contentArray
- the content array; may be nullvoid setContent(ByteBuffer content)
content
- the content buffer, or null if there is no content bodyvoid setContentAsString(String contentType, String content) throws IOException
getContentAsString()
.contentType
- the Content-Type to isecontent
- the content, as a StringIOException
- if the content cannot be encoded as the given Content-TypeByteBuffer getContentBuffer()
void unshare()
void setImmutable()
unshare()
to get a truely
immutable message. Calling this on an immutable message is a no-op.