/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.juneau.rest.server;

import static java.time.format.DateTimeFormatter.*;
import static org.apache.juneau.commons.httppart.HttpPartType.*;
import static org.apache.juneau.commons.utils.IoUtils.*;
import static org.apache.juneau.commons.utils.ObjectUtils.*;
import static org.apache.juneau.commons.utils.Shorts.*;
import static org.apache.juneau.commons.utils.StringUtils.*;
import static org.apache.juneau.commons.utils.ThrowableUtils.*;
import static org.apache.juneau.rest.RestSharedConstants.*;

import java.io.*;
import java.lang.reflect.*;
import java.lang.reflect.Proxy;
import java.net.*;
import java.nio.charset.*;
import java.security.*;
import java.text.*;
import java.time.*;
import java.time.format.*;
import java.time.temporal.*;
import java.util.*;
import java.util.concurrent.atomic.*;
import java.util.function.*;
import java.util.stream.*;

import org.apache.juneau.bean.openapi3.OpenApi;
import org.apache.juneau.bean.swagger.Operation;
import org.apache.juneau.bean.swagger.Swagger;
import org.apache.juneau.commons.bean.*;
import org.apache.juneau.commons.http.*;
import org.apache.juneau.commons.http.MediaType;
import org.apache.juneau.commons.httppart.*;
import org.apache.juneau.commons.logging.*;
import org.apache.juneau.commons.svl.*;
import org.apache.juneau.commons.utils.*;
import org.apache.juneau.config.*;
import org.apache.juneau.http.*;
import org.apache.juneau.http.header.*;
import org.apache.juneau.http.header.Date;
import org.apache.juneau.http.request.*;
import org.apache.juneau.http.response.*;
import org.apache.juneau.httppart.bean.*;
import org.apache.juneau.marshall.*;
import org.apache.juneau.marshall.collections.*;
import org.apache.juneau.marshall.cp.Messages;
import org.apache.juneau.marshall.httppart.*;
import org.apache.juneau.marshall.marshaller.*;
import org.apache.juneau.marshall.marshaller.Uon;
import org.apache.juneau.marshall.parser.ParseException;
import org.apache.juneau.marshall.uon.*;
import org.apache.juneau.rest.server.arg.*;
import org.apache.juneau.rest.server.assertions.*;
import org.apache.juneau.rest.server.auth.*;
import org.apache.juneau.rest.server.guard.*;
import org.apache.juneau.rest.server.httppart.*;
import org.apache.juneau.rest.server.staticfile.*;
import org.apache.juneau.rest.server.util.*;
import org.apache.juneau.bct.assertions.*;

import jakarta.servlet.*;
import jakarta.servlet.http.*;

/**
 * Represents an HTTP request for a REST resource.
 *
 * <p>
 *    The {@link RestRequest} object is an extension of the <l>HttpServletRequest</l> 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:
 * </p>
 *
 * <p class='bjava'>
 *    <ja>@RestPost</ja>(...)
 *    <jk>public</jk> Object myMethod(RestRequest <jv>req</jv>) {...}
 * </p>
 *
 * <p>
 *    The primary methods on this class are:
 * </p>
 * <ul class='javatree'>
 *    <li class='jc'>{@link RestRequest}
 *    <ul class='spaced-list'>
 *       <li>Methods for accessing the request content:
 *       <ul class='javatreec'>
 *          <li class='jm'>{@link RestRequest#getContent() getContent()}
 *          <li class='jm'>{@link RestRequest#getInputStream() getInputStream()}
 *          <li class='jm'>{@link RestRequest#getReader() getReader()}
 *       </ul>
 *       <li>Methods for accessing HTTP parts:
 *       <ul class='javatreec'>
 *          <li class='jm'>{@link RestRequest#checkPreconditions(RestResponse) checkPreconditions(RestResponse)}
 *          <li class='jm'>{@link RestRequest#containsFormParam(String) containsFormParam(String)}
 *          <li class='jm'>{@link RestRequest#containsHeader(String) containsHeader(String)}
 *          <li class='jm'>{@link RestRequest#containsQueryParam(String) containsQueryParam(String)}
 *          <li class='jm'>{@link RestRequest#getHeader(Class) getHeader(Class)}
 *          <li class='jm'>{@link RestRequest#getHeader(String) getHeader(String)}
 *          <li class='jm'>{@link RestRequest#getHeaders() getHeaders()}
 *          <li class='jm'>{@link RestRequest#getFormParam(Class) getFormParam(Class)}
 *          <li class='jm'>{@link RestRequest#getFormParam(String) getFormParam(String)}
 *          <li class='jm'>{@link RestRequest#getFormParams() getFormParams()}
 *          <li class='jm'>{@link RestRequest#getPathParam(Class) getPathParam(Class)}
 *          <li class='jm'>{@link RestRequest#getPathParam(String) getPathParam(String)}
 *          <li class='jm'>{@link RestRequest#getPathParams() getPathParams()}
 *          <li class='jm'>{@link RestRequest#getPathRemainder() getPathRemainder()}
 *          <li class='jm'>{@link RestRequest#getQueryParam(Class) getQueryParam(Class)}
 *          <li class='jm'>{@link RestRequest#getQueryParam(String) getQueryParam(String)}
 *          <li class='jm'>{@link RestRequest#getQueryParams() getQueryParams()}
 *          <li class='jm'>{@link RestRequest#getQueryString() getQueryString()}
 *       </ul>
 *       <li>Methods for localization:
 *       <ul class='javatreec'>
 *          <li class='jm'>{@link RestRequest#getLocale() getLocale()}
 *          <li class='jm'>{@link RestRequest#getMessage(String,Object...) getMessage(String,Object...)}
 *          <li class='jm'>{@link RestRequest#getMessages() getMessages()}
 *          <li class='jm'>{@link RestRequest#getTimeZone() getTimeZone()}
 *       </ul>
 *       <li>Methods for accessing static files:
 *       <ul class='javatreec'>
 *          <li class='jm'>{@link RestRequest#getVarResolverSession() getVarResolverSession()}
 *       </ul>
 *       <li>Methods for assertions:
 *       <ul class='javatreec'>
 *          <li class='jm'>{@link RestRequest#assertContent() assertContent()}
 *          <li class='jm'>{@link RestRequest#assertCharset() assertCharset()}
 *          <li class='jm'>{@link RestRequest#assertFormParam(String) assertFormParam(String)}
 *          <li class='jm'>{@link RestRequest#assertHeader(String) assertHeader(String)}
 *          <li class='jm'>{@link RestRequest#assertQueryParam(String) assertQueryParam(String)}
 *          <li class='jm'>{@link RestRequest#assertRequestLine() assertRequestLine()}
 *       </ul>
 *       <li>Other:
 *       <ul class='javatreec'>
 *          <li class='jm'>{@link RestRequest#getAttribute(String) getAttribute(String)}
 *          <li class='jm'>{@link RestRequest#getAttributes() getAttributes()}
 *          <li class='jm'>{@link RestRequest#getAuthorityPath() getAuthorityPath()}
 *          <li class='jm'>{@link RestRequest#getMarshallingSession() getMarshallingSession()}
 *          <li class='jm'>{@link RestRequest#getCharset() getCharset()}
 *          <li class='jm'>{@link RestRequest#getConfig() getConfig()}
 *          <li class='jm'>{@link RestRequest#getContext() getContext()}
 *          <li class='jm'>{@link RestRequest#getContextPath() getContextPath()}
 *          <li class='jm'>{@link RestRequest#getHttpServletRequest() getHttpServletRequest()}
 *          <li class='jm'>{@link RestRequest#getMethod() getMethod()}
 *          <li class='jm'>{@link RestRequest#getOpContext() getOpContext()}
 *          <li class='jm'>{@link RestRequest#getOperationSwagger() getOperationSwagger()}
 *          <li class='jm'>{@link RestRequest#getPartParserSession() getPartParserSession()}
 *          <li class='jm'>{@link RestRequest#getPartSerializerSession() getPartSerializerSession()}
 *          <li class='jm'>{@link RestRequest#getPathInfo() getPathInfo()}
 *          <li class='jm'>{@link RestRequest#getProtocolVersion() getProtocolVersion()}
 *          <li class='jm'>{@link RestRequest#getRequest(Class) getRequest(Class)}
 *          <li class='jm'>{@link RestRequest#getRequestLine() getRequestLine()}
 *          <li class='jm'>{@link RestRequest#getRequestURI() getRequestURI()}
 *          <li class='jm'>{@link RestRequest#getRequestURL() getRequestURL()}
 *          <li class='jm'>{@link RestRequest#getServletPath() getServletPath()}
 *          <li class='jm'>{@link RestRequest#getSession() getSession()}
 *          <li class='jm'>{@link RestRequest#getSwagger() getSwagger()}
 *          <li class='jm'>{@link RestRequest#getUriContext() getUriContext()}
 *          <li class='jm'>{@link RestRequest#getUriResolver() getUriResolver()}
 *          <li class='jm'>{@link RestRequest#isDebug() isDebug()}
 *          <li class='jm'>{@link RestRequest#isDebugMarshalling() isDebugMarshalling()}
 *          <li class='jm'>{@link RestRequest#isPlainText() isPlainText()}
 *          <li class='jm'>{@link RestRequest#isUserInRole(String) isUserInRole(String)}
 *          <li class='jm'>{@link RestRequest#setAttribute(String,Object) setAttribute(String,Object)}
 *          <li class='jm'>{@link RestRequest#setCharset(Charset) setCharset(Charset)}
 *          <li class='jm'>{@link RestRequest#setException(Throwable) setException(Throwable)}
 *          <li class='jm'>{@link RestRequest#setNoTrace() setNoTrace()}
 *       </ul>
 *    </ul>
 * </ul>
 *
 */
@SuppressWarnings({
   "java:S3776", // checkPreconditions() walks the chained RFC 7232 If-Match/If-Unmodified-Since/If-None-Match/If-Modified-Since steps in order; splitting would obscure the precedence rules
   "java:S6539", // Collection.toArray() usage intentional
   "javabugs:S2259", // Null accesses are guarded by nn() checks; Sonar's flow analysis does not track nn() as a null guard
   "rawtypes", // Collection constructed from ClassMeta.newInstance() is untyped.
   "resource", // Streams returned to servlet container; lifecycle managed by the container
   "unchecked", // Type erasure requires unchecked casts in REST client operations
   "unused" // Unused parameters in HttpServletRequest overrides and helper methods
})
public class RestRequest extends HttpServletRequestWrapper {

   /**
    * Request-attribute name under which the per-response Content-Security-Policy nonce is cached.
    *
    * <p>
    * Set by {@link RestResponse} when an emitted CSP header contains a nonce placeholder, and read by the
    * serialization layer (to stamp the matching {@code nonce="..."} on inline {@code <script>}/{@code <style>} tags)
    * so the header and the markup share the same nonce.
    */
   public static final String CSP_NONCE_ATTR = "CspNonce";

