Module org.eclipse.jetty.server

Package org.eclipse.jetty.server

Interface Response

All Superinterfaces:

org.eclipse.jetty.io.Content.Sink

All Known Implementing Classes:

ContextResponse, GzipResponseAndCallback, Response.Wrapper, StatisticsHandler.MinimumDataRateHandler.MinimumDataRateResponse

public interface Response
extends org.eclipse.jetty.io.Content.Sink

The representation of an HTTP response, for any protocol version (HTTP/1.1, HTTP/2, HTTP/3).

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	Response.Wrapper

Method Summary

Modifier and Type	Method	Description
static void	addCookie(Response response, org.eclipse.jetty.http.HttpCookie cookie)	Adds an HTTP HttpHeader.SET_COOKIE header to the response.
static <T> T	as(Response response, Class<T> type)	Unwraps the given response, recursively, until the wrapped instance is an instance of the given type, otherwise returns null.
static OutputStream	asBufferedOutputStream(Request request, Response response)	Wraps a Response as a OutputStream that performs buffering.
static org.eclipse.jetty.io.Content.Sink	asBufferedSink(Request request, Response response)	Wraps a Response as a Content.Sink that performs buffering.
static <T extends Response> T	asInContext(Response response, Class<T> type)	Unwrap a Response back to the given type, ensuring that we do not cross a context boundary (as might be the case during cross-context dispatch).
static long	getContentBytesWritten(Response response)
org.eclipse.jetty.http.HttpFields.Mutable	getHeaders()
static Response	getOriginalResponse(Response response)	Unwraps the given response until the innermost wrapped response instance.
Request	getRequest()
int	getStatus()
Supplier<org.eclipse.jetty.http.HttpFields>	getTrailersSupplier()
boolean	hasLastWrite()	Returns whether the last write has been initiated on the response.
boolean	isCommitted()	Returns whether this response has already been committed.
boolean	isCompletedSuccessfully()	Returns whether the response completed successfully.
static org.eclipse.jetty.io.Content.Chunk.Processor	newTrailersChunkProcessor(Response response)	Returns a chunk processor suitable to be passed to the Content.copy(Content.Source, Content.Sink, Content.Chunk.Processor, Callback) method, that will handle Trailers chunks by adding their fields to the HttpFields supplied by getTrailersSupplier().
static void	putCookie(Response response, org.eclipse.jetty.http.HttpCookie cookie)	Put a HTTP HttpHeader.SET_COOKIE header to the response.
static void	replaceCookie(Response response, org.eclipse.jetty.http.HttpCookie cookie)	Deprecated. use putCookie(Response, HttpCookie)
void	reset()	Resets this response, clearing the HTTP status code, HTTP headers and HTTP trailers.
static void	sendRedirect(Request request, Response response, org.eclipse.jetty.util.Callback callback, int code, String location, boolean consumeAvailable)	Sends a 302 HTTP redirect status code to the given location.
static void	sendRedirect(Request request, Response response, org.eclipse.jetty.util.Callback callback, String location)	Sends a HTTP redirect status code to the given location, without consuming the available request content.
static void	sendRedirect(Request request, Response response, org.eclipse.jetty.util.Callback callback, String location, boolean consumeAvailable)	Sends HTTP redirect status code to the given location, without consuming the available request content.
void	setStatus(int code)	Set the response HTTP status code.
void	setTrailersSupplier(Supplier<org.eclipse.jetty.http.HttpFields> trailers)	Sets the supplier for the HTTP trailers.
static String	toRedirectURI(Request request, String location)	Common point to generate a proper "Location" header for redirects.
void	write(boolean last, ByteBuffer byteBuffer, org.eclipse.jetty.util.Callback callback)
static void	writeError(Request request, Response response, org.eclipse.jetty.util.Callback callback, int status)	Writes an error response with the given HTTP status code.
static void	writeError(Request request, Response response, org.eclipse.jetty.util.Callback callback, int status, String message)	Writes an error response with the given HTTP status code, and the given message in the response content.
static void	writeError(Request request, Response response, org.eclipse.jetty.util.Callback callback, int status, String message, Throwable cause)	Writes an error response with the given HTTP status code, and the given message in the response content.
static void	writeError(Request request, Response response, org.eclipse.jetty.util.Callback callback, Throwable cause)	Writes an error response with HTTP status code 500.
CompletableFuture<Void>	writeInterim(int status, org.eclipse.jetty.http.HttpFields headers)	Writes an HTTP interim response, with the given HTTP status code and HTTP headers.

