Package io.helidon.webserver

Interface ServerResponse

public interface ServerResponse

Represents HTTP Response.

Lifecycle

HTTP response is send to the client in two or more steps (chunks). First contains HTTP status code and headers. First part can be send explicitly by calling ResponseHeaders.send() method or implicitly by sending a first part of the the response content. As soon as first part is send it become immutable - status(int) method and all muting operations of ResponseHeaders will throw IllegalStateException.

Response content (body/payload) can be constructed using send(...) methods.

Method Summary

Modifier and Type	Method	Description
ResponseHeaders	headers()	Returns response headers.
ServerResponse	registerFilter(Function<Flow.Publisher<DataChunk>,Flow.Publisher<DataChunk>> function)	Registers a provider of the new response content publisher - typically a filter.
<T> ServerResponse	registerWriter(Class<T> type, MediaType contentType, Function<? extends T,Flow.Publisher<DataChunk>> function)	Registers a content writer for a given type and media type.
<T> ServerResponse	registerWriter(Class<T> type, Function<T,Flow.Publisher<DataChunk>> function)	Registers a content writer for a given type.
<T> ServerResponse	registerWriter(Predicate<?> accept, MediaType contentType, Function<T,Flow.Publisher<DataChunk>> function)	Registers a content writer for all accepted contents.
<T> ServerResponse	registerWriter(Predicate<?> accept, Function<T,Flow.Publisher<DataChunk>> function)	Registers a content writer for all accepted contents.
long	requestId()	A unique correlation ID that is associated with this response and its associated request.
CompletionStage<ServerResponse>	send()	Sends an empty response.
CompletionStage<ServerResponse>	send(Flow.Publisher<DataChunk> content)	Send a message as is without any other marshalling.
<T> CompletionStage<ServerResponse>	send(T content)	Send a message and close the response.
Http.ResponseStatus	status()	Returns actual response status code.
default ServerResponse	status(int statusCode)	Sets new HTTP status code.
ServerResponse	status(Http.ResponseStatus status)	Sets new HTTP status.
WebServer	webServer()	Returns actual WebServer instance.
CompletionStage<ServerResponse>	whenSent()	Completion stage is completed when response is completed.

Method Detail

webServer

WebServer webServer()

Returns actual WebServer instance.

Returns:

an actual WebServer instance

status

Http.ResponseStatus status()

Returns actual response status code.

Default value for handlers is 200 and for failure handlers 500. Value can be redefined using status(int) method before headers are send.

Returns:

an HTTP status code

status

default ServerResponse status(int statusCode)
                       throws AlreadyCompletedException

Sets new HTTP status code. Can be done before headers are completed - see ResponseHeaders documentation.

Parameters:

statusCode - new status code

Returns:

this instance of ServerResponse

Throws:

AlreadyCompletedException - if headers were completed (sent to the client)

status

ServerResponse status(Http.ResponseStatus status)
               throws AlreadyCompletedException,
                      NullPointerException

Sets new HTTP status. Can be done before headers are completed - see ResponseHeaders documentation.

Parameters:

status - new status

Returns:

this instance of ServerResponse

Throws:

AlreadyCompletedException - if headers were completed (sent to the client)

NullPointerException - if status parameter is null

headers

ResponseHeaders headers()

Returns response headers. It can be modified before headers are sent to the client.

Returns:

a response headers

send

<T> CompletionStage<ServerResponse> send(T content)

Send a message and close the response.

Marshalling

Data are marshaled using default or registered writer to the format of ByteBuffer Publisher. The last registered compatible writer is used.

Default writers supports:

• CharSequence
• byte[]
• Path
• File

Blocking

The method blocks only during marshalling. It means until registered writer produce a Publisher and subscribe HTTP IO implementation on it. If the thread is used for publishing is up to HTTP IO and generated Publisher implementations. Use returned CompletionStage to monitor and react on finished sending tryProcess.

Type Parameters:

T - a type of the content

Parameters:

content - a response content to send

Returns:

a completion stage of the response - completed when response is transferred

Throws:

IllegalArgumentException - if there is no registered writer for a given type

IllegalStateException - if any send(...) method was already called

send

CompletionStage<ServerResponse> send(Flow.Publisher<DataChunk> content)

