Class Request

java.lang.Object
com.soklet.core.Request
@ThreadSafe public class Request extends Object
Encapsulates information specified in an HTTP request.

Detailed documentation available at https://www.soklet.com/docs/request-handling.

Author:
Mark Allen

  • Method Details

    • with

      @Nonnull public static Request.Builder with(@Nonnull HttpMethod httpMethod, @Nonnull String uri)
      Acquires a builder for Request instances.
      Parameters:
      httpMethod - the HTTP method for this request (GET, POST, etc.)
      uri - the URI for this request, which must start with a / character and might include query parameters, e.g. /example/123 or /one?two=three
      Returns:
      the builder

    • copy

      @Nonnull public Request.Copier copy()
      Vends a mutable copier seeded with this instance's data, suitable for building new instances.
      Returns:
      a copier for this instance

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • equals

      public boolean equals(@Nullable Object object)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • getId

      @Nonnull public Object getId()
      An application-specific identifier for this request.

      The identifier is not necessarily unique (for example, numbers that "wrap around" if they get too large).

      Returns:
      the request's identifier

    • getHttpMethod

      @Nonnull public HttpMethod getHttpMethod()
      The HTTP method for this request.
      Returns:
      the request's HTTP method

    • getUri

      @Nonnull public String getUri()
      The URI for this request, which must start with a / character and might include query parameters, such as /example/123 or /one?two=three.
      Returns:
      the request's URI

    • getPath

      @Nonnull public String getPath()
      The path component of this request, which is a representation of the value returned by getUri() with the query string (if any) removed.
      Returns:
      the path for this request

    • getResourcePath

      @Nonnull public ResourcePath getResourcePath()
      Convenience method to acquire a ResourcePath representation of getPath().
      Returns:
      the resource path for this request

    • getCookies

      @Nonnull public Map<String,Set<String>> getCookies()
      The cookies provided by the client for this request.

      The keys are the Cookie header names and the values are Cookie header values (it is possible for a client to send multiple Cookie headers with the same name).

      Note that Cookie headers, like all request headers, have case-insensitive names per the HTTP spec.

      Use getCookie(String) for a convenience method to access cookie values when only one is expected.

      Returns:
      the request's cookies

    • getQueryParameters

      @Nonnull public Map<String,Set<String>> getQueryParameters()
      The query parameters provided by the client for this request.

      The keys are the query parameter names and the values are query parameter values (it is possible for a client to send multiple query parameters with the same name, e.g. ?test=1&test=2).

      Note that query parameters have case-sensitive names per the HTTP spec.

      Use getQueryParameter(String) for a convenience method to access query parameter values when only one is expected.

      Returns:
      the request's query parameters

    • getFormParameters

      @Nonnull public Map<String,Set<String>> getFormParameters()
      The HTML form parameters provided by the client for this request.

      The keys are the form parameter names and the values are form parameter values (it is possible for a client to send multiple form parameters with the same name, e.g. ?test=1&test=2).

      Note that form parameters have case-sensitive names per the HTTP spec.

      Use getFormParameter(String) for a convenience method to access form parameter values when only one is expected.

      Returns:
      the request's form parameters

    • getHeaders

      @Nonnull public Map<String,Set<String>> getHeaders()
      The headers provided by the client for this request.

      The keys are the header names and the values are header values (it is possible for a client to send multiple headers with the same name).

      Note that request headers have case-insensitive names per the HTTP spec.

      Use getHeader(String) for a convenience method to access header values when only one is expected.

      Returns:
      the request's headers

    • getContentType

      @Nonnull public Optional<String> getContentType()
      The Content-Type header value, as specified by the client.
      Returns:
      the request's Content-Type header value, or Optional.empty() if not specified

    • getCharset

      @Nonnull public Optional<Charset> getCharset()
      The request's character encoding, as specified by the client in the Content-Type header value.
      Returns:
      the request's character encoding, or Optional.empty() if not specified

    • isMultipart

      @Nonnull public Boolean isMultipart()
      Is this a request with Content-Type of multipart/form-data?
      Returns:
      true if this is a multipart/form-data request, false otherwise

    • getMultipartFields

      @Nonnull public Map<String,Set<MultipartField>> getMultipartFields()
      The HTML multipart/form-data fields provided by the client for this request.

      The keys are the multipart field names and the values are multipart field values (it is possible for a client to send multiple multipart fields with the same name).

      Note that multipart fields have case-sensitive names per the HTTP spec.

      Use getMultipartField(String) for a convenience method to access a multipart parameter field value when only one is expected.

      When using DefaultServer, multipart fields are parsed using the MultipartParser as configured by DefaultServer.Builder.multipartParser(MultipartParser).

      Returns:
      the request's multipart fields, or the empty map if none are present

    • getBody

      @Nonnull public Optional<byte[]> getBody()
      The raw bytes of the request body.

      For convenience, getBodyAsString() is available if you expect your request body to be of type String.

      Returns:
      the request body bytes, or Optional.empty() if none was supplied

    • isContentTooLarge

      @Nonnull public Boolean isContentTooLarge()
      Was this request too large for the server to handle?

      If so, this request might have incomplete sets of headers/cookies. It will always have a zero-length body.

      Soklet is designed to power systems that exchange small "transactional" payloads that live entirely in memory. It is not appropriate for handling multipart files at scale, buffering uploads to disk, streaming, etc.

      When using DefaultServer, maximum request size is configured by DefaultServer.Builder.maximumRequestSizeInBytes(Integer).

      Returns:
      true if this request is larger than the server is able to handle, false otherwise

    • getBodyAsString

      @Nonnull public Optional<String> getBodyAsString()
      Convenience method that provides the getBody() bytes as a String encoded using the client-specified character set per getCharset().

      If no character set is specified, StandardCharsets.UTF_8 is used to perform the encoding.

      This method will lazily convert the raw bytes as specified by getBody() to an instance of String when first invoked. The String representation is then cached and re-used for subsequent invocations.

      This method is threadsafe.

      Returns:
      a String representation of this request's body, or Optional.empty() if no request body was specified by the client

    • getCors

      @Nonnull public Optional<Cors> getCors()
      Non-preflight CORS request data.

      See https://www.soklet.com/docs/cors for details.

      Returns:
      non-preflight CORS request data, or Optional.empty() if none was specified

    • getCorsPreflight

      @Nonnull public Optional<CorsPreflight> getCorsPreflight()
      CORS preflight-related request data.

      See https://www.soklet.com/docs/cors for details.

      Returns:
      preflight CORS request data, or Optional.empty() if none was specified

    • getLocales

      @Nonnull public List<Locale> getLocales()
      Locale information for this request as specified by Accept-Language header value[s] and ordered by weight as defined by RFC 7231, Section 5.3.5.

      This method will lazily parse Accept-Language header values into to an ordered List of Locale when first invoked. This representation is then cached and re-used for subsequent invocations.

      This method is threadsafe.

      Returns:
      locale information for this request, or the empty list if none was specified

    • getQueryParameter

      @Nonnull public Optional<String> getQueryParameter(@Nonnull String name)
      Convenience method to access a query parameter's value when at most one is expected for the given name.

      If a query parameter name can support multiple values, getQueryParameters() should be used instead of this method.

      If this method is invoked for a query parameter name with multiple values, Soklet does not guarantee which value will be returned.

      Note that query parameters have case-sensitive names per the HTTP spec.

      Parameters:
      name - the name of the query parameter
      Returns:
      the value for the query parameter, or Optional.empty() if none is present

    • getFormParameter

      @Nonnull public Optional<String> getFormParameter(@Nonnull String name)
      Convenience method to access a form parameter's value when at most one is expected for the given name.

      If a form parameter name can support multiple values, getFormParameters() should be used instead of this method.

      If this method is invoked for a form parameter name with multiple values, Soklet does not guarantee which value will be returned.

      Note that form parameters have case-sensitive names per the HTTP spec.

      Parameters:
      name - the name of the form parameter
      Returns:
      the value for the form parameter, or Optional.empty() if none is present

    • getHeader

      @Nonnull public Optional<String> getHeader(@Nonnull String name)
      Convenience method to access a header's value when at most one is expected for the given name.

      If a header name can support multiple values, getHeaders() should be used instead of this method.

      If this method is invoked for a header name with multiple values, Soklet does not guarantee which value will be returned.

      Note that request headers have case-insensitive names per the HTTP spec.

      Parameters:
      name - the name of the header
      Returns:
      the value for the header, or Optional.empty() if none is present

    • getCookie

      @Nonnull public Optional<String> getCookie(@Nonnull String name)
      Convenience method to access a cookie's value when at most one is expected for the given name.

      If a cookie name can support multiple values, getCookies() should be used instead of this method.

      If this method is invoked for a cookie name with multiple values, Soklet does not guarantee which value will be returned.

      Note that Cookie headers, like all request headers, have case-insensitive names per the HTTP spec.

      Parameters:
      name - the name of the cookie
      Returns:
      the value for the cookie, or Optional.empty() if none is present

    • getMultipartField

      @Nonnull public Optional<MultipartField> getMultipartField(@Nonnull String name)
      Convenience method to access a multipart field when at most one is expected for the given name.

      If a name can support multiple multipart fields, getMultipartFields() should be used instead of this method.

      If this method is invoked for a name with multiple multipart field values, Soklet does not guarantee which value will be returned.

      Note that multipart fields have case-sensitive names per the HTTP spec.

      Parameters:
      name - the name of the multipart field
      Returns:
      the multipart field value, or Optional.empty() if none is present