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

Interface IRequest

All Known Implementing Classes:
Request
public interface IRequest
An HTTP request.

From Wikipedia

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

  • a request line, consisting of the case-sensitive request method, a space, the requested URL, another space, the protocol version, a carriage return, and a line feed, e.g.: 
              GET /images/logo.png HTTP/1.1
  • zero or more request header fields (at least 1 or more headers in case of HTTP/1.1), 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.: 
          Host: www.example.com
      Accept-Language: en
  • an empty line, consisting of a carriage return and a line feed;
  • an optional message body.
    • In the HTTP/1.1 protocol, all header fields except Host: hostname are optional.

A request line containing only the path name is accepted by servers to maintain compatibility with HTTP clients before the HTTP/1.0 specification in RFC 1945.

  • Method Details

    • getHeaders

      Headers getHeaders()
      Get a Headers object, which contains all the headers in the request

    • getRequestLine

      RequestLine getRequestLine()
      Obtain information about the first line. An example of a RequestLine is: 
      GET /foo?bar=baz HTTP/1.1

      This is where you look for anything in the request line, like paths or query strings.

    • getBody

      Body getBody()
      This getter will process the body data fully on the first call, and cache that data for subsequent calls.
      If there is a need to deal with very large data, such as large images or videos, consider using getSocketWrapper() instead, which will allow fine-grained control over pulling the bytes off the socket.
      For instance, if expecting a video (a large file), it may be prudent to store the data into a file while it downloads, so that the server does not need to hold the entire file in memory.

      Further explanation:

      The body contains the data beyond the initial status line and headers. For example, you will find HTML, images, and other bulk data stored in the body. If you are expecting data sent in a POST, it is usually found in the body.

      By calling this method, the entire body contents will be read. In the case of ordinary-sized data, this is not a problem. But, for the sake of explanation, if the data were a gigabyte in size, then your server would need to set aside that much in memory for it.

      It is therefore a security concern, and the defaults of the Minum system are set to prevent security failures. It is recommended that the developer handle such large data by another means, such as by using the aforementioned getSocketWrapper(). By default, the system will not read the body if the content-length is greater than the size specified by MAX_READ_SIZE_BYTES, described in the Constants class and in the "minum.config" file.

    • getRemoteRequester

      String getRemoteRequester()
      Gets a string of the ip address of the client sending this request. For example, "123.123.123.123"

    • getSocketWrapper

      ISocketWrapper getSocketWrapper()
      This getter is expected to be used for situations required finer-grained control over the socket, such as when dealing with streaming input like a game or chat, or receiving a very large file like a video. This will enable the user to read and send on the socket - powerful, but requires care.


      Note: This is an unusual method.

      It is an error to call this in addition to getBody(). Use one or the other. Mostly, expect to use getBody unless you really know what you are doing, such as streaming situations or custom body protocols.

    • getUrlEncodedIterable

      Iterable<UrlEncodedKeyValue> getUrlEncodedIterable()
      This method provides an Iterable for getting the key-value pairs of a URL-encoded body in an HTTP request. This method is intended to be used for situations where the developer requires greater control, for example, if allowing large uploads such as videos.
      If this extra level of control is not needed, the developer would benefit more from using the getBody() method, which is far more convenient.

    • getMultipartIterable

      Iterable<StreamingMultipartPartition> getMultipartIterable()
      This method provides an Iterable for getting the partitions of a multipart-form formatted body in an HTTP request. This method is intended to be used for situations where the developer requires greater control, for example, if allowing large uploads such as videos.
      If this extra level of control is not needed, the developer would benefit more from using the getBody() method, which is far more convenient.