   /**
    * Returns {@code true} if {@code method} is one of the methods the {@code content} URL-parameter body
    * override (see {@link Rest#disableContentParam()}) is documented to apply to.
    *
    * <p>
    * Package-private for direct unit-test coverage. Restricting the override to {@code PUT}/{@code POST} (its
    * documented scope all along) keeps a plain cross-origin {@code GET} &mdash; the kind a browser will issue
    * with no preflight and no custom header for something as simple as an <code>&lt;img src=...&gt;</code> tag
    * &mdash; from ever having its body-carrying {@code Content-Type} gate bypassed via a query string, without
    * touching the {@link Rest#disableContentParam()} default itself.
    *
    * @param method The request's HTTP method. Can be {@code null} (returns {@code false}).
    * @return {@code true} if {@code method} is {@code PUT} or {@code POST}, case-insensitively.
    */
   static boolean isContentParamMethod(String method) {
      return eqic("PUT", method) || eqic("POST", method);
   }

   /*
    * Converts an Accept-Language value entry to a Locale.
    */
   @SuppressWarnings({
      "java:S1874" // The new Locale(String,String) constructor is not deprecated on the Java 17 baseline; its replacement Locale.of(...) was only added in Java 19.
   })
   private static Locale toLocale(String lang) {
      var country = "";
      var i = lang.indexOf('-');
      if (i > -1) {
         country = lang.substring(i + 1).trim();
         lang = lang.substring(0, i).trim();
      }
      return new Locale(lang, country);
   }

   // Constructor initialized.
   private final HttpServletRequest inner;
   private final RestContext context;
   private final RestOpContext opContext;
   private final RequestContent content;
   private final MarshallingSession marshallingSession;
   private final RequestQueryParamList queryParams;
   private final RequestPathParamList pathParams;
   private final RequestHeaderList headers;
   private final RequestAttributes attrs;
   private final HttpPartParserSession partParserSession;

   private final RestSession session;
   // Lazy initialized.
   private VarResolverSession varSession;
   private RequestFormParamList formParams;
   private UriContext uriContext;
   private String authorityPath;
   private Config config;
   private Swagger swagger;

   private Charset charset;
   private Map<String,Object> serializerSessionProperties;
   private Map<String,Object> parserSessionProperties;

   // Framework-set resource-level authentication result; may be null.
   private AuthResult authResult;

   /**
    * Constructor.
    */
   RestRequest(RestOpContext opContext, RestSession session) {
      super(session.getRequest());
      this.session = session;
      this.opContext = opContext;

      inner = session.getRequest();
      context = session.getContext();

      attrs = new RequestAttributes(this);

      queryParams = new RequestQueryParamList(this, session.getQueryParams(), true);

      headers = new RequestHeaderList(this, queryParams, false);

      content = new RequestContent(this);

      if (context.isAllowContentParam() && isContentParamMethod(inner.getMethod())) {
         var b = queryParams.get("content").asString().orElse(null);
         if (b != null) {
            headers.set("Content-Type", UonSerializer.DEFAULT.getResponseContentType());
            content.mediaType(MediaType.UON).parser(UonParser.DEFAULT).content(b.getBytes(UTF8));
         }
      }

      pathParams = new RequestPathParamList(session, this, true);

      marshallingSession = opContext.getMarshallingContext().getSession();

      partParserSession = new LazyPartParserSession(opContext.getPartParser());

      pathParams.parser(partParserSession);

      // @formatter:off
      queryParams
         .addDefault(opContext.getDefaultRequestQueryData().getAll())
         .parser(partParserSession);

      headers
         .addDefault(opContext.getDefaultRequestHeaders().getAll())
         .addDefault(context.getDefaultRequestHeaders().getAll())
         .parser(partParserSession);

      content
         .encoders(opContext.getEncoders())
         .parsers(opContext.getParsers())
         .maxInput(opContext.getMaxInput());

      attrs
         .addDefault(opContext.getDefaultRequestAttributes())
         .addDefault(context.getDefaultRequestAttributes());
      // @formatter:on

      // Body-caching wrappers are installed by the two-phase debug pipeline before this object is
      // constructed, based on the resolved logger's level. Nothing to wrap here.
   }

   /**
    * Provides the ability to perform fluent-style assertions on the response character encoding.
    *
    * <h5 class='section'>Examples:</h5>
    * <p class='bjava'>
    *    <jc>// Validates that the response content charset is UTF-8.</jc>
    *    <jv>request</jv>
    *       .assertCharset().is(<js>"utf-8"</js>);
    * </p>
    *
    * @return A new fluent assertion object.
    * @throws BasicHttpException If REST call failed.
    */
   public FluentStringAssertion<RestRequest> assertCharset() {
      return new FluentStringAssertion<>(getCharset().name(), this);
   }

   /**
    * Returns a fluent assertion for the request content.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    <jc>// Validates the request content contains "foo".</jc>
    *    <jv>request</jv>
    *       .assertContent().asString().is(<js>"foo"</js>);
    * </p>
    *
    * @return A new fluent assertion on the content, never <jk>null</jk>.
    */
   public FluentRequestContentAssertion<RestRequest> assertContent() {
      return new FluentRequestContentAssertion<>(getContent(), this);
   }

   /**
    * Returns a fluent assertion for the specified form parameter.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    <jc>// Validates the content type is JSON.</jc>
    *    <jv>request</jv>
    *       .assertFormParam(<js>"foo"</js>).asString().contains(<js>"bar"</js>);
    * </p>
    *
    * @param name The query parameter name.
    * @return A new fluent assertion on the parameter, never <jk>null</jk>.
    */
   public FluentRequestFormParamAssertion<RestRequest> assertFormParam(String name) {
      return new FluentRequestFormParamAssertion<>(getFormParam(name), this);
   }

   /**
    * Returns a fluent assertion for the specified header.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    <jc>// Validates the content type is JSON.</jc>
    *    <jv>request</jv>
    *       .assertHeader(<js>"Content-Type"</js>).asString().is(<js>"application/json"</js>);
    * </p>
    *
    * @param name The header name.
    * @return A new fluent assertion on the parameter, never <jk>null</jk>.
    */
   public FluentRequestHeaderAssertion<RestRequest> assertHeader(String name) {
      return new FluentRequestHeaderAssertion<>(getHeaderParam(name), this);
   }

   /**
    * Returns a fluent assertion for the specified query parameter.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    <jc>// Validates the content type is JSON.</jc>
    *    <jv>request</jv>
    *       .assertQueryParam(<js>"foo"</js>).asString().contains(<js>"bar"</js>);
    * </p>
    *
    * @param name The query parameter name.
    * @return A new fluent assertion on the parameter, never <jk>null</jk>.
    */
   public FluentRequestQueryParamAssertion<RestRequest> assertQueryParam(String name) {
      return new FluentRequestQueryParamAssertion<>(getQueryParam(name), this);
   }

   /**
    * Returns an assertion on the request line returned by {@link #getRequestLine()}.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    <jc>// Validates the request content contains "foo".</jc>
    *    <jv>request</jv>
    *       .assertRequestLine().protocol().minor().is(1);
    * </p>
    *
    * @return A new assertion object.
    */
   public FluentRequestLineAssertion<RestRequest> assertRequestLine() {
      return new FluentRequestLineAssertion<>(getRequestLine(), this);
   }

   /**
    * Evaluates the conditional-request headers on this request against the response's currently-set
    * <c>ETag</c> and <c>Last-Modified</c> values.
    *
    * <p>
    * Implements the precondition-evaluation order defined by
    * <a class='doclink' href='https://www.rfc-editor.org/rfc/rfc7232#section-6'>RFC 7232 §6</a>:
    * <ol>
    *    <li><c>If-Match</c> — strong comparison; returns <c>412 Precondition Failed</c> on mismatch.
    *    <li><c>If-Unmodified-Since</c> — only consulted when <c>If-Match</c> is absent;
    *       returns <c>412 Precondition Failed</c> when the response's <c>Last-Modified</c> is
    *       strictly after the supplied date.
    *    <li><c>If-None-Match</c> — weak comparison; returns <c>304 Not Modified</c> on match
    *       (for safe methods, per RFC 7232 §6).
    *    <li><c>If-Modified-Since</c> — only consulted when <c>If-None-Match</c> is absent;
    *       returns <c>304 Not Modified</c> when the response's <c>Last-Modified</c> is at-or-before
    *       the supplied date.
    * </ol>
    *
    * <h5 class='section'>Usage:</h5>
    *
    * <p>
    * Set the response's <c>ETag</c> and/or <c>Last-Modified</c> <b>first</b>, then call this method.
    * The check reads the headers currently on the response, so any value set after the call is not
    * considered.
    *
    * <p class='bjava'>
    *    <ja>@RestGet</ja>(<js>"/{id}"</js>)
    *    <jk>public</jk> Order get(<ja>@Path</ja> <jk>long</jk> <jv>id</jv>, RestRequest <jv>req</jv>, RestResponse <jv>res</jv>) {
    *       <jk>var</jk> <jv>order</jv> = <jv>repo</jv>.find(<jv>id</jv>);
    *       <jv>res</jv>.eTag(<js>"\""</js> + <jv>order</jv>.version() + <js>"\""</js>).lastModified(<jv>order</jv>.updated());
    *       <jv>req</jv>.checkPreconditions(<jv>res</jv>).ifPresent(<jv>e</jv> -&gt; { <jk>throw</jk> <jv>e</jv>; });
    *       <jk>return</jk> <jv>order</jv>;
    *    }
    * </p>
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>Returns an {@link Optional} so the caller controls how to handle the failure
    *       (throw inline, hand off to a logger, etc.). Both the returned <c>304</c> and <c>412</c>
    *       failures are {@link BasicHttpException} instances, which are {@link RuntimeException}s,
    *       so {@code ifPresent(e -&gt; { throw e; })} compiles cleanly.
    *    <li class='note'><c>If-None-Match: *</c> matches any present <c>ETag</c>; <c>If-Match: *</c>
    *       fails only when no <c>ETag</c> is set on the response.
    *    <li class='note'>Per RFC 7232 §3.1, <c>If-Match</c> requires strong comparison: a weak
    *       <c>ETag</c> on the response side never satisfies an <c>If-Match</c>.
    *    <li class='note'>Per RFC 7232 §3.2, <c>If-None-Match</c> uses weak comparison: the weak/strong
    *       flag is ignored when comparing tag values.
    * </ul>
    *
    * <h5 class='section'>See Also:</h5><ul>
    *    <li class='jm'>{@link RestResponse#eTag(String) RestResponse.eTag(String)}
    *    <li class='jm'>{@link RestResponse#lastModified(Instant) RestResponse.lastModified(Instant)}
    * </ul>
    *
    * @param response The response carrying the resource's current <c>ETag</c> and/or <c>Last-Modified</c>.
    *    Must not be <jk>null</jk>.
    * @return Empty if all preconditions pass; otherwise an {@link Optional} holding either a
    *    <c>304 Not Modified</c> {@link BasicHttpException} (when the request's cache copy is still
    *    fresh) or a {@link PreconditionFailed} (when an <c>If-Match</c> / <c>If-Unmodified-Since</c>
    *    guard failed).
    * @throws IllegalArgumentException If {@code response} is <jk>null</jk>.
    */
   public Optional<BasicHttpException> checkPreconditions(RestResponse response) {
      reqnn("response", response);
      var resTagStr = response.getHeader(ETag.NAME);
      var resTag = nn(resTagStr) ? EntityTag.of(resTagStr) : null;
      var resLastModStr = response.getHeader(LastModified.NAME);
      var resLastMod = nn(resLastModStr) ? parseHttpDate(resLastModStr) : null;

      // RFC 7232 §6 step 1: If-Match (strong comparison; 412 on failure).
      var ifMatch = getHeaderParam(IfMatch.NAME).orElse(null);
      if (nn(ifMatch)) {
         if (! matchesAnyStrong(EntityTags.of(ifMatch), resTag))
            return o(preconditionFailed(IfMatch.NAME));
      } else {
         // RFC 7232 §6 step 2: If-Unmodified-Since (only when If-Match absent).
         var ius = getHeaderParam(IfUnmodifiedSince.NAME).orElse(null);
         if (nn(ius)) {
            var iusDate = parseHttpDate(ius);
            if (nn(iusDate) && nn(resLastMod) && resLastMod.toInstant().isAfter(iusDate.toInstant()))
               return o(preconditionFailed(IfUnmodifiedSince.NAME));
         }
      }

      // RFC 7232 §6 step 3: If-None-Match (weak comparison; 304 on match for safe methods).
      var ifNoneMatch = getHeaderParam(IfNoneMatch.NAME).orElse(null);
      if (nn(ifNoneMatch)) {
         if (matchesAnyWeak(EntityTags.of(ifNoneMatch), resTag))
            return o(notModified());
      } else {
         // RFC 7232 §6 step 4: If-Modified-Since (only when If-None-Match absent; only for GET/HEAD).
         if (isSafeMethod()) {
            var ims = getHeaderParam(IfModifiedSince.NAME).orElse(null);
            if (nn(ims)) {
               var imsDate = parseHttpDate(ims);
               if (nn(imsDate) && nn(resLastMod) && ! resLastMod.toInstant().isAfter(imsDate.toInstant()))
                  return o(notModified());
            }
         }
      }

      return oe();
   }

