Interface ResponseMarshaler

public interface ResponseMarshaler

Prepares responses for each request scenario Soklet supports (happy path, exception, CORS preflight, etc.)

The MarshaledResponse value returned from these methods is what is ultimately sent back to clients as bytes over the wire.

Standard implementations can be acquired via these factory methods:

• withDefaults()
• withCharset(Charset)

Full documentation is available at https://www.soklet.com/docs/response-writing.

Author:

Mark Allen

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	ResponseMarshaler.Builder	Builder used to construct a standard implementation of ResponseMarshaler.

Method Summary

Modifier and Type	Method	Description
MarshaledResponse	forContentTooLarge(Request request, ResourceMethod resourceMethod)	Prepares a response for a request that triggers an HTTP 413 Content Too Large.
MarshaledResponse	forCorsAllowed(Request request, Cors cors, CorsResponse corsResponse, MarshaledResponse marshaledResponse)	Applies "CORS is permitted for this request" data to a response.
MarshaledResponse	forCorsPreflightAllowed(Request request, CorsPreflight corsPreflight, CorsPreflightResponse corsPreflightResponse)	Prepares a response for "CORS preflight allowed" scenario when your CorsAuthorizer approves a preflight request.
MarshaledResponse	forCorsPreflightRejected(Request request, CorsPreflight corsPreflight)	Prepares a response for "CORS preflight rejected" scenario when your CorsAuthorizer denies a preflight request.
MarshaledResponse	forHappyPath(Request request, Response response, ResourceMethod resourceMethod)	Prepares a "happy path" response - the request was matched to a Resource Method and executed non-exceptionally.
MarshaledResponse	forHead(Request request, MarshaledResponse getMethodMarshaledResponse)	Prepares a response for an HTTP HEAD request.
MarshaledResponse	forMethodNotAllowed(Request request, Set<HttpMethod> allowedHttpMethods)	Prepares a response for a request that triggers an HTTP 405 Method Not Allowed.
MarshaledResponse	forNotFound(Request request)	Prepares a response for a request that triggers an HTTP 404 Not Found.
MarshaledResponse	forOptions(Request request, Set<HttpMethod> allowedHttpMethods)	Prepares a response for an HTTP OPTIONS request.
MarshaledResponse	forThrowable(Request request, Throwable throwable, ResourceMethod resourceMethod)	Prepares a response for scenarios in which an uncaught exception is encountered.
static ResponseMarshaler.Builder	withCharset(Charset charset)	Acquires a builder for a default ResponseMarshaler implementation.
static ResponseMarshaler	withDefaults()	Acquires a ResponseMarshaler with a reasonable "out of the box" configuration.

Method Details

forHappyPath

@Nonnull
MarshaledResponse forHappyPath(@Nonnull
 Request request,
 @Nonnull
 Response response,
 @Nonnull
 ResourceMethod resourceMethod)

Prepares a "happy path" response - the request was matched to a Resource Method and executed non-exceptionally.

Detailed documentation is available at https://www.soklet.com/docs/response-writing#happy-path.

Parameters:

request - the HTTP request

response - the response provided by the Resource Method that handled the request

resourceMethod - the Resource Method that handled the request

Returns:

the response to be sent over the wire

forNotFound

@Nonnull
MarshaledResponse forNotFound(@Nonnull
 Request request)

Prepares a response for a request that triggers an HTTP 404 Not Found.

Detailed documentation is available at https://www.soklet.com/docs/response-writing#404-not-found.

Parameters:

request - the HTTP request

Returns:

the response to be sent over the wire

forMethodNotAllowed

@Nonnull
MarshaledResponse forMethodNotAllowed(@Nonnull
 Request request,
 @Nonnull
 Set<HttpMethod> allowedHttpMethods)

Prepares a response for a request that triggers an HTTP 405 Method Not Allowed.

Detailed documentation is available at https://www.soklet.com/docs/response-writing#405-method-not-allowed.

Parameters:

request - the HTTP request

allowedHttpMethods - appropriate HTTP methods to write to the Allow response header

Returns:

the response to be sent over the wire

forContentTooLarge

@Nonnull
MarshaledResponse forContentTooLarge(@Nonnull
 Request request,
 @Nullable
 ResourceMethod resourceMethod)

Prepares a response for a request that triggers an HTTP 413 Content Too Large.

Detailed documentation is available at https://www.soklet.com/docs/response-writing#413-content-too-large.

Parameters:

