Module io.helidon.reactive.webserver

Package io.helidon.reactive.webserver

Interface ServerResponse

All Superinterfaces:

MessageBodyFilters, MessageBodyWriters

public interface ServerResponse
extends MessageBodyFilters, MessageBodyWriters

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.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static enum	ServerResponse.CachingStrategy	Declares common groups of Cache-Control settings.

Method Summary

Modifier and Type	Method	Description
default ServerResponse	addHeader(Http.HeaderName name, String... values)	Adds header values for a specified name.
default ServerResponse	addHeader(Http.HeaderValue value)	Adds header values for a specified name.
default ServerResponse	addHeader(String name, String... values)	Deprecated. use addHeader(io.helidon.common.http.Http.HeaderName, String...)
default ServerResponse	addHeader(String name, List<String> values)	Deprecated. use addHeader(io.helidon.common.http.Http.HeaderName, String...)
default ServerResponse	cachingStrategy(ServerResponse.CachingStrategy cachingStrategy)	Sets the Cache-Control header values according to the specified strategy.
default void	header(Http.HeaderValue headerValue)	Set a header.
ResponseHeaders	headers()	Returns response headers.
ServerResponse	registerFilter(MessageBodyFilter filter)	Registers a message body filter.
ServerResponse	registerWriter(MessageBodyStreamWriter<?> writer)	Register a stream writer.
ServerResponse	registerWriter(MessageBodyWriter<?> writer)	Register a writer.
long	requestId()	A unique correlation ID that is associated with this response and its associated request.
Single<ServerResponse>	send()	Sends an empty response.
Void	send(Throwable content)	Send a Throwable and close the response.
Single<ServerResponse>	send(Flow.Publisher<DataChunk> content)	Send a message as is without any other marshalling, registered filters are applied.
Single<ServerResponse>	send(Flow.Publisher<DataChunk> content, boolean applyFilters)	Send a message as is without any other marshalling.
<T> Single<ServerResponse>	send(Flow.Publisher<T> content, Class<T> clazz)	Send a message with the given entity stream as content and close the response.
Single<ServerResponse>	send(Function<MessageBodyWriterContext,Flow.Publisher<DataChunk>> function)	Send a message using the given marshalling function.
<T> Single<ServerResponse>	send(T content)	Send a message and close the response.
Http.Status	status()	Returns actual response status code.
default ServerResponse	status(int statusCode)	Sets new HTTP status code.
ServerResponse	status(Http.Status status)	Sets new HTTP status.
WebServer	webServer()	Returns actual WebServer instance.
Single<ServerResponse>	whenSent()	Completion stage is completed when response is completed.
MessageBodyWriterContext	writerContext()	Get the writer context used to marshall data.

Method Details

webServer

WebServer webServer()

Returns actual WebServer instance.

Returns:

an actual WebServer instance

status

Http.Status 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.Status 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

addHeader

@Deprecated
default ServerResponse addHeader(String name,
 String... values)

Deprecated.

use addHeader(io.helidon.common.http.Http.HeaderName, String...)

Adds header values for a specified name.

Parameters:

name - header name

values - header values

Returns:

this instance of ServerResponse

Throws:

NullPointerException - if the specified name is null.

See Also:

• headers()
• header names constants

addHeader

@Deprecated
default ServerResponse addHeader(String name,
 List<String> values)

Deprecated.

use addHeader(io.helidon.common.http.Http.HeaderName, String...)

Adds header values for a specified name.

Parameters:

name - header name

values - header values

Returns:

this instance of ServerResponse

Throws:

NullPointerException - if the specified name is null.

See Also:

• headers()
• header names constants

addHeader

default ServerResponse addHeader(Http.HeaderName name,
 String... values)

Adds header values for a specified name.

Parameters:

name - header name

values - header values

Returns:

this instance of ServerResponse

Throws:

NullPointerException - if the specified name is null.

See Also:

• headers()
• header names constants

header

default void header(Http.HeaderValue headerValue)

Set a header.

Parameters:

headerValue - header name and value to set (replaces existing)

addHeader

default ServerResponse addHeader(Http.HeaderValue value)

Adds header values for a specified name.

Parameters:

value - header value

Returns:

this instance of ServerResponse

Throws:

NullPointerException - if the specified name is null.

See Also:

• headers()
• header names constants

cachingStrategy

default ServerResponse cachingStrategy(ServerResponse.CachingStrategy cachingStrategy)

Sets the Cache-Control header values according to the specified strategy.

Parameters:

cachingStrategy - ServerResponse.CachingStrategy to apply to this response

Returns:

updated response

writerContext

MessageBodyWriterContext writerContext()

Get the writer context used to marshall data.

Returns:

MessageBodyWriterContext

send

Void send(Throwable content)

Send a Throwable and close the response. Invokes error handlers if defined.

Parameters:

content - the Throwable to send

Returns:

null when invoked

Throws:

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

See Also:

• send(Object)

send

<T> Single<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 Single to monitor and react on finished sending process.

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

<T> Single<ServerResponse> send(Flow.Publisher<T> content,
 Class<T> clazz)

Send a message with the given entity stream as content and close the response.

Type Parameters:

T - entity type

Parameters:

content - entity stream

clazz - class representing the entity type

Returns:

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

send

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

Send a message as is without any other marshalling, registered filters are applied. 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

If the thread is used for publishing is up to HTTP IO and generated Publisher implementations. Use returned Single to monitor and react on finished sending process.

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

Single<ServerResponse> send(Flow.Publisher<DataChunk> content,
 boolean applyFilters)

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

If the thread is used for publishing is up to HTTP IO and generated Publisher implementations. Use returned Single to monitor and react on finished sending process.

Parameters:

content - a response content publisher

applyFilters - if true all registered filters are applied

Returns:

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

Throws:

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

send

Single<ServerResponse> send(Function<MessageBodyWriterContext,Flow.Publisher<DataChunk>> function)

Send a message using the given marshalling function.

Parameters:

function - marshalling function

Returns:

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

send

Single<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

registerFilter

ServerResponse registerFilter(MessageBodyFilter filter)

Description copied from interface: MessageBodyFilters

Registers a message body filter.

The registered filters are applied to form a chain from the first registered to the last registered. The first evaluation of the function transforms the original publisher to a new publisher. Any subsequent evaluation receives the publisher transformed by the last previously registered filter.

Specified by:

registerFilter in interface MessageBodyFilters

Parameters:

filter - 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 MessageBodyFilters

See Also:

• MessageBodyContext.applyFilters(Flow.Publisher)

registerWriter

ServerResponse registerWriter(MessageBodyWriter<?> writer)

Description copied from interface: MessageBodyWriters

Register a writer.

Specified by:

registerWriter in interface MessageBodyWriters

Parameters:

writer - writer to register

Returns:

Writers

registerWriter

ServerResponse registerWriter(MessageBodyStreamWriter<?> writer)

Description copied from interface: MessageBodyWriters

Register a stream writer.

Specified by:

registerWriter in interface MessageBodyWriters

Parameters:

writer - writer to register

Returns:

Writers

whenSent

Single<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