   private boolean isSafeMethod() {
      var m = getMethod();
      return eqic("GET", m) || eqic("HEAD", m);
   }

   private static ZonedDateTime parseHttpDate(String value) {
      try {
         return ZonedDateTime.from(RFC_1123_DATE_TIME.parse(value)).truncatedTo(ChronoUnit.SECONDS);
      } catch (@SuppressWarnings("unused") DateTimeParseException e) {
         return null;
      }
   }

   private static boolean matchesAnyStrong(EntityTags clientTags, EntityTag resTag) {
      if (clientTags == null)
         return false;
      for (var t : clientTags.toArray()) {
         if (t.isAny())
            return resTag != null;
         // Strong comparison: both sides must be strong AND opaque-tag values must be equal.
         if (! t.isWeak() && resTag != null && ! resTag.isWeak() && eq(t.getEntityValue(), resTag.getEntityValue()))
            return true;
      }
      return false;
   }

   private static boolean matchesAnyWeak(EntityTags clientTags, EntityTag resTag) {
      if (clientTags == null)
         return false;
      for (var t : clientTags.toArray()) {
         if (t.isAny())
            return resTag != null;
         // Weak comparison: opaque-tag values must be equal; weak/strong flag is ignored.
         if (resTag != null && eq(t.getEntityValue(), resTag.getEntityValue()))
            return true;
      }
      return false;
   }

   private static BasicHttpException notModified() {
      return new BasicHttpException(NotModified.STATUS_CODE, NotModified.REASON_PHRASE);
   }

   private static PreconditionFailed preconditionFailed(String headerName) {
      return new PreconditionFailed("Precondition '%s' failed.", headerName);
   }

   /**
    * Returns <jk>true</jk> if this request contains the specified header.
    *
    * @param name The header name.
    * @return <jk>true</jk> if this request contains the specified header.
    */
   public boolean containsFormParam(String name) {
      return getFormParams().contains(name);
   }

   /**
    * Returns <jk>true</jk> if this request contains the specified header.
    *
    * @param name The header name.
    * @return <jk>true</jk> if this request contains the specified header.
    */
   public boolean containsHeader(String name) {
      return headers.contains(name);
   }

   /**
    * Returns <jk>true</jk> if this request contains the specified header.
    *
    * @param name The header name.
    * @return <jk>true</jk> if this request contains the specified header.
    */
   public boolean containsQueryParam(String name) {
      return queryParams.contains(name);
   }

   /**
    * Returns the request attribute with the specified name.
    *
    * @param name The attribute name.
    * @return The attribute value, never <jk>null</jk>.
    */
   @Override
   public RequestAttribute getAttribute(String name) {
      return attrs.get(name);
   }

   /**
    * Request attributes.
    *
    * <p>
    * Returns a {@link RequestAttributes} object that encapsulates access to attributes on the request.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    <ja>@RestPost</ja>(...)
    *    <jk>public</jk> Object myMethod(RestRequest <jv>req</jv>) {
    *
    *       <jc>// Get access to attributes.</jc>
    *       RequestAttributes <jv>attributes</jv> = <jv>req</jv>.getAttributes();
    *
    *    <jc>// Get a header value as a POJO.</jc>
    *       UUID <jv>etag</jv> = <jv>attributes</jv>.get(<js>"ETag"</js>, UUID.<jk>class</jk>);
    *    }
    * </p>
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>
    *       This object is modifiable.
    *    <li class='note'>
    *       Values are converted from strings using the registered part parser on the resource class.
    *    <li class='note'>
    *       The {@link RequestAttributes} object can also be passed as a parameter on the method.
    *    <li class='note'>
    *       The {@link Attr @Attr} annotation can be used to access individual attribute values.
    * </ul>
    *
    * <h5 class='section'>See Also:</h5><ul>
    *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerHttpParts">HTTP parts in REST servers</a>
    * </ul>
    *
    * @return
    *    The headers on this request.
    *    <br>Never <jk>null</jk>.
    */
   public RequestAttributes getAttributes() { return attrs; }

   /**
    * Returns the URI authority portion of the request.
    *
    * @return The URI authority portion of the request.
    */
   public String getAuthorityPath() {
      if (authorityPath == null)
         authorityPath = context.getUriAuthority();
      if (authorityPath == null) {
         var scheme = inner.getScheme();
         var port = inner.getServerPort();
         var sb = new StringBuilder(inner.getScheme()).append("://").append(inner.getServerName());
         if (! (port == 80 && eq(scheme, "http") || port == 443 && eq(scheme, "https")))
            sb.append(':').append(port);
         authorityPath = sb.toString();
      }
      return authorityPath;
   }

   /**
    * Returns the {@link MarshallingSession} associated with this request.
    *
    * @return The request bean session.
    */
   public MarshallingSession getMarshallingSession() { return marshallingSession; }

   /**
    * Returns the charset specified on the <c>Content-Type</c> header, or <js>"UTF-8"</js> if not specified.
    *
    * @return The charset to use to decode the request content.
    */
   public Charset getCharset() {
      if (charset == null) {
         // Determine charset
         // NOTE:  Don't use super.getCharacterEncoding() because the spec is implemented inconsistently.
         // Jetty returns the default charset instead of null if the character is not specified on the request.
         var h = getHeaderParam("Content-Type").orElse(null);
         if (nn(h)) {
            var i = h.indexOf(";charset=");
            if (i > 0)
               charset = Charset.forName(h.substring(i + 9).trim());
         }
         if (charset == null)
            charset = opContext.getDefaultCharset();
         if (charset == null)
            charset = StandardCharsets.UTF_8;
      }
      return charset;
   }

   /**
    * Config file associated with the resource.
    *
    * <p>
    * Returns a config file with session-level variable resolution.
    *
    * The config file is identified via {@link Rest#config()}.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    <ja>@RestGet</ja>(...)
    *    <jk>public void</jk> doGet(RestRequest <jv>req</jv>) {
    *
    *       <jc>// Get config file.</jc>
    *       Config <jv>config</jv> = <jv>req</jv>.getConfig();
    *
    *       <jc>// Get simple values from config file.</jc>
    *       <jk>int</jk> <jv>timeout</jv> = <jv>config</jv>.get(<js>"MyResource/timeout"</js>).asInteger().orElse(=10000);
    *
    *       <jc>// Get complex values from config file.</jc>
    *       MyBean <jv>bean</jv> = <jv>config</jv>.get(<js>"MyResource/myBean"</js>).as(MyBean.<jk>class</jk>).orElse(<jk>null</jk>);
    *    }
    * </p>
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>
    *       The {@link Config} object can also be passed as a parameter on the method.
    * </ul>
    *
    * <h5 class='section'>See Also:</h5><ul>
    *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/ConfigurationFiles">Configuration Files</a>
    * </ul>
    *
    * @return
    *    The config file associated with the resource, or <jk>null</jk> if resource does not have a config file
    *    associated with it.
    */
   public Config getConfig() {
      if (config == null)
         config = context.getConfig().resolving(getVarResolverSession());
      return config;
   }

   /**
    * Request content.
    *
    * <p>
    * Returns a {@link RequestContent} object that encapsulates access to the HTTP request content.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    <ja>@RestPost</ja>(...)
    *    <jk>public void</jk> doPost(RestRequest <jv>req</jv>) {
    *
    *       <jc>// Convert content to a linked list of Person objects.</jc>
    *       List&lt;Person&gt; <jv>list</jv> = <jv>req</jv>.getContent().as(LinkedList.<jk>class</jk>, Person.<jk>class</jk>);
    *       ..
    *    }
    * </p>
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>
    *       The {@link RequestContent} object can also be passed as a parameter on the method.
    *    <li class='note'>
    *       The {@link Content @Content} annotation can be used to access the content as well.
    * </ul>
    *
    * <h5 class='section'>See Also:</h5><ul>
    *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerHttpParts">HTTP parts in REST servers</a>
    * </ul>
    *
    * @return
    *    The content of this HTTP request.
    *    <br>Never <jk>null</jk>.
    */
   public RequestContent getContent() { return content; }

   /**
    * Returns the resource context handling the request.
    *
    * <p>
    * Can be used to access servlet-init parameters or annotations during requests, such as in calls to
    * {@link RestGuard#guard(RestRequest, RestResponse)}..
    *
    * @return The resource context handling the request.
    */
   public RestContext getContext() { return context; }

   /**
    * Returns the correlation id resolved for this request (mint-or-honor), cached at session-build time.
    *
    * <p>
    * Delegates to {@link RestSession#getRequestId()} &mdash; the synchronous, session-cached value, never a live
    * public/custom-key attribute re-read.  This is the {@code X-Request-Id} correlation id echoed on the response and
    * carried in the {@code requestId} log-context field.
    *
    * @return The resolved request id.  Never <jk>null</jk> (unless a custom id supplier returned <jk>null</jk>).
    * @since 10.0.0
    */
   @Override /* Overridden from ServletRequest (jakarta.servlet-api 6.1+ default method) */
   public String getRequestId() { return session.getRequestId(); }

   /**
    * Returns the portion of the request URI that indicates the context of the request.
    *
    * <p>The context path always comes first in a request URI.
    * The path starts with a <js>"/"</js> character but does not end with a <js>"/"</js> character.
    * For servlets in the default (root) context, this method returns <js>""</js>.
    * The container does not decode this string.
    *
    * @return The context path, never <jk>null</jk>.
    * @see HttpServletRequest#getContextPath()
    */
   @Override
   public String getContextPath() {
      var cp = context.getUriContext();
      return cp == null ? inner.getContextPath() : cp;
   }