request - the HTTP request

resourceMethod - the Resource Method that would have handled the request, if available

Returns:

the response to be sent over the wire

forOptions

@Nonnull
MarshaledResponse forOptions(@Nonnull
 Request request,
 @Nonnull
 Set<HttpMethod> allowedHttpMethods)

Prepares a response for an HTTP OPTIONS request.

Note that CORS preflight responses are handled specially by forCorsPreflightAllowed(Request, CorsPreflight, CorsPreflightResponse) and forCorsPreflightRejected(Request, CorsPreflight) - not this method.

Detailed documentation is available at https://www.soklet.com/docs/response-writing#http-options.

Parameters:

request - the HTTP request

allowedHttpMethods - appropriate HTTP methods to write to the Allow response header

Returns:

the response to be sent over the wire

forThrowable

@Nonnull
MarshaledResponse forThrowable(@Nonnull
 Request request,
 @Nonnull
 Throwable throwable,
 @Nullable
 ResourceMethod resourceMethod)

Prepares a response for scenarios in which an uncaught exception is encountered.

Detailed documentation is available at https://www.soklet.com/docs/response-writing#uncaught-exceptions.

Parameters:

request - the HTTP request

throwable - the exception that was thrown

resourceMethod - the Resource Method that would have handled the request, if available

Returns:

the response to be sent over the wire

forHead

@Nonnull
MarshaledResponse forHead(@Nonnull
 Request request,
 @Nonnull
 MarshaledResponse getMethodMarshaledResponse)

Prepares a response for an HTTP HEAD request.

Detailed documentation is available at https://www.soklet.com/docs/response-writing#http-head.

Parameters:

request - the HTTP request

getMethodMarshaledResponse - the binary data that would have been sent over the wire for an equivalent GET request (necessary in order to write the Content-Length header for a HEAD response)

Returns:

the response to be sent over the wire

forCorsPreflightAllowed

@Nonnull
MarshaledResponse forCorsPreflightAllowed(@Nonnull
 Request request,
 @Nonnull
 CorsPreflight corsPreflight,
 @Nonnull
 CorsPreflightResponse corsPreflightResponse)

Prepares a response for "CORS preflight allowed" scenario when your CorsAuthorizer approves a preflight request.

Detailed documentation is available at https://www.soklet.com/docs/cors#writing-cors-responses.

Parameters:

request - the HTTP request

corsPreflight - the CORS preflight request data

corsPreflightResponse - the data that should be included in this CORS preflight response

Returns:

the response to be sent over the wire

forCorsPreflightRejected

@Nonnull
MarshaledResponse forCorsPreflightRejected(@Nonnull
 Request request,
 @Nonnull
 CorsPreflight corsPreflight)

Prepares a response for "CORS preflight rejected" scenario when your CorsAuthorizer denies a preflight request.

Detailed documentation is available at https://www.soklet.com/docs/cors#writing-cors-responses.

Parameters:

request - the HTTP request

corsPreflight - the CORS preflight request data

Returns:

the response to be sent over the wire

forCorsAllowed

@Nonnull
MarshaledResponse forCorsAllowed(@Nonnull
 Request request,
 @Nonnull
 Cors cors,
 @Nonnull
 CorsResponse corsResponse,
 @Nonnull
 MarshaledResponse marshaledResponse)

Applies "CORS is permitted for this request" data to a response.

Invoked for any non-preflight CORS request that your CorsAuthorizer approves.

This method will normally return a copy of the marshaledResponse with these headers applied based on the values of corsResponse:

• Access-Control-Allow-Origin (required)
• Access-Control-Allow-Credentials (optional)
• Access-Control-Expose-Headers (optional)

Parameters:

request - the HTTP request

cors - the CORS request data

corsResponse - CORS response data to write as specified by CorsAuthorizer

marshaledResponse - the existing response to which we should apply relevant CORS headers

Returns:

the response to be sent over the wire

withDefaults

@Nonnull
static ResponseMarshaler withDefaults()

Acquires a ResponseMarshaler with a reasonable "out of the box" configuration.

Callers should not rely on reference identity; this method may return a new or cached instance.

Returns:

a ResponseMarshaler with default settings

withCharset

@Nonnull
static ResponseMarshaler.Builder withCharset(@Nonnull
 Charset charset)

Acquires a builder for a default ResponseMarshaler implementation.

Parameters:

charset - the default charset to use when writing response data

Returns:

a ResponseMarshaler builder