Package org.forgerock.http.protocol

Class Entity

java.lang.Object

org.forgerock.http.protocol.Entity

All Implemented Interfaces:

Closeable, AutoCloseable

public final class Entity
extends Object
implements Closeable

Message content. An entity wraps a BranchingInputStream and provides various convenience methods for accessing the content, transparently handling content encoding. The underlying input stream can be branched in order to perform repeated reads of the data. This is achieved by either calling push(), newDecodedContentReader(Charset), or newDecodedContentInputStream(). The branch can then be closed by calling pop() on the entity, or close() on the returned BufferedReader or InputStream. Calling close() on the entity fully closes the input stream invaliding any branches in the process.

Several convenience methods are provided for accessing the entity as either byte, string, or JSON content.

Field Summary

Fields

Modifier and Type	Field	Description
static String	APPLICATION_JSON_CHARSET_UTF_8	The Content-Type used when setting the entity to JSON.

Method Summary

Modifier and Type	Method	Description
void	close()	Closes all resources associated with this entity.
void	copyDecodedContentTo(OutputStream out)	Copies the decoded content of this entity to the provided writer.
void	copyDecodedContentTo(Writer out)	Copies the decoded content of this entity to the provided writer.
void	copyRawContentTo(OutputStream out)	Copies the raw content of this entity to the provided output stream.
byte[]	getBytes()	Returns a byte array containing a copy of the decoded content of this entity.
Object	getJson()	Returns the content of this entity decoded as a JSON object.
InputStream	getRawContentInputStream()	Returns an input stream representing the raw content of this entity.
String	getString()	Returns the content of this entity decoded as a string.
boolean	isDecodedContentEmpty()	Returns true if this entity's decoded content is empty.
boolean	isRawContentEmpty()	Returns true if this entity's raw content is empty.
InputStream	newDecodedContentInputStream()	Returns a branched input stream representing the decoded content of this entity.
BufferedReader	newDecodedContentReader(Charset charset)	Returns a branched reader representing the decoded content of this entity.
void	pop()	Restores the underlying input stream to the state it had immediately before the last call to push().
void	push()	Saves the current position of the underlying input stream and creates a new buffered input stream.
void	setBytes(byte[] value)	Sets the content of this entity to the raw data contained in the provided byte array.
void	setEmpty()	Mark this entity as being empty.
void	setJson(Object value)	Sets the content of this entity to the JSON representation of the provided object.
void	setRawContentInputStream(BranchingInputStream is)	Sets the content of this entity to the provided input stream.
void	setString(String value)	Sets the content of this entity to the provided string.
String	toString()	Returns the content of this entity decoded as a string.

Methods inherited from class java.lang.Object

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

Field Detail

APPLICATION_JSON_CHARSET_UTF_8

public static final String APPLICATION_JSON_CHARSET_UTF_8

The Content-Type used when setting the entity to JSON.

See Also:

Constant Field Values

Method Detail

isRawContentEmpty

public boolean isRawContentEmpty()

Returns true if this entity's raw content is empty.

Returns:

true if this entity's raw content is empty.

isDecodedContentEmpty

public boolean isDecodedContentEmpty()

Returns true if this entity's decoded content is empty.

Returns:

true if this entity's decoded content is empty.

setEmpty

public void setEmpty()

Mark this entity as being empty.

close

public void close()

Closes all resources associated with this entity. Any open streams will be closed, and the underlying content reset back to a zero length.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

copyDecodedContentTo

public void copyDecodedContentTo(OutputStream out)
                          throws IOException

Copies the decoded content of this entity to the provided writer. After the method returns it will no longer be possible to read data from this entity. This method does not push or pop branches. It does, however, decode the content according to the Content-Encoding header if it is present in the message.

Parameters:

out - The destination writer.

Throws:

IOException - If an IO error occurred while copying the decoded content.

copyDecodedContentTo

public void copyDecodedContentTo(Writer out)
                          throws IOException

Copies the decoded content of this entity to the provided writer. After the method returns it will no longer be possible to read data from this entity. This method does not push or pop branches. It does, however, decode the content according to the Content-Encoding and Content-Type headers if they are present in the message.

Parameters:

out - The destination writer.

Throws:

IOException - If an IO error occurred while copying the decoded content.

copyRawContentTo

public void copyRawContentTo(OutputStream out)
                      throws IOException

Copies the raw content of this entity to the provided output stream. After the method returns it will no longer be possible to read data from this entity. This method does not push or pop branches nor does it perform any decoding of the raw data.

Parameters:

out - The destination output stream.

Throws:

IOException - If an IO error occurred while copying the raw content.

getBytes

public byte[] getBytes()
                throws IOException

