Entity (org.openidentityplatform.commons.parent 2.2.3 Documentation)

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 and Description

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

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

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and 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 Closeable
    
    Specified by:
    
    close in interface AutoCloseable
  - 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).

Class Entity

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

APPLICATION_JSON_CHARSET_UTF_8

Method Detail

isRawContentEmpty

isDecodedContentEmpty

setEmpty

close

copyDecodedContentTo

copyDecodedContentTo

copyRawContentTo

getBytes

getJson

getRawContentInputStream

getString

newDecodedContentInputStream

newDecodedContentReader

pop

push

setBytes

setJson

setRawContentInputStream

setString

toString