   /**
    * Returns the request form-data parameter of the specified type.
    *
    * <p>
    * Type must have a name specified via the {@link FormData} annotation
    * and a public constructor that takes in either <c>value</c> or <c>name,value</c> as strings.
    *
    * @param <T> The bean type to create.
    * @param type The bean type to create.
    * @return The parsed form-data parameter on the request, never <jk>null</jk>.
    */
   public <T> Optional<T> getFormParam(Class<T> type) {
      return getFormParams().get(type);
   }

   /**
    * Shortcut for calling <c>getFormParams().get(name)</c>.
    *
    * @param name The form data parameter name.
    * @return The form data parameter, never <jk>null</jk>.
    */
   public RequestFormParam getFormParam(String name) {
      return getFormParams().get(name);
   }

   /**
    * Form-data.
    *
    * <p>
    * Returns a {@link RequestFormParamList} object that encapsulates access to form post parameters.
    *
    * <p>
    * Similar to {@link HttpServletRequest#getParameterMap()}, but only looks for form data in the HTTP content.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    <ja>@RestPost</ja>(...)
    *    <jk>public void</jk> doPost(RestRequest <jv>req</jv>) {
    *
    *       <jc>// Get access to parsed form data parameters.</jc>
    *       RequestFormParamList <jv>formParams</jv> = <jv>req</jv>.getFormParams();
    *
    *       <jc>// Get form data parameters converted to various types.</jc>
    *       <jk>int</jk> <jv>p1</jv> = <jv>formParams</jv>.get(<js>"p1"</js>).asInteger().orElse(0);
    *       String <jv>p2</jv> = <jv>formParams</jv>.get(<js>"p2"</js>).asString().orElse(<jk>null</jk>);
    *       UUID <jv>p3</jv> = <jv>formParams</jv>.get(<js>"p3"</js>).as(UUID.<jk>class</jk>).orElse(<jk>null</jk>);
    *    }
    * </p>
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>
    *       This object is modifiable.
    *    <li class='note'>
    *       Values are converted from strings using the registered part parser on the resource class.
    *    <li class='note'>
    *       The {@link RequestFormParamList} object can also be passed as a parameter on the method.
    *    <li class='note'>
    *       The {@link FormData @FormDAta} annotation can be used to access individual form data parameter values.
    * </ul>
    *
    * <h5 class='section'>See Also:</h5><ul>
    *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerHttpParts">HTTP parts in REST servers</a>
    * </ul>
    *
    * @return
    *    The URL-encoded form data from the request.
    *    <br>Never <jk>null</jk>.
    * @throws InternalServerError If query parameters could not be parsed.
    * @see FormData
    */
   public RequestFormParamList getFormParams() throws InternalServerError {
      try {
         if (formParams == null)
            formParams = new RequestFormParamList(this, true).parser(partParserSession);
         formParams.addDefault(opContext.getDefaultRequestFormData().getAll());
         return formParams;
      } catch (Exception e) {
         throw new InternalServerError(e);
      }
   }

   /**
    * Returns the request header of the specified type.
    *
    * <p>
    * Type must have a name specified via the {@link Header} annotation
    * and a public constructor that takes in either <c>value</c> or <c>name,value</c> as strings.
    *
    * <p>
    * Typically any of the following:
    * <ul class='javatreec'>
    *    <li class='jc'>{@link Accept}
    *    <li class='jc'>{@link AcceptCharset}
    *    <li class='jc'>{@link AcceptEncoding}
    *    <li class='jc'>{@link AcceptLanguage}
    *    <li class='jc'>{@link AcceptRanges}
    *    <li class='jc'>{@link Authorization}
    *    <li class='jc'>{@link CacheControl}
    *    <li class='jc'>{@link ClientVersion}
    *    <li class='jc'>{@link Connection}
    *    <li class='jc'>{@link ContentDisposition}
    *    <li class='jc'>{@link ContentEncoding}
    *    <li class='jc'>{@link ContentLength}
    *    <li class='jc'>{@link ContentType}
    *    <li class='jc'>{@link Date}
    *    <li class='jc'>{@link Debug}
    *    <li class='jc'>{@link Expect}
    *    <li class='jc'>{@link Forwarded}
    *    <li class='jc'>{@link From}
    *    <li class='jc'>{@link Host}
    *    <li class='jc'>{@link IfMatch}
    *    <li class='jc'>{@link IfModifiedSince}
    *    <li class='jc'>{@link IfNoneMatch}
    *    <li class='jc'>{@link IfRange}
    *    <li class='jc'>{@link IfUnmodifiedSince}
    *    <li class='jc'>{@link MaxForwards}
    *    <li class='jc'>{@link NoTrace}
    *    <li class='jc'>{@link Origin}
    *    <li class='jc'>{@link Pragma}
    *    <li class='jc'>{@link ProxyAuthorization}
    *    <li class='jc'>{@link Range}
    *    <li class='jc'>{@link Referer}
    *    <li class='jc'>{@link TE}
    *    <li class='jc'>{@link Thrown}
    *    <li class='jc'>{@link Upgrade}
    *    <li class='jc'>{@link UserAgent}
    *    <li class='jc'>{@link Warning}
    * </ul>
    *
    * @param <T> The bean type to create.
    * @param type The bean type to create.
    * @return The parsed header on the request, never <jk>null</jk>.
    */
   public <T> Optional<T> getHeader(Class<T> type) {
      return headers.get(type);
   }

   /**
    * Returns the last header with a specified name of this message.
    *
    * <p>
    * If there is more than one matching header in the message the last element of <c>getHeaders(String)</c> is returned.
    * <br>If there is no matching header in the message, an empty request header object is returned.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    <jc>// Gets a header and throws a BadRequest if it doesn't exist.</jc>
    *    <jv>request</jv>
    *       .getHeader(<js>"Foo"</js>)
    *       .assertValue().exists()
    *       .get();
    * </p>
    *
    * @param name The header name.
    * @return The request header object, never <jk>null</jk>.
    */
   public RequestHeader getHeaderParam(String name) {
      return headers.getLast(name);
   }

   /**
    * Request headers.
    *
    * <p>
    * Returns a {@link RequestHeaderList} object that encapsulates access to HTTP headers on the request.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    <ja>@RestPost</ja>(...)
    *    <jk>public</jk> Object myMethod(RestRequest <jv>req</jv>) {
    *
    *       <jc>// Get access to headers.</jc>
    *       RequestHeaderList <jv>headers</jv> = <jv>req</jv>.getRequestHeaders();
    *
    *       <jc>// Add a default value.</jc>
    *       <jv>headers</jv>.addDefault(<js>"ETag"</js>, <jsf>DEFAULT_UUID</jsf>);
    *
    *    <jc>// Get a header value as a POJO.</jc>
    *       UUID etag = <jv>headers</jv>.get(<js>"ETag"</js>).as(UUID.<jk>class</jk>).orElse(<jk>null</jk>);
    *
    *       <jc>// Get a standard header.</jc>
    *       Optional&lt;CacheControl&gt; = <jv>headers</jv>.getCacheControl();
    *    }
    * </p>
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>
    *       This object is modifiable.
    *    <li class='note'>
    *       Values are converted from strings using the registered part parser on the resource class.
    *    <li class='note'>
    *       The {@link RequestHeaderList} object can also be passed as a parameter on the method.
    *    <li class='note'>
    *       The {@link Header @Header} annotation can be used to access individual header values.
    * </ul>
    *
    * <h5 class='section'>See Also:</h5><ul>
    *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerHttpParts">HTTP parts in REST servers</a>
    * </ul>
    *
    * @return
    *    The headers on this request.
    *    <br>Never <jk>null</jk>.
    */
   public RequestHeaderList getHeaders() { return headers; }

   /**
    * Returns the wrapped servlet request.
    *
    * @return The wrapped servlet request.
    */
   public HttpServletRequest getHttpServletRequest() { return inner; }

   /**
    * Returns the HTTP content content as an {@link InputStream}.
    *
    * <p>
    * Automatically handles GZipped input streams.
    *
    * <p>
    * This method is equivalent to calling <c>getContent().getInputStream()</c>.
    *
    * @return The negotiated input stream.
    * @throws IOException If any error occurred while trying to get the input stream or wrap it in the GZIP wrapper.
    */
   @Override
   public ServletInputStream getInputStream() throws IOException { return getContent().getInputStream(); }

   /**
    * Returns the preferred Locale that the client will accept content in, based on the Accept-Language header.
    *
    * <p>
    * If the client request doesn't provide an <c>Accept-Language</c> header, this method returns the default locale for the server.
    *
    * @return The preferred Locale that the client will accept content in.  Never <jk>null</jk>.
    */
   @Override
   public Locale getLocale() {
      var best = inner.getLocale();
      var h = headers.get("Accept-Language").asString().orElse(null);
      if (nn(h)) {
         var sr = StringRanges.of(h);
         float qValue = 0;
         for (var r : sr.toList()) {
            if (r.getQValue() > qValue) {
               best = toLocale(r.getName());
               qValue = r.getQValue();
            }
         }
      }
      return best;
   }

   /**
    * Shortcut method for calling {@link RestRequest#getMessages()} and {@link Messages#getString(String,Object...)}.
    *
    * @param key The message key.
    * @param args Optional {@link MessageFormat}-style arguments.
    * @return The localized message.
    */
   public String getMessage(String key, Object...args) {
      return getMessages().getString(key, args);
   }

   /**
    * Returns the resource bundle for the request locale.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    <ja>@RestGet</ja>
    *    <jk>public</jk> String hello(RestRequest <jv>req</jv>, <ja>@Query</ja>(<js>"user"</js>) String <jv>user</jv>) {
    *
    *       <jc>// Return a localized message.</jc>
    *       <jk>return</jk> <jv>req</jv>.getMessages().getString(<js>"hello.message"</js>, <jv>user</jv>);
    *    }
    * </p>
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>
    *       The {@link Messages} object can also be passed as a parameter on the method.
    * </ul>
    *
    * <h5 class='section'>See Also:</h5><ul>
    *    <li class='jm'>{@link RestRequest#getMessage(String,Object...)}
    *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/LocalizedMessages">Localized Messages</a>
    * </ul>
    *
    * @return
    *    The resource bundle.
    *    <br>Never <jk>null</jk>.
    */
   public Messages getMessages() { return context.getMessages().forLocale(getLocale()); }

   /**
    * Returns the HTTP method of this request.
    *
    * <p>
    * If <c>allowHeaderParams</c> init parameter is <jk>true</jk>, then first looks for
    * <c>&amp;method=xxx</c> in the URL query string.
    *
    * @return The HTTP method of this request.
    */
   @Override
   public String getMethod() { return session.getMethod(); }

   /**
    * Returns access to the inner {@link RestOpContext} of this method.
    *
    * @return The {@link RestOpContext} of this method.  May be <jk>null</jk> if method has not yet been found.
    */
   public RestOpContext getOpContext() { return opContext; }

