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

  • Method Details

    • method

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

    • 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.

    • 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.

    • apiVersionStrategy

      @Nullable ApiVersionStrategy apiVersionStrategy()
      Return the configured ApiVersionStrategy, or null.
      Since:
      7.0

    • 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

    • bind

      default <T> T bind(Class<T> bindType) throws BindException
      Bind to this request and return an instance of the given type.
      Type Parameters:
      T - the type to bind to
      Parameters:
      bindType - the type of class to bind this request to
      Returns:
      a constructed and bound instance of bindType
      Throws:
      BindException - in case of binding errors
      Since:
      6.1

    • bind

      <T> T bind(Class<T> bindType, Consumer<WebDataBinder> dataBinderCustomizer) throws BindException
      Bind to this request and return an instance of the given type.
      Type Parameters:
      T - the type to bind to
      Parameters:
      bindType - the type of class to bind this request to
      dataBinderCustomizer - used to customize the data binder, for example, set (dis)allowed fields
      Returns:
      a constructed and bound instance of bindType
      Throws:
      BindException - in case of binding errors
      Since:
      6.1

    • 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:

    • 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:

    • 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:

    • 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

    • create

      static ServerRequest create(HttpServletRequest servletRequest, List<HttpMessageConverter<?>> messageReaders, @Nullable ApiVersionStrategy versionStrategy)
      Create a new ServerRequest based on the given HttpServletRequest and message converters.
      Parameters:
      servletRequest - the request
      messageReaders - the message readers
      versionStrategy - a strategy to use to parse version
      Returns:
      the created ServerRequest
      Since:
      7.0

    • 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