Module io.helidon.webserver

Package io.helidon.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 class	ServerResponse.CachingStrategy	Declares common groups of Cache-Control settings.

Method Summary

Modifier and Type	Method	Description
default ServerResponse	addHeader(String name, Iterable<String> values)	Adds header values for a specified name.
default ServerResponse	addHeader(String name, String... values)	Adds header values for a specified name.
default ServerResponse	addHeaders(Parameters parameters)	Copies all of the mappings from the specified parameters to this response headers instance.
default ServerResponse	cachingStrategy(ServerResponse.CachingStrategy cachingStrategy)	Sets the Cache-Control header values according to the specified strategy.
ResponseHeaders	headers()	Returns response headers.
ServerResponse	registerFilter(MessageBodyFilter filter)	Registers a message body filter.
ServerResponse	registerFilter(Function<Flow.Publisher<DataChunk>,Flow.Publisher<DataChunk>> function)	Deprecated. since 2.0.0, use registerFilter(io.helidon.media.common.MessageBodyFilter) instead
ServerResponse	registerWriter(MessageBodyStreamWriter<?> writer)	Register a stream writer.
ServerResponse	registerWriter(MessageBodyWriter<?> writer)	Register a writer.
<T> ServerResponse	registerWriter(Class<T> type, MediaType contentType, Function<? extends T,Flow.Publisher<DataChunk>> function)	Deprecated. since 2.0.0, use registerWriter(io.helidon.media.common.MessageBodyWriter) instead
<T> ServerResponse	registerWriter(Class<T> type, Function<T,Flow.Publisher<DataChunk>> function)	Deprecated. Since 2.0.0, use registerWriter(io.helidon.media.common.MessageBodyWriter) instead
<T> ServerResponse	registerWriter(Predicate<?> accept, MediaType contentType, Function<T,Flow.Publisher<DataChunk>> function)	Deprecated. since 2.0.0, use registerWriter(io.helidon.media.common.MessageBodyWriter) instead
<T> ServerResponse	registerWriter(Predicate<?> accept, Function<T,Flow.Publisher<DataChunk>> function)	Deprecated. since 2.0.0, use registerWriter(io.helidon.media.common.MessageBodyWriter) instead
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.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.
Single<ServerResponse>	whenSent()	Completion stage is completed when response is completed.
MessageBodyWriterContext	writerContext()	Get the writer context used to marshall data.

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

addHeader

default ServerResponse addHeader(String 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(), Parameters.add(String, String...), header names constants

addHeader

default ServerResponse addHeader(String name,
                                 Iterable<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(), Parameters.add(String, Iterable), header names constants

addHeaders

default ServerResponse addHeaders(Parameters parameters)

Copies all of the mappings from the specified parameters to this response headers instance.

Parameters:

parameters - to copy.

Returns:

this instance of ServerResponse

Throws:

NullPointerException - if the specified parameters are null.

See Also:

headers(), Parameters.addAll(Parameters)

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

registerWriter

@Deprecated(since="2.0.0")
<T> ServerResponse registerWriter(Class<T> type,
                                  Function<T,Flow.Publisher<DataChunk>> function)

Deprecated.

Since 2.0.0, use registerWriter(io.helidon.media.common.MessageBodyWriter) instead

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

@Deprecated(since="2.0.0")
<T> ServerResponse registerWriter(Class<T> type,
                                  MediaType contentType,
                                  Function<? extends T,Flow.Publisher<DataChunk>> function)

Deprecated.

since 2.0.0, use registerWriter(io.helidon.media.common.MessageBodyWriter) instead

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

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

Deprecated.

since 2.0.0, use registerWriter(io.helidon.media.common.MessageBodyWriter) instead

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

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

Deprecated.

since 2.0.0, use registerWriter(io.helidon.media.common.MessageBodyWriter) instead

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

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

Deprecated.

since 2.0.0, use registerFilter(io.helidon.media.common.MessageBodyFilter) instead

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

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