Package org.apache.juneau.rest.server

Class RestRequest

java.lang.Object
jakarta.servlet.ServletRequestWrapper
jakarta.servlet.http.HttpServletRequestWrapper
org.apache.juneau.rest.server.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:

  • Field Details

    • CSP_NONCE_ATTR

      public static final String CSP_NONCE_ATTR
      Request-attribute name under which the per-response Content-Security-Policy nonce is cached.

      Set by RestResponse when an emitted CSP header contains a nonce placeholder, and read by the serialization layer (to stamp the matching nonce="..." on inline <script>/<style> tags) so the header and the markup share the same nonce.

      See Also:

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

    • checkPreconditions

      public Optional<BasicHttpException> checkPreconditions(RestResponse response)
      Evaluates the conditional-request headers on this request against the response's currently-set ETag and Last-Modified values.

      Implements the precondition-evaluation order defined by RFC 7232 §6:

      1. If-Match — strong comparison; returns 412 Precondition Failed on mismatch.
      2. If-Unmodified-Since — only consulted when If-Match is absent; returns 412 Precondition Failed when the response's Last-Modified is strictly after the supplied date.
      3. If-None-Match — weak comparison; returns 304 Not Modified on match (for safe methods, per RFC 7232 §6).
      4. If-Modified-Since — only consulted when If-None-Match is absent; returns 304 Not Modified when the response's Last-Modified is at-or-before the supplied date.
      Usage:

      Set the response's ETag and/or Last-Modified first, then call this method. The check reads the headers currently on the response, so any value set after the call is not considered.

      @RestGet("/{id}") public Order get(@Path long id, RestRequest req, RestResponse res) { var order = repo.find(id); res.eTag("\"" + order.version() + "\"").lastModified(order.updated()); req.checkPreconditions(res).ifPresent(e -> { throw e; }); return order; }

      Notes:
      • Returns an Optional so the caller controls how to handle the failure (throw inline, hand off to a logger, etc.). Both the returned 304 and 412 failures are BasicHttpException instances, which are RuntimeExceptions, so ifPresent(e -&gt; { throw e; }) compiles cleanly.
      • If-None-Match: * matches any present ETag; If-Match: * fails only when no ETag is set on the response.
      • Per RFC 7232 §3.1, If-Match requires strong comparison: a weak ETag on the response side never satisfies an If-Match.
      • Per RFC 7232 §3.2, If-None-Match uses weak comparison: the weak/strong flag is ignored when comparing tag values.
      See Also:
      Parameters:
      response - The response carrying the resource's current ETag and/or Last-Modified. Must not be null.
      Returns:
      Empty if all preconditions pass; otherwise an Optional holding either a 304 Not Modified BasicHttpException (when the request's cache copy is still fresh) or a PreconditionFailed (when an If-Match / If-Unmodified-Since guard failed).
      Throws:
      IllegalArgumentException - If response is null.

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

    • getMarshallingSession

      public MarshallingSession getMarshallingSession()
      Returns the MarshallingSession 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 Rest.config().

      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.

    • getRequestId

      public String getRequestId()
      Returns the correlation id resolved for this request (mint-or-honor), cached at session-build time.

      Delegates to RestSession.getRequestId() — the synchronous, session-cached value, never a live public/custom-key attribute re-read. This is the X-Request-Id correlation id echoed on the response and carried in the requestId log-context field.

      Specified by:
      getRequestId in interface jakarta.servlet.ServletRequest
      Overrides:
      getRequestId in class jakarta.servlet.ServletRequestWrapper
      Returns:
      The resolved request id. Never null (unless a custom id supplier returned null).
      Since:
      10.0.0

    • 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 getFormParams().get(name).
      Parameters:
      name - The form data parameter name.
      Returns:
      The form data parameter, never null.

    • getFormParams

      public RequestFormParamList getFormParams() throws InternalServerError
      Form-data.

      Returns a RequestFormParamList 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. RequestFormParamList 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 RequestFormParamList 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 RequestHeaderList getHeaders()
      Request headers.

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

      Example:

      @RestPost(...) public Object myMethod(RestRequest req) { // Get access to headers. RequestHeaderList 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 RequestHeaderList 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 parser session associated with this request.
      Returns:
      The part parser session 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 path 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 RequestPathParamList getPathParams()
      Path parameters.

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

      Example:

      @RestGet("/{foo}/{bar}/{baz}/*") public void doGet(RestRequest req) { // Get access to path data. RequestPathParamList 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 HttpProtocolVersion 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 RequestQueryParamList getQueryParams()
      Query parameters.

      Returns a RequestQueryParamList 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. RequestQueryParamList 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.
      Must not be null.
      Returns:
      A new request bean proxy for this REST request.

    • getRequest

      public <T> T getRequest(RequestBeanMeta rbm, RequestBeanSetters setters)
      Same as getRequest(RequestBeanMeta), but reuses setters already resolved when the @RestOp's arguments were built instead of resolving them on this call.
      Type Parameters:
      T - The request bean interface to instantiate.
      Parameters:
      rbm - The metadata about the request bean interface to create.
      Must not be null.
      setters - The pre-resolved constructor/setters for a concrete bean class, or null to resolve them on this call (callers such as Queryable that only have a Class, not a registered RequestBeanArg). Resolving here throws the same IllegalArgumentException message as RequestBeanArg, wrapped the same way as any other exception from this method.
      Returns:
      A new request bean proxy or instance for this REST request.

    • getRequestLine

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

    • getResponse

      public RestResponse getResponse()
      Returns the HTTP response associated with this request.

      Only safe to call once the REST call has reached the point of invoking the matched Java method, e.g. from inside a RestConverter, which only ever runs after method invocation. Calling it any earlier throws InternalServerError.

      Returns:
      The response associated with 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 associated with the resource.

      Shortcut for RestContext.getStaticFiles().

      Returns:
      The static files for this resource.
      Never null.

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

    • getOpenApi

      public Optional<OpenApi> getOpenApi()
      Returns the localized OpenAPI 3.1 document associated with the resource.

      Sibling of getSwagger() for the OpenAPI 3.1 emission path.

      See Also:
      Returns:
      The OpenAPI 3.1 document 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.
      Can be null (no additional parameters are added).
      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()
      Log-level query only: returns whether this request's resolved (per-operation) JUL logger is loggable at FINE-or-finer.

      This is read-only; there is no request attribute or setter driving it. It reports logging verbosity only and is not consulted by any framework behavior. Do not key security or marshalling behavior on this method — use the explicit, non-logging controls instead:

      Returns:
      true if the resolved logger is loggable at FINE-or-finer.

    • getLogger

      public RichLogger getLogger()
      Returns the resolved per-operation RichLogger for this request.

      This is the same logger isDebug() queries (`opContext.getLogger()`, delegating to RestOpContext.getLogger()), so anything logged through it — including the fine/info/… convenience methods below — rides the existing parent-chain capture propagation: a LogRecordCapture attached at a resource-class-level logger name still observes these per-operation emissions.

      These convenience methods are for application handler code that wants to emit its own ad hoc log statements during request processing and have them automatically carry whatever LogContext is active (most notably requestId). They are complementary to — not a replacement for — the REST debug pipeline's one cumulative per-request record; they produce independent, additional LogRecords.

      Returns:
      The resolved per-operation logger. Never null.

    • severe

      public void severe(String pattern, Object... args)
      Logs a formatted message at SEVERE through this request's logger.
      Parameters:
      pattern - The Formatter-style message pattern.
      args - The message arguments.

    • severe

      public void severe(Throwable thrown, String pattern, Object... args)
      Logs a formatted message with an associated throwable at SEVERE.
      Parameters:
      thrown - The throwable to associate with the record.
      pattern - The Formatter-style message pattern.
      args - The message arguments.

    • warning

      public void warning(String pattern, Object... args)
      Logs a formatted message at WARNING through this request's logger.
      Parameters:
      pattern - The Formatter-style message pattern.
      args - The message arguments.

    • warning

      public void warning(Throwable thrown, String pattern, Object... args)
      Logs a formatted message with an associated throwable at WARNING.
      Parameters:
      thrown - The throwable to associate with the record.
      pattern - The Formatter-style message pattern.
      args - The message arguments.

    • info

      public void info(String pattern, Object... args)
      Logs a formatted message at INFO through this request's logger.
      Parameters:
      pattern - The Formatter-style message pattern.
      args - The message arguments.

    • info

      public void info(Throwable thrown, String pattern, Object... args)
      Logs a formatted message with an associated throwable at INFO.
      Parameters:
      thrown - The throwable to associate with the record.
      pattern - The Formatter-style message pattern.
      args - The message arguments.

    • config

      public void config(String pattern, Object... args)
      Logs a formatted message at CONFIG through this request's logger.
      Parameters:
      pattern - The Formatter-style message pattern.
      args - The message arguments.

    • config

      public void config(Throwable thrown, String pattern, Object... args)
      Logs a formatted message with an associated throwable at CONFIG.
      Parameters:
      thrown - The throwable to associate with the record.
      pattern - The Formatter-style message pattern.
      args - The message arguments.

    • fine

      public void fine(String pattern, Object... args)
      Logs a formatted message at FINE through this request's logger.
      Parameters:
      pattern - The Formatter-style message pattern.
      args - The message arguments.

    • fine

      public void fine(Throwable thrown, String pattern, Object... args)
      Logs a formatted message with an associated throwable at FINE.
      Parameters:
      thrown - The throwable to associate with the record.
      pattern - The Formatter-style message pattern.
      args - The message arguments.

    • finer

      public void finer(String pattern, Object... args)
      Logs a formatted message at FINER through this request's logger.
      Parameters:
      pattern - The Formatter-style message pattern.
      args - The message arguments.

    • finer

      public void finer(Throwable thrown, String pattern, Object... args)
      Logs a formatted message with an associated throwable at FINER.
      Parameters:
      thrown - The throwable to associate with the record.
      pattern - The Formatter-style message pattern.
      args - The message arguments.

    • finest

      public void finest(String pattern, Object... args)
      Logs a formatted message at FINEST through this request's logger.
      Parameters:
      pattern - The Formatter-style message pattern.
      args - The message arguments.

    • finest

      public void finest(Throwable thrown, String pattern, Object... args)
      Logs a formatted message with an associated throwable at FINEST.
      Parameters:
      thrown - The throwable to associate with the record.
      pattern - The Formatter-style message pattern.
      args - The message arguments.

    • isDebugMarshalling

      public boolean isDebugMarshalling()
      Returns whether REST-driven serializer/parser debug behavior is enabled for this request's operation.

      Resolved from the cascading @Rest(debugMarshalling) / @RestOp(debugMarshalling) setting (default OFF), independent of the JUL logger level. When enabled, the REST layer forces Context.debug on the serializer/parser session used to handle this request — engaging recursion-detection-that-throws, parse-input buffering, and stack-trace-prefixed marshalling exceptions.

      Returns:
      true if REST-driven marshalling debug is enabled for this operation.

    • getCachedContent

      public byte[] getCachedContent()
      Returns the captured (bounded) request body bytes for debug logging.

      Populated by the two-phase debug pipeline only when the resolved logger is loggable at FINEST; otherwise returns null. The captured copy is capped at the formatter's body cap (default 8 KB); use getCachedContentLength() for the full byte count.

      Returns:
      The captured request body bytes, or null if body caching was not installed.

    • getCachedContentLength

      public long getCachedContentLength()
      Returns the total number of request body bytes read, including any beyond the capture cap.
      Returns:
      The total request body length in bytes, or -1 if body caching was not installed.

    • getException

      public Throwable getException()
      Returns the exception thrown while processing this request, if any.
      Returns:
      The thrown exception, or null if none occurred.

    • getExecTime

      public Long getExecTime()
      Returns the total request execution time in milliseconds, if it has been recorded.
      Returns:
      The execution time in milliseconds, or null if not yet recorded.

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

    • setAuthResult

      public RestRequest setAuthResult(AuthResult value)
      Sets the resolved resource-level authentication result.

      Invoked by the framework after the RestAuthenticator fold resolves an identity for this request. The stored result drives getUserPrincipal(), isUserInRole(String), and getRemoteUser(), and (when a principal is present) stashes the principal under "juneau.principal" so @Auth argument injection resolves it.

      Parameters:
      value - The result. Can be null to unset.
      Returns:
      This object.
      Since:
      10.0.0

    • getUserPrincipal

      public Principal getUserPrincipal()
      Specified by:
      getUserPrincipal in interface jakarta.servlet.http.HttpServletRequest
      Overrides:
      getUserPrincipal in class jakarta.servlet.http.HttpServletRequestWrapper

    • isUserInRole

      public boolean isUserInRole(String role)
      Specified by:
      isUserInRole in interface jakarta.servlet.http.HttpServletRequest
      Overrides:
      isUserInRole in class jakarta.servlet.http.HttpServletRequestWrapper

    • getRemoteUser

      public String getRemoteUser()
      Specified by:
      getRemoteUser in interface jakarta.servlet.http.HttpServletRequest
      Overrides:
      getRemoteUser in class jakarta.servlet.http.HttpServletRequestWrapper

    • setSerializerSessionProperty

      public RestRequest setSerializerSessionProperty(String name, Object value)
      Sets a serializer session property programmatically.

      Session properties override context-level properties and can be used to customize serializer behavior for this request only.

      Parameters:
      name - The property name (e.g. "escapeSolidus").
      value - The property value.
      Returns:
      This object.

    • setParserSessionProperty

      public RestRequest setParserSessionProperty(String name, Object value)
      Sets a parser session property programmatically.

      Session properties override context-level properties and can be used to customize parser behavior for this request only.

      Parameters:
      name - The property name (e.g. "trimStrings").
      value - The property value.
      Returns:
      This object.

    • setSerializerSessionProperties

      public RestRequest setSerializerSessionProperties(Map<String,Object> values)
      Sets multiple serializer session properties programmatically.
      Parameters:
      values - The properties to set. Can be null.
      Returns:
      This object.

    • setParserSessionProperties

      public RestRequest setParserSessionProperties(Map<String,Object> values)
      Sets multiple parser session properties programmatically.
      Parameters:
      values - The properties to set. Can be null.
      Returns:
      This object.

    • getSerializerSessionPropertyMap

      public Map<String,Object> getSerializerSessionPropertyMap()
      Returns the merged serializer session property map for this request.

      Merges (in order of increasing priority):

      1. Request attributes (from getAttributes(), e.g. defaultRequestAttributes)
      2. UON-encoded juneauSerializerOptions query parameter
      3. JSON5-encoded X-Juneau-Serializer-Options header
      4. Programmatically-set properties via setSerializerSessionProperty(java.lang.String, java.lang.Object)

      Client-supplied keys are validated against the allowlist from RestOpContext.getAllowedSerializerOptions(). Keys not in the allowlist cause a 400 Bad Request response.

      Returns:
      An unmodifiable map of session properties; may be empty but never null.

    • getParserSessionPropertyMap

      public Map<String,Object> getParserSessionPropertyMap()
      Returns the merged parser session property map for this request.

      Merges (in order of increasing priority):

      1. Request attributes (from getAttributes(), e.g. defaultRequestAttributes)
      2. UON-encoded juneauParserOptions query parameter
      3. JSON5-encoded X-Juneau-Parser-Options header
      4. Programmatically-set properties via setParserSessionProperty(java.lang.String, java.lang.Object)

      Client-supplied keys are validated against the allowlist from RestOpContext.getAllowedParserOptions(). Keys not in the allowlist cause a 400 Bad Request response.

      Returns:
      An unmodifiable map of session properties; may be empty but never null.

    • setCharset

      public void setCharset(Charset value)
      Sets the charset to expect on the request content.
      Parameters:
      value - The new charset to use for the request content.
      Can be null (resets to the negotiated/default charset on the next getCharset() call).

    • setException

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

      This exception is surfaced by the debug pipeline as the thrown of the emitted log record.

      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 tells the framework not to trace the current request: the access-log record for the call is still emitted, but without the exception's stack trace. A No-Trace: true request header has the same effect; when both are present, the attribute wins.

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

    • toString

      public String toString()
      Overrides:
      toString in class Object