Module io.helidon.webserver
Package io.helidon.webserver.http

Interface ServerResponse

All Known Subinterfaces:
JsonRpcResponse, RoutingResponse
All Known Implementing Classes:
ServerResponseBase
@Describe(PerRequest.class) public interface ServerResponse
Http server response.

  • Method Details

    • status

      ServerResponse status(Status status)
      Status of the response.

      The status is mutable response metadata. Once configured, it remains on this response unless later application code or error handling changes it. Calling next(), calling reroute(String), or throwing an exception does not clear the configured status automatically.

      Configure the status before calling send() or outputStream() when it should apply to the response emitted by this route.

      Parameters:
      status - HTTP status
      Returns:
      this instance

    • status

      default ServerResponse status(int status)
      Status of the response.
      Parameters:
      status - HTTP status as integer
      Returns:
      this instance

    • status

      Status status()
      Configured HTTP status, if not configured, returns Status.OK_200.
      Returns:
      status

    • header

      default ServerResponse header(HeaderName name, String... values)
      Set a header. If the values are constant, please use HeaderValues.create(io.helidon.http.HeaderName, String...) and store the header in a constant field and call header(io.helidon.http.Header).
      Parameters:
      name - header name
      values - value(s) of the header
      Returns:
      this instance

    • header

      default ServerResponse header(String name, String... values)
      Not optimized method for setting a header. Use for unknown headers, where HeaderName cannot be cached. Use header(io.helidon.http.Header) or header(HeaderName, String...) otherwise.
      Parameters:
      name - name of the header
      values - values of the header
      Returns:
      this instance

    • header

      ServerResponse header(Header header)
      Set header with a value.

      Headers are mutable response metadata. Once configured, they remain on this response unless later application code or error handling changes them. Calling next(), calling reroute(String), or throwing an exception does not clear configured headers automatically.

      Headers cannot be set after outputStream() method is called, or after the response was sent.

      Parameters:
      header - header value
      Returns:
      this instance
      Throws:
      IllegalStateException - in case a header is set after output stream was requested, or the response was sent
      See Also:

    • send

      void send()
      Send a response with no entity.

    • send

      void send(byte[] bytes)
      Send a byte array response.
      Parameters:
      bytes - bytes to send

    • send

      default void send(byte[] bytes, int position, int length)
      Send a byte array response.
      Parameters:
      bytes - bytes to send
      position - starting position
      length - number of bytes send

    • send

      void send(Object entity)
      Send an entity, a MediaContext will be used to serialize the entity.
      Parameters:
      entity - entity object

    • send

      default void send(Optional<?> entity)
      Send an entity if present, throw NotFoundException if empty.
      Parameters:
      entity - entity as an optional

    • isSent

      boolean isSent()
      Whether this response has been sent.
      Returns:
      whether sent

    • isResponseHandled

      default boolean isResponseHandled()
      Whether this response has already been handled by the application.

      This method is intended for generated or framework code that may send a default response only when user code has not already sent an entity, obtained an output stream, or selected another routing action. Header and status changes alone do not handle the response.

      The default implementation returns isSent().

      Returns:
      whether response handling was already selected

    • outputStream

      OutputStream outputStream()
      Alternative way to send an entity, using an output stream. This should be used for entities that are big and that should not be materialized into memory.

      Configure response status and headers before requesting the output stream. The returned stream completes the response when it is closed, so it must be closed before the handler method returns.

      Returns:
      output stream

    • bytesWritten

      long bytesWritten()
      Number of bytes written to response. Only available once the response is sent.
      Returns:
      bytes written (combination of all bytes of status, headers and entity)

    • beforeSend

      default ServerResponse beforeSend(Runnable listener)
      Executed right before the first byte is written to the socket (including response status and headers). Response can be modified (i.e. headers, status) at this point, though modifying the entity may not be done, as this method is most likely called from within one of the send() methods.

      Note: this method is implemented as a default method that does nothing, for backward compatibility.

      Parameters:
      listener - lister to add to the list of listeners that will be triggered before the response is sent
      Returns:
      this instance

    • whenSent

      ServerResponse whenSent(Runnable listener)
      Completed when last byte is buffered for socket write.
      Parameters:
      listener - listener to add to the list of listeners that will be triggered once the response is sent
      Returns:
      this instance

    • reroute

      ServerResponse reroute(String newPath)
      Re-route using a different path. Configured response status and headers remain on this response unless later handling changes them.
      Parameters:
      newPath - new path to use
      Returns:
      this instance

    • reroute

      ServerResponse reroute(String path, UriQuery query)
      Re-route using a different path and query. Configured response status and headers remain on this response unless later handling changes them.
      Parameters:
      path - new path
      query - new query
      Returns:
      this instance
      Throws:
      IllegalStateException - in case the entity was already configured
      See Also:

    • next

      ServerResponse next()
      Continue processing with the next route (and if none found, return a Status.NOT_FOUND_404). If any entity method was called, this method will throw an exception. Configured response status and headers remain on this response unless later handling changes them.
      Returns:
      this instance
      Throws:
      IllegalStateException - in case the entity was already configured

    • headers

      ServerResponseHeaders headers()
      Response headers (mutable).

      Changes to these headers have the same lifecycle as headers configured through header(Header).

      Returns:
      headers

    • trailers

      ServerResponseTrailers trailers()
      Response trailers (mutable).
      Returns:
      trailers
      Throws:
      IllegalStateException - if client didn't ask for trailers with TE: trailers header in request or response doesn't contain trailer declaration headers Trailer: <trailer-name>

    • beforeTrailers

      default ServerResponse beforeTrailers(Consumer<ServerResponseTrailers> beforeTrailers)
      Callback to update any last minute trailers before they are written to the output stream.
      Parameters:
      beforeTrailers - consumer of mutable trailers
      Returns:
      this instance

    • streamResult

      void streamResult(String result)
      Description of the result of output stream processing. In case an output stream was used, calling this method will immediately close the stream and return this message as the reason for closing the response. In HTTP/1 this would be in a trailer header
      Parameters:
      result - result description

    • contentLength

      default void contentLength(long length)
      Configure a content length header for this response.
      Parameters:
      length - content length

    • sink

      default <T extends Sink<?>> T sink(GenericType<T> sinkType)
      Returns a sink from this response based on the sink type, if available.
      Type Parameters:
      T - type of sink returned
      Parameters:
      sinkType - type of sink
      Returns:
      sink or null if not available

    • streamFilter

      void streamFilter(UnaryOperator<OutputStream> filterFunction)
      Configure a custom output stream to wrap the output stream of the response.
      Parameters:
      filterFunction - the function to replace output stream of this response with a user provided one