Send a message as is without any other marshalling. The response is completed when publisher send Flow.Subscriber.onComplete() method to its subscriber.

A single Subscriber subscribes to the provided Publisher during the method execution.

Blocking

The method blocks only during marshalling. It means until registered writer produce a Publisher and subscribe HTTP IO implementation on it. If the thread is used for publishing is up to HTTP IO and generated Publisher implementations. Use returned CompletionStage to monitor and react on finished sending tryProcess.

Parameters:

content - a response content publisher

Returns:

a completion stage of the response - completed when response is transferred

Throws:

IllegalStateException - if any send(...) method was already called

send

CompletionStage<ServerResponse> send()

Sends an empty response. Do nothing if response was already send.

Returns:

a completion stage of the response - completed when response is transferred

registerWriter

<T> ServerResponse registerWriter(Class<T> type,
                                  Function<T,Flow.Publisher<DataChunk>> function)

Registers a content writer for a given type.

Registered writer is used to marshal response content of given type to the Publisher of response chunks.

Type Parameters:

T - a type of the content

Parameters:

type - a type of the content. If null then accepts any type.

function - a writer function

Returns:

this instance of ServerResponse

Throws:

NullPointerException - if function parameter is null

registerWriter

<T> ServerResponse registerWriter(Class<T> type,
                                  MediaType contentType,
                                  Function<? extends T,Flow.Publisher<DataChunk>> function)

Registers a content writer for a given type and media type.

Registered writer is used to marshal response content of given type to the Publisher of response chunks. It is used only if Content-Type header is compatible with a given content type or if it is null. If Content-Type is null and it is still possible to modify headers (headers were not send yet), the provided content type will be set.

Type Parameters:

T - a type of the content

Parameters:

type - a type of the content. If null then accepts any type.

contentType - a Content-Type of the entity

function - a writer function

Returns:

this instance of ServerResponse

Throws:

NullPointerException - if function parameter is null

registerWriter

<T> ServerResponse registerWriter(Predicate<?> accept,
                                  Function<T,Flow.Publisher<DataChunk>> function)

Registers a content writer for all accepted contents.

Registered writer is used to marshal response content of given type to the Publisher of response chunks.

Type Parameters:

T - a type of the content

Parameters:

accept - a predicate to test if content is marshallable by the writer. If null then accepts any type.

function - a writer function

Returns:

this instance of ServerResponse

Throws:

NullPointerException - if function parameter is null

registerWriter

<T> ServerResponse registerWriter(Predicate<?> accept,
                                  MediaType contentType,
                                  Function<T,Flow.Publisher<DataChunk>> function)

Registers a content writer for all accepted contents.

Registered writer is used to marshal response content of given type to the Publisher of response chunks. It is used only if Content-Type header is compatible with a given content type or if it is null. If Content-Type is null and it is still possible to modify headers (headers were not send yet), the provided content type will be set.

Type Parameters:

T - a type of the content

Parameters:

accept - a predicate to test if content is marshallable by the writer. If null then accepts any type.

contentType - a Content-Type of the entity

function - a writer function

Returns:

this instance of ServerResponse

Throws:

NullPointerException - if function parameter is null

registerFilter

ServerResponse registerFilter(Function<Flow.Publisher<DataChunk>,Flow.Publisher<DataChunk>> function)

Registers a provider of the new response content publisher - typically a filter.

All response content is always represented by a single Publisher of response chunks. This method can be used to filter or completely replace original publisher by a new one with different contract. For example data coding, logging, filtering, caching, etc.

New publisher is created at the moment of content write by any send(...) method including the empty one.

All registered filters are used as a chain from original content Publisher, first registered to the last registered.

Parameters:

function - a function to map previously registered or original Publisher to the new one. If returns null then the result will be ignored.

Returns:

this instance of ServerResponse

Throws:

NullPointerException - if parameter function is null

whenSent

CompletionStage<ServerResponse> whenSent()

Completion stage is completed when response is completed.

It can be used to react on the response completion without invocation of a closing event.

Returns:

a completion stage of the response

requestId

long requestId()

A unique correlation ID that is associated with this response and its associated request.

Returns:

a unique correlation ID associated with this response and its request