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 callingunshare()
to force a shared message to take a copy of the content.
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method 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 messagevoid
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(String contentType, byte[] content)
Set the message's content and content type.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
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 messagevoid
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 namevalue
- the value to set, or null to remove the header- Throws:
NullPointerException
- if name is nullIllegalStateException
- if this message is immutable
-
removeHeader
void removeHeader(String name)
Remove a HTTP header. This is equivalent tosetHeader(name, null)
.- Parameters:
name
- the header name to remove- Throws:
NullPointerException
- if name is nullIllegalStateException
- 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, callunshare()
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 nulloffset
- the first byte of the contentlength
- 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; callunshare()
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 togetContentAsString()
.- Parameters:
contentType
- the Content-Type to isecontent
- 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 callunshare()
to get a truely immutable message. Calling this on an immutable message is a no-op.
-
-