org.springframework.web.reactive.function.server

## Interface ServerRequest

- All Known Implementing Classes:
    MockServerRequest, ServerRequestWrapper

      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(BodyExtractor)`, respectively.

  Since:
    5.0
  Author:
    Arjen Poutsma, Sebastien Deleuze

- - ### 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(BodyExtractor<T,? super ServerHttpRequest> extractor)` Extract the body with the given `BodyExtractor`.
    `<T> T` | `body(BodyExtractor<T,? super ServerHttpRequest> extractor, Map<String,Object> hints)` Extract the body with the given `BodyExtractor` and hints.
    `<T> reactor.core.publisher.Flux<T>` | `bodyToFlux(Class<? extends T> elementClass)` Extract the body to a `Flux`.
    `<T> reactor.core.publisher.Flux<T>` | `bodyToFlux(ParameterizedTypeReference<T> typeReference)` Extract the body to a `Flux`.
    `<T> reactor.core.publisher.Mono<T>` | `bodyToMono(Class<? extends T> elementClass)` Extract the body to a `Mono`.
    `<T> reactor.core.publisher.Mono<T>` | `bodyToMono(ParameterizedTypeReference<T> typeReference)` Extract the body to a `Mono`.
    `default reactor.core.publisher.Mono<ServerResponse>` | `checkNotModified(Instant lastModified)` Check whether the requested resource has been modified given the supplied last-modified timestamp (as determined by the application).
    `default reactor.core.publisher.Mono<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 reactor.core.publisher.Mono<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,HttpCookie>` | `cookies()` Get the cookies of this request.
    `static ServerRequest` | `create(ServerWebExchange exchange, List<HttpMessageReader<?>> messageReaders)` Create a new `ServerRequest` based on the given `ServerWebExchange` and message readers.
    `ServerWebExchange` | `exchange()` Get the web exchange that this request is based on.
    `reactor.core.publisher.Mono<MultiValueMap<String,String>>` | `formData()` Get the form data from the body of the request if the Content-Type is `"application/x-www-form-urlencoded"` or an empty map otherwise.
    `static ServerRequest.Builder` | `from(ServerRequest other)` Create a builder with the message readers, method name, URI, headers, cookies, and attributes of the given request.
    `ServerRequest.Headers` | `headers()` Get the headers of this request.
    `Optional<InetSocketAddress>` | `localAddress()` Get the local address to which this request is connected, if available.
    `List<HttpMessageReader<?>>` | `messageReaders()` 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.
    `reactor.core.publisher.Mono<MultiValueMap<String,Part>>` | `multipartData()` Get the parts of a multipart request if the Content-Type is `"multipart/form-data"` or an empty map otherwise.
    `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.
    `reactor.core.publisher.Mono<? extends Principal>` | `principal()` Get the authenticated user for the request, if any.
    `default Optional<String>` | `queryParam(String name)` Get the first query parameter with the given name, if present.
    `MultiValueMap<String,String>` | `queryParams()` Get all query parameters for this request.
    `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`.
    `reactor.core.publisher.Mono<WebSession>` | `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`.

      Note: as of 5.1 this method ignores `"Forwarded"` and `"X-Forwarded-*"` headers that specify the client-originated address. Consider using the `ForwardedHeaderFilter` to extract and use, or to discard such headers.

      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,HttpCookie> cookies()

      Get the cookies of this request.

    - #### remoteAddress

          Optional<InetSocketAddress> remoteAddress()

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

    - #### localAddress

          Optional<InetSocketAddress> localAddress()

      Get the local address to which this request is connected, if available.
      Since:
        5.2.3

    - #### messageReaders

          List<HttpMessageReader<?>> messageReaders()

      Get the readers used to convert the body of this request.
      Since:
        5.1

    - #### body

          <T> T body(BodyExtractor<T,? super ServerHttpRequest> extractor)

      Extract the body with the given `BodyExtractor`.
      Type Parameters:
        `T` - the type of the body returned
      Parameters:
        `extractor` - the `BodyExtractor` that reads from the request
      Returns:
        the extracted body
      See Also:
        `body(BodyExtractor, Map)`

    - #### body

          <T> T body(BodyExtractor<T,? super ServerHttpRequest> extractor,
                     Map<String,Object> hints)

      Extract the body with the given `BodyExtractor` and hints.
      Type Parameters:
        `T` - the type of the body returned
      Parameters:
        `extractor` - the `BodyExtractor` that reads from the request
        `hints` - the map of hints like `Jackson2CodecSupport.JSON_VIEW_HINT` to use to customize body extraction
      Returns:
        the extracted body

    - #### bodyToMono

          <T> reactor.core.publisher.Mono<T> bodyToMono(Class<? extends T> elementClass)

      Extract the body to a `Mono`.
      Type Parameters:
        `T` - the element type
      Parameters:
        `elementClass` - the class of element in the `Mono`
      Returns:
        the body as a mono

    - #### bodyToMono

          <T> reactor.core.publisher.Mono<T> bodyToMono(ParameterizedTypeReference<T> typeReference)

      Extract the body to a `Mono`.
      Type Parameters:
        `T` - the element type
      Parameters:
        `typeReference` - a type reference describing the expected response request type
      Returns:
        a mono containing the body of the given type `T`

    - #### bodyToFlux

          <T> reactor.core.publisher.Flux<T> bodyToFlux(Class<? extends T> elementClass)

      Extract the body to a `Flux`.
      Type Parameters:
        `T` - the element type
      Parameters:
        `elementClass` - the class of element in the `Flux`
      Returns:
        the body as a flux

    - #### bodyToFlux

          <T> reactor.core.publisher.Flux<T> bodyToFlux(ParameterizedTypeReference<T> typeReference)

      Extract the body to a `Flux`.
      Type Parameters:
        `T` - the element type
      Parameters:
        `typeReference` - a type reference describing the expected request body type
      Returns:
        a flux containing the body of the given type `T`

    - #### 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

    - #### queryParam

          default Optional<String> queryParam(String name)

      Get the first query parameter with the given name, if present.
      Parameters:
        `name` - the parameter name
      Returns:
        the parameter value

    - #### queryParams

          MultiValueMap<String,String> queryParams()

      Get all query parameters for this request.

    - #### 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

          reactor.core.publisher.Mono<WebSession> session()

      Get the web session for this request.

      Always guaranteed to return an instance either matching 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

          reactor.core.publisher.Mono<? extends Principal> principal()

      Get the authenticated user for the request, if any.

    - #### formData

          reactor.core.publisher.Mono<MultiValueMap<String,String>> formData()

      Get the form data from the body of the request if the Content-Type is `"application/x-www-form-urlencoded"` or an empty map otherwise.

      Note: calling this method causes the request body to be read and parsed in full, and the resulting `MultiValueMap` is cached so that this method is safe to call more than once.

    - #### multipartData

          reactor.core.publisher.Mono<MultiValueMap<String,Part>> multipartData()

      Get the parts of a multipart request if the Content-Type is `"multipart/form-data"` or an empty map otherwise.

      Note: calling this method causes the request body to be read and parsed in full, and the resulting `MultiValueMap` is cached so that this method is safe to call more than once.

    - #### exchange

          ServerWebExchange exchange()

      Get the web exchange that this request is based on.

      Note: Manipulating the exchange directly (instead of using the methods provided on `ServerRequest` and `ServerResponse`) can lead to irregular results.

      Since:
        5.1

    - #### checkNotModified

          default reactor.core.publisher.Mono<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 Mono<ServerResponse> myHandleMethod(ServerRequest request) {
             Instant lastModified = // application-specific calculation
                   return request.checkNotModified(lastModified)
                     .switchIfEmpty(Mono.defer(() -> {
                       // 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 reactor.core.publisher.Mono<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 Mono<ServerResponse> myHandleMethod(ServerRequest request) {
             String eTag = // application-specific calculation
                   return request.checkNotModified(eTag)
                     .switchIfEmpty(Mono.defer(() -> {
                       // 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 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 reactor.core.publisher.Mono<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 Mono<ServerResponse> myHandleMethod(ServerRequest request) {
             Instant lastModified = // application-specific calculation
             String eTag = // application-specific calculation
                   return request.checkNotModified(lastModified, eTag)
                     .switchIfEmpty(Mono.defer(() -> {
                       // 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(ServerWebExchange exchange,
                                      List<HttpMessageReader<?>> messageReaders)

      Create a new `ServerRequest` based on the given `ServerWebExchange` and message readers.
      Parameters:
        `exchange` - the exchange
        `messageReaders` - the message readers
      Returns:
        the created `ServerRequest`

    - #### from

          static ServerRequest.Builder from(ServerRequest other)

      Create a builder with the message readers, method name, URI, headers, cookies, and attributes of the given request.
      Parameters:
        `other` - the request to copy the message readers, method name, URI, headers, and attributes from
      Returns:
        the created builder
      Since:
        5.1