com.atlassian.httpclient.api
Interface Message

All Known Subinterfaces:

Request, Response

public interface Message

An abstract base class for HTTP messages (i.e. Request and Response) with support for header and entity management.

Method Summary

java.lang.String	getContentCharset() Returns the currently set content charset value, if any.
java.lang.String	getContentType() Returns the IANA media type, minus charset information, for the current entity, if any.
java.lang.String	getEntity() Returns the current entity in String form, if available, converting the underlying entity stream to a string using the currently set content charset, or defaulting to the HTTP standard of "ISO-8859-1" if no content charset has been specified.
java.io.InputStream	getEntityStream() Returns the current entity as an input stream, or null if not set.
java.lang.String	getHeader(java.lang.String name) Returns the specified header by name.
java.util.Map<java.lang.String,java.lang.String>	getHeaders() Returns a map of all headers that have been set on this object.
boolean	hasEntity() Returns whether or not an entity has been set on this object.
boolean	hasReadEntity() Returns whether or not the current entity property, if any, has been read from this object.
boolean	isFrozen() Returns whether or not this object has been made immutable.
Message	setContentCharset(java.lang.String contentCharset) Sets the charset for this object's entity, if any.
Message	setContentType(java.lang.String contentType) Sets the IANA media type, for the current entity, if any.
Message	setEntity(java.lang.String entity) Sets this object's entity stream from a string.
Message	setEntityStream(java.io.InputStream entityStream) Sets this object's entity as an input stream.
Message	setEntityStream(java.io.InputStream entityStream, java.lang.String charset) Sets this object's entity as an input stream, encoded with the specified charset.
Message	setHeader(java.lang.String name, java.lang.String value) Sets an HTTP header on this object.
Message	setHeaders(java.util.Map<java.lang.String,java.lang.String> headers) Copies the specified map of HTTP headers into this object.

Method Detail

getContentType

java.lang.String getContentType()

Returns the IANA media type, minus charset information, for the current entity, if any. To access charset information, use getContentCharset(). To get the full Content-Type header value including charset if specified, use getHeader("Content-Type").

Returns:

An IANA media type, or null

setContentType

Message setContentType(java.lang.String contentType)

Sets the IANA media type, for the current entity, if any. If the contentType argument also contains charset information, this method will have the side effect of parsing the charset out and storing the component parts independently. The method getContentCharset() can be used to retrieve extracted content charset, if present, and getHeader("Content-Type") can be used to retrieve the entire Content-Type header, complete with charset information, if set. The content type property is required when an entity is present.

Parameters:

contentType - An IANA media type with optional charset information

Returns:

This object, for builder-style chaining

getContentCharset

java.lang.String getContentCharset()

Returns the currently set content charset value, if any.

Returns:

The current content charset

setContentCharset

Message setContentCharset(java.lang.String contentCharset)

Sets the charset for this object's entity, if any. This value is ignored during headeer access if no entity is present or if the content type property is not set.

Parameters:

contentCharset - The entity's charset value, or null

Returns:

This object, for builder-style chaining

getEntityStream

java.io.InputStream getEntityStream()
                                    throws java.lang.IllegalStateException

Returns the current entity as an input stream, or null if not set. Use hasEntity() to check if this message has an entity value.

Returns:

An input stream for the current entity, or null if not set

Throws:

java.lang.IllegalStateException - If the non-null entity has already been accessed once, through any accessor for this object

setEntityStream

Message setEntityStream(java.io.InputStream entityStream)

Sets this object's entity as an input stream. Invocations of this method reset this object's hasReadEntity() state to false. It is recommended to also set this object's content charset property when setting an entity stream for a textual media type (or using the overloaded form that takes both the entity stream and charset in the same call). Clients of this object should assume the HTTP standard of ISO-8859-1 (latin-1) for the content charset property if a textual media type is set but no explcit charset was provided for this message. A charset should NOT be provided for entity streams targetting binary media types.

Parameters:

entityStream - An entity input stream ready to be read

Returns:

This object, for builder-style chaining

setEntityStream

Message setEntityStream(java.io.InputStream entityStream,
                        java.lang.String charset)

Sets this object's entity as an input stream, encoded with the specified charset. Invocations of this method reset this object's hasReadEntity() state to false. This method should only be called for entity streams targetting textual media types -- that is, it's nonsensical to set the charset of an entity stream for binary media types (e.g. image/*, etc).

Parameters:

entityStream - An entity input stream ready to be read

charset - The charset in which the entity stream is encoded

Returns:

This object, for builder-style chaining

getEntity

java.lang.String getEntity()
                           throws java.lang.IllegalStateException,
                                  java.lang.IllegalArgumentException

Returns the current entity in String form, if available, converting the underlying entity stream to a string using the currently set content charset, or defaulting to the HTTP standard of "ISO-8859-1" if no content charset has been specified.

Returns:

The entity string, or null if no entity has been set

Throws:

java.lang.IllegalStateException - If the non-null entity has already been accessed once, through any accessor for this object. Also thrown if underlying body cannot be converted into a String

java.lang.IllegalArgumentException - If the entity exceeds the maximum size

setEntity

Message setEntity(java.lang.String entity)

Sets this object's entity stream from a string. Using this method of setting the entity automatically sets this object's content charset property to "UTF-8" if the entity is not null.

Parameters:

entity - An entity string

Returns:

This object, for builder-style chaining

hasEntity

boolean hasEntity()

Returns whether or not an entity has been set on this object. Use this instead of calling an entity getter to test for presence of an entity, as the getters will affect this object's hasReadEntity() state.

Returns:

This object, for builder-style chaining

hasReadEntity

boolean hasReadEntity()

Returns whether or not the current entity property, if any, has been read from this object. If this method returns true, any further calls to entity property accessors on this object will result in an IllegalStateException being thrown.

Returns:

True if the entity has already been read

getHeaders

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

Returns a map of all headers that have been set on this object. If the content type property has been set, a full "Content-Type" header including content charset, if set, is generated as part of this map.

Returns:

The headers map

setHeaders

Message setHeaders(java.util.Map<java.lang.String,java.lang.String> headers)

Copies the specified map of HTTP headers into this object. It will also parse any included Content-Type header into its constituent parts of IANA media type and content charset, updating those properties as appropriate.

Parameters:

headers - A map of HTTP headers

Returns:

This object, for builder-style chaining

getHeader

java.lang.String getHeader(java.lang.String name)

Returns the specified header by name. If "Content-Type" is requested, the value will be constructed from this object's content type and content charset properties, if set and as appropriate.

Parameters:

name - The name of the header to fetch

Returns:

The value of the named header, or null if not set

setHeader

Message setHeader(java.lang.String name,
                  java.lang.String value)

Sets an HTTP header on this object. If the header's name is "Content-Type", the value will be parsed into this object's content type and content charset properties, as appropriate.

Parameters:

name - The name of the header to be set

value - The value of the header to be set

Returns:

This object, for builder-style chaining

isFrozen

boolean isFrozen()

Returns whether or not this object has been made immutable.

Returns:

True if the object is immutable