Method Details

getRequest

Request getRequest()

Returns:

the Request associated with this Response

getStatus

int getStatus()

Returns:

the response HTTP status code

setStatus

void setStatus(int code)

Set the response HTTP status code.

Parameters:

code - the response HTTP status code

getHeaders

org.eclipse.jetty.http.HttpFields.Mutable getHeaders()

Returns:

the response HTTP headers

getTrailersSupplier

Supplier<org.eclipse.jetty.http.HttpFields> getTrailersSupplier()

Returns:

a supplier for the HTTP trailers

setTrailersSupplier

void setTrailersSupplier(Supplier<org.eclipse.jetty.http.HttpFields> trailers)

Sets the supplier for the HTTP trailers.

The method Supplier.get() may be called by the implementation multiple times, so it is important that the same value is returned in every invocation.

Example:

 // Correct usage.
 HttpFields.Mutable trailers = HttpFields.build();
 response.setTrailersSupplier(() -> trailers);

 // WRONG usage, as the value changes for
 // every invocation of supplier.get().
 response.setTrailersSupplier(() -> HttpFields.build());
 

Parameters:

trailers - a supplier for the HTTP trailers

isCommitted

boolean isCommitted()

Returns whether this response has already been committed.

Committing a response means that the HTTP status code and HTTP headers cannot be modified anymore, typically because they have already been serialized and sent over the network.

Returns:

whether this response has already been committed

hasLastWrite

boolean hasLastWrite()

Returns whether the last write has been initiated on the response.

Returns:

true if last==true has been passed to write(boolean, ByteBuffer, Callback).

isCompletedSuccessfully

boolean isCompletedSuccessfully()

Returns whether the response completed successfully.

The response HTTP status code, HTTP headers and content have been successfully serialized and sent over the network without errors.

Returns:

whether the response completed successfully

reset

void reset()

Resets this response, clearing the HTTP status code, HTTP headers and HTTP trailers.

Throws:

IllegalStateException - if the response is already committed

writeInterim

CompletableFuture<Void> writeInterim(int status,
 org.eclipse.jetty.http.HttpFields headers)

Writes an HTTP interim response, with the given HTTP status code and HTTP headers.

It is possible to write more than one interim response, for example in case of HttpStatus.EARLY_HINTS_103.

The returned CompletableFuture is notified of the result of this write, whether it succeeded or failed.

Parameters:

status - the interim HTTP status code

headers - the HTTP headers

Returns:

a CompletableFuture with the result of the write

write

void write(boolean last,
 ByteBuffer byteBuffer,
 org.eclipse.jetty.util.Callback callback)

The invocation of the passed Callback is serialized with previous calls of this method, so that it is not invoked until any invocation of the callback of a previous call to this method has returned.

Thus a Callback should not block waiting for a callback of a future call to this method.

Specified by:

write in interface org.eclipse.jetty.io.Content.Sink

Parameters:

last - whether the ByteBuffer is the last to write

byteBuffer - the ByteBuffer to write

callback - the callback to notify when the write operation is complete

newTrailersChunkProcessor

static org.eclipse.jetty.io.Content.Chunk.Processor newTrailersChunkProcessor(Response response)

Returns a chunk processor suitable to be passed to the Content.copy(Content.Source, Content.Sink, Content.Chunk.Processor, Callback) method, that will handle Trailers chunks by adding their fields to the HttpFields supplied by getTrailersSupplier().