   /**
    * Returns the swagger for the Java method invoked.
    *
    * @return The swagger for the Java method as an {@link Optional}.  Never <jk>null</jk>.
    */
   public Optional<Operation> getOperationSwagger() {

      var swagger2 = getSwagger();
      if (! swagger2.isPresent())
         return oe();

      return o(swagger2.get().getOperation(opContext.getPathPattern(), lcr(getMethod())));
   }

   /**
    * Returns the part parser session associated with this request.
    *
    * @return The part parser session associated with this request.
    */
   public HttpPartParserSession getPartParserSession() { return partParserSession; }

   /**
    * Returns the part serializer session for this request.
    *
    * @return The part serializer session for this request.
    */
   public HttpPartSerializerSession getPartSerializerSession() { return opContext.getPartSerializer().getPartSession(); }

   /**
    * Returns the request path parameter of the specified type.
    *
    * <p>
    * Type must have a name specified via the {@link Path} annotation
    * and a public constructor that takes in either <c>value</c> or <c>name,value</c> as strings.
    *
    * @param <T> The bean type to create.
    * @param type The bean type to create.
    * @return The parsed path parameter on the request, never <jk>null</jk>.
    */
   public <T> Optional<T> getPathParam(Class<T> type) {
      return pathParams.get(type);
   }

   /**
    * Shortcut for calling <c>getPathParams().get(<jv>name</jv>)</c>.
    *
    * @param name The path parameter name.
    * @return The path parameter, never <jk>null</jk>.
    */
   public RequestPathParam getPathParam(String name) {
      return pathParams.get(name);
   }

   /**
    * Path parameters.
    *
    * <p>
    * Returns a {@link RequestPathParamList} object that encapsulates access to URL path parameters.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    <ja>@RestGet</ja>(<js>"/{foo}/{bar}/{baz}/*"</js>)
    *    <jk>public void</jk> doGet(RestRequest <jv>req</jv>) {
    *
    *       <jc>// Get access to path data.</jc>
    *       RequestPathParamList <jv>pathParams</jv> = <jv>req</jv>.getPathParams();
    *
    *       <jc>// Example URL:  /123/qux/true/quux</jc>
    *
    *       <jk>int</jk> <jv>foo</jv> = <jv>pathParams</jv>.get(<js>"foo"</js>).asInteger().orElse(-1);  <jc>// =123</jc>
    *       String <jv>bar</jv> = <jv>pathParams</jv>.get(<js>"bar"</js>).orElse(<jk>null</jk>);  <jc>// =qux</jc>
    *       <jk>boolean</jk> <jv>baz</jv> = <jv>pathParams</jv>.get(<js>"baz"</js>).asBoolean().orElse(<jk>false</jk>);  <jc>// =true</jc>
    *       String <jv>remainder</jv> = <jv>pathParams</jv>.getRemainder().orElse(<jk>null</jk>);  <jc>// =quux</jc>
    *    }
    * </p>
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>
    *       This object is modifiable.
    * </ul>
    *
    * @return
    *    The path parameters.
    *    <br>Never <jk>null</jk>.
    */
   public RequestPathParamList getPathParams() { return pathParams; }

   /**
    * Shortcut for calling <c>getPathParams().getRemainder()</c>.
    *
    * @return The path remainder value, never <jk>null</jk>.
    */
   public RequestPathParam getPathRemainder() { return pathParams.getRemainder(); }

   /**
    * Returns the protocol version from the request line of this request.
    *
    * @return The protocol version from the request line of this request.
    */
   public HttpProtocolVersion getProtocolVersion() { return getRequestLine().getProtocolVersion(); }

   /**
    * Returns the request query parameter of the specified type.
    *
    * <p>
    * Type must have a name specified via the {@link Query} annotation
    * and a public constructor that takes in either <c>value</c> or <c>name,value</c> as strings.
    *
    * @param <T> The bean type to create.
    * @param type The bean type to create.
    * @return The parsed query parameter on the request, never <jk>null</jk>.
    */
   public <T> Optional<T> getQueryParam(Class<T> type) {
      return queryParams.get(type);
   }

   /**
    * Shortcut for calling <c>getRequestQuery().getLast(<jv>name</jv>)</c>.
    *
    * @param name The query parameter name.
    * @return The query parameter, never <jk>null</jk>.
    */
   public RequestQueryParam getQueryParam(String name) {
      return queryParams.get(name);
   }

   /**
    * Query parameters.
    *
    * <p>
    * Returns a {@link RequestQueryParamList} object that encapsulates access to URL GET parameters.
    *
    * <p>
    * Similar to {@link HttpServletRequest#getParameterMap()} but only looks for query parameters in the URL and not form posts.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    <ja>@RestGet</ja>(...)
    *    <jk>public void</jk> doGet(RestRequest <jv>req</jv>) {
    *
    *       <jc>// Get access to query parameters on the URL.</jc>
    *       RequestQueryParamList <jv>query</jv> = <jv>req</jv>.getQuery();
    *
    *       <jc>// Get query parameters converted to various types.</jc>
    *       <jk>int</jk> <jv>p1/</jv> = <jv>query</jv>.getInteger(<js>"p1"</js>).orElse(<jk>null</jk>);
    *       String <jv>p2</jv> = <jv>query</jv>.getString(<js>"p2"</js>).orElse(<jk>null</jk>);
    *       UUID <jv>p3</jv> = <jv>query</jv>.get(<js>"p3"</js>).as(UUID.<jk>class</jk>).orElse(<jk>null</jk>);
    *    }
    * </p>
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>
    *       This object is modifiable.
    * </ul>
    *
    * <h5 class='section'>See Also:</h5><ul>
    *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerHttpParts">HTTP parts in REST servers</a>
    * </ul>
    *
    * @return
    *    The query parameters as a modifiable map.
    *    <br>Never <jk>null</jk>.
    */
   public RequestQueryParamList getQueryParams() { return queryParams; }

   /**
    * Returns the HTTP content content as a {@link Reader}.
    *
    * <p>
    * If {@code allowHeaderParams} init parameter is true, then first looks for {@code &content=xxx} in the URL query
    * string.
    *
    * <p>
    * Automatically handles GZipped input streams.
    *
    * <p>
    * This method is equivalent to calling <c>getContent().getReader()</c>.
    *
    * @return The HTTP content content as a {@link Reader}.
    * @throws IOException If content could not be read.
    */
   @Override
   public BufferedReader getReader() throws IOException { return getContent().getReader(); }

   /**
    * Creates a proxy interface to retrieve HTTP parts of this request as a proxy bean.
    *
    * <h5 class='section'>Examples:</h5>
    * <p class='bjava'>
    *    <ja>@RestPost</ja>(<js>"/mypath/{p1}/{p2}/*"</js>)
    *    <jk>public void</jk> myMethod(<ja>@Request</ja> MyRequest <jv>requestBean</jv>) {...}
    *
    *    <jk>public interface</jk> MyRequest {
    *
    *       <ja>@Path</ja> <jc>// Path variable name inferred from getter.</jc>
    *       String getP1();
    *
    *       <ja>@Path</ja>(<js>"p2"</js>)
    *       String getX();
    *
    *       <ja>@Path</ja>(<js>"/*"</js>)
    *       String getRemainder();
    *
    *       <ja>@Query</ja>
    *       String getQ1();
    *
    *    <jc>// Schema-based query parameter:  Pipe-delimited lists of comma-delimited lists of integers.</jc>
    *       <ja>@Query</ja>(
    *          collectionFormat=<js>"pipes"</js>
    *          items=<ja>@Items</ja>(
    *             items=<ja>@SubItems</ja>(
    *                collectionFormat=<js>"csv"</js>
    *                type=<js>"integer"</js>
    *             )
    *          )
    *       )
    *       <jk>int</jk>[][] getQ3();
    *
    *       <ja>@Header</ja>(<js>"*"</js>)
    *       Map&lt;String,Object&gt; getHeaders();
    * </p>
    *
    * @param <T> The request bean interface to instantiate.
    * @param c The request bean interface to instantiate.
    * @return A new request bean proxy for this REST request.
    */
   public <T> T getRequest(Class<T> c) {
      return getRequest(RequestBeanMeta.create(c, getContext().getAnnotations()));
   }

   /**
    * Same as {@link #getRequest(Class)} but used on pre-instantiated {@link RequestBeanMeta} objects.
    *
    * @param <T> The request bean interface to instantiate.
    * @param rbm The metadata about the request bean interface to create.
    *    <br>Must not be <jk>null</jk>.
    * @return A new request bean proxy for this REST request.
    */
   public <T> T getRequest(RequestBeanMeta rbm) {
      return getRequest(rbm, null);
   }

   /**
    * Same as {@link #getRequest(RequestBeanMeta)}, but reuses setters already resolved when the {@code @RestOp}'s
    * arguments were built instead of resolving them on this call.
    *
    * @param <T> The request bean interface to instantiate.
    * @param rbm The metadata about the request bean interface to create.
    *    <br>Must not be <jk>null</jk>.
    * @param setters
    *    The pre-resolved constructor/setters for a concrete bean class, or <jk>null</jk> to resolve them on this call
    *    (callers such as {@code Queryable} that only have a {@link Class}, not a registered {@link RequestBeanArg}).
    *    Resolving here throws the same {@link IllegalArgumentException} message as {@link RequestBeanArg},
    *    wrapped the same way as any other exception from this method.
    * @return A new request bean proxy or instance for this REST request.
    */
   public <T> T getRequest(RequestBeanMeta rbm, RequestBeanSetters setters) {
      try {
         var c = (Class<T>)rbm.getBeanInfo().inner();
         final MarshallingSession bs = getMarshallingSession();
         if (c.isInterface())
            return (T)Proxy.newProxyInstance(c.getClassLoader(), a(c), (InvocationHandler)(proxy, method, args) -> {
               RequestBeanPropertyMeta pm = rbm.getProperty(method.getName());
               if (nn(pm))
                  return resolveRequestBeanProperty(pm, method, bs);
               return null;
            });
         return newRequestBean(rbm, bs, nn(setters) ? setters : RequestBeanSetters.resolve(c, rbm));
      } catch (Exception e) {
         throw toRex(e);
      }
   }

   /**
    * Instantiates a concrete {@link Request @Request} bean class via the resolved {@link RequestBeanSetters} and
    * populates it by invoking the setter matching each annotated getter.  Absent parameters (a <jk>null</jk> resolved
    * value) are left at their default.
    */
   private <T> T newRequestBean(RequestBeanMeta rbm, MarshallingSession bs, RequestBeanSetters setters) throws Exception {
      T bean = setters.newInstance();
      for (var pm : rbm.getProperties()) {
         var getter = pm.getGetter();
         var value = resolveRequestBeanProperty(pm, getter, bs);
         if (value == null)
            continue;
         setters.set(bean, getter, value);
      }
      return bean;
   }

