Package ratpack.core.http

Interface Response

  • public interface Response
    A response to a request.

    The headers and status are configured, before committing the response with one of the send() methods.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static com.google.common.reflect.TypeToken<Response> TYPE
      A type token for this type.

    • Method Summary

      All Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      Response beforeSend​(Action<? super Response> responseFinalizer)
      Register a callback to execute with the response immediately before sending it to the client.
      Response contentType​(CharSequence contentType)
      Sets the response Content-Type header.
      default Response contentTypeIfNotSet​(CharSequence contentType)
      Sets the response Content-Type header, if it has not already been set.
      Response contentTypeIfNotSet​(Supplier<CharSequence> contentType)  
      io.netty.handler.codec.http.cookie.Cookie cookie​(String name, String value)
      Creates a new cookie with the given name and value.
      io.netty.handler.codec.http.cookie.Cookie expireCookie​(String name)
      Adds a cookie to the response with a 0 max-age, forcing the client to expire it.
      default Response forceCloseConnection()
      Forces the closing of the current connection, even if the client requested it to be kept alive.
      Set<io.netty.handler.codec.http.cookie.Cookie> getCookies()
      The cookies that are to be part of the response.
      MutableHeaders getHeaders()
      The response headers.
      Status getStatus()
      The status that will be part of the response when sent.
      Response noCompress()
      Prevents the response from being compressed.
      void send()
      Sends the response back to the client, with no body.
      void send​(byte[] bytes)
      Sends the response, using "application/octet-stream" as the content type (if a content type hasn't already been set) and the given byte array as the response body.
      void send​(io.netty.buffer.ByteBuf buffer)
      Sends the response, using "application/octet-stream" as the content type (if a content type hasn't already been set) and the given bytes as the response body.
      void send​(CharSequence contentType, byte[] bytes)
      Sends the response, using the given content type and byte array as the response body.
      void send​(CharSequence contentType, io.netty.buffer.ByteBuf buffer)
      Sends the response, using the given content type and bytes as the response body.
      void send​(CharSequence contentType, String body)
      Sends the response, using the given content type and string as the response body.
      void send​(String text)
      Sends the response, using "text/plain" as the content type and the given string as the response body.
      void sendFile​(Path file)
      Sends the response, using the file as the response body.
      void sendStream​(Publisher<? extends io.netty.buffer.ByteBuf> stream)
      Sends the response, streaming the bytes emitted by the given publisher.
      default Response status​(int code)
      Sets the status line of the response.
      Response status​(Status status)
      Sets the status line of the response.

    • Field Detail

      • TYPE

        static final com.google.common.reflect.TypeToken<Response> TYPE
        A type token for this type.
        Since:
        1.1

    • Method Detail

      • cookie

        io.netty.handler.codec.http.cookie.Cookie cookie​(String name,
                                                 String value)
        Creates a new cookie with the given name and value.

        The cookie will have no expiry. Use the returned cookie object to fine tune the cookie.

        Parameters:
        name - The name of the cookie
        value - The value of the cookie
        Returns:
        The cookie that will be sent

      • expireCookie

        io.netty.handler.codec.http.cookie.Cookie expireCookie​(String name)
        Adds a cookie to the response with a 0 max-age, forcing the client to expire it.

        If the cookie that you want to expire has an explicit path, you must use Cookie.setPath(String) on the return value of this method to have the cookie expire.

        Parameters:
        name - The name of the cookie to expire.
        Returns:
        The created cookie

      • getCookies

        Set<io.netty.handler.codec.http.cookie.Cookie> getCookies()
        The cookies that are to be part of the response.

        The cookies are mutable.

        Returns:
        The cookies that are to be part of the response.

      • getHeaders

        MutableHeaders getHeaders()
        The response headers.
        Returns:
        The response headers.

      • getStatus

        Status getStatus()
        The status that will be part of the response when sent.

        By default, this will return a "200 OK" response.

        Returns:
        The status that will be part of the response when sent
        See Also:
        status(int)

      • status

        default Response status​(int code)
        Sets the status line of the response.

        The message used will be the standard for the code.

        Parameters:
        code - The status code of the response to use when it is sent.
        Returns:
        This

      • status

        Response status​(Status status)
        Sets the status line of the response.
        Parameters:
        status - The status of the response to use when it is sent.
        Returns:
        This

      • send

        @NonBlocking
void send()
        Sends the response back to the client, with no body.

      • send

        @NonBlocking
void send​(String text)
        Sends the response, using "text/plain" as the content type and the given string as the response body.

        Equivalent to calling "send\("text/plain", text).

        Parameters:
        text - The text to render as a plain text response.

      • send

        @NonBlocking
void send​(CharSequence contentType,
          String body)
        Sends the response, using the given content type and string as the response body.

        The string will be sent in "utf8" encoding, and the given content type will have this appended. That is, given a contentType of "application/json" the actual value for the Content-Type header will be "application/json;charset=utf8".

        The value given for content type will override any previously set value for this header.

        Parameters:
        contentType - The value of the content type header
        body - The string to render as the body of the response

      • send

        @NonBlocking
void send​(byte[] bytes)
        Sends the response, using "application/octet-stream" as the content type (if a content type hasn't already been set) and the given byte array as the response body.
        Parameters:
        bytes - The response body

      • send

        @NonBlocking
void send​(CharSequence contentType,
          byte[] bytes)
        Sends the response, using the given content type and byte array as the response body.
        Parameters:
        contentType - The value of the Content-Type header
        bytes - The response body

      • send

        @NonBlocking
void send​(io.netty.buffer.ByteBuf buffer)
        Sends the response, using "application/octet-stream" as the content type (if a content type hasn't already been set) and the given bytes as the response body.
        Parameters:
        buffer - The response body

      • send

        @NonBlocking
void send​(CharSequence contentType,
          io.netty.buffer.ByteBuf buffer)
        Sends the response, using the given content type and bytes as the response body.
        Parameters:
        contentType - The value of the Content-Type header
        buffer - The response body

      • contentType

        Response contentType​(CharSequence contentType)
        Sets the response Content-Type header.
        Parameters:
        contentType - The value of the Content-Type header
        Returns:
        This

      • contentTypeIfNotSet

        default Response contentTypeIfNotSet​(CharSequence contentType)
        Sets the response Content-Type header, if it has not already been set.
        Parameters:
        contentType - The value of the Content-Type header
        Returns:
        This

      • sendFile

        @NonBlocking
void sendFile​(Path file)
        Sends the response, using the file as the response body.

        This method does not set the content length, content type or anything else. It is generally preferable to use the Context.render(Object) method with a file/path object, or an Chain.files(Action).

        Parameters:
        file - the response body

      • sendStream

        @NonBlocking
void sendStream​(Publisher<? extends io.netty.buffer.ByteBuf> stream)
        Sends the response, streaming the bytes emitted by the given publisher.

        This method does not perform chunked transfer encoding. It merely sends the raw bytes emitted by the publisher. As such, it is generally preferable to renderchunks than use this method directly.

        The response headers will be sent as is, without the implicit addition of a Content-Length header like the other send methods.

        Back pressure is applied to the given publisher based on the flow control of the network connection. That is, items are requested from the publisher as they are able to be sent by the underlying Netty layer. As such, the given publisher MUST respect back pressure. If this is not feasible, consider using Streams.buffer(org.reactivestreams.Publisher).

        The back pressure applied will be irregular, based on factors including:

        • Socket send/receive buffers
        • Client consumption rates
        • Size of the emitted byte buffers

        Data requested of the publisher is not always written immediately to the client. Netty maintains its own buffer that is fed by the given publisher. This means that data is more likely ready to send as soon as the client receives it.

        If your data source produces a small amount of data that is expensive to produce (i.e. there is a significant latency between a data request and the production of data) you may want to consider an intermediate buffer to maximize throughput to the client. However, this is rarely necessary.

        Parameters:
        stream - a stream of byte bufs to be written to the response

      • beforeSend

        Response beforeSend​(@NonBlocking
                    Action<? super Response> responseFinalizer)
        Register a callback to execute with the response immediately before sending it to the client.

        This method is often used to add response headers “at the last second”.

        The callbacks are executed after one of the send* methods. As such, those methods cannot be called during an action given to this method.

        Parameters:
        responseFinalizer - the action to execute on the response.
        Returns:
        this

      • noCompress

        Response noCompress()
        Prevents the response from being compressed.
        Returns:
        this

      • forceCloseConnection

        default Response forceCloseConnection()
        Forces the closing of the current connection, even if the client requested it to be kept alive.

        This method can be used when it is desirable to force the client's connection to close, defeating HTTP keep alive. This can be desirable in some networking environments where rate limiting or throttling is performed via edge routers or similar.

        This method simply calls getHeaders().set("Connection", "close"), which has the same effect.

        Returns:
        this
        Since:
        1.1