Package org.apache.juneau.rest

Class RestRequest

java.lang.Object
jakarta.servlet.ServletRequestWrapper
jakarta.servlet.http.HttpServletRequestWrapper
org.apache.juneau.rest.RestRequest
All Implemented Interfaces:
jakarta.servlet.http.HttpServletRequest, jakarta.servlet.ServletRequest
public class RestRequest extends jakarta.servlet.http.HttpServletRequestWrapper
Represents an HTTP request for a REST resource.

The RestRequest object is an extension of the HttpServletRequest class with various built-in convenience methods for use in building REST interfaces. It can be accessed by passing it as a parameter on your REST Java method:

@RestPost(...) public Object myMethod(RestRequest req) {...}

The primary methods on this class are:

  • Method Details

    • assertCharset

      public FluentStringAssertion<RestRequest> assertCharset()
      Provides the ability to perform fluent-style assertions on the response character encoding.
      Examples:

      // Validates that the response content charset is UTF-8. request .assertCharset().is("utf-8");

      Returns:
      A new fluent assertion object.
      Throws:
      BasicHttpException - If REST call failed.

    • assertContent

      public FluentRequestContentAssertion<RestRequest> assertContent()
      Returns a fluent assertion for the request content.
      Example:

      // Validates the request content contains "foo". request .assertContent().asString().is("foo");

      Returns:
      A new fluent assertion on the content, never null.

    • assertFormParam

      public FluentRequestFormParamAssertion<RestRequest> assertFormParam(String name)
      Returns a fluent assertion for the specified form parameter.
      Example:

      // Validates the content type is JSON. request .assertFormParam("foo").asString().contains("bar");

      Parameters:
      name - The query parameter name.
      Returns:
      A new fluent assertion on the parameter, never null.

    • assertHeader

      public FluentRequestHeaderAssertion<RestRequest> assertHeader(String name)
      Returns a fluent assertion for the specified header.
      Example:

      // Validates the content type is JSON. request .assertHeader("Content-Type").asString().is("application/json");

      Parameters:
      name - The header name.
      Returns:
      A new fluent assertion on the parameter, never null.

    • assertQueryParam

      public FluentRequestQueryParamAssertion<RestRequest> assertQueryParam(String name)
      Returns a fluent assertion for the specified query parameter.
      Example:

      // Validates the content type is JSON. request .assertQueryParam("foo").asString().contains("bar");

      Parameters:
      name - The query parameter name.
      Returns:
      A new fluent assertion on the parameter, never null.

    • assertRequestLine

      public FluentRequestLineAssertion<RestRequest> assertRequestLine()
      Returns an assertion on the request line returned by getRequestLine().
      Example:

      // Validates the request content contains "foo". request .assertRequestLine().protocol().minor().is(1);

      Returns:
      A new assertion object.

    • containsFormParam

      public boolean containsFormParam(String name)
      Returns true if this request contains the specified header.
      Parameters:
      name - The header name.
      Returns:
      true if this request contains the specified header.

    • containsHeader

      public boolean containsHeader(String name)
      Returns true if this request contains the specified header.
      Parameters:
      name - The header name.
      Returns:
      true if this request contains the specified header.

    • containsQueryParam

      public boolean containsQueryParam(String name)
      Returns true if this request contains the specified header.
      Parameters:
      name - The header name.
      Returns:
      true if this request contains the specified header.

    • getAttribute

      public RequestAttribute getAttribute(String name)
      Returns the request attribute with the specified name.
      Specified by:
      getAttribute in interface jakarta.servlet.ServletRequest
      Overrides:
      getAttribute in class jakarta.servlet.ServletRequestWrapper
      Parameters:
      name - The attribute name.
      Returns:
      The attribute value, never null.

    • getAttributes

      public RequestAttributes getAttributes()
      Request attributes.

      Returns a RequestAttributes object that encapsulates access to attributes on the request.

      Example:

      @RestPost(...) public Object myMethod(RestRequest req) { // Get access to attributes. RequestAttributes attributes = req.getAttributes(); // Get a header value as a POJO. UUID etag = attributes.get("ETag", UUID.class); }

      Notes:
      • This object is modifiable.
      • Values are converted from strings using the registered part parser on the resource class.
      • The RequestAttributes object can also be passed as a parameter on the method.
      • The @Attr annotation can be used to access individual attribute values.
      See Also:
      Returns:
      The headers on this request.
      Never null.

    • getAuthorityPath

      public String getAuthorityPath()
      Returns the URI authority portion of the request.
      Returns:
      The URI authority portion of the request.

    • getBeanSession

      public BeanSession getBeanSession()
      Returns the BeanSession associated with this request.
      Returns:
      The request bean session.

    • getCharset

      public Charset getCharset()
      Returns the charset specified on the Content-Type header, or "UTF-8" if not specified.
      Returns:
      The charset to use to decode the request content.

    • getConfig

      public Config getConfig()
      Config file associated with the resource.

      Returns a config file with session-level variable resolution. The config file is identified via one of the following:

      Example:

      @RestGet(...) public void doGet(RestRequest req) { // Get config file. Config config = req.getConfig(); // Get simple values from config file. int timeout = config.get("MyResource/timeout").asInteger().orElse(=10000); // Get complex values from config file. MyBean bean = config.get("MyResource/myBean").as(MyBean.class).orElse(null); }

      Notes:
      • The Config object can also be passed as a parameter on the method.
      See Also:
      Returns:
      The config file associated with the resource, or null if resource does not have a config file associated with it.

    • getContent

      public RequestContent getContent()
      Request content.

      Returns a RequestContent object that encapsulates access to the HTTP request content.

      Example:

      @RestPost(...) public void doPost(RestRequest req) { // Convert content to a linked list of Person objects. List<Person> list = req.getContent().as(LinkedList.class, Person.class); .. }

      Notes:
      • The RequestContent object can also be passed as a parameter on the method.
      • The @Content annotation can be used to access the content as well.
      See Also:
      Returns:
      The content of this HTTP request.
      Never null.

    • getContext

      public RestContext getContext()
      Returns the resource context handling the request.

      Can be used to access servlet-init parameters or annotations during requests, such as in calls to RestGuard.guard(RestRequest, RestResponse)..

      Returns:
      The resource context handling the request.

    • getContextPath

      public String getContextPath()
      Returns the portion of the request URI that indicates the context of the request.

      The context path always comes first in a request URI. The path starts with a "/" character but does not end with a "/" character. For servlets in the default (root) context, this method returns "". The container does not decode this string.

      Specified by:
      getContextPath in interface jakarta.servlet.http.HttpServletRequest
      Overrides:
      getContextPath in class jakarta.servlet.http.HttpServletRequestWrapper
      Returns:
      The context path, never null.
      See Also:
      • HttpServletRequest.getContextPath()

    • getFormParam

      public <T> Optional<T> getFormParam(Class<T> type)
      Returns the request form-data parameter of the specified type.

      Type must have a name specified via the FormData annotation and a public constructor that takes in either value or name,value as strings.

      Type Parameters:
      T - The bean type to create.
      Parameters:
      type - The bean type to create.
      Returns:
      The parsed form-data parameter on the request, never null.

    • getFormParam

      public RequestFormParam getFormParam(String name)
      Shortcut for calling getFormData().getString(name).
      Parameters:
      name - The form data parameter name.
      Returns:
      The form data parameter value, or null if not found.

    • getFormParams

      public RequestFormParams getFormParams() throws InternalServerError
      Form-data.

      Returns a RequestFormParams object that encapsulates access to form post parameters.

      Similar to ServletRequest.getParameterMap(), but only looks for form data in the HTTP content.

      Example:

      @RestPost(...) public void doPost(RestRequest req) { // Get access to parsed form data parameters. RequestFormParams formParams = req.getFormParams(); // Get form data parameters converted to various types. int p1 = formParams.get("p1").asInteger().orElse(0); String p2 = formParams.get("p2").asString().orElse(null); UUID p3 = formParams.get("p3").as(UUID.class).orElse(null); }

      Notes:
      • This object is modifiable.
      • Values are converted from strings using the registered part parser on the resource class.
      • The RequestFormParams object can also be passed as a parameter on the method.
      • The @FormDAta annotation can be used to access individual form data parameter values.
      See Also:
      Returns:
      The URL-encoded form data from the request.
      Never null.
      Throws:
      InternalServerError - If query parameters could not be parsed.
      See Also:

    • getHeader

      public <T> Optional<T> getHeader(Class<T> type)
      Returns the request header of the specified type.

      Type must have a name specified via the Header annotation and a public constructor that takes in either value or name,value as strings.

      Typically any of the following:

      Type Parameters:
      T - The bean type to create.
      Parameters:
      type - The bean type to create.
      Returns:
      The parsed header on the request, never null.

    • getHeaderParam

      public RequestHeader getHeaderParam(String name)
      Returns the last header with a specified name of this message.

      If there is more than one matching header in the message the last element of getHeaders(String) is returned.
      If there is no matching header in the message, an empty request header object is returned.

      Example:

      // Gets a header and throws a BadRequest if it doesn't exist. request .getHeader("Foo") .assertValue().exists() .get();

      Parameters:
      name - The header name.
      Returns:
      The request header object, never null.

    • getHeaders

      public RequestHeaders getHeaders()
      Request headers.

      Returns a RequestHeaders object that encapsulates access to HTTP headers on the request.

      Example:

      @RestPost(...) public Object myMethod(RestRequest req) { // Get access to headers. RequestHeaders headers = req.getRequestHeaders(); // Add a default value. headers.addDefault("ETag", DEFAULT_UUID); // Get a header value as a POJO. UUID etag = headers.get("ETag").as(UUID.class).orElse(null); // Get a standard header. Optional<CacheControl> = headers.getCacheControl(); }

      Notes:
      • This object is modifiable.
      • Values are converted from strings using the registered part parser on the resource class.
      • The RequestHeaders object can also be passed as a parameter on the method.
      • The @Header annotation can be used to access individual header values.
      See Also:
      Returns:
      The headers on this request.
      Never null.

    • getHttpServletRequest

      public jakarta.servlet.http.HttpServletRequest getHttpServletRequest()
      Returns the wrapped servlet request.
      Returns:
      The wrapped servlet request.

    • getInputStream

      public jakarta.servlet.ServletInputStream getInputStream() throws IOException
      Returns the HTTP content content as an InputStream.

      Automatically handles GZipped input streams.

      This method is equivalent to calling getContent().getInputStream().

      Specified by:
      getInputStream in interface jakarta.servlet.ServletRequest
      Overrides:
      getInputStream in class jakarta.servlet.ServletRequestWrapper
      Returns:
      The negotiated input stream.
      Throws:
      IOException - If any error occurred while trying to get the input stream or wrap it in the GZIP wrapper.

    • getLocale

      public Locale getLocale()
      Returns the preferred Locale that the client will accept content in, based on the Accept-Language header.

      If the client request doesn't provide an Accept-Language header, this method returns the default locale for the server.

      Specified by:
      getLocale in interface jakarta.servlet.ServletRequest
      Overrides:
      getLocale in class jakarta.servlet.ServletRequestWrapper
      Returns:
      The preferred Locale that the client will accept content in. Never null.

    • getMessage

      public String getMessage(String key, Object... args)
      Shortcut method for calling getMessages() and Messages.getString(String,Object...).
      Parameters:
      key - The message key.
      args - Optional MessageFormat-style arguments.
      Returns:
      The localized message.

    • getMessages

      public Messages getMessages()
      Returns the resource bundle for the request locale.
      Example:

      @RestGet public String hello(RestRequest req, @Query("user") String user) { // Return a localized message. return req.getMessages().getString("hello.message", user); }

      Notes:
      • The Messages object can also be passed as a parameter on the method.
      See Also:
      Returns:
      The resource bundle.
      Never null.

    • getMethod

      public String getMethod()
      Returns the HTTP method of this request.

      If allowHeaderParams init parameter is true, then first looks for &method=xxx in the URL query string.

      Specified by:
      getMethod in interface jakarta.servlet.http.HttpServletRequest
      Overrides:
      getMethod in class jakarta.servlet.http.HttpServletRequestWrapper
      Returns:
      The HTTP method of this request.

    • getOpContext

      public RestOpContext getOpContext()
      Returns access to the inner RestOpContext of this method.
      Returns:
      The RestOpContext of this method. May be null if method has not yet been found.

    • getOperationSwagger

      public Optional<Operation> getOperationSwagger()
      Returns the swagger for the Java method invoked.
      Returns:
      The swagger for the Java method as an Optional. Never null.

    • getPartParserSession

      public HttpPartParserSession getPartParserSession()
      Returns the part serializer associated with this request.
      Returns:
      The part serializer associated with this request.

    • getPartSerializerSession

      public HttpPartSerializerSession getPartSerializerSession()
      Returns the part serializer session for this request.
      Returns:
      The part serializer session for this request.

    • getPathParam

      public <T> Optional<T> getPathParam(Class<T> type)
      Returns the request path parameter of the specified type.

      Type must have a name specified via the Path annotation and a public constructor that takes in either value or name,value as strings.

      Type Parameters:
      T - The bean type to create.
      Parameters:
      type - The bean type to create.
      Returns:
      The parsed form-data parameter on the request, never null.

    • getPathParam

      public RequestPathParam getPathParam(String name)
      Shortcut for calling getPathParams().get(name).
      Parameters:
      name - The path parameter name.
      Returns:
      The path parameter, never null.

    • getPathParams

      public RequestPathParams getPathParams()
      Path parameters.

      Returns a RequestPathParams object that encapsulates access to URL path parameters.

      Example:

      @RestGet("/{foo}/{bar}/{baz}/*") public void doGet(RestRequest req) { // Get access to path data. RequestPathParams pathParams = req.getPathParams(); // Example URL: /123/qux/true/quux int foo = pathParams.get("foo").asInteger().orElse(-1); // =123 String bar = pathParams.get("bar").orElse(null); // =qux boolean baz = pathParams.get("baz").asBoolean().orElse(false); // =true String remainder = pathParams.getRemainder().orElse(null); // =quux }

      Notes:
      • This object is modifiable.
      Returns:
      The path parameters.
      Never null.

    • getPathRemainder

      public RequestPathParam getPathRemainder()
      Shortcut for calling getPathParams().getRemainder().
      Returns:
      The path remainder value, never null.

    • getProtocolVersion

      public ProtocolVersion getProtocolVersion()
      Returns the protocol version from the request line of this request.
      Returns:
      The protocol version from the request line of this request.

    • getQueryParam

      public <T> Optional<T> getQueryParam(Class<T> type)
      Returns the request query parameter of the specified type.

      Type must have a name specified via the Query annotation and a public constructor that takes in either value or name,value as strings.

      Type Parameters:
      T - The bean type to create.
      Parameters:
      type - The bean type to create.
      Returns:
      The parsed query parameter on the request, never null.

    • getQueryParam

      public RequestQueryParam getQueryParam(String name)
      Shortcut for calling getRequestQuery().getLast(name).
      Parameters:
      name - The query parameter name.
      Returns:
      The query parameter, never null.

    • getQueryParams

      public RequestQueryParams getQueryParams()
      Query parameters.

      Returns a RequestQueryParams object that encapsulates access to URL GET parameters.

      Similar to ServletRequest.getParameterMap() but only looks for query parameters in the URL and not form posts.

      Example:

      @RestGet(...) public void doGet(RestRequest req) { // Get access to query parameters on the URL. RequestQueryParams query = req.getQuery(); // Get query parameters converted to various types. int p1/ = query.getInteger("p1").orElse(null); String p2 = query.getString("p2").orElse(null); UUID p3 = query.get("p3").as(UUID.class).orElse(null); }

      Notes:
      • This object is modifiable.
      See Also:
      Returns:
      The query parameters as a modifiable map.
      Never null.

    • getReader

      public BufferedReader getReader() throws IOException
      Returns the HTTP content content as a Reader.

      If allowHeaderParams init parameter is true, then first looks for &content=xxx in the URL query string.

      Automatically handles GZipped input streams.

      This method is equivalent to calling getContent().getReader().

      Specified by:
      getReader in interface jakarta.servlet.ServletRequest
      Overrides:
      getReader in class jakarta.servlet.ServletRequestWrapper
      Returns:
      The HTTP content content as a Reader.
      Throws:
      IOException - If content could not be read.

    • getRequest

      public <T> T getRequest(Class<T> c)
      Creates a proxy interface to retrieve HTTP parts of this request as a proxy bean.
      Examples:

      @RestPost("/mypath/{p1}/{p2}/*") public void myMethod(@Request MyRequest requestBean) {...} public interface MyRequest { @Path // Path variable name inferred from getter. String getP1(); @Path("p2") String getX(); @Path("/*") String getRemainder(); @Query String getQ1(); // Schema-based query parameter: Pipe-delimited lists of comma-delimited lists of integers. @Query( collectionFormat="pipes" items=@Items( items=@SubItems( collectionFormat="csv" type="integer" ) ) ) int[][] getQ3(); @Header("*") Map<String,Object> getHeaders();

      Type Parameters:
      T - The request bean interface to instantiate.
      Parameters:
      c - The request bean interface to instantiate.
      Returns:
      A new request bean proxy for this REST request.

    • getRequest

      public <T> T getRequest(RequestBeanMeta rbm)
      Same as getRequest(Class) but used on pre-instantiated RequestBeanMeta objects.
      Type Parameters:
      T - The request bean interface to instantiate.
      Parameters:
      rbm - The metadata about the request bean interface to create.
      Returns:
      A new request bean proxy for this REST request.

    • getRequestLine

      public RequestLine getRequestLine()
      Returns the request line of this request.
      Returns:
      The request line of this request.

    • getServletPath

      public String getServletPath()
      Returns the part of this request's URL that calls the servlet.

      This path starts with a "/" character and includes either the servlet name or a path to the servlet, but does not include any extra path information or a query string.

      Specified by:
      getServletPath in interface jakarta.servlet.http.HttpServletRequest
      Overrides:
      getServletPath in class jakarta.servlet.http.HttpServletRequestWrapper
      Returns:
      The servlet path, never null.
      See Also:
      • HttpServletRequest.getServletPath()

    • getStaticFiles

      public StaticFiles getStaticFiles()
      Returns the static files registered on the REST resource context object.

      Used to retrieve localized files to be served up as static files through the REST API.

      Returns:
      This object.

    • getSwagger

      public Optional<Swagger> getSwagger()
      Returns the localized swagger associated with the resource.

      A shortcut for calling getInfoProvider().getSwagger(request);

      Example:

      @RestGet public List<Tag> swaggerTags(RestRequest req) { return req.getSwagger().getTags(); }

      Notes:
      • The Swagger object can also be passed as a parameter on the method.
      See Also:
      Returns:
      The swagger associated with the resource.
      Never null.

    • getTimeZone

      public Optional<TimeZone> getTimeZone()
      Returns the Time-Zone header value on the request if there is one.

      Example: "GMT".

      Returns:
      The parsed header on the request, never null.

    • getUri

      public URI getUri(boolean includeQuery, Map<String,Object> addQueryParams)
      Returns the URI for this request.

      Similar to HttpServletRequestWrapper.getRequestURI() but returns the value as a URI. It also gives you the capability to override the query parameters (e.g. add new query parameters to the existing URI).

      Parameters:
      includeQuery - If true include the query parameters on the request.
      addQueryParams - Augment the request URI with the specified query parameters.
      Returns:
      A new URI.

    • getUriContext

      public UriContext getUriContext()
      Returns the URI context of the request.

      The URI context contains all the information about the URI of the request, such as the servlet URI, context path, etc...

      Returns:
      The URI context of the request.

    • getUriResolver

      public UriResolver getUriResolver()
      Shortcut for calling getUriResolver() using UriResolution.ROOT_RELATIVE and UriRelativity.RESOURCE
      Returns:
      The URI resolver for this request.

    • getUriResolver

      public UriResolver getUriResolver(UriResolution resolution, UriRelativity relativity)
      Returns a URI resolver that can be used to convert URIs to absolute or root-relative form.
      Parameters:
      resolution - The URI resolution rule.
      relativity - The relative URI relativity rule.
      Returns:
      The URI resolver for this request.

    • getVarResolverSession

      public VarResolverSession getVarResolverSession()
      Request-level variable resolver session.

      Used to resolve SVL variables in text.

      Example:

      @RestGet public String hello(RestRequest req) { // Get var resolver session. VarResolverSession session = getVarResolverSession(); // Use it to construct a customized message from a query parameter. return session.resolve("Hello $RQ{user}!"); }

      Notes:
      See Also:
      Returns:
      The variable resolver for this request.

    • isDebug

      public boolean isDebug()
      Returns true if debug mode is enabled. Debug mode is enabled by simply adding "?debug=true" to the query string or adding a Debug: true header on the request.
      Returns:
      true if debug mode is enabled.

    • isPlainText

      public boolean isPlainText()
      Returns true if &plainText=true was specified as a URL parameter.

      This indicates that the Content-Type of the output should always be set to "text/plain" to make it easy to render in a browser.

      This feature is useful for debugging.

      Returns:
      true if &amp;plainText=true was specified as a URL parameter

    • setAttribute

      public void setAttribute(String name, Object value)
      Sets a request attribute.
      Specified by:
      setAttribute in interface jakarta.servlet.ServletRequest
      Overrides:
      setAttribute in class jakarta.servlet.ServletRequestWrapper
      Parameters:
      name - The attribute name.
      value - The attribute value.

    • setCharset

      public void setCharset(Charset value)
      Sets the charset to expect on the request content.
      Parameters:
      value - The new value to use for the request content.

    • setDebug

      public RestRequest setDebug() throws IOException
      Shortcut for calling setDebug(true).
      Returns:
      This object.
      Throws:
      IOException - If content could not be cached.

    • setDebug

      public RestRequest setDebug(Boolean b) throws IOException
      Sets the "Debug" attribute to the specified boolean.

      This flag is used by CallLogger to help determine how a request should be logged.

      Parameters:
      b - The attribute value.
      Returns:
      This object.
      Throws:
      IOException - If content could not be cached.

    • setException

      public RestRequest setException(Throwable t)
      Sets the "Exception" attribute to the specified throwable.

      This exception is used by CallLogger for logging purposes.

      Parameters:
      t - The attribute value.
      Returns:
      This object.

    • setNoTrace

      public RestRequest setNoTrace()
      Shortcut for calling setNoTrace(true).
      Returns:
      This object.

    • setNoTrace

      public RestRequest setNoTrace(Boolean b)
      Sets the "NoTrace" attribute to the specified boolean.

      This flag is used by CallLogger and tells it not to log the current request.

      Parameters:
      b - The attribute value.
      Returns:
      This object.

    • toString

      public String toString()
      Overrides:
      toString in class Object