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, jakarta.servlet.http.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 jakarta.servlet.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:
      jakarta.servlet.ServletException
      IOException

    • body

      <T> T body(ParameterizedTypeReference<T> bodyType) throws jakarta.servlet.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:
      jakarta.servlet.ServletException
      IOException

    • bind

      default <T> T bind(Class<T> bindType) throws BindException
      Bind to this request and return an instance of the given type.

      Please read the security warning om DataBinder and review the guidance on model object design in the Data Binding section for Spring MVC in the reference documentation.

      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.

      Please read the security warning om DataBinder and review the guidance on model object design in the Data Binding section for Spring MVC in the reference documentation.

      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 allowed fields if using property (instead of constructor) binding.
      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:
      • 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, jakarta.servlet.http.Part> multipartData() throws IOException, jakarta.servlet.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
      jakarta.servlet.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

      jakarta.servlet.http.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

      jakarta.servlet.http.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(jakarta.servlet.http.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(jakarta.servlet.http.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