Interface ServerResponse

All Known Subinterfaces:
JsonRpcResponse, RoutingResponse
All Known Implementing Classes:
ServerResponseBase
@Describe(Service.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() or reroute(String) does not clear configured headers automatically. If error handling replaces an unsent response entity, it removes entity-specific headers while preserving response metadata unrelated to the entity.

      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. Use this method for a HEAD response after configuring the representation metadata in the response headers.

    • send

      void send(byte[] bytes)
      Send a byte array response.
      Parameters:
      bytes - bytes to send
      Throws:
      IllegalStateException - if non-empty bytes are sent for a HEAD request

    • 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
      Throws:
      IllegalStateException - if a positive length is sent for a HEAD request

    • send

      void send(Object entity)
      Send an entity, a MediaContext will be used to serialize the entity.
      Parameters:
      entity - entity object
      Throws:
      IllegalStateException - if serialization writes a non-empty entity for a HEAD request

    • send

      default void send(Optional<?> entity)
      Send an entity if present, throw NotFoundException if empty.
      Parameters:
      entity - entity as an optional
      Throws:
      IllegalStateException - if serialization writes a non-empty entity for a HEAD request

    • 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. Writing non-empty data to the stream for a HEAD request throws an IllegalStateException.

      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)

    • automaticContentEncoding

      default ServerResponse automaticContentEncoding(boolean enabled)
      Configure whether the WebServer response layer may automatically encode the response entity using the listener content encoding context. This does not remove or rewrite any explicitly configured Content-Encoding header. Repeated calls replace the previous setting until response content encoding is selected. Content encoding is selected when an entity is sent or the response output stream is obtained.
      Parameters:
      enabled - whether automatic response content encoding is enabled
      Returns:
      this instance
      Throws:
      IllegalStateException - if response content encoding was already selected, or the response was sent

    • contentEncoder

      default ServerResponse contentEncoder(ContentEncoder encoder)
      Configure an explicit response content encoder.

      The explicit encoder takes precedence over automatic content encoding. Response stream filters process the plain entity before this encoder. Repeated calls replace the previous encoder until response content encoding is selected. The selected encoder's headers are applied once during selection, so a HEAD response exposes the same representation metadata as GET without sending the encoded entity.

      Parameters:
      encoder - content encoder
      Returns:
      this instance
      Throws:
      NullPointerException - if encoder is null
      IllegalStateException - if response content encoding was already selected, or the response was sent

    • 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. Changing the response status is supported only if the new status has the same response entity semantics. For example, changing between an entity-bearing status and a status without an entity may leave response framing inconsistent and break the response. The listener remains registered if error handling replaces the unsent response entity.

      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). Trailer state is associated with the current response entity and is cleared if error handling replaces that entity before it is sent.
      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. The callback is associated with the current response entity and is cleared if error handling replaces that entity before it is sent. A response-scoped policy should use beforeSend(Runnable) to register a fresh callback for each entity.
      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 The result is associated with the current response entity and is cleared if error handling replaces that entity before it is sent.
      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.
      Type Parameters:
      T - type of sink returned
      Parameters:
      sinkType - type of sink
      Returns:
      sink
      Throws:
      UnsupportedOperationException - if sinks are not supported by this implementation
      HttpException - if no sink provider is available for the requested type

    • streamFilter

      void streamFilter(UnaryOperator<OutputStream> filterFunction)
      Configure a custom output stream to wrap the output stream of the response. The filter remains registered if error handling replaces the unsent response entity. A filter that changes representation metadata, such as Content-Encoding, must use beforeSend(Runnable) to configure the matching headers for each entity that is sent.
      Parameters:
      filterFunction - the function to replace output stream of this response with a user provided one