This is specifically useful for writing trailers that have been received via the Content.Source.read() API, for example when echoing a request to a response:

   Content.copy(request, response, Response.asTrailerChunkHandler(response), callback);
 

Parameters:

response - The response for which to process a trailers chunk. If the setTrailersSupplier(Supplier) method has not been called prior to this method, then a noop processor is returned.

Returns:

A chunk processor that will add trailer chunks to the response's trailer supplied fields.

See Also:

• Content.copy(Content.Source, Content.Sink, Content.Chunk.Processor, Callback)
• Trailers

asInContext

static <T extends Response> T asInContext(Response response,
 Class<T> type)

Unwrap a Response back to the given type, ensuring that we do not cross a context boundary (as might be the case during cross-context dispatch).

Parameters:

response - the possibly wrapped response to unwrap

type - the type to unwrap to

Returns:

the response unwrapped back to the given type, or null if it cannot be unwrapped to that type or a context boundary is crossed.

as

static <T> T as(Response response,
 Class<T> type)

Unwraps the given response, recursively, until the wrapped instance is an instance of the given type, otherwise returns null.

Type Parameters:

T - the response type

Parameters:

response - the response to unwrap

type - the response type to find

Returns:

the response as the given type, or null

See Also:

• Response.Wrapper

sendRedirect

static void sendRedirect(Request request,
 Response response,
 org.eclipse.jetty.util.Callback callback,
 String location)

Sends a HTTP redirect status code to the given location, without consuming the available request content. The HttpStatus.SEE_OTHER_303 code is used, unless the request is HTTP/1.0, in which case HttpStatus.MOVED_TEMPORARILY_302 is used, unless the request is not a GET and the protocol is HTTP/1.1 or later, in which case a HttpStatus.SEE_OTHER_303 is used to make the client consistently redirect with a GET.

Parameters:

request - the HTTP request

response - the HTTP response

callback - the callback to complete

location - the redirect location as an absolute URI or encoded relative URI path.

See Also:

• sendRedirect(Request, Response, Callback, int, String, boolean)

sendRedirect

static void sendRedirect(Request request,
 Response response,
 org.eclipse.jetty.util.Callback callback,
 String location,
 boolean consumeAvailable)

Sends HTTP redirect status code to the given location, without consuming the available request content. The HttpStatus.SEE_OTHER_303 code is used, unless the request is HTTP/1.0, in which case HttpStatus.MOVED_TEMPORARILY_302 is used, unless the request is not a GET and the protocol is HTTP/1.1 or later, in which case a HttpStatus.SEE_OTHER_303 is used to make the client consistently redirect with a GET.

Parameters:

request - the HTTP request

response - the HTTP response

callback - the callback to complete

location - the redirect location as an absolute URI or encoded relative URI path.

consumeAvailable - whether to consumer the available request content

See Also:

• sendRedirect(Request, Response, Callback, int, String, boolean)

sendRedirect

static void sendRedirect(Request request,
 Response response,
 org.eclipse.jetty.util.Callback callback,
 int code,
 String location,
 boolean consumeAvailable)

Sends a 302 HTTP redirect status code to the given location.

Parameters:

request - the HTTP request

response - the HTTP response

callback - the callback to complete

code - the redirect HTTP status code

location - the redirect location as an absolute URI or encoded relative URI path.

consumeAvailable - whether to consumer the available request content

Throws:

IllegalArgumentException - if the status code is not a redirect, or the location is null

IllegalStateException - if the response is already committed

See Also:

• toRedirectURI(Request, String)

toRedirectURI

static String toRedirectURI(Request request,
 String location)

Common point to generate a proper "Location" header for redirects.

Parameters:

request - the request the redirect should be based on (needed when relative locations are provided, so that server name, scheme, port can be built out properly)

location - the redirect location as an absolute URI or encoded relative URI path. If a relative path starts with '/', then it is relative to the root, otherwise it is relative to the request.

Returns:

the full redirect "Location" URL (including scheme, host, port, path, etc...)

