Module com.renomad.minum
Package com.renomad.minum.web

Class Response

java.lang.Object
com.renomad.minum.web.Response
All Implemented Interfaces:
IResponse
public final class Response extends Object implements IResponse
Represents an HTTP response. This is what will get sent back to the client (that is, to the browser). There are a variety of overloads of this record for different situations. The overarching paradigm is to provide you high flexibility.

A response message is sent by a server to a client as a reply to its former request message.

Response syntax

A server sends response messages to the client, which consist of:

  • a status line, consisting of the protocol version, a space, the response status code, another space, a possibly empty reason phrase, a carriage return and a line feed, e.g.: 
     HTTP/1.1 200 OK
  • zero or more response header fields, each consisting of the case-insensitive field name, a colon, optional leading whitespace, the field value, an optional trailing whitespace and ending with a carriage return and a line feed, e.g.: 
     Content-Type: text/html
  • an empty line, consisting of a carriage return and a line feed;
  • an optional message body.

  • Method Details

    • buildStreamingResponse

      public static IResponse buildStreamingResponse(StatusLine.StatusCode statusCode, Map<String,String> extraHeaders, ThrowingConsumer<ISocketWrapper> outputGenerator)
      This factory method is intended for situations where the user wishes to stream data but lacks the content length. This is only for unusual situations where the developer needs the extra control. In most cases, other methods are more suitable.
      Parameters:
      extraHeaders - any extra headers for the response, such as the content-type
      outputGenerator - a function that will be given a ISocketWrapper, providing the ability to send bytes on the socket.

    • buildStreamingResponse

      public static IResponse buildStreamingResponse(StatusLine.StatusCode statusCode, Map<String,String> extraHeaders, ThrowingConsumer<ISocketWrapper> outputGenerator, long bodyLength)
      Similar to buildStreamingResponse(StatusLine.StatusCode, Map, ThrowingConsumer) but here we know the body length, so that will be sent to the client as content-length.
      Parameters:
      extraHeaders - any extra headers for the response, such as the content-type
      outputGenerator - a function that will be given a ISocketWrapper, providing the ability to send bytes on the socket.
      bodyLength - the length, in bytes, of the data to be sent to the client

    • buildResponse

      public static IResponse buildResponse(StatusLine.StatusCode statusCode, Map<String,String> extraHeaders, byte[] body)
      A constructor for situations where the developer wishes to send a small (less than a megabyte) byte array to the client. If there is need to send something of larger size, choose one these alternate constructors: FileChannel - for sending a large file: buildLargeFileResponse(Map, String, Headers) Streaming - for more custom streaming control with a known body size: buildStreamingResponse(StatusLine.StatusCode, Map, ThrowingConsumer, long) Streaming - for more custom streaming control with body size unknown: buildStreamingResponse(StatusLine.StatusCode, Map, ThrowingConsumer)
      Parameters:
      extraHeaders - any extra headers for the response, such as the content-type.

    • buildResponse

      public static IResponse buildResponse(StatusLine.StatusCode statusCode, Map<String,String> extraHeaders, String body)
      Build an ordinary response, with a known body
      Parameters:
      extraHeaders - extra HTTP headers, like 
      content-type: text/html

    • buildLargeFileResponse

      public static IResponse buildLargeFileResponse(Map<String,String> extraHeaders, String filePath, Headers requestHeaders) throws IOException
      This will send a large file to the client as a stream. Note that this does not check that the requested file is within a directory. If you expect the path value to be untrusted - that is, set by a user - use buildLargeFileResponse(Map, String, String, Headers)
      Parameters:
      extraHeaders - extra headers you would like in the response, as key-value pairs in a map - for example "Content-Type: video/mp4" or "Content-Type: application/zip"
      filePath - the string value of the path to this file. Caution! if this is set by the user. See notes above
      requestHeaders - these are the headers from the request, which is needed here to set proper response headers in some cases.
      Throws:
      IOException

    • buildLargeFileResponse

      public static IResponse buildLargeFileResponse(Map<String,String> extraHeaders, String filePath, String parentDirectory, Headers requestHeaders) throws IOException
      This will send a large file to the client as a stream. This is a safe version of the method, for when the file path is set by a user, meaning it is untrusted. By setting a parentDirectory, the system will ensure that the requested path is within that directory, thus disallowing path strings that could escape it, like prefixing with a slash.
      Parameters:
      extraHeaders - extra headers you would like in the response, as key-value pairs in a map - for example "Content-Type: video/mp4" or "Content-Type: application/zip"
      filePath - the string value of the path to this file. Caution! if this is set by the user. See notes above
      parentDirectory - this value is presumed to be set by the developer, and thus isn't checked for safety. This allows the developer to use directories anywhere in the system.
      requestHeaders - these are the headers from the request, which is needed here to set proper response headers in some cases.
      Throws:
      IOException

    • buildLeanResponse

      public static IResponse buildLeanResponse(StatusLine.StatusCode statusCode, Map<String,String> extraHeaders)
      Build a Response with just a status code and headers, without a body
      Parameters:
      extraHeaders - extra HTTP headers

    • buildLeanResponse

      public static IResponse buildLeanResponse(StatusLine.StatusCode statusCode)
      Build a Response with only a status code, with no body and no extra headers.

    • redirectTo

      public static IResponse redirectTo(String locationUrl)
      A helper method to create a response that returns a 303 status code ("see other"). Provide a url that will be handed to the browser. This url may be relative or absolute.

    • htmlOk

      public static IResponse htmlOk(String body, Map<String,String> extraHeaders)
      If you are returning HTML text with a 200 ok, this is a helper that lets you skip some of the boilerplate. This version of the helper lets you add extra headers on top of the basic content-type headers that are needed to specify this is HTML.

    • htmlOk

      public static IResponse htmlOk(String body)
      If you are returning HTML text with a 200 ok, this is a helper that lets you skip some of the boilerplate.

    • getExtraHeaders

      public Map<String,String> getExtraHeaders()
      Description copied from interface: IResponse
      Any extra headers set on the Response by the developer
      Specified by:
      getExtraHeaders in interface IResponse

    • getStatusCode

      public StatusLine.StatusCode getStatusCode()
      Description copied from interface: IResponse
      The StatusLine.StatusCode set by the developer for this Response.
      Specified by:
      getStatusCode in interface IResponse

    • getBody

      public byte[] getBody()
      Description copied from interface: IResponse
      Returns the bytes of the Response body being sent to the client
      Specified by:
      getBody in interface IResponse

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object