Returns a byte array containing a copy of the decoded content of this entity. Calling this method does not change the state of the underlying input stream. Subsequent changes to the content of this entity will not be reflected in the returned byte array, nor will changes in the returned byte array be reflected in the content.

Returns:

A byte array containing a copy of the decoded content of this entity (never null).

Throws:

IOException - If an IO error occurred while reading the content.

getJson

public Object getJson()
               throws IOException

Returns the content of this entity decoded as a JSON object. Calling this method does not change the state of the underlying input stream. Subsequent changes to the content of this entity will not be reflected in the returned JSON object, nor will changes in the returned JSON object be reflected in the content.

Returns:

The content of this entity decoded as a JSON object, which will be null only if the content represents the JSON null value.

Throws:

IOException - If an IO error occurred while reading the content or if the JSON is malformed.

getRawContentInputStream

public InputStream getRawContentInputStream()

Returns an input stream representing the raw content of this entity. Reading from the input stream will update the state of this entity.

Returns:

An input stream representing the raw content of this entity.

getString

public String getString()
                 throws IOException

Returns the content of this entity decoded as a string. Calling this method does not change the state of the underlying input stream. Subsequent changes to the content of this entity will not be reflected in the returned string, nor will changes in the returned string be reflected in the content.

Returns:

The content of this entity decoded as a string (never null).

Throws:

IOException - If an IO error occurred while reading the content.

newDecodedContentInputStream

public InputStream newDecodedContentInputStream()
                                         throws IOException

Returns a branched input stream representing the decoded content of this entity. Reading from the returned input stream will NOT update the state of this entity.

The entity will be decompressed based on any codings that are specified in the Content-Encoding header.

Note: The caller is responsible for calling the input stream's close method when it is finished reading the entity.

Returns:

A buffered input stream for reading the decoded entity.

Throws:

UnsupportedEncodingException - If content encoding are not supported.

IOException - If an IO error occurred while reading the content.

newDecodedContentReader

public BufferedReader newDecodedContentReader(Charset charset)
                                       throws IOException

Returns a branched reader representing the decoded content of this entity. Reading from the returned reader will NOT update the state of this entity.

The entity will be decoded and/or decompressed based on any codings that are specified in the Content-Encoding header.

If charset is not null then it will be used to decode the entity, otherwise the character set specified in the message's Content-Type header (if present) will be used, otherwise the default ISO-8859-1 character set.

Note: The caller is responsible for calling the reader's close method when it is finished reading the entity.

Parameters:

charset - The character set to decode with, or message-specified or default if null.

Returns:

A buffered reader for reading the decoded entity.

Throws:

UnsupportedEncodingException - If content encoding or charset are not supported.

IOException - If an IO error occurred while reading the content.

pop

public void pop()

Restores the underlying input stream to the state it had immediately before the last call to push().

push

public void push()
          throws IOException

Saves the current position of the underlying input stream and creates a new buffered input stream. Subsequent attempts to read from this entity, e.g. using copyRawContentTo or #getRawInputStream(), will not impact the saved state.

Use the pop() method to restore the entity to the previous state it had before this method was called.

Throws:

IOException - If this entity has been closed.

setBytes

public void setBytes(byte[] value)

Sets the content of this entity to the raw data contained in the provided byte array. Calling this method will close any existing streams associated with the entity. Also sets the Content-Length header, overwriting any existing header.

Note: This method does not attempt to encode the entity based-on any codings specified in the Content-Encoding header.

Parameters:

value - A byte array containing the raw data.

setJson

public void setJson(Object value)

Sets the content of this entity to the JSON representation of the provided object. Calling this method will close any existing streams associated with the entity. Also sets the Content-Type and Content-Length headers, overwriting any existing header.

Note: This method does not attempt to encode the entity based-on any codings specified in the Content-Encoding header.

Parameters:

value - The object whose JSON representation is to be store in this entity.

setRawContentInputStream

public void setRawContentInputStream(BranchingInputStream is)

Sets the content of this entity to the provided input stream. Calling this method will close any existing streams associated with the entity. No headers will be set.

Parameters:

is - The input stream.

setString

public void setString(String value)

Sets the content of this entity to the provided string. Calling this method will close any existing streams associated with the entity. Also sets the Content-Length header, overwriting any existing header.

The character set specified in the message's Content-Type header (if present) will be used, otherwise the default ISO-8859-1 character set.

Note: This method does not attempt to encode the entity based-on any codings specified in the Content-Encoding header.

Parameters:

value - The string whose value is to be store in this entity.

toString

public String toString()

Returns the content of this entity decoded as a string. Calling this method does not change the state of the underlying input stream.

Overrides:

toString in class Object

Returns:

The content of this entity decoded as a string (never null).