org.forgerock.http.protocol

Interface Message

All Superinterfaces:

AutoCloseable, Closeable

All Known Implementing Classes:

MessageImpl, Request, Response

public interface Message
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:

Utils.closeSilently(Closeable...)

Method Summary

Modifier and Type	Method and Description
void	close() Closes all resources associated with the entity.
Entity	getEntity() Returns the entity.
Headers	getHeaders() Returns the headers.
String	getVersion() Returns the protocol version.
Message	setEntity(Object o) Sets the content of the entity to the provided value.
Message	setVersion(String version) Sets the protocol version.

Method Detail

getEntity

Entity getEntity()

Returns the entity.

Returns:

The entity.

getHeaders

Headers getHeaders()

Returns the headers.

Returns:

The headers.

getVersion

String getVersion()

Returns the protocol version. Default: HTTP/1.1.

Returns:

The protocol version.

setEntity

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

• BranchingInputStream - equivalent to calling Entity.setRawContentInputStream(org.forgerock.http.io.BranchingInputStream)
• byte[] - equivalent to calling Entity.setBytes(byte[])
• String - equivalent to calling Entity.setString(java.lang.String)
• Object - equivalent to calling Entity.setJson(java.lang.Object).

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

Message 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()