   private Object resolveRequestBeanProperty(RequestBeanPropertyMeta pm, java.lang.reflect.Method method, MarshallingSession bs) throws Exception {
      HttpPartParserSession pp = pm.getParser(getPartParserSession());
      HttpPartSchema schema = pm.getSchema();
      String name = pm.getPartName();
      var type = bs.getClassMeta(method.getGenericReturnType());
      HttpPartType pt = pm.getPartType();
      if (pt == HttpPartType.BODY)
         return getContent().setSchema(schema).as(type);
      if (schema.getCollectionFormat() == HttpPartCollectionFormat.MULTI) {
         var valueType = type.isOptional() ? type.getElementType() : type;
         if (valueType.isMap())
            return resolveRequestBeanMultiMap(pt, name, schema, type);
         if (valueType.isCollectionOrArray())
            return resolveRequestBeanMultiCollection(pt, name, pp, schema, type);
      }
      var part = requestBeanPartLast(pt, name);
      if (part == null)
         return type.isOptional() ? Optional.empty() : null;
      return part.parser(pp).schema(schema).def(schema.getDefault()).as(type).orElse(null);
   }

   private Object resolveRequestBeanMultiMap(HttpPartType pt, String name, HttpPartSchema schema, ClassMeta<?> type) {
      try {
         var parts = requestBeanParts(pt, name);
         var optional = type.isOptional();
         if (parts.isEmpty()) {
            if (optional) {
               if (ine(schema.getDefault()))
                  return Optional.of(UonUtils.mergePairs(schema.getDefault()));
               return Optional.empty();
            }
            return JsonMap.create();
         }
         var dest = JsonMap.create();
         for (var p : parts)
            UonUtils.mergePair(dest, p.getValue());
         return optional ? o(dest) : dest;
      } catch (ParseException | SchemaValidationException e) {
         throw new BadRequest(e, "Could not parse query parameter '%s'.", name);
      }
   }

   private Object resolveRequestBeanMultiCollection(HttpPartType pt, String name, HttpPartParserSession pp, HttpPartSchema schema, ClassMeta<?> type) throws Exception {
      var optional = type.isOptional();
      var raw = optional ? type.getElementType() : type;
      var elemType = raw.getElementType();
      var parts = requestBeanParts(pt, name);
      if (parts.isEmpty()) {
         if (optional) {
            if (ine(schema.getDefault()))
               return Optional.of(readDefaultCollection(schema.getDefault(), raw, elemType, pp, schema, pt));
            return Optional.empty();
         }
         return emptyCollection(raw, elemType);
      }
      Collection c = newCollection(raw);
      for (var p : parts) {
         if (elemType.is(String.class)) {
            var v = p.getValue();
            c.add(v == null ? "" : v);
         } else {
            c.add(p.parser(pp).schema(schema).as(elemType).orElse(null));
         }
      }
      if (optional && elemType.is(String.class) && c.stream().allMatch(x -> isBlank(s(x))))
         return Optional.of(emptyCollection(raw, elemType));
      var collected = raw.isArray() ? CollectionUtils.toArray(c, elemType.inner()) : c;
      return optional ? o(collected) : collected;
   }

   @SuppressWarnings({
      "java:S112" // throws Exception intentional - HttpPartParserSession.read declares Exception
   })
   private Object readDefaultCollection(String def, ClassMeta<?> raw, ClassMeta<?> elemType, HttpPartParserSession pp, HttpPartSchema schema, HttpPartType pt) throws Exception {
      try {
         var one = pp.read(pt, schema, def, elemType);
         var c = newCollection(raw);
         c.add(one);
         return raw.isArray() ? CollectionUtils.toArray(c, elemType.inner()) : c;
      } catch (ParseException | SchemaValidationException e) {
         throw new BadRequest(e, "Could not parse %s parameter '%s'.", pt.toString().toLowerCase(), schema.getName());
      }
   }

   private static Collection newCollection(ClassMeta<?> raw) {
      if (raw.isArray())
         return CollectionUtils.list();
      if (raw.canCreateNewInstance())
         return (Collection)raw.newInstance();
      return new JsonList();
   }

   private static Object emptyCollection(ClassMeta<?> raw, ClassMeta<?> elemType) {
      var c = newCollection(raw);
      return raw.isArray() ? CollectionUtils.toArray(c, elemType.inner()) : c;
   }

   private List<? extends RequestHttpPart> requestBeanParts(HttpPartType pt, String name) {
      return switch (pt) {
         case QUERY -> getQueryParams().getAll(name);
         case FORMDATA -> getFormParams().getAll(name);
         case HEADER -> getHeaders().getAll(name);
         case PATH -> getPathParams().getAll(name);
         default -> List.of();
      };
   }

   private RequestHttpPart requestBeanPartLast(HttpPartType pt, String name) {
      return switch (pt) {
         case QUERY -> getQueryParams().getLast(name);
         case FORMDATA -> getFormParams().getLast(name);
         case HEADER -> getHeaderParam(name);
         case PATH -> getPathParams().getLast(name);
         default -> null;
      };
   }

   /**
    * Returns the request line of this request.
    *
    * @return The request line of this request.
    */
   public HttpRequestLine getRequestLine() {
      var x = inner.getProtocol();
      var i = x.indexOf('/');
      var j = x.indexOf('.', i);
      var pv = HttpProtocolVersion.of(x.substring(0, i), StringUtils.parseInt(x.substring(i + 1, j)), StringUtils.parseInt(x.substring(j + 1)));
      return HttpRequestLineBean.of(inner.getMethod(), inner.getRequestURI(), pv);
   }

   /**
    * Returns the HTTP response associated with this request.
    *
    * <p>
    * Only safe to call once the REST call has reached the point of invoking the matched Java method, e.g. from inside
    * a {@link org.apache.juneau.rest.server.converter.RestConverter}, which only ever runs after method invocation.
    * Calling it any earlier throws {@link InternalServerError}.
    *
    * @return The response associated with this request.
    */
   public RestResponse getResponse() {
      return session.getOpSession().getResponse();
   }

   /**
    * Returns the part of this request's URL that calls the servlet.
    *
    * <p>
    * This path starts with a <js>"/"</js> 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.
    *
    * @return The servlet path, never <jk>null</jk>.
    * @see HttpServletRequest#getServletPath()
    */
   @Override
   public String getServletPath() {
      var cp = context.getUriContext();
      var sp = inner.getServletPath();
      return cp == null || ! sp.startsWith(cp) ? sp : sp.substring(cp.length());
   }

   /**
    * Returns the static files associated with the resource.
    *
    * <p>
    * Shortcut for {@link RestContext#getStaticFiles()}.
    *
    * @return
    *    The static files for this resource.
    *    <br>Never <jk>null</jk>.
    */
   public StaticFiles getStaticFiles() { return context.getStaticFiles(); }

   /**
    * Returns the localized swagger associated with the resource.
    *
    * <p>
    * A shortcut for calling <c>getInfoProvider().getSwagger(request);</c>
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    <ja>@RestGet</ja>
    *    <jk>public</jk> List&lt;Tag&gt; swaggerTags(RestRequest <jv>req</jv>) {
    *       <jk>return</jk> <jv>req</jv>.getSwagger().getTags();
    *    }
    * </p>
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>
    *       The {@link Swagger} object can also be passed as a parameter on the method.
    * </ul>
    *
    * <h5 class='section'>See Also:</h5><ul>
    *    <li class='ja'>{@link Rest#swaggerProvider()}
    *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanSwagger2">juneau-bean-swagger-v2</a>
    * </ul>
    *
    * @return
    *    The swagger associated with the resource.
    *    <br>Never <jk>null</jk>.
    */
   public Optional<Swagger> getSwagger() { return context.getSwagger(getLocale()); }

   /**
    * Returns the localized OpenAPI 3.1 document associated with the resource.
    *
    * <p>
    * Sibling of {@link #getSwagger()} for the OpenAPI 3.1 emission path.
    *
    * <h5 class='section'>See Also:</h5><ul>
    *    <li class='ja'>{@link Rest#openApiProvider()}
    *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/ApiDocsMixins">API-Docs Mixin Pack</a>
    * </ul>
    *
    * @return The OpenAPI 3.1 document associated with the resource. Never <jk>null</jk>.
    */
   public Optional<OpenApi> getOpenApi() { return context.getOpenApi(getLocale()); }

   /**
    * Returns the <c>Time-Zone</c> header value on the request if there is one.
    *
    * <p>
    * Example: <js>"GMT"</js>.
    *
    * @return The parsed header on the request, never <jk>null</jk>.
    */
   public Optional<TimeZone> getTimeZone() {
      var tz = headers.get("Time-Zone").asString().orElse(null);
      if (nn(tz))
         return o(TimeZone.getTimeZone(tz));
      return oe();
   }

   /**
    * Returns the URI for this request.
    *
    * <p>
    * Similar to {@link #getRequestURI()} but returns the value as a {@link URI}.
    * It also gives you the capability to override the query parameters (e.g. add new query parameters to the existing
    * URI).
    *
    * @param includeQuery If <jk>true</jk> include the query parameters on the request.
    * @param addQueryParams Augment the request URI with the specified query parameters.
    *    <br>Can be <jk>null</jk> (no additional parameters are added).
    * @return A new URI.
    */
   public URI getUri(boolean includeQuery, Map<String,Object> addQueryParams) {
      var uri = inner.getRequestURI();
      if (includeQuery || nn(addQueryParams)) {
         var sb = new StringBuilder(uri);
         var rq = queryParams.copy();
         if (nn(addQueryParams))
            for (var e : addQueryParams.entrySet())
               rq.set(e.getKey(), e.getValue());
         if (! rq.isEmpty())
            sb.append('?').append(rq.asQueryString());
         uri = sb.toString();
      }
      try {
         return new URI(uri);
      } catch (URISyntaxException e) {
         // Shouldn't happen.
         throw toRex(e);
      }
   }

   /**
    * Returns the URI context of the request.
    *
    * <p>
    * The URI context contains all the information about the URI of the request, such as the servlet URI, context
    * path, etc...
    *
    * @return The URI context of the request.
    */
   public UriContext getUriContext() {
      if (uriContext == null)
         uriContext = UriContext.of(getAuthorityPath(), getContextPath(), getServletPath(), urlEncodePath(inner.getPathInfo()));
      return uriContext;
   }

   /**
    * Shortcut for calling {@link #getUriResolver()} using {@link UriResolution#ROOT_RELATIVE} and
    * {@link UriRelativity#RESOURCE}
    *
    * @return The URI resolver for this request.
    */
   public UriResolver getUriResolver() { return UriResolver.of(context.getUriResolution(), context.getUriRelativity(), getUriContext()); }

   /**
    * Returns a URI resolver that can be used to convert URIs to absolute or root-relative form.
    *
    * @param resolution The URI resolution rule.
    * @param relativity The relative URI relativity rule.
    * @return The URI resolver for this request.
    */
   public UriResolver getUriResolver(UriResolution resolution, UriRelativity relativity) {
      return UriResolver.of(resolution, relativity, getUriContext());
   }

