Package org.forgerock.http.protocol

Interface Message<M extends Message<M>>

  • Type Parameters:
    M - The sub-type of this message.
    All Superinterfaces:
    AutoCloseable, Closeable
    All Known Implementing Classes:
    MessageImpl, Request, Response
    public interface Message<M extends Message<M>>
extends Closeable
    Elements common to requests and responses.

    A message is a resource container, and thus needs to be closed in order to free-up acquired resources.

    Please carefully note the following regarding closing a message: the asynchronous nature of both Handler and Filter that produce promises of Response make it impossible to know, for the producer of the message, when it can be closed. Thus, the responsibility of closing the message is on the final consumer: the point after which the message is no longer used.

    Example of such situations:

    • In a Filter: Production and forwarding of a new Response instance in one of the callbacks (Function / AsyncFunction) attached to a promise, instead of the given response parameter.
    • When consuming/extracting something out of a response because a different type (not Response) has to be returned.
    See Also:
    Closeables.closeSilently(Closeable...)

    • Method Detail

      • getEntity

        Entity getEntity()
        Returns the entity.
        Returns:
        The entity.

      • getHeaders

        Headers getHeaders()
        Returns the headers.
        Returns:
        The headers.

      • modifyHeaders

        M modifyHeaders​(Consumer<Headers> headersConsumer)
        Interact with the Headers object from the getHeaders() in a fluent way.
        Parameters:
        headersConsumer - A consumer function.
        Returns:
        This message.

      • addHeaders

        M addHeaders​(Header... headers)
        Add one or more headers to the message.
        Parameters:
        headers - The headers.
        Returns:
        This message.

      • putHeaders

        M putHeaders​(Header... headers)
        Put one or more headers to the message. This will overwrite any existing header values for the names of the headers provided.
        Parameters:
        headers - The headers.
        Returns:
        This message.

      • getVersion

        String getVersion()
        Returns the protocol version. Default: HTTP/1.1.
        Returns:
        The protocol version.

      • setEntity

        M setEntity​(Object o)
        Sets the content of the entity to the provided value. Calling this method will close any existing streams associated with the entity. May also set the Content-Length header, overwriting any existing header.

        This method is intended mostly as a convenience method within scripts. The parameter will be handled depending on its type as follows:

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

        Parameters:
        o - The object whose value should be stored in the entity.
        Returns:
        This message.

      • setVersion

        M setVersion​(String version)
        Sets the protocol version. Default: HTTP/1.1.
        Parameters:
        version - The protocol version.
        Returns:
        This message.

      • close

        void close()
        Closes all resources associated with the 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
        See Also:
        Entity.close()