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 allows to access a message's content in a repeatable way. It provides various convenience methods for accessing the content, transparently handling content encoding like with newDecodedContentReader(Charset), or newDecodedContentInputStream(). Calling close() on the entity fully closes the underlying stream of data.

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

Respective asynchronous accessors are also available (and should be preferred):

There are 2 ways to feed the Entity: either synchronously through the setRawContentInputStream(BranchingInputStream) or asynchronously through the setContent(Publisher). This class is not thread-safe, there is absolutely no guarantee of its behaviour if it is used in concurrent ways.

  • Field Details

    • 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:

    • APPLICATION_X_WWW_FORM_URLENCODED

      public static final String APPLICATION_X_WWW_FORM_URLENCODED
      The Content-Type when setting the entity to form.
      See Also:

  • Method Details

    • 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.

    • getBytesAsync

      public Promise<byte[],IOException> getBytesAsync()
      Returns a promise of the decoded entity content as a byte array.

      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.

      The returned promise will fail with an IOException if an IO error occurred while reading the content.

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

    • 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.

    • getJsonAsync

      public Promise<Object,IOException> getJsonAsync()
      Returns a promise of 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.

      The returned promise will fail with an IOException if an IO error occurred while reading the content.

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

    • 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.

    • getRawContentInputStreamAsync

      public Promise<InputStream,NeverThrowsException> getRawContentInputStreamAsync()
      Returns a promise of an input stream representing the raw content of this entity. Reading from the input stream will update the state of this entity. The Promise only completes once the InputStream is in a state where it can be fully read without blocking/polling. EXPERIMENTAL: This method is experimental and is subject to changes or even disappear at any time. It is not recommended to use it.
      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.

    • getStringAsync

      public Promise<String,IOException> getStringAsync()
      Returns a promise of 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.

      The returned promise will fail with an IOException if an IO error occurred while reading the content.

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

    • getForm

      public Form getForm() throws IOException
      Returns a copy of the "application/x-www-form-urlencoded" entity decoded as a form. Modifications to the returned form are not reflected in this entity.
      Returns:
      The "application/x-www-form-urlencoded" entity as a form.
      Throws:
      IOException - if the entity cannot be read entirely as a string.
      See Also:

    • getFormAsync

      public Promise<Form,IOException> getFormAsync()
      Returns a promise of a copy of the "application/x-www-form-urlencoded" entity decoded as a form. Modifications to the returned form are not reflected in this entity.

      The returned promise will fail with an IOException if an IO error occurred while reading the content.

      Returns:
      The promise of the "application/x-www-form-urlencoded" entity as a form.
      See Also:

    • 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.

    • 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.

    • setForm

      public void setForm(Form form)
      Sets the content of this entity to the String representation of the provided Form. 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 encoding specified in the Content-Encoding header.

      Parameters:
      form - The form parameters to be stored 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.

    • setContent

      public void setContent(org.reactivestreams.Publisher<ByteBuffer> publisher)
      Sets the content of this entity to the provided publisher. Calling this method will close any existing streams associated with the entity. No headers will be set. EXPERIMENTAL: This method is experimental and is subject to changes or even disappear at any time. It is not recommended to use it.
      Parameters:
      publisher - The publisher of bytes that will feed the Entity.

    • getRawContentFlowable

      public io.reactivex.rxjava3.core.Flowable<ByteBuffer> getRawContentFlowable()
      Returns a publisher of bytes representing the raw content of this entity. Reading from the flow of bytes may update update the state of this entity. EXPERIMENTAL: This method is experimental and is subject to changes or even disappear at any time. It is not recommended to use it.
      Returns:
      a publisher of bytes representing the raw content of this entity.

    • newDecompressedContentFlowable

      public io.reactivex.rxjava3.core.Flowable<ByteBuffer> newDecompressedContentFlowable()
      Returns a publisher of bytes representing the decompressed content of this entity, according to the Content-Encoding header. Reading from the flow of bytes will not update the state of this entity. EXPERIMENTAL: This method is experimental and is subject to changes or even disappear at any time. It is not recommended to use it. The returned Flowable may convey some exceptions:
      Returns:
      a publisher of bytes representing the decompressed content of this entity.

    • decodedContentAsFlowable

      public io.reactivex.rxjava3.core.Flowable<CharBuffer> decodedContentAsFlowable(Charset charset)
      Returns a publisher of chars representing decoded content of this entity, honouring the charset if provided. Reading from the flow of bytes will not update the state of this entity.

      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. EXPERIMENTAL: This method is experimental and is subject to changes or even disappear at any time. It is not recommended to use it. The returned Flowable may convey some exceptions:

      Parameters:
      charset - The character set to decode with, or message-specified or default if null.
      Returns:
      a publisher of bytes representing the decompressed and decoded content of this entity.

    • 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 a description of this entity content (not the content itself).
      Overrides:
      toString in class Object
      Returns:
      a description of this entity content (not the content itself).