   /**
    * Request-level variable resolver session.
    *
    * <p>
    * Used to resolve SVL variables in text.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    <ja>@RestGet</ja>
    *    <jk>public</jk> String hello(RestRequest <jv>req</jv>) {
    *
    *       <jc>// Get var resolver session.</jc>
    *       VarResolverSession <jv>session</jv> = getVarResolverSession();
    *
    *       <jc>// Use it to construct a customized message from a query parameter.</jc>
    *       <jk>return</jk> <jv>session</jv>.resolve(<js>"Hello $RQ{user}!"</js>);
    *    }
    * </p>
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>
    *       The {@link VarResolverSession} object can also be passed as a parameter on the method.
    * </ul>
    *
    * <h5 class='section'>See Also:</h5><ul>
    *    <li class='jm'>{@link RestContext#getVarResolver()}
    *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a>
    * </ul>
    *
    * @return The variable resolver for this request.
    */
   public VarResolverSession getVarResolverSession() {
      // @formatter:off
      if (varSession == null)
         varSession = context
            .getVarResolver()
            .createSession(session.getBeanStore())
            .bean(RestRequest.class, this)
            .bean(RestSession.class, session);
      return varSession;
      // @formatter:on
   }

   /**
    * Log-level query only: returns whether this request's resolved (per-operation) JUL logger is loggable at
    * {@link java.util.logging.Level#FINE FINE}-or-finer.
    *
    * <p>
    * This is read-only; there is no request attribute or setter driving it. It reports <b>logging verbosity</b> only
    * and is <b>not</b> consulted by any framework behavior. Do <b>not</b> key security or marshalling behavior on this
    * method &mdash; use the explicit, non-logging controls instead:
    * <ul class='spaced-list'>
    *    <li>Echo-endpoint reachability &rarr; {@link org.apache.juneau.rest.server.ops.EchoMixin.Builder#enabled(Boolean) EchoMixin enablement}.
    *    <li>Serializer/parser debug behavior &rarr; {@link #isDebugMarshalling()} / {@link Rest#debugMarshalling() @Rest(debugMarshalling)}.
    * </ul>
    *
    * @return <jk>true</jk> if the resolved logger is loggable at {@code FINE}-or-finer.
    */
   public boolean isDebug() { return opContext.getLogger().isLoggable(java.util.logging.Level.FINE); }

   /**
    * Returns the resolved per-operation {@link RichLogger} for this request.
    *
    * <p>
    * This is the same logger {@link #isDebug()} queries (`opContext.getLogger()`, delegating to
    * {@link RestOpContext#getLogger()}), so anything logged through it &mdash; including the
    * {@code fine}/{@code info}/&hellip; convenience methods below &mdash; rides the existing parent-chain capture
    * propagation: a {@code LogRecordCapture} attached at a resource-class-level logger name still
    * observes these per-operation emissions.
    *
    * <p>
    * These convenience methods are for <b>application handler code</b> that wants to emit its own ad hoc log statements
    * <i>during</i> request processing and have them automatically carry whatever {@link RichLogger#context() LogContext}
    * is active (most notably {@code requestId}). They are complementary to &mdash; not a replacement for &mdash; the
    * REST debug pipeline's one cumulative per-request record; they produce independent, additional {@code LogRecord}s.
    *
    * @return The resolved per-operation logger. Never <jk>null</jk>.
    */
   public RichLogger getLogger() { return opContext.getLogger(); }

   /**
    * Logs a formatted message at {@link java.util.logging.Level#SEVERE SEVERE} through this request's {@link #getLogger() logger}.
    *
    * @param pattern The {@link java.util.Formatter}-style message pattern.
    * @param args The message arguments.
    */
   public void severe(String pattern, Object...args) { getLogger().severe(pattern, args); }

   /**
    * Logs a formatted message with an associated throwable at {@link java.util.logging.Level#SEVERE SEVERE}.
    *
    * @param thrown The throwable to associate with the record.
    * @param pattern The {@link java.util.Formatter}-style message pattern.
    * @param args The message arguments.
    */
   public void severe(Throwable thrown, String pattern, Object...args) { getLogger().severe(thrown, pattern, args); }

   /**
    * Logs a formatted message at {@link java.util.logging.Level#WARNING WARNING} through this request's {@link #getLogger() logger}.
    *
    * @param pattern The {@link java.util.Formatter}-style message pattern.
    * @param args The message arguments.
    */
   public void warning(String pattern, Object...args) { getLogger().warning(pattern, args); }

   /**
    * Logs a formatted message with an associated throwable at {@link java.util.logging.Level#WARNING WARNING}.
    *
    * @param thrown The throwable to associate with the record.
    * @param pattern The {@link java.util.Formatter}-style message pattern.
    * @param args The message arguments.
    */
   public void warning(Throwable thrown, String pattern, Object...args) { getLogger().warning(thrown, pattern, args); }

   /**
    * Logs a formatted message at {@link java.util.logging.Level#INFO INFO} through this request's {@link #getLogger() logger}.
    *
    * @param pattern The {@link java.util.Formatter}-style message pattern.
    * @param args The message arguments.
    */
   public void info(String pattern, Object...args) { getLogger().info(pattern, args); }

   /**
    * Logs a formatted message with an associated throwable at {@link java.util.logging.Level#INFO INFO}.
    *
    * @param thrown The throwable to associate with the record.
    * @param pattern The {@link java.util.Formatter}-style message pattern.
    * @param args The message arguments.
    */
   public void info(Throwable thrown, String pattern, Object...args) { getLogger().info(thrown, pattern, args); }

   /**
    * Logs a formatted message at {@link java.util.logging.Level#CONFIG CONFIG} through this request's {@link #getLogger() logger}.
    *
    * @param pattern The {@link java.util.Formatter}-style message pattern.
    * @param args The message arguments.
    */
   public void config(String pattern, Object...args) { getLogger().config(pattern, args); }

   /**
    * Logs a formatted message with an associated throwable at {@link java.util.logging.Level#CONFIG CONFIG}.
    *
    * @param thrown The throwable to associate with the record.
    * @param pattern The {@link java.util.Formatter}-style message pattern.
    * @param args The message arguments.
    */
   public void config(Throwable thrown, String pattern, Object...args) { getLogger().config(thrown, pattern, args); }

   /**
    * Logs a formatted message at {@link java.util.logging.Level#FINE FINE} through this request's {@link #getLogger() logger}.
    *
    * @param pattern The {@link java.util.Formatter}-style message pattern.
    * @param args The message arguments.
    */
   public void fine(String pattern, Object...args) { getLogger().fine(pattern, args); }

   /**
    * Logs a formatted message with an associated throwable at {@link java.util.logging.Level#FINE FINE}.
    *
    * @param thrown The throwable to associate with the record.
    * @param pattern The {@link java.util.Formatter}-style message pattern.
    * @param args The message arguments.
    */
   public void fine(Throwable thrown, String pattern, Object...args) { getLogger().fine(thrown, pattern, args); }

   /**
    * Logs a formatted message at {@link java.util.logging.Level#FINER FINER} through this request's {@link #getLogger() logger}.
    *
    * @param pattern The {@link java.util.Formatter}-style message pattern.
    * @param args The message arguments.
    */
   public void finer(String pattern, Object...args) { getLogger().finer(pattern, args); }

   /**
    * Logs a formatted message with an associated throwable at {@link java.util.logging.Level#FINER FINER}.
    *
    * @param thrown The throwable to associate with the record.
    * @param pattern The {@link java.util.Formatter}-style message pattern.
    * @param args The message arguments.
    */
   public void finer(Throwable thrown, String pattern, Object...args) { getLogger().finer(thrown, pattern, args); }

   /**
    * Logs a formatted message at {@link java.util.logging.Level#FINEST FINEST} through this request's {@link #getLogger() logger}.
    *
    * @param pattern The {@link java.util.Formatter}-style message pattern.
    * @param args The message arguments.
    */
   public void finest(String pattern, Object...args) { getLogger().finest(pattern, args); }

   /**
    * Logs a formatted message with an associated throwable at {@link java.util.logging.Level#FINEST FINEST}.
    *
    * @param thrown The throwable to associate with the record.
    * @param pattern The {@link java.util.Formatter}-style message pattern.
    * @param args The message arguments.
    */
   public void finest(Throwable thrown, String pattern, Object...args) { getLogger().finest(thrown, pattern, args); }

   /**
    * Returns whether REST-driven serializer/parser debug behavior is enabled for this request's operation.
    *
    * <p>
    * Resolved from the cascading {@link Rest#debugMarshalling() @Rest(debugMarshalling)} /
    * {@link RestOp#debugMarshalling() @RestOp(debugMarshalling)} setting (default OFF), <b>independent</b> of the JUL
    * logger level. When enabled, the REST layer forces {@code Context.debug} on the serializer/parser session used to
    * handle this request &mdash; engaging recursion-detection-that-throws, parse-input buffering, and stack-trace-prefixed
    * marshalling exceptions.
    *
    * @return <jk>true</jk> if REST-driven marshalling debug is enabled for this operation.
    */
   public boolean isDebugMarshalling() { return opContext.isDebugMarshalling(); }

   /**
    * Returns the captured (bounded) request body bytes for debug logging.
    *
    * <p>
    * Populated by the two-phase debug pipeline only when the resolved logger is loggable at
    * {@link java.util.logging.Level#FINEST FINEST}; otherwise returns <jk>null</jk>. The captured copy is capped at the
    * formatter's body cap (default 8&nbsp;KB); use {@link #getCachedContentLength()} for the full byte count.
    *
    * @return The captured request body bytes, or <jk>null</jk> if body caching was not installed.
    */
   public byte[] getCachedContent() {
      return inner instanceof CachingHttpServletRequest c ? c.getContent() : null;
   }

   /**
    * Returns the total number of request body bytes read, including any beyond the capture cap.
    *
    * @return The total request body length in bytes, or {@code -1} if body caching was not installed.
    */
   public long getCachedContentLength() {
      return inner instanceof CachingHttpServletRequest c ? c.getTotalLength() : -1;
   }

   /**
    * Returns the exception thrown while processing this request, if any.
    *
    * @return The thrown exception, or <jk>null</jk> if none occurred.
    */
   public Throwable getException() {
      return session.getException();
   }

   /**
    * Returns the total request execution time in milliseconds, if it has been recorded.
    *
    * @return The execution time in milliseconds, or <jk>null</jk> if not yet recorded.
    */
   public Long getExecTime() {
      return getAttribute("ExecTime").as(Long.class).orElse(null);
   }

   /**
    * Returns <jk>true</jk> if <c>&amp;plainText=true</c> was specified as a URL parameter.
    *
    * <p>
    * This indicates that the <c>Content-Type</c> of the output should always be set to <js>"text/plain"</js>
    * to make it easy to render in a browser.
    *
    * <p>
    * This feature is useful for debugging.
    *
    * @return <jk>true</jk> if {@code &amp;plainText=true} was specified as a URL parameter
    */
   public boolean isPlainText() { return eq(queryParams.get("plainText").asString().orElse("false"), "true"); }

   /**
    * Sets a request attribute.
    *
    * @param name The attribute name.
    * @param value The attribute value.
    */
   @Override
   public void setAttribute(String name, Object value) {
      attrs.set(name, value);
   }

   /**
    * Sets the resolved resource-level authentication result.
    *
    * <p>
    * Invoked by the framework after the {@link RestAuthenticator} fold resolves
    * an identity for this request.  The stored result drives {@link #getUserPrincipal()}, {@link #isUserInRole(String)},
    * and {@link #getRemoteUser()}, and (when a principal is present) stashes the principal under
    * {@code "juneau.principal"} so {@code @Auth} argument injection resolves it.
    *
    * @param value The result. Can be <jk>null</jk> to unset.
    * @return This object.
    * @since 10.0.0
    */
   public RestRequest setAuthResult(AuthResult value) {
      authResult = value;
      if (value != null && value.getPrincipal() != null)
         setAttribute("juneau.principal", value.getPrincipal());
      return this;
   }

