Interface Response

All Superinterfaces:
Content.Sink
All Known Subinterfaces:
AuthenticationState.Deferred.DeferredResponse, ServerUpgradeResponse, ServerUpgradeResponse
All Known Implementing Classes:
ContextResponse, GzipResponseAndCallback, Response.Wrapper, ServletContextResponse, ServletContextResponse, ServletCoreResponse, ServletCoreResponse, ServletCoreResponse, ServletCoreResponse, StatisticsHandler.MinimumDataRateHandler.MinimumDataRateResponse
public interface Response extends Content.Sink

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

  • 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

      HttpFields.Mutable getHeaders()
      Returns:
      the response HTTP headers

    • getTrailersSupplier

      Supplier<HttpFields> getTrailersSupplier()
      Returns:
      a supplier for the HTTP trailers

    • setTrailersSupplier

      void setTrailersSupplier(Supplier<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, 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, Callback callback)

      Writes the given ByteBuffer, notifying the Callback when the write is complete.

      Implementations guarantee that calls to this method are safely reentrant so that stack overflows are avoided in the case of mutual recursion between the execution of the Callback and a call to this method.

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

    • 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:

    • sendRedirect

      static void sendRedirect(Request request, Response response, 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

      static void sendRedirect(Request request, Response response, 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

      static void sendRedirect(Request request, Response response, 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:

    • sendRedirect

      static void sendRedirect(Request request, Response response, Callback callback, int code, String location, boolean consumeAvailable, ByteBuffer content)

      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, or 0 for a default
      location - the redirect location as an absolute URI or encoded relative URI path.
      consumeAvailable - whether to consumer the available request content
      content - the content of the response, or null for a generated HTML message if HttpConfiguration.isGenerateRedirectBody() is true.
      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

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

      static void putCookie(Response response, 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:

    • replaceCookie

      @Deprecated static void replaceCookie(Response response, 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, 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, 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, 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, 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:

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