org.springframework.web.servlet.function

## Interface ServerRequest

-     public interface ServerRequest

  Represents a server-side HTTP request, as handled by a `HandlerFunction`. Access to headers and body is offered by `ServerRequest.Headers` and `body(Class)`, respectively.
  Since:
    5.2
  Author:
    Arjen Poutsma

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static interface` | `ServerRequest.Builder` Defines a builder for a request.
    `static interface` | `ServerRequest.Headers` Represents the headers of the HTTP request.

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Default Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `default Optional<Object>` | `attribute(String name)` Get the request attribute value if present.
    `Map<String,Object>` | `attributes()` Get a mutable map of request attributes.
    `<T> T` | `body(Class<T> bodyType)` Extract the body as an object of the given type.
    `<T> T` | `body(ParameterizedTypeReference<T> bodyType)` Extract the body as an object of the given type.
    `default Optional<ServerResponse>` | `checkNotModified(Instant lastModified)` Check whether the requested resource has been modified given the supplied last-modified timestamp (as determined by the application).
    `default Optional<ServerResponse>` | `checkNotModified(Instant lastModified, String etag)` Check whether the requested resource has been modified given the supplied `ETag` (entity tag) and last-modified timestamp, as determined by the application.
    `default Optional<ServerResponse>` | `checkNotModified(String etag)` Check whether the requested resource has been modified given the supplied `ETag` (entity tag), as determined by the application.
    `MultiValueMap<String,Cookie>` | `cookies()` Get the cookies of this request.
    `static ServerRequest` | `create(HttpServletRequest servletRequest, List<HttpMessageConverter<?>> messageReaders)` Create a new `ServerRequest` based on the given `HttpServletRequest` and message converters.
    `static ServerRequest.Builder` | `from(ServerRequest other)` Create a builder with the status, headers, and cookies of the given request.
    `ServerRequest.Headers` | `headers()` Get the headers of this request.
    `List<HttpMessageConverter<?>>` | `messageConverters()` Get the readers used to convert the body of this request.
    `default HttpMethod` | `method()` Get the HTTP method.
    `String` | `methodName()` Get the name of the HTTP method.
    `MultiValueMap<String,Part>` | `multipartData()` Get the parts of a multipart request, provided the Content-Type is `"multipart/form-data"`, or an exception otherwise.
    `default Optional<String>` | `param(String name)` Get the first parameter with the given name, if present.
    `MultiValueMap<String,String>` | `params()` Get all parameters for this request.
    `default String` | `path()` Get the request path.
    `default PathContainer` | `pathContainer()` Deprecated. as of 5.3, in favor on `requestPath()`
    `default String` | `pathVariable(String name)` Get the path variable with the given name, if present.
    `Map<String,String>` | `pathVariables()` Get all path variables for this request.
    `Optional<Principal>` | `principal()` Get the authenticated user for the request, if any.
    `Optional<InetSocketAddress>` | `remoteAddress()` Get the remote address to which this request is connected, if available.
    `default RequestPath` | `requestPath()` Get the request path as a `PathContainer`.
    `HttpServletRequest` | `servletRequest()` Get the servlet request that this request is based on.
    `HttpSession` | `session()` Get the web session for this request.
    `URI` | `uri()` Get the request URI.
    `UriBuilder` | `uriBuilder()` Get a `UriBuilderComponents` from the URI associated with this `ServerRequest`.

- - ### Method Detail

    - #### method

          @Nullable
          default HttpMethod method()

      Get the HTTP method.
      Returns:
        the HTTP method as an HttpMethod enum value, or `null` if not resolvable (e.g. in case of a non-standard HTTP method)

    - #### methodName

          String methodName()

      Get the name of the HTTP method.
      Returns:
        the HTTP method as a String

    - #### uri

          URI uri()

      Get the request URI.

    - #### uriBuilder

          UriBuilder uriBuilder()

      Get a `UriBuilderComponents` from the URI associated with this `ServerRequest`.
      Returns:
        a URI builder

    - #### path

          default String path()

      Get the request path.

    - #### pathContainer

          @Deprecated
          default PathContainer pathContainer()

      Deprecated. as of 5.3, in favor on `requestPath()`
      Get the request path as a `PathContainer`.

    - #### requestPath

          default RequestPath requestPath()

      Get the request path as a `PathContainer`.
      Since:
        5.3

    - #### headers

          ServerRequest.Headers headers()

      Get the headers of this request.

    - #### cookies

          MultiValueMap<String,Cookie> cookies()

      Get the cookies of this request.

    - #### remoteAddress

          Optional<InetSocketAddress> remoteAddress()

      Get the remote address to which this request is connected, if available.

    - #### messageConverters

          List<HttpMessageConverter<?>> messageConverters()

      Get the readers used to convert the body of this request.

    - #### body

          <T> T body(Class<T> bodyType)
              throws ServletException,
                     IOException

      Extract the body as an object of the given type.
      Type Parameters:
        `T` - the body type
      Parameters:
        `bodyType` - the type of return value
      Returns:
        the body
      Throws:
        `ServletException`
        `IOException`

    - #### body

          <T> T body(ParameterizedTypeReference<T> bodyType)
              throws ServletException,
                     IOException

      Extract the body as an object of the given type.
      Type Parameters:
        `T` - the body type
      Parameters:
        `bodyType` - the type of return value
      Returns:
        the body
      Throws:
        `ServletException`
        `IOException`

    - #### attribute

          default Optional<Object> attribute(String name)

      Get the request attribute value if present.
      Parameters:
        `name` - the attribute name
      Returns:
        the attribute value

    - #### attributes

          Map<String,Object> attributes()

      Get a mutable map of request attributes.
      Returns:
        the request attributes

    - #### param

          default Optional<String> param(String name)

      Get the first parameter with the given name, if present. Servlet parameters are contained in the query string or posted form data.
      Parameters:
        `name` - the parameter name
      Returns:
        the parameter value
      See Also:
        `ServletRequest.getParameter(String)`

    - #### params

          MultiValueMap<String,String> params()

      Get all parameters for this request. Servlet parameters are contained in the query string or posted form data.
      See Also:
        `ServletRequest.getParameterMap()`

    - #### multipartData

          MultiValueMap<String,Part> multipartData()
                                            throws IOException,
                                                   ServletException

      Get the parts of a multipart request, provided the Content-Type is `"multipart/form-data"`, or an exception otherwise.
      Returns:
        the multipart data, mapping from name to part(s)
      Throws:
        `IOException` - if an I/O error occurred during the retrieval
        `ServletException` - if this request is not of type `"multipart/form-data"`
      Since:
        5.3
      See Also:
        `HttpServletRequest.getParts()`

    - #### pathVariable

          default String pathVariable(String name)

      Get the path variable with the given name, if present.
      Parameters:
        `name` - the variable name
      Returns:
        the variable value
      Throws:
        `IllegalArgumentException` - if there is no path variable with the given name

    - #### pathVariables

          Map<String,String> pathVariables()

      Get all path variables for this request.

    - #### session

          HttpSession session()

      Get the web session for this request. Always guaranteed to return an instance either matching to the session id requested by the client, or with a new session id either because the client did not specify one or because the underlying session had expired. Use of this method does not automatically create a session.

    - #### principal

          Optional<Principal> principal()

      Get the authenticated user for the request, if any.

    - #### servletRequest

          HttpServletRequest servletRequest()

      Get the servlet request that this request is based on.

    - #### checkNotModified

          default Optional<ServerResponse> checkNotModified(Instant lastModified)

      Check whether the requested resource has been modified given the supplied last-modified timestamp (as determined by the application). If not modified, this method returns a response with corresponding status code and headers, otherwise an empty result.

      Typical usage:

           public ServerResponse myHandleMethod(ServerRequest request) {
             Instant lastModified = // application-specific calculation
                   return request.checkNotModified(lastModified)
                     .orElseGet(() -> {
                       // further request processing, actually building content
                           return ServerResponse.ok().body(...);
                     });
           }

      This method works with conditional GET/HEAD requests, but also with conditional POST/PUT/DELETE requests.

      Note: you can use either this `#checkNotModified(Instant)` method; or `checkNotModified(String)`. If you want to enforce both a strong entity tag and a Last-Modified value, as recommended by the HTTP specification, then you should use `checkNotModified(Instant, String)`.

      Parameters:
        `lastModified` - the last-modified timestamp that the application determined for the underlying resource
      Returns:
        a corresponding response if the request qualifies as not modified, or an empty result otherwise.
      Since:
        5.2.5

    - #### checkNotModified

          default Optional<ServerResponse> checkNotModified(String etag)

      Check whether the requested resource has been modified given the supplied `ETag` (entity tag), as determined by the application. If not modified, this method returns a response with corresponding status code and headers, otherwise an empty result.

      Typical usage:

           public ServerResponse myHandleMethod(ServerRequest request) {
             String eTag = // application-specific calculation
                   return request.checkNotModified(eTag)
                     .orElseGet(() -> {
                       // further request processing, actually building content
                           return ServerResponse.ok().body(...);
                     });
           }

      This method works with conditional GET/HEAD requests, but also with conditional POST/PUT/DELETE requests.

      Note: you can use either this `checkNotModified(Instant)` method; or `#checkNotModified(String)`. If you want to enforce both a strong entity tag and a Last-Modified value, as recommended by the HTTP specification, then you should use `checkNotModified(Instant, String)`.

      Parameters:
        `etag` - the entity tag that the application determined for the underlying resource. This parameter will be padded with quotes (") if necessary.
      Returns:
        a corresponding response if the request qualifies as not modified, or an empty result otherwise.
      Since:
        5.2.5

    - #### checkNotModified

          default Optional<ServerResponse> checkNotModified(Instant lastModified,
                                                            String etag)

      Check whether the requested resource has been modified given the supplied `ETag` (entity tag) and last-modified timestamp, as determined by the application. If not modified, this method returns a response with corresponding status code and headers, otherwise an empty result.

      Typical usage:

           public ServerResponse myHandleMethod(ServerRequest request) {
             Instant lastModified = // application-specific calculation
             String eTag = // application-specific calculation
                   return request.checkNotModified(lastModified, eTag)
                     .orElseGet(() -> {
                       // further request processing, actually building content
                           return ServerResponse.ok().body(...);
                     });
           }

      This method works with conditional GET/HEAD requests, but also with conditional POST/PUT/DELETE requests.

      Parameters:
        `lastModified` - the last-modified timestamp that the application determined for the underlying resource
        `etag` - the entity tag that the application determined for the underlying resource. This parameter will be padded with quotes (") if necessary.
      Returns:
        a corresponding response if the request qualifies as not modified, or an empty result otherwise.
      Since:
        5.2.5

    - #### create

          static ServerRequest create(HttpServletRequest servletRequest,
                                      List<HttpMessageConverter<?>> messageReaders)

      Create a new `ServerRequest` based on the given `HttpServletRequest` and message converters.
      Parameters:
        `servletRequest` - the request
        `messageReaders` - the message readers
      Returns:
        the created `ServerRequest`

    - #### from

          static ServerRequest.Builder from(ServerRequest other)

      Create a builder with the status, headers, and cookies of the given request.
      Parameters:
        `other` - the response to copy the status, headers, and cookies from
      Returns:
        the created builder