addCookie

static void addCookie(Response response,
 org.eclipse.jetty.http.HttpCookie cookie)

Adds an HTTP HttpHeader.SET_COOKIE header to the response.

Parameters:

response - the HTTP response

cookie - the HTTP cookie to add

See Also:

• putCookie(Response, HttpCookie)

putCookie

static void putCookie(Response response,
 org.eclipse.jetty.http.HttpCookie cookie)

Put a HTTP HttpHeader.SET_COOKIE header to the response.

If a matching HttpHeader.SET_COOKIE already exists for matching name, path, domain etc. then it will be replaced.

Parameters:

response - the HTTP response

cookie - the HTTP cookie to add

See Also:

• addCookie(Response, HttpCookie)

replaceCookie

@Deprecated
static void replaceCookie(Response response,
 org.eclipse.jetty.http.HttpCookie cookie)

Deprecated.

use putCookie(Response, HttpCookie)

Replace a cookie

Parameters:

response - the HTTP response

cookie - the HTTP cookie to add

writeError

static void writeError(Request request,
 Response response,
 org.eclipse.jetty.util.Callback callback,
 Throwable cause)

Writes an error response with HTTP status code 500.

The error Request.Handler returned by Context.getErrorHandler(), if any, is invoked.

Parameters:

request - the HTTP request

response - the HTTP response

callback - the callback to complete

cause - the cause of the error

writeError

static void writeError(Request request,
 Response response,
 org.eclipse.jetty.util.Callback callback,
 int status)

Writes an error response with the given HTTP status code.

The error Request.Handler returned by Context.getErrorHandler(), if any, is invoked.

Parameters:

request - the HTTP request

response - the HTTP response

callback - the callback to complete

status - the error HTTP status code

writeError

static void writeError(Request request,
 Response response,
 org.eclipse.jetty.util.Callback callback,
 int status,
 String message)

Writes an error response with the given HTTP status code, and the given message in the response content.

The error Request.Handler returned by Context.getErrorHandler(), if any, is invoked.

Parameters:

request - the HTTP request

response - the HTTP response

callback - the callback to complete

status - the error HTTP status code

message - the error message to write in the response content

writeError

static void writeError(Request request,
 Response response,
 org.eclipse.jetty.util.Callback callback,
 int status,
 String message,
 Throwable cause)

Writes an error response with the given HTTP status code, and the given message in the response content.

The error Request.Handler returned by Context.getErrorHandler(), if any, is invoked.

Parameters:

request - the HTTP request

response - the HTTP response

callback - the callback to complete

status - the error HTTP status code

message - the error message to write in the response content

cause - the cause of the error

getOriginalResponse

static Response getOriginalResponse(Response response)

Unwraps the given response until the innermost wrapped response instance.

Parameters:

response - the response to unwrap

Returns:

the innermost wrapped response instance

See Also:

• Response.Wrapper

getContentBytesWritten

static long getContentBytesWritten(Response response)

Parameters:

response - the HTTP response

Returns:

the number of response content bytes written to the network so far, or -1 if the number is unknown

asBufferedOutputStream

static OutputStream asBufferedOutputStream(Request request,
 Response response)

Wraps a Response as a OutputStream that performs buffering. The necessary ByteBufferPool is taken from the request's connector while the size and direction of the buffer is read from the request's HttpConfiguration.

This is equivalent to:

Content.Sink.asOutputStream(Response.asBufferedSink(request, response))

Parameters:

request - the request from which to get the buffering sink's settings

response - the response to wrap

Returns:

a buffering OutputStream

asBufferedSink

static org.eclipse.jetty.io.Content.Sink asBufferedSink(Request request,
 Response response)

Wraps a Response as a Content.Sink that performs buffering. The necessary ByteBufferPool is taken from the request's connector while the size, direction of the buffer and commit size are read from the request's HttpConfiguration.

Parameters:

request - the request from which to get the buffering sink's settings

response - the response to wrap

Returns:

a buffering Content.Sink