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 Summary

Modifier and Type	Method	Description
M	addHeaders(Header... headers)	Add one or more headers to the message.
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.
M	modifyHeaders(Consumer<Headers> headersConsumer)	Interact with the Headers object from the getHeaders() in a fluent way.
M	putHeaders(Header... headers)	Put one or more headers to the message.
M	setEntity(Object o)	Sets the content of the entity to the provided value.
M	setVersion(String version)	Sets the protocol version.

Method Details

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:

• 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

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