   @Override /* Overridden from HttpServletRequestWrapper */
   public Principal getUserPrincipal() {
      var p = authResult == null ? null : authResult.getPrincipal();
      return p != null ? p : super.getUserPrincipal();
   }

   @Override /* Overridden from HttpServletRequestWrapper */
   public boolean isUserInRole(String role) {
      if (authResult != null && authResult.getRoles().contains(role))
         return true;
      return super.isUserInRole(role);
   }

   @Override /* Overridden from HttpServletRequestWrapper */
   public String getRemoteUser() {
      var p = authResult == null ? null : authResult.getPrincipal();
      return p != null ? p.getName() : super.getRemoteUser();
   }

   /**
    * Sets a serializer session property programmatically.
    *
    * <p>
    * Session properties override context-level properties and can be used to customize serializer behavior for this request only.
    *
    * @param name The property name (e.g. {@code "escapeSolidus"}).
    * @param value The property value.
    * @return This object.
    */
   public RestRequest setSerializerSessionProperty(String name, Object value) {
      if (serializerSessionProperties == null)
         serializerSessionProperties = m();
      serializerSessionProperties.put(name, value);
      return this;
   }

   /**
    * Sets a parser session property programmatically.
    *
    * <p>
    * Session properties override context-level properties and can be used to customize parser behavior for this request only.
    *
    * @param name The property name (e.g. {@code "trimStrings"}).
    * @param value The property value.
    * @return This object.
    */
   public RestRequest setParserSessionProperty(String name, Object value) {
      if (parserSessionProperties == null)
         parserSessionProperties = m();
      parserSessionProperties.put(name, value);
      return this;
   }

   /**
    * Sets multiple serializer session properties programmatically.
    *
    * @param values The properties to set. Can be {@code null}.
    * @return This object.
    */
   public RestRequest setSerializerSessionProperties(Map<String,Object> values) {
      if (ine(values)) {
         if (serializerSessionProperties == null)
            serializerSessionProperties = m();
         serializerSessionProperties.putAll(values);
      }
      return this;
   }

   /**
    * Sets multiple parser session properties programmatically.
    *
    * @param values The properties to set. Can be {@code null}.
    * @return This object.
    */
   public RestRequest setParserSessionProperties(Map<String,Object> values) {
      if (ine(values)) {
         if (parserSessionProperties == null)
            parserSessionProperties = m();
         parserSessionProperties.putAll(values);
      }
      return this;
   }

   /**
    * Returns the merged serializer session property map for this request.
    *
    * <p>
    * Merges (in order of increasing priority):
    * <ol>
    *    <li>Request attributes (from {@link #getAttributes()}, e.g. {@code defaultRequestAttributes})
    *    <li>UON-encoded {@code juneauSerializerOptions} query parameter
    *    <li>JSON5-encoded {@code X-Juneau-Serializer-Options} header
    *    <li>Programmatically-set properties via {@link #setSerializerSessionProperty}
    * </ol>
    *
    * <p>
    * Client-supplied keys are validated against the allowlist from {@link RestOpContext#getAllowedSerializerOptions()}.
    * Keys not in the allowlist cause a {@code 400 Bad Request} response.
    *
    * @return An unmodifiable map of session properties; may be empty but never {@code null}.
    */
   public Map<String,Object> getSerializerSessionPropertyMap() {
      var allowlist = opContext.getAllowedSerializerOptions();
      Map<String,Object> m1 = null;
      Map<String,Object> m2 = null;

      var q = getQueryParams().get(QUERY_juneauSerializerOptions).asString().orElse(null);
      if (inb(q)) {
         m1 = parseUonMap(q, e -> badRequest(e, "Could not parse UON session options from query parameter '%s'.", QUERY_juneauSerializerOptions));
         var invalid = m1.keySet().stream().filter(k -> !allowlist.contains(k)).collect(Collectors.joining(","));
         if (!invalid.isEmpty())
            badRequest("Invalid session options in query parameter '%s': '%s'", QUERY_juneauSerializerOptions, invalid);
      }

      var h = getHeaderParam(HEADER_JuneauSerializerOptions).asString().orElse(null);
      if (inb(h)) {
         m2 = parseJsonMap(h, e -> badRequest(e, "Could not parse JSON5 session options from header '%s'.", HEADER_JuneauSerializerOptions));
         var invalid = m2.keySet().stream().filter(k -> !allowlist.contains(k)).collect(Collectors.joining(","));
         if (!invalid.isEmpty())
            badRequest("Invalid session options in header '%s': '%s'", HEADER_JuneauSerializerOptions, invalid);
      }

      return mergeSessionMaps(getAttributes().asMap(), m1, m2, serializerSessionProperties);
   }

   /**
    * Returns the merged parser session property map for this request.
    *
    * <p>
    * Merges (in order of increasing priority):
    * <ol>
    *    <li>Request attributes (from {@link #getAttributes()}, e.g. {@code defaultRequestAttributes})
    *    <li>UON-encoded {@code juneauParserOptions} query parameter
    *    <li>JSON5-encoded {@code X-Juneau-Parser-Options} header
    *    <li>Programmatically-set properties via {@link #setParserSessionProperty}
    * </ol>
    *
    * <p>
    * Client-supplied keys are validated against the allowlist from {@link RestOpContext#getAllowedParserOptions()}.
    * Keys not in the allowlist cause a {@code 400 Bad Request} response.
    *
    * @return An unmodifiable map of session properties; may be empty but never {@code null}.
    */
   public Map<String,Object> getParserSessionPropertyMap() {
      var allowlist = opContext.getAllowedParserOptions();
      Map<String,Object> m1 = null;
      Map<String,Object> m2 = null;

      var q = getQueryParams().get(QUERY_juneauParserOptions).asString().orElse(null);
      if (inb(q)) {
         m1 = parseUonMap(q, e -> badRequest(e, "Could not parse UON session options from query parameter '%s'.", QUERY_juneauParserOptions));
         var invalid = m1.keySet().stream().filter(k -> !allowlist.contains(k)).collect(Collectors.joining(","));
         if (!invalid.isEmpty())
            badRequest("Invalid session options in query parameter '%s': '%s'", QUERY_juneauParserOptions, invalid);
      }

      var h = getHeaderParam(HEADER_JuneauParserOptions).asString().orElse(null);
      if (inb(h)) {
         m2 = parseJsonMap(h, e -> badRequest(e, "Could not parse JSON5 session options from header '%s'.", HEADER_JuneauParserOptions));
         var invalid = m2.keySet().stream().filter(k -> !allowlist.contains(k)).collect(Collectors.joining(","));
         if (!invalid.isEmpty())
            badRequest("Invalid session options in header '%s': '%s'", HEADER_JuneauParserOptions, invalid);
      }

      return mergeSessionMaps(getAttributes().asMap(), m1, m2, parserSessionProperties);
   }

   @SafeVarargs
   private static Map<String,Object> mergeSessionMaps(Map<String,Object>...maps) {
      Map<String,Object> result = null;
      for (var map : maps) {
         if (ine(map)) {
            if (result == null)
               result = new LinkedHashMap<>(map);
            else
               result.putAll(map);
         }
      }
      return result != null ? u(result) : Collections.emptyMap();
   }

   private static void badRequest(String msg, Object...args) {
      throw new BadRequest(msg, args);
   }

   private static void badRequest(Exception causedBy, String msg, Object...args) {
      throw new BadRequest(causedBy, msg, args);
   }

   private static Map<String,Object> parseUonMap(String input, Consumer<ParseException> onError) {
      try {
         var m = Uon.to(input, JsonMap.class);
         return m != null ? m : Collections.emptyMap();
      } catch (ParseException e) {
         onError.accept(e);
         return Collections.emptyMap();
      }
   }

   private static Map<String,Object> parseJsonMap(String input, Consumer<ParseException> onError) {
      try {
         var m = Json5.to(input, JsonMap.class);
         return m != null ? m : Collections.emptyMap();
      } catch (ParseException e) {
         onError.accept(e);
         return Collections.emptyMap();
      }
   }

   /**
    * Sets the charset to expect on the request content.
    *
    * @param value The new charset to use for the request content.
    *    <br>Can be <jk>null</jk> (resets to the negotiated/default charset on the next {@link #getCharset()} call).
    */
   public void setCharset(Charset value) { this.charset = value; }

   /**
    * Sets the <js>"Exception"</js> attribute to the specified throwable.
    *
    * <p>
    * This exception is surfaced by the debug pipeline as the {@code thrown} of the emitted log record.
    *
    * @param t The attribute value.
    * @return This object.
    */
   public RestRequest setException(Throwable t) {
      setAttribute("Exception", t);
      return this;
   }

   /**
    * Shortcut for calling <c>setNoTrace(<jk>true</jk>)</c>.
    *
    * @return This object.
    */
   public RestRequest setNoTrace() {
      return setNoTrace(true);
   }

   /**
    * Sets the <js>"NoTrace"</js> attribute to the specified boolean.
    *
    * <p>
    * 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 <c>No-Trace: true</c> request header has the same effect; when both are present, the attribute wins.
    *
    * @param b The attribute value.
    * @return This object.
    */
   public RestRequest setNoTrace(Boolean b) {
      setAttribute("NoTrace", b);
      return this;
   }

   @Override /* Overridden from Object */
   public String toString() {
      var sb = new StringBuilder("\n").append(getRequestLine()).append("\n");
      sb.append("---Headers---\n");
      getHeaders().forEach(x -> sb.append("\t").append(x).append("\n"));
      var m = getMethod();
      if (eqa(m, "PUT", "POST")) {
         try {
            sb.append("---Content UTF-8---\n");
            sb.append(content.asString()).append("\n");
            sb.append("---Content Hex---\n");
            sb.append(content.asSpacedHex()).append("\n");
         } catch (Exception e1) {
            sb.append(localizedMessage(e1));
         }
      }
      return sb.toString();
   }

   /* Called by RestSession.finish() */
   void close() {
      if (nn(config)) {
         config.close();
      }
   }

   /**
    * Creates the underlying part-parser session only when a part actually has to be parsed.
    *
    * <p>
    * Most requests never parse a header, query, path or form value into a schema-typed object, so building the
    * (comparatively heavy) OpenAPI parser session up front is wasted work.
    */
   private static final class LazyPartParserSession implements HttpPartParserSession {
      private final HttpPartParser parser;
      private final AtomicReference<HttpPartParserSession> session = new AtomicReference<>();

      LazyPartParserSession(HttpPartParser parser) {
         this.parser = parser;
      }

      @Override /* Overridden from HttpPartParserSession */
      public <T> T read(HttpPartType partType, HttpPartSchema schema, String in, ClassMeta<T> toType) throws ParseException, SchemaValidationException {
         var s = session.get();
         if (s == null) {
            s = parser.getPartSession();
            session.set(s);
         }
         return s.read(partType, schema, in, toType);
      }
   }
}