/*
 * 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.client.classic;

import static org.apache.juneau.commons.httppart.HttpPartType.*;
import static org.apache.juneau.commons.utils.ClassUtils.*;
import static org.apache.juneau.commons.utils.CollectionUtils.*;
import static org.apache.juneau.commons.utils.IoUtils.*;
import static org.apache.juneau.commons.utils.Shorts.*;
import static org.apache.juneau.http.classic.HttpEntities.*;
import static org.apache.juneau.http.classic.HttpHeaders.*;
import static org.apache.juneau.rest.RestSharedConstants.*;
import static org.apache.juneau.rest.client.classic.RestOperation.*;

import java.io.*;
import java.lang.reflect.*;
import java.net.*;
import java.util.*;
import java.util.concurrent.*;
import java.util.function.*;
import java.util.logging.*;

import org.apache.http.*;
import org.apache.http.ParseException;
import org.apache.http.client.*;
import org.apache.http.client.config.*;
import org.apache.http.client.entity.*;
import org.apache.http.client.methods.*;
import org.apache.http.client.protocol.HttpClientContext;
import org.apache.http.client.utils.*;
import org.apache.http.concurrent.*;
import org.apache.http.entity.BasicHttpEntity;
import org.apache.http.params.*;
import org.apache.http.protocol.*;
import org.apache.http.util.*;
import org.apache.juneau.commons.bean.*;
import org.apache.juneau.commons.collections.*;
import org.apache.juneau.commons.httppart.*;
import org.apache.juneau.commons.reflect.*;
import org.apache.juneau.http.classic.*;
import org.apache.juneau.http.classic.HttpHeaders;
import org.apache.juneau.http.classic.entity.*;
import org.apache.juneau.http.classic.header.*;
import org.apache.juneau.http.classic.header.ContentType;
import org.apache.juneau.http.classic.part.*;
import org.apache.juneau.http.classic.resource.*;
import org.apache.juneau.http.remote.*;
import org.apache.juneau.rest.client.RedirectSecurity;
import org.apache.juneau.rest.client.classic.remote.*;
import org.apache.juneau.marshall.*;
import org.apache.juneau.marshall.bson.*;
import org.apache.juneau.marshall.html.*;
import org.apache.juneau.marshall.httppart.*;
import org.apache.juneau.marshall.jcs.*;
import org.apache.juneau.marshall.json.*;
import org.apache.juneau.marshall.json5.*;
import org.apache.juneau.marshall.marshaller.*;
import org.apache.juneau.marshall.marshaller.Uon;
import org.apache.juneau.marshall.msgpack.*;
import org.apache.juneau.marshall.oapi.*;
import org.apache.juneau.marshall.parser.*;
import org.apache.juneau.marshall.plaintext.*;
import org.apache.juneau.marshall.serializer.*;
import org.apache.juneau.marshall.stream.*;
import org.apache.juneau.marshall.uon.*;
import org.apache.juneau.marshall.urlencoding.*;
import org.apache.juneau.marshall.xml.*;

/**
 * Represents a request to a remote REST resource.
 *
 * <p>
 * Instances of this class are created by the various creator methods on the {@link RestClient} class.
 *
 * <h5 class='section'>Example:</h5>
 * <p class='bjava'>
 *    <jc>// Create a request and automatically close it.</jc>
 *    <jk>try</jk> (<jv>RestRequest</jv> <jv>req</jv> = <jv>client</jv>.get(<js>"/myResource"</js>)) {
 *       <jv>req</jv>
 *          .queryData(<js>"foo"</js>, <js>"bar"</js>)
 *          .run()
 *          .assertStatus().asCode().is(200);
 *    }
 * </p>
 *
 * <p>
 * The {@link #close()} method will automatically close any associated {@link RestResponse} if one was created via {@link #run()}.
 *
 * <h5 class='section'>Notes:</h5><ul>
 *    <li class='warn'>This class is not thread safe.
 *    <li class='note'>This class implements {@link AutoCloseable} and can be used in try-with-resources blocks.
 *       The {@link #close()} method allows unchecked exceptions to propagate for debuggability,
 *       while catching and logging checked exceptions to follow AutoCloseable best practices.
 * </ul>
 *
 * <h5 class='section'>See Also:</h5><ul>
 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauRestClient">juneau-rest-client-classic</a>
 * </ul>
 */
@SuppressWarnings({
   "java:S1133", // Intentional deprecation retained for backward compatibility until the documented removal; the reminder is not actionable now.
   "java:S1192", // Duplicated literals (argument/property names) read more clearly inline than as constants
   "java:S3776", // Cognitive complexity acceptable for request-building and dispatch logic.
   "java:S3740", // Raw Class/Supplier types used for fluent REST request building where response type is unknown at construction time
   "java:S6539", // Monster class; RestRequest is intentionally a single per-request fluent builder aggregating headers/query/form/body/serialization config
   "resource", // Resource management handled externally
   "unchecked" // toMap() casts a value already verified to be a Map to Map<Object,Object>.
})
public class RestRequest extends MarshallingSession implements HttpUriRequest, Configurable, AutoCloseable {

   private static final String HEADER_ACCEPT = org.apache.juneau.http.header.Accept.NAME;
   private static final String HEADER_CONTENT_TYPE = org.apache.juneau.http.header.ContentType.NAME;

   // URI path separator (always "/" per RFC 3986)
   private static final String URI_PATH_SEPARATOR = "/";

   private class SimpleFormData extends SimplePart {
      SimpleFormData(NameValuePair x) {
         super(x, client.isSkipEmptyFormData());
      }
   }

   private class SimpleHeader extends SimplePart implements Header {

      SimpleHeader(NameValuePair x) {
         super(x, client.isSkipEmptyHeaderData());
      }

      @Override
      public HeaderElement[] getElements() throws ParseException { return new HeaderElement[0]; }
   }

   private class SimplePart implements NameValuePair {
      final String name;
      final String value;

      SimplePart(NameValuePair x, boolean skipIfEmpty) {
         name = x.getName();
         if (x instanceof SerializedHeader x2) {
            value = x2.copyWith(getPartSerializerSession(), null).getValue();
         } else if (x instanceof SerializedPart x2) {
            value = x2.copyWith(getPartSerializerSession(), null).getValue();
         } else {
            var v = x.getValue();
            value = (ie(v) && skipIfEmpty) ? null : v;
         }
      }

      @Override
      public String getName() { return name; }

      @Override
      public String getValue() { return value; }

      boolean isValid() {
         return !(ie(name) || value == null);
      }
   }

   private class SimplePath extends SimplePart {
      SimplePath(NameValuePair x) {
         super(x, false);
      }
   }

   private class SimpleQuery extends SimplePart {
      SimpleQuery(NameValuePair x) {
         super(x, client.isSkipEmptyQueryData());
      }
   }

   private static final ContentType TEXT_PLAIN = ContentType.TEXT_PLAIN;

   private static boolean isHeaderArray(Object o) {
      if (! isArray(o))
         return false;
      return Header.class.isAssignableFrom(o.getClass().getComponentType());
   }

   private static boolean isNameValuePairArray(Object o) {
      if (! isArray(o))
         return false;
      return NameValuePair.class.isAssignableFrom(o.getClass().getComponentType());
   }

   private static Map<Object,Object> toMap(Object o) {
      return (Map<Object,Object>)o;
   }

   final RestClient client;                               // The client that created this call.
   private final HttpRequestBase request;                 // The request.
   private boolean ignoreErrors;
   private boolean suppressLogging;
   private HttpContext context;
   // Set for the request of an SSRF-guard-active @Remote call (by RestClient, or by run() while the calling thread runs
   // a guarded call); it then sends every hop with the SsrfGuardMarker on its context.  Volatile: the request's
   // HttpClient may run on another thread.
   private volatile boolean ssrfGuarded;
   private HttpHost target;
   private HttpPartSchema contentSchema;
   private HttpPartSerializerSession partSerializerSession;
   private final HeaderList headerData;
   private List<Class<? extends Throwable>> rethrow;
   List<RestCallInterceptor> interceptors = list();   // Used for intercepting and altering requests.
   private Object content;
   private Parser parser;
   private final PartList formData;
   private final PartList pathData;
   private final PartList queryData;
   private Predicate<Integer> errorCodes;
   private RestResponse response;                         // The response.
   private Serializer serializer;
   private final URIBuilder uriBuilder;

   private final Map<HttpPartSerializer,HttpPartSerializerSession> partSerializerSessions = new IdentityHashMap<>();

   /**
    * Constructs a REST call with the specified method name.
    *
    * @param client The client that created this request.
    *    <br>Cannot be <jk>null</jk>.
    * @param uri The target URI.
    *    <br>Cannot be <jk>null</jk>.
    * @param method The HTTP method name (uppercase).
    *    <br>Cannot be <jk>null</jk>.
    * @param hasBody Whether this method has a body.
    * @throws RestCallException If an exception or non-200 response code occurred during the connection attempt.
    */
   protected RestRequest(RestClient client, URI uri, String method, boolean hasBody) throws RestCallException {
      super(reqnn("client", client).getMarshallingContext().createSession());
      this.client = client;
      this.request = createInnerRequest(reqnn("method", method), reqnn("uri", uri), hasBody);
      this.errorCodes = client.errorCodes;
      this.formData = client.createFormData();
      this.headerData = client.createHeaderData();
      this.ignoreErrors = client.ignoreErrors;
      this.pathData = client.createPathData();
      this.queryData = client.createQueryData();
      this.uriBuilder = new URIBuilder(request.getURI());
   }

   /**
    * Aborts this http request. Any active execution of this method should return immediately.
    *
    * If the request has not started, it will abort after the next execution.
    * <br>Aborting this request will cause all subsequent executions with this request to fail.
    */
   @Override /* Overridden from HttpUriRequest */
   public void abort() throws UnsupportedOperationException {
      request.abort();
   }

   /**
    * Sets the value for the <c>Accept</c> request header.
    *
    * <p>
    * This overrides the media type specified on the parser, but is overridden by calling
    * <code>header(<js>"Accept"</js>, value);</code>
    *
    * @param value The new header value.
    *    <br>Can be <jk>null</jk> (header will not be set).
    * @return This object.
    * @throws RestCallException Invalid input.
    */
   public RestRequest accept(String value) throws RestCallException {
      return header(Accept.of(value));
   }

   /**
    * Sets the value for the <c>Accept-Charset</c> request header.
    *
    * <p>
    * This is a shortcut for calling <code>header(<js>"Accept-Charset"</js>, value);</code>
    *
    * @param value The new header value.
    *    <br>Can be <jk>null</jk> (header will not be set).
    * @return This object.
    * @throws RestCallException Invalid input.
    */
   public RestRequest acceptCharset(String value) throws RestCallException {
      return header(AcceptCharset.of(value));
   }

   /**
    * Adds a header to this message.
    *
    * The header will be appended to the end of the list.
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>{@link #header(Header)} is an equivalent method and the preferred method for fluent-style coding.
    * </ul>
    *
    * @param header The header to append.
    *    <br>Can be <jk>null</jk> (ignored).
    */
   @Override /* Overridden from HttpMessage */
   public void addHeader(Header header) {
      headerData.append(header);
   }

   /**
    * Adds a header to this message.
    *
    * The header will be appended to the end of the list.
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>{@link #header(String,Object)} is an equivalent method and the preferred method for fluent-style coding.
    * </ul>
    *
    * @param name The name of the header.
    *    <br>Cannot be <jk>null</jk> or empty (header will not be created).
    * @param value The value of the header.
    *    <br>Can be <jk>null</jk>.
    */
   @Override /* Overridden from HttpMessage */
   public void addHeader(String name, String value) {
      headerData.append(stringHeader(name, value));
   }

   /**
    * Sets {@link Cancellable} for the ongoing operation.
    *
    * @param cancellable The cancellable object.
    *    <br>Can be <jk>null</jk> (no cancellation will be available).
    * @return This object.
    */
   public RestRequest cancellable(Cancellable cancellable) {
      request.setCancellable(cancellable);
      return this;
   }

   /**
    * Closes this request and its associated response (if one was created).
    *
    * <p>
    * This method is idempotent and can be called multiple times without side effects.
    *
    * <h5 class='section'>Implementation Notes:</h5>
    * <p>
    * This implementation represents a compromise between strict AutoCloseable compliance and debuggability:
    * <ul>
    *    <li>Unchecked exceptions ({@link RuntimeException} and {@link Error}) from the response close are allowed to propagate.
    *       This ensures programming errors and serious issues are visible during development and testing.
    *    <li>Checked exceptions (including {@link RestCallException}) are caught and logged but not thrown.
    *       This follows AutoCloseable best practices and prevents close exceptions from interfering with
    *       try-with-resources cleanup or masking the original exception.
    * </ul>
    */
   @Override /* Overridden from AutoCloseable */
   public void close() {
      try {
         if (nn(response)) {
            response.close();
         }
      } catch (RuntimeException e) {
         // Let unchecked exceptions propagate for debuggability
         throw e;
      } catch (Exception e) {
         // Log checked exceptions but don't throw - follows AutoCloseable best practices
         client.log(Level.WARNING, e, "Error closing RestResponse");
      }
   }

   /**
    * Same as {@link #run()} but immediately calls {@link RestResponse#consume()} to clean up the response.
    *
    * <p>
    * Use this method if you're only interested in the status line of the response and not the response entity.
    * Attempts to call any of the methods on the response object that retrieve the body (e.g. {@link ResponseContent#asReader()}
    * will cause a {@link RestCallException} to be thrown.
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>You do not need to execute {@link InputStream#close()} on the response body to consume the response.
    * </ul>
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *  <jc>// Get the response code.
    *  // No need to call close() on the RestResponse object.</jc>
    *  <jk>int</jk> <jv>rc</jv> = <jv>client</jv>.get(<jsf>URI</jsf>).complete().getResponseCode();
    * </p>
    *
    * @return The response object.
    * @throws RestCallException If an exception or non-200 response code occurred during the connection attempt.
    */
   public RestResponse complete() throws RestCallException {
      return run().consume();
   }

   /**
    * Used in combination with {@link #cancellable(Cancellable)}.
    *
    * @deprecated Since 10.0, for removal.
    * @return This object.
    */
   @Deprecated(since = "10.0", forRemoval = true)
   public RestRequest completed() {
      request.completed();
      return this;
   }

   /**
    * Same as {@link #complete()} but allows you to run the call asynchronously.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    Future&lt;RestResponse&gt; <jv>future</jv> = <jv>client</jv>.get(<jsf>URI</jsf>).completeFuture();
    *
    *    <jc>// Do some other stuff</jc>
    *
    *    <jk>int</jk> <jv>rc</jv> = <jv>future</jv>.get().getResponseStatus();
    * </p>
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>Use the {@link RestClient.Builder#executorService(ExecutorService, boolean)} method to customize the
    *       executor service used for creating {@link Future Futures}.
    *    <li class='note'>You do not need to execute {@link InputStream#close()} on the response body to consume the response.
    * </ul>
    *
    * @return The HTTP status code.
    * @throws RestCallException If the executor service was not defined.
    */
   public Future<RestResponse> completeFuture() throws RestCallException {
      return client.getExecutorService().submit(this::complete);
   }

   /**
    * Sets the actual request configuration.
    *
    * @param value The new value.
    *    <br>Can be <jk>null</jk> (default configuration will be used).
    * @return This object.
    */
   public RestRequest config(RequestConfig value) {
      request.setConfig(value);
      return this;
   }

   /**
    * Checks if a certain header is present in this message.
    *
    * Header values are ignored.
    *
    * @param name The header name to check for.
    *    <br>Cannot be <jk>null</jk>.
    * @return <jk>true</jk> if at least one header with this name is present.
    */
   @Override /* Overridden from HttpMessage */
   public boolean containsHeader(String name) {
      return headerData.contains(name);
   }

   /**
    * Sets the body of this request.
    *
    * @param value
    *    The input to be sent to the REST resource (only valid for PUT/POST/PATCH) requests.
    *    <br>Can be of the following types:
    *    <ul class='spaced-list'>
    *       <li>
    *          {@link Reader} - Raw contents of {@code Reader} will be serialized to remote resource.
    *       <li>
    *          {@link InputStream} - Raw contents of {@code InputStream} will be serialized to remote resource.
    *       <li>
    *          {@link HttpResource} - Raw contents will be serialized to remote resource.  Additional headers and media type will be set on request.
    *       <li>
    *          {@link HttpEntity}/{@link BasicHttpEntity} - Bypass Juneau serialization and pass HttpEntity directly to HttpClient.
    *       <li>
    *          {@link Object} - POJO to be converted to text using the {@link Serializer} registered with the
    *          {@link RestClient}.
    *       <li>
    *          {@link PartList} - Converted to a URL-encoded FORM post.
    *       <li>
    *          A {@link Supplier} of anything on this list.
    *    </ul>
    *    <br>Can be <jk>null</jk> (no body will be sent).
    * @return This object.
    */
   public RestRequest content(Object value) {
      content = value;
      return this;
   }

   /**
    * Sets the body of this request.
    *
    * @param input
    *    The input to be sent to the REST resource (only valid for PUT/POST/PATCH) requests.
    *    <br>Can be of the following types:
    *    <ul class='spaced-list'>
    *       <li>
    *          {@link Reader} - Raw contents of {@code Reader} will be serialized to remote resource.
    *       <li>
    *          {@link InputStream} - Raw contents of {@code InputStream} will be serialized to remote resource.
    *       <li>
    *          {@link HttpResource} - Raw contents will be serialized to remote resource.  Additional headers and media type will be set on request.
    *       <li>
    *          {@link HttpEntity}/{@link BasicHttpEntity} - Bypass Juneau serialization and pass HttpEntity directly to HttpClient.
    *       <li>
    *          {@link Object} - POJO to be converted to text using the {@link Serializer} registered with the
    *          {@link RestClient}.
    *       <li>
    *          {@link PartList} - Converted to a URL-encoded FORM post.
    *       <li>
    *          A {@link Supplier} of anything on this list.
    *    </ul>
    * @param schema The schema object that defines the format of the output.
    *    <ul>
    *       <li>If <jk>null</jk>, defaults to {@link HttpPartSchema#DEFAULT}.
    *       <li>Only used if serializer is schema-aware (e.g. {@link OpenApiSerializer}).
    *    </ul>
    * @return This object.
    */
   public RestRequest content(Object input, HttpPartSchema schema) {
      this.content = input;
      this.contentSchema = schema;
      return this;
   }

   /**
    * Sets the body of this request as straight text bypassing the serializer.
    *
    * <p class='bjava'>
    *    <jv>client</jv>
    *       .put(<js>"/foo"</js>)
    *       .content(<jk>new</jk> StringReader(<js>"foo"</js>))
    *       .contentType(<js>"text/foo"</js>)
    *       .run();
    *
    * <jv>client</jv>
    *       .put(<js>"/foo"</js>)
    *       .bodyString(<js>"foo"</js>)
    *       .run();
    * </p>
    *
    * <p>
    * Note that this is different than the following which will serialize <l>foo</l> as a JSON string <l>"foo"</l>.
    * <p class='bjava'>
    *    <jv>client</jv>
    *       .put(<js>"/foo"</js>)
    *       .json()
    *       .content(<js>"foo"</js>)
    *       .run();
    * </p>
    *
    * @param input
    *    The input to be sent to the REST resource (only valid for PUT/POST/PATCH) requests.
    * @return This object.
    * @throws RestCallException If a retry was attempted, but the entity was not repeatable.
    */
   public RestRequest contentString(Object input) throws RestCallException {
      return content(input == null ? null : new StringReader(s(input)));
   }

   /**
    * Sets the value for the <c>Content-Type</c> request header.
    *
    * <p>
    * This overrides the media type specified on the serializer, but is overridden by calling
    * <code>header(<js>"Content-Type"</js>, value);</code>
    *
    * @param value The new header value.
    *    <br>Can be <jk>null</jk> (header will not be set).
    * @return This object.
    * @throws RestCallException Invalid input.
    */
   public RestRequest contentType(String value) throws RestCallException {
      return header(ContentType.of(value));
   }

   /**
    * Override the context to use for the execution.
    *
    * @param context The context to use for the execution, or <jk>null</jk> to use the default context.
    * @return This object.
    */
   public RestRequest context(HttpContext context) {
      this.context = context;
      return this;
   }

   /**
    * Sets <c>Debug: value</c> header on this request.
    *
    * @return This object.
    * @throws RestCallException Invalid input.
    */
   public RestRequest debug() throws RestCallException {
      header("Debug", true);
      return this;
   }

   /**
    * Allows you to override what status codes are considered error codes that would result in a {@link RestCallException}.
    *
    * <p>
    * The default error code predicate is: <code>x -&gt; x &gt;= 400</code>.
    *
    * @param value The new predicate for calculating error codes.
    *    <br>Cannot be <jk>null</jk>.
    * @return This object.
    */
   public RestRequest errorCodes(Predicate<Integer> value) {
      errorCodes = reqnn("value", value);
      return this;
   }

   /**
    * Appends multiple form-data parameters to the request.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    <jc>// Appends two form-data parameters to the request.</jc>
    *    <jv>client</jv>
    *       .get(<jsf>URI</jsf>)
    *       .formData(
    *          BasicStringPart.<jsm>of</jsm>(<js>"foo"</js>, <js>"bar"</js>),
    *          BasicBooleanPart.<jsm>of</jsm>(<js>"baz"</js>, <jk>true</jk>)
    *       )
    *       .run();
    * </p>
    *
    * @param parts
    *    The parameters to set.
    *    <jk>null</jk> values are ignored.
    * @return This object.
    */
   public RestRequest formData(NameValuePair...parts) {
      formData.append(parts);
      return this;
   }

   /**
    * Adds a form-data parameter to the request body.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    <jc>// Adds form data parameter "foo=bar".</jc>
    *    <jv>client</jv>
    *       .formPost(<jsf>URI</jsf>)
    *       .formData(<js>"foo"</js>, <js>"bar"</js>)
    *       .run();
    * </p>
    *
    * @param name
    *    The parameter name.
    *    <br>Cannot be <jk>null</jk> or empty (parameter will not be created).
    * @param value
    *    The parameter value.
    *    <br>Non-string values are converted to strings using the {@link HttpPartSerializer} defined on the client.
    *    <br>Can be <jk>null</jk>.
    * @return This object.
    */
   public RestRequest formData(String name, Object value) {
      formData.append(createPart(FORMDATA, name, value));
      return this;
   }

   /**
    * Appends multiple form-data parameters to the request from properties defined on a Java bean.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    <jk>public class</jk> MyFormData {
    *       <jk>public</jk> String getFooBar() { <jk>return</jk> <js>"baz"</js>; }
    *       <jk>public</jk> Integer getQux() { <jk>return</jk> 123; }
    *    }
    *
    *    <jc>// Appends form data "fooBar=baz&amp;qux=123".</jc>
    *    <jv>client</jv>
    *       .get(<jsf>URI</jsf>)
    *       .formDataBean(<jk>new</jk> MyFormData())
    *       .run();
    * </p>
    *
    * @param value The bean containing the properties to set as form-data parameter values.
    *    <br>Cannot be <jk>null</jk>.
    * @return This object.
    */
   public RestRequest formDataBean(Object value) {
      req(isBean(reqnn("value", value)), "Object passed into formDataBean(Object) is not a bean.");
      var b = formData;
      toBeanMap(value).forEach((k, v) -> b.append(createPart(FORMDATA, k, v)));
      return this;
   }

   /**
    * Adds form-data parameters as the entire body of the request.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    <jc>// Creates form data "foo=bar&amp;baz=qux".</jc>
    *    <jv>client</jv>
    *       .formPost(<jsf>URI</jsf>)
    *       .formDataCustom(<js>"foo=bar&amp;baz=qux"</js>)
    *       .run();
    *
    *    <jc>// Creates form data "foo=bar&amp;baz=qux" using StringEntity.</jc>
    *    <jv>client</jv>
    *       .formPost(<jsf>URI</jsf>)
    *       .formDataCustom(<jk>new</jk> StringEntity(<js>"foo=bar&amp;baz=qux"</js>,<js>"application/x-www-form-urlencoded"</js>))
    *       .run();
    *
    *    <jc>// Creates form data "foo=bar&amp;baz=qux" using StringEntity and body().</jc>
    *    <jv>client</jv>
    *       .formPost(<jsf>URI</jsf>)
    *       .content(<jk>new</jk> StringEntity(<js>"foo=bar&amp;baz=qux"</js>,<js>"application/x-www-form-urlencoded"</js>))
    *       .run();
    * </p>
    *
    * @param value The parameter value.
    *    <br>Can be any of the following types:
    *    <ul class='spaced-list'>
    *       <li>
    *          {@link CharSequence}
    *       <li>
    *          {@link Reader} - Raw contents of {@code Reader} will be serialized to remote resource.
    *       <li>
    *          {@link InputStream} - Raw contents of {@code InputStream} will be serialized to remote resource.
    *       <li>
    *          {@link HttpResource} - Raw contents will be serialized to remote resource.  Additional headers and media type will be set on request.
    *       <li>
    *          {@link HttpEntity}/{@link BasicHttpEntity} - Bypass Juneau serialization and pass HttpEntity directly to HttpClient.
    *       <li>
    *          {@link Object} - POJO to be converted to text using the {@link Serializer} registered with the
    *          {@link RestClient}.
    *       <li>
    *          {@link PartList} - Converted to a URL-encoded FORM post.
    *    </ul>
    *    <br>Can be <jk>null</jk> (no body will be sent).
    * @return This object.
    */
   public RestRequest formDataCustom(Object value) {
      header(ContentType.APPLICATION_FORM_URLENCODED);
      content(value instanceof CharSequence ? new StringReader(value.toString()) : value);
      return this;
   }

   /**
    * Adds form-data parameters to the request body using free-form key/value pairs.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    <jc>// Creates form data "key1=val1&amp;key2=val2".</jc>
    *    <jv>client</jv>
    *       .formPost(<jsf>URI</jsf>)
    *       .formDataPairs(<js>"key1"</js>,<js>"val1"</js>,<js>"key2"</js>,<js>"val2"</js>)
    *       .run();
    * </p>
    *
    * @param pairs The form-data key/value pairs.
    *    <ul>
    *       <li>Values can be any POJO.
    *       <li>Values converted to a string using the configured part serializer.
    *    </ul>
    *    <br>Cannot be <jk>null</jk>.
    *    <br>Must have an even number of elements (key/value pairs).
    *    <br>Null keys are ignored (parameter will not be created).
    *    <br>Null values are allowed.
    * @return This object.
    * @throws RestCallException Invalid input.
    */
   public RestRequest formDataPairs(String...pairs) throws RestCallException {
      req(pairs.length % 2 == 0, "Odd number of parameters passed into formDataPairs(String...)");
      var b = formData;
      for (var i = 0; i < pairs.length; i += 2)
         b.append(pairs[i], pairs[i + 1]);
      return this;
   }

   /**
    * Returns all the headers of this message.
    *
    * Headers are ordered in the sequence they will be sent over a connection.
    *
    * @return All the headers of this message
    */
   @Override /* Overridden from HttpMessage */
   public Header[] getAllHeaders() { return headerData.getAll(); }

   /**
    * Returns the actual request configuration.
    *
    * @return The actual request configuration.
    */
   @Override /* Overridden from Configurable */
   public RequestConfig getConfig() { return request.getConfig(); }

   /**
    * Returns the first header with a specified name of this message.
    *
    * Header values are ignored.
    * <br>If there is more than one matching header in the message the first element of {@link #getHeaders(String)} is returned.
    * <br>If there is no matching header in the message <jk>null</jk> is returned.
    *
    * @param name The name of the header to return.
    *    <br>Cannot be <jk>null</jk>.
    * @return The first header whose name property equals name or <jk>null</jk> if no such header could be found.
    */
   @Override /* Overridden from HttpMessage */
   public Header getFirstHeader(String name) {
      return headerData.getFirst(name).orElse(null);
   }

   /**
    * Returns the form data for the request.
    *
    * @return An immutable list of form data to send on the request.
    */
   public PartList getFormData() { return formData; }

   /**
    * Returns the header data for the request.
    *
    * @return An immutable list of headers to send on the request.
    */
   public HeaderList getHeaders() { return headerData; }

   /**
    * Returns all the headers with a specified name of this message.
    *
    * Header values are ignored.
    * <br>Headers are ordered in the sequence they will be sent over a connection.
    *
    * @param name The name of the headers to return.
    *    <br>Cannot be <jk>null</jk>.
    * @return The headers whose name property equals name.
    */
   @Override /* Overridden from HttpMessage */
   public Header[] getHeaders(String name) {
      return headerData.getAll(name);
   }

   /**
    * Returns the body of this request.
    *
    * @return The body of this request, or <jk>null</jk> if it doesn't have a body.
    */
   public HttpEntity getHttpEntity() { return hasHttpEntity() ? ((HttpEntityEnclosingRequestBase)request).getEntity() : null; }

   /**
    * Returns the last header with a specified name of this message.
    *
    * Header values are ignored.
    * <br>If there is more than one matching header in the message the last element of {@link #getHeaders(String)} is returned.
    * <br>If there is no matching header in the message, <jk>null</jk> is returned.
    *
    * @param name The name of the header to return.
    *    <br>Cannot be <jk>null</jk>.
    * @return The last header whose name property equals name or <jk>null</jk> if no such header could be found.
    */
   @Override /* Overridden from HttpMessage */
   public Header getLastHeader(String name) {
      return headerData.getLast(name).orElse(null);
   }

   /**
    * Returns the HTTP method this request uses, such as GET, PUT, POST, or other.
    *
    * @return The HTTP method this request uses, such as GET, PUT, POST, or other.
    */
   @Override /* Overridden from HttpUriRequest */
   public String getMethod() { return request.getMethod(); }

   /**
    * Returns the parameters effective for this message as set by {@link #setParams(HttpParams)}.
    *
    * @return The parameters effective for this message as set by {@link #setParams(HttpParams)}.
    * @deprecated Use constructor parameters of configuration API provided by HttpClient.
    */
   @Override /* Overridden from HttpMessage */
   @Deprecated(since = "10.0", forRemoval = true)
   public HttpParams getParams() { return request.getParams(); }

   /**
    * Returns the path data for the request.
    *
    * @return An immutable list of path data to send on the request.
    */
   public PartList getPathData() { return pathData; }

   /**
    * Returns the protocol version this message is compatible with.
    *
    * @return The protocol version.
    */
   @Override /* Overridden from HttpMessage */
   public ProtocolVersion getProtocolVersion() { return request.getProtocolVersion(); }

   /**
    * Returns the query data for the request.
    *
    * @return An immutable list of query data to send on the request.
    */
   public PartList getQueryData() { return queryData; }

   /**
    * Returns the request line of this request.
    *
    * @return The request line.
    */
   @Override /* Overridden from HttpRequest */
   public RequestLine getRequestLine() { return request.getRequestLine(); }

   /**
    * A shortcut for calling <c>run().getContent().as(<js>type</js>)</c>.
    *
    * @param type The object type to create.
    *    <br>Cannot be <jk>null</jk>.
    * @param <T> The object type to create.
    * @see ResponseContent#as(Class)
    * @return The response content as a simple string.
    * @throws RestCallException If an exception or non-200 response code occurred during the connection attempt.
    */
   public <T> T getResponse(Class<T> type) throws RestCallException {
      return run().getContent().as(type);
   }

   /**
    * A shortcut for calling <c>run().getContent().as(<js>type</js>,<js>args</js>)</c>.
    *
    * @param <T>
    *    The object type to create.
    * @param type
    *    The object type to create.
    *    <br>Can be any of the following: {@link ClassMeta}, {@link Class}, {@link ParameterizedType}, {@link GenericArrayType}
    *    <br>Cannot be <jk>null</jk>.
    * @param args
    *    The type arguments of the class if it's a collection or map.
    *    <br>Can be any of the following: {@link ClassMeta}, {@link Class}, {@link ParameterizedType}, {@link GenericArrayType}
    *    <br>Ignored if the main type is not a map or collection.
    *    <br>Can contain <jk>null</jk> values (ignored).
    * @see ResponseContent#as(Type,Type...)
    * @return The response content as a simple string.
    * @throws RestCallException If an exception or non-200 response code occurred during the connection attempt.
    */
   public <T> T getResponse(Type type, Type...args) throws RestCallException {
      return run().getContent().as(type, args);
   }

   /**
    * A shortcut for calling <c>run().getContent().asString()</c>.
    *
    * @return The response content as a simple string.
    * @throws RestCallException If an exception or non-200 response code occurred during the connection attempt.
    */
   public String getResponseAsString() throws RestCallException { return run().getContent().asString(); }

   /**
    * Returns the original request URI.
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>URI remains unchanged in the course of request execution and is not updated if the request is redirected to another location.
    * </ul>
    *
    * @return The original request URI.
    */
   @Override /* Overridden from HttpUriRequest */
   public URI getURI() { return request.getURI(); }

   /**
    * Returns <jk>true</jk> if this request has a body.
    *
    * @return <jk>true</jk> if this request has a body.
    */
   public boolean hasHttpEntity() {
      return request instanceof HttpEntityEnclosingRequestBase;
   }

   /**
    * Appends a header to the request.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    <jc>// Adds header "Foo: bar".</jc>
    *    <jv>client</jv>
    *       .get(<jsf>URI</jsf>)
    *       .header(Accept.<jsf>TEXT_XML</jsf>)
    *       .run();
    * </p>
    *
    * @param part
    *    The parameter to set.
    *    <jk>null</jk> values are ignored.
    * @return This object.
    */
   public RestRequest header(Header part) {
      return headers(part);
   }

   /**
    * Appends a header to the request.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    <jc>// Adds header "Foo: bar".</jc>
    *    <jv>client</jv>
    *       .get(<jsf>URI</jsf>)
    *       .header(<js>"Foo"</js>, <js>"bar"</js>)
    *       .run();
    * </p>
    *
    * @param name
    *    The parameter name.
    * @param value
    *    The parameter value.
    *    <br>Non-string values are converted to strings using the {@link HttpPartSerializer} defined on the client.
    * @return This object.
    */
   public RestRequest header(String name, Object value) {
      headerData.append(createHeader(name, value));
      return this;
   }

   /**
    * Returns an iterator of all the headers.
    *
    * @return Iterator that returns {@link Header} objects in the sequence they are sent over a connection.
    */
   @Override /* Overridden from HttpMessage */
   public HeaderIterator headerIterator() {
      return headerData.headerIterator();
   }

   /**
    * Returns an iterator of the headers with a given name.
    *
    * @param name the name of the headers over which to iterate, or <jk>null</jk> for all headers.
    * @return Iterator that returns {@link Header} objects with the argument name in the sequence they are sent over a connection.
    */
   @Override /* Overridden from HttpMessage */
   public HeaderIterator headerIterator(String name) {
      return headerData.headerIterator(name);
   }

   /**
    * Appends multiple headers to the request using freeform key/value pairs.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    <jc>// Adds headers "Foo: bar" and "Baz: qux".</jc>
    *    <jv>client</jv>
    *       .get(<jsf>URI</jsf>)
    *       .headerPairs(<js>"Foo"</js>,<js>"bar"</js>,<js>"Baz"</js>,<js>"qux"</js>)
    *       .run();
    * </p>
    *
    * @param pairs The header key/value pairs.
    *    <br>Cannot be <jk>null</jk>.
    *    <br>Must have an even number of elements (key/value pairs).
    *    <br>Null keys are ignored (header will not be created).
    *    <br>Null values are allowed.
    * @return This object.
    */
   public RestRequest headerPairs(String...pairs) {
      req(pairs.length % 2 == 0, "Odd number of parameters passed into headerPairs(String...)");
      var b = headerData;
      for (var i = 0; i < pairs.length; i += 2)
         b.append(pairs[i], pairs[i + 1]);
      return this;
   }

   /**
    * Appends multiple headers to the request.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    <jc>// Appends two headers to the request.</jc>
    *    <jv>client</jv>
    *       .get(<jsf>URI</jsf>)
    *       .headers(
    *          BasicHeader.<jsm>of</jsm>(<js>"Foo"</js>, <js>"bar"</js>),
    *          Accept.<jsf>TEXT_XML</jsf>
    *       )
    *       .run();
    * </p>
    *
    * @param parts
    *    The parameters to set.
    *    <jk>null</jk> values are ignored.
    * @return This object.
    */
   public RestRequest headers(Header...parts) {
      headerData.append(parts);
      return this;
   }

   /**
    * Appends multiple headers to the request from properties defined on a Java bean.
    *
    * <p>
    * Uses {@link PropertyNamerDUCS} for resolving the header names from property names.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    <ja>@Marshalled</ja>
    *    <jk>public class</jk> MyHeaders {
    *       <jk>public</jk> String getFooBar() { <jk>return</jk> <js>"baz"</js>; }
    *       <jk>public</jk> Integer getQux() { <jk>return</jk> 123; }
    *    }
    *
    *    <jc>// Appends headers "Foo-Bar: baz" and "Qux: 123".</jc>
    *    <jv>client</jv>
    *       .get(<jsf>URI</jsf>)
    *       .headersBean(<jk>new</jk> MyHeaders())
    *       .run();
    * </p>
    *
    * @param value The bean containing the properties to set as header values.
    *    <br>Cannot be <jk>null</jk>.
    * @return This object.
    */
   public RestRequest headersBean(Object value) {
      req(isBean(reqnn("value", value)), "Object passed into headersBean(Object) is not a bean.");
      var b = headerData;
      toBeanMap(value, PropertyNamerDUCS.INSTANCE).forEach((k, v) -> b.append(createHeader(k, v)));
      return this;
   }

   /**
    * Convenience method for specifying HTML as the marshalling transmission media type for this request only.
    *
    * <p>
    * POJOs are converted to HTML without any sort of doc wrappers.
    *
    * <p>
    *    {@link HtmlSerializer} will be used to serialize POJOs to request bodies unless overridden per request via {@link RestRequest#serializer(Serializer)}.
    *    <ul>
    *       <li>The serializer can be configured using any of the serializer property setters (e.g. {@link RestClient.Builder#sortCollections()}) or
    *          bean context property setters (e.g. {@link RestClient.Builder#swaps(Class...)}) defined on this builder class.
    *    </ul>
    * <p>
    *    {@link HtmlParser} will be used to parse POJOs from response bodies unless overridden per request via {@link RestRequest#parser(Parser)}.
    *    <ul>
    *       <li>The parser can be configured using any of the parser property setters (e.g. {@link RestClient.Builder#ignoreUnknownBeanProperties()}) or
    *          bean context property setters (e.g. {@link RestClient.Builder#swaps(Class...)}) defined on this builder class.
    *    </ul>
    * <p>
    *    <c>Accept</c> request header will be set to <js>"text/html"</js> unless overridden
    *       by {@link RestRequest#header(String,Object)} or {@link RestRequest#accept(String)}.
    * <p>
    *    <c>Content-Type</c> request header will be set to <js>"text/html"</js> unless overridden
    *       by {@link RestRequest#header(String,Object)} or {@link RestRequest#contentType(String)}.
    * <p>
    *    Identical to calling <c>serializer(HtmlSerializer.<jk>class</jk>).parser(HtmlParser.<jk>class</jk>)</c>.
    *
    * @return This object.
    */
   public RestRequest html() {
      return serializer(HtmlSerializer.class).parser(HtmlParser.class);
   }

   /**
    * Convenience method for specifying HTML DOC as the marshalling transmission media type for this request only.
    *
    * <p>
    * POJOs are converted to fully renderable HTML pages.
    *
    * <p>
    *    {@link HtmlDocSerializer} will be used to serialize POJOs to request bodies unless overridden per request via {@link RestRequest#serializer(Serializer)}.
    *    <ul>
    *       <li>The serializer can be configured using any of the serializer property setters (e.g. {@link RestClient.Builder#sortCollections()}) or
    *          bean context property setters (e.g. {@link RestClient.Builder#swaps(Class...)}) defined on this builder class.
    *    </ul>
    * <p>
    *    {@link HtmlParser} will be used to parse POJOs from response bodies unless overridden per request via {@link RestRequest#parser(Parser)}.
    *    <ul>
    *       <li>The parser can be configured using any of the parser property setters (e.g. {@link RestClient.Builder#ignoreUnknownBeanProperties()}) or
    *          bean context property setters (e.g. {@link RestClient.Builder#swaps(Class...)}) defined on this builder class.
    *    </ul>
    * <p>
    *    <c>Accept</c> request header will be set to <js>"text/html"</js> unless overridden
    *       by {@link RestRequest#header(String,Object)} or {@link RestRequest#accept(String)}.
    * <p>
    *    <c>Content-Type</c> request header will be set to <js>"text/html"</js> unless overridden
    *       by {@link RestRequest#header(String,Object)} or {@link RestRequest#contentType(String)}.
    * <p>
    *    Identical to calling <c>serializer(HtmlDocSerializer.<jk>class</jk>).parser(HtmlParser.<jk>class</jk>)</c>.
    *
    * @return This object.
    */
   public RestRequest htmlDoc() {
      return serializer(HtmlDocSerializer.class).parser(HtmlParser.class);
   }

   /**
    * Convenience method for specifying Stripped HTML DOC as the marshalling transmission media type for this request only.
    *
    * <p>
    * Same as {@link #htmlDoc()} but without the header and body tags and page title and description.
    *
    * <p>
    *    {@link HtmlStrippedDocSerializer} will be used to serialize POJOs to request bodies unless overridden per request via {@link RestRequest#serializer(Serializer)}.
    *    <ul>
    *       <li>The serializer can be configured using any of the serializer property setters (e.g. {@link RestClient.Builder#sortCollections()}) or
    *          bean context property setters (e.g. {@link RestClient.Builder#swaps(Class...)}) defined on this builder class.
    *    </ul>
    * <p>
    *    {@link HtmlParser} will be used to parse POJOs from response bodies unless overridden per request via {@link RestRequest#parser(Parser)}.
    *    <ul>
    *       <li>The parser can be configured using any of the parser property setters (e.g. {@link RestClient.Builder#ignoreUnknownBeanProperties()}) or
    *          bean context property setters (e.g. {@link RestClient.Builder#swaps(Class...)}) defined on this builder class.
    *    </ul>
    * <p>
    *    <c>Accept</c> request header will be set to <js>"text/html+stripped"</js> unless overridden
    *       by {@link RestRequest#header(String,Object)} or {@link RestRequest#accept(String)}.
    * <p>
    *    <c>Content-Type</c> request header will be set to <js>"text/html+stripped"</js> unless overridden
    *       by {@link RestRequest#header(String,Object)} or {@link RestRequest#contentType(String)}.
    * <p>
    *    Identical to calling <c>serializer(HtmlStrippedDocSerializer.<jk>class</jk>).parser(HtmlParser.<jk>class</jk>)</c>.
    *
    * @return This object.
    */
   public RestRequest htmlStrippedDoc() {
      return serializer(HtmlStrippedDocSerializer.class).parser(HtmlParser.class);
   }

   /**
    * Prevent {@link RestCallException RestCallExceptions} from being thrown when HTTP status 400+ is encountered.
    *
    * <p>
    * This overrides the <l>ignoreErrors</l> property on the client.
    *
    * @return This object.
    */
   public RestRequest ignoreErrors() {
      this.ignoreErrors = true;
      return this;
   }

   /**
    * Add one or more interceptors for this call only.
    *
    * @param interceptors The interceptors to add to this call.
    *    <br>Cannot contain <jk>null</jk> values.
    * @return This object.
    * @throws RestCallException If init method on interceptor threw an exception.
    */
   public RestRequest interceptors(RestCallInterceptor...interceptors) throws RestCallException {
      reqnns("interceptors", interceptors);
      try {
         for (var i : interceptors) {
            this.interceptors.add(i);
            i.onInit(this);
         }
      } catch (RuntimeException | RestCallException e) {
         throw e;
      } catch (Exception e) {
         throw new RestCallException(null, e, "Interceptor threw an exception on init.");
      }

      return this;
   }

   @Override /* Overridden from HttpUriRequest */
   public boolean isAborted() { return request.isAborted(); }

   /**
    * Returns <jk>true</jk> if debug mode is currently enabled.
    */
   @Override
   public boolean isDebug() { return headerData.get("Debug", Boolean.class).orElse(false); }

   /**
    * Convenience method for specifying JSON as the marshalling transmission media type for this request only.
    *
    * <p>
    * {@link JsonSerializer} will be used to serialize POJOs to request bodies unless overridden per request via {@link RestRequest#serializer(Serializer)}.
    *    <ul>
    *       <li>The serializer can be configured using any of the serializer property setters (e.g. {@link RestClient.Builder#sortCollections()}) or
    *          bean context property setters (e.g. {@link RestClient.Builder#swaps(Class...)}) defined on this builder class.
    *    </ul>
    * <p>
    *    {@link JsonParser} will be used to parse POJOs from response bodies unless overridden per request via {@link RestRequest#parser(Parser)}.
    *    <ul>
    *       <li>The parser can be configured using any of the parser property setters (e.g. {@link RestClient.Builder#ignoreUnknownBeanProperties()}) or
    *          bean context property setters (e.g. {@link RestClient.Builder#swaps(Class...)}) defined on this builder class.
    *    </ul>
    * <p>
    *    <c>Accept</c> request header will be set to <js>"application/json"</js> unless overridden
    *       by {@link RestRequest#header(String,Object)} or {@link RestRequest#accept(String)}.
    * <p>
    *    <c>Content-Type</c> request header will be set to <js>"application/json"</js> unless overridden
    *       {@link RestRequest#header(String,Object)} or {@link RestRequest#contentType(String)}.
    * <p>
    *    Identical to calling <c>serializer(JsonSerializer.<jk>class</jk>).parser(JsonParser.<jk>class</jk>)</c>.
    *
    * @return This object.
    */
   public RestRequest json() {
      return serializer(JsonSerializer.class).parser(JsonParser.class);
   }

   /**
    * Convenience method for specifying Simplified JSON as the marshalling transmission media type for this request only.
    *
    * <p>
    * Simplified JSON is typically useful for automated tests because you can do simple string comparison of results
    * without having to escape lots of quotes.
    *
    * <p>
    *    {@link Json5Serializer} will be used to serialize POJOs to request bodies unless overridden per request via {@link RestRequest#serializer(Serializer)}.
    *    <ul>
    *       <li>The serializer can be configured using any of the serializer property setters (e.g. {@link RestClient.Builder#sortCollections()}) or
    *          bean context property setters (e.g. {@link RestClient.Builder#swaps(Class...)}) defined on this builder class.
    *    </ul>
    * <p>
    *    {@link Json5Parser} will be used to parse POJOs from response bodies unless overridden per request via {@link RestRequest#parser(Parser)}.
    *    <ul>
    *       <li>The parser can be configured using any of the parser property setters (e.g. {@link RestClient.Builder#ignoreUnknownBeanProperties()}) or
    *          bean context property setters (e.g. {@link RestClient.Builder#swaps(Class...)}) defined on this builder class.
    *    </ul>
    * <p>
    *    <c>Accept</c> request header will be set to <js>"application/json5"</js> unless overridden
    *       by {@link #header(String,Object)} or {@link #accept(String)}, or per-request via {@link RestRequest#header(String,Object)} or {@link RestRequest#accept(String)}.
    * <p>
    *    <c>Content-Type</c> request header will be set to <js>"application/json5"</js> unless overridden
    *       by {@link #header(String,Object)} or {@link #contentType(String)}, or per-request via {@link RestRequest#header(String,Object)} or {@link RestRequest#contentType(String)}.
    * <p>
    *    A server that only handles JSON may reply <c>406 Not Acceptable</c> or <c>415 Unsupported Media Type</c> to these
    *    JSON5 media types.
    * <p>
    *    Can be combined with other marshaller setters such as {@link #xml()} to provide support for multiple languages.
    *    <ul>
    *       <li>When multiple languages are supported, the <c>Accept</c> and <c>Content-Type</c> headers control which marshallers are used, or uses the
    *       last-enabled language if the headers are not set.
    *    </ul>
    * <p>
    *    Identical to calling <c>serializer(Json5Serializer.<jk>class</jk>).parser(Json5Parser.<jk>class</jk>)</c>.
    *
    * @return This object.
    */
   public RestRequest json5() {
      return serializer(Json5Serializer.class).parser(Json5Parser.class);
   }

   /**
    * Convenience method for specifying JCS (JSON Canonicalization Scheme, RFC 8785) as the marshalling transmission media type for this request only.
    *
    * <p>
    *    {@link JcsSerializer} will be used to serialize POJOs to request bodies.
    *    {@link JsonParser} will be used to parse POJOs from response bodies (JCS output is valid JSON).
    * <p>
    *    <c>Accept</c> and <c>Content-Type</c> will be set to <js>"application/jcs+json"</js>.
    * <p>
    *    Identical to calling <c>serializer(JcsSerializer.<jk>class</jk>).parser(JsonParser.<jk>class</jk>)</c>.
    *
    * @return This object.
    */
   public RestRequest jcs() {
      return serializer(JcsSerializer.class).parser(JsonParser.class);
   }

   /**
    * Logs a message.
    *
    * @param level The log level.
    *    <br>Cannot be <jk>null</jk>.
    * @param msg The message with {@link String#format(String, Object...) String.format}-style (<c>%s</c>) arguments.
    *    <br>Cannot be <jk>null</jk>.
    * @param args The arguments.
    *    <br>Can contain <jk>null</jk> values.
    * @return This object.
    */
   public RestRequest log(Level level, String msg, Object...args) {
      client.log(level, msg, args);
      return this;
   }

   /**
    * Logs a message.
    *
    * @param level The log level.
    *    <br>Cannot be <jk>null</jk>.
    * @param t The throwable cause.
    *    <br>Can be <jk>null</jk> (no exception details are logged).
    * @param msg The message with {@link String#format(String, Object...) String.format}-style (<c>%s</c>) arguments.
    *    <br>Cannot be <jk>null</jk>.
    * @param args The arguments.
    *    <br>Can contain <jk>null</jk> values.
    * @return This object.
    */
   public RestRequest log(Level level, Throwable t, String msg, Object...args) {
      client.log(level, t, msg, args);
      return this;
   }

   /**
    * Shortcut for setting the <c>Accept</c> and <c>Content-Type</c> headers on a request.
    *
    * @param value The new header values.
    *    <br>Can be <jk>null</jk> (headers will not be set).
    * @return This object.
    * @throws RestCallException Invalid input.
    */
   public RestRequest mediaType(String value) throws RestCallException {
      return header(Accept.of(value)).header(ContentType.of(value));
   }

   /**
    * Convenience method for specifying BSON as the marshalling transmission media type for this request only.
    *
    * <p>
    * Identical to calling <c>serializer(BsonSerializer.<jk>class</jk>).parser(BsonParser.<jk>class</jk>)</c>.
    *
    * @return This object.
    */
   public RestRequest bson() {
      return serializer(BsonSerializer.class).parser(BsonParser.class);
   }

   /**
    * Convenience method for specifying MessagePack as the marshalling transmission media type for this request only.
    *
    * <p>
    * MessagePack is a binary equivalent to JSON that takes up considerably less space than JSON.
    *
    * <p>
    *    {@link MsgPackSerializer} will be used to serialize POJOs to request bodies unless overridden per request via {@link RestRequest#serializer(Serializer)}.
    *    <ul>
    *       <li>The serializer can be configured using any of the serializer property setters (e.g. {@link RestClient.Builder#sortCollections()}) or
    *          bean context property setters (e.g. {@link RestClient.Builder#swaps(Class...)}) defined on this builder class.
    *    </ul>
    * <p>
    *    {@link MsgPackParser} will be used to parse POJOs from response bodies unless overridden per request via {@link RestRequest#parser(Parser)}.
    *    <ul>
    *       <li>The parser can be configured using any of the parser property setters (e.g. {@link RestClient.Builder#ignoreUnknownBeanProperties()}) or
    *          bean context property setters (e.g. {@link RestClient.Builder#swaps(Class...)}) defined on this builder class.
    *    </ul>
    * <p>
    *    <c>Accept</c> request header will be set to <js>"application/msgpack"</js> unless overridden
    *       by {@link RestRequest#header(String,Object)} or {@link RestRequest#accept(String)}.
    * <p>
    *    <c>Content-Type</c> request header will be set to <js>"application/msgpack"</js> unless overridden
    *       by {@link RestRequest#header(String,Object)} or {@link RestRequest#contentType(String)}.
    * <p>
    *    Identical to calling <c>serializer(MsgPackSerializer.<jk>class</jk>).parser(MsgPackParser.<jk>class</jk>)</c>.
    *
    * @return This object.
    */
   public RestRequest msgPack() {
      return serializer(MsgPackSerializer.class).parser(MsgPackParser.class);
   }

   /**
    * When called, <c>No-Trace: true</c> is added to requests.
    *
    * <p>
    * This gives the opportunity for the servlet to not log errors on invalid requests.
    * This is useful for testing purposes when you don't want your log file to show lots of errors that are simply the
    * results of testing.
    *
    * @return This object.
    * @throws RestCallException Invalid input.
    */
   public RestRequest noTrace() throws RestCallException {
      return header(NoTrace.TRUE);
   }

   /**
    * Convenience method for specifying OpenAPI as the marshalling transmission media type for this request only.
    *
    * <p>
    * OpenAPI is a language that allows serialization to formats that use {@link HttpPartSchema} objects to describe their structure.
    *
    * <p>
    *    {@link OpenApiSerializer} will be used to serialize POJOs to request bodies unless overridden per request via {@link RestRequest#serializer(Serializer)}.
    *    <ul>
    *       <li>The serializer can be configured using any of the serializer property setters (e.g. {@link RestClient.Builder#sortCollections()}) or
    *          bean context property setters (e.g. {@link RestClient.Builder#swaps(Class...)}) defined on this builder class.
    *       <li>Typically the {@link RestRequest#content(Object, HttpPartSchema)} method will be used to specify the body of the request with the
    *          schema describing it's structure.
    *    </ul>
    * <p>
    *    {@link OpenApiParser} will be used to parse POJOs from response bodies unless overridden per request via {@link RestRequest#parser(Parser)}.
    *    <ul>
    *       <li>The parser can be configured using any of the parser property setters (e.g. {@link RestClient.Builder#ignoreUnknownBeanProperties()}) or
    *          bean context property setters (e.g. {@link RestClient.Builder#swaps(Class...)}) defined on this builder class.
    *       <li>Typically the {@link ResponseContent#schema(HttpPartSchema)} method will be used to specify the structure of the response body.
    *    </ul>
    * <p>
    *    <c>Accept</c> request header will be set to <js>"text/openapi"</js> unless overridden
    *       by {@link RestRequest#header(String,Object)} or {@link RestRequest#accept(String)}.
    * <p>
    *    <c>Content-Type</c> request header will be set to <js>"text/openapi"</js> unless overridden
    *       by {@link RestRequest#header(String,Object)} or {@link RestRequest#contentType(String)}.
    * <p>
    *    Identical to calling <c>serializer(OpenApiSerializer.<jk>class</jk>).parser(OpenApiParser.<jk>class</jk>)</c>.
    *
    * @return This object.
    */
   public RestRequest openApi() {
      return serializer(OpenApiSerializer.class).parser(OpenApiParser.class);
   }

   /**
    * Specifies the parser to use on the response body.
    *
    * <p>
    * Overrides the parsers specified on the {@link RestClient}.
    *
    * <p>
    *    The parser can be configured using any of the parser property setters (e.g. {@link RestClient.Builder#ignoreUnknownBeanProperties()}) or
    *    bean context property setters (e.g. {@link RestClient.Builder#swaps(Class...)}) defined on this builder class.
    *
    * <p>
    * If the <c>Accept</c> header is not set on the request, it will be set to the media type of this parser.
    *
    * @param parser The parser used to parse POJOs from the body of the HTTP response.
    *    <br>Cannot be <jk>null</jk>.
    * @return This object.
    */
   public RestRequest parser(Class<? extends Parser> parser) {
      this.parser = client.getInstance(reqnn("parser", parser));
      return this;
   }

   /**
    * Specifies the parser to use on the response body.
    *
    * <p>
    * Overrides the parsers specified on the {@link RestClient}.
    *
    * <p>
    *    The parser is not modified by any of the parser property setters (e.g. {@link RestClient.Builder#ignoreUnknownBeanProperties()}) or
    *    bean context property setters (e.g. {@link RestClient.Builder#swaps(Class...)}) defined on this builder class.
    *
    * <p>
    * If the <c>Accept</c> header is not set on the request, it will be set to the media type of this parser.
    *
    * @param parser The parser used to parse POJOs from the body of the HTTP response.
    *    <br>Cannot be <jk>null</jk>.
    * @return This object.
    */
   public RestRequest parser(Parser parser) {
      this.parser = reqnn("parser", parser);
      return this;
   }

   /**
    * Sets or replaces multiple path parameters on the request.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    <jc>// Appends two path parameters to the request.</jc>
    *    <jv>client</jv>
    *       .get(<jsf>URI</jsf>)
    *       .pathData(
    *          BasicStringPart.<jsm>of</jsm>(<js>"foo"</js>, <js>"bar"</js>),
    *          BasicBooleanPart.<jsm>of</jsm>(<js>"baz"</js>, <jk>true</jk>)
    *       )
    *       .run();
    * </p>
    *
    * @param parts
    *    The parameters to set.
    *    <jk>null</jk> values are ignored.
    * @return This object.
    */
   public RestRequest pathData(NameValuePair...parts) {
      pathData.set(parts);
      return this;
   }

   /**
    * Sets or replaces a path parameter of the form <js>"{name}"</js> in the URI.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    <jc>// Sets path to "/bar".</jc>
    *    <jv>client</jv>
    *       .get(<js>"/{foo}"</js>)
    *       .pathData(<js>"foo"</js>, <js>"bar"</js>)
    *       .run();
    * </p>
    *
    * @param name
    *    The parameter name.
    *    <br>Cannot be <jk>null</jk> or empty (parameter will not be created).
    * @param value
    *    The parameter value.
    *    <br>Non-string values are converted to strings using the {@link HttpPartSerializer} defined on the client.
    *    <br>Can be <jk>null</jk>.
    * @return This object.
    */
   public RestRequest pathData(String name, Object value) {
      pathData.set(createPart(PATH, name, value));
      return this;
   }

   /**
    * Sets multiple path parameters to the request from properties defined on a Java bean.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    <jk>public class</jk> MyPathVars {
    *       <jk>public</jk> String getFooBar() { <jk>return</jk> <js>"baz"</js>; }
    *       <jk>public</jk> Integer getQux() { <jk>return</jk> 123; }
    *    }
    *
    *    <jc>// Given path "/{fooBar}/{qux}/", gets converted to "/baz/123/".</jc>
    *    <jv>client</jv>
    *       .get(<jsf>URI</jsf>)
    *       .pathDataBean(<jk>new</jk> MyPathVars())
    *       .run();
    * </p>
    *
    * @param value The bean containing the properties to set as path parameter values.
    *    <br>Cannot be <jk>null</jk>.
    * @return This object.
    */
   public RestRequest pathDataBean(Object value) {
      req(isBean(reqnn("value", value)), "Object passed into pathDataBean(Object) is not a bean.");
      var b = pathData;
      toBeanMap(value).forEach((k, v) -> b.set(createPart(PATH, k, v)));
      return this;
   }

   /**
    * Replaces path parameters of the form <js>"{name}"</js> in the URI using free-form key/value pairs.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    <jc>// Sets path to "/baz/qux".</jc>
    *    <jv>client</jv>
    *       .get(<js>"/{foo}/{bar}"</js>)
    *       .pathDataPairs(
    *          <js>"foo"</js>,<js>"baz"</js>,
    *          <js>"bar"</js>,<js>"qux"</js>
    *       )
    *       .run();
    * </p>
    *
    * @param pairs The path key/value pairs.
    *    <ul>
    *       <li>Values can be any POJO.
    *       <li>Values converted to a string using the configured part serializer.
    *    </ul>
    *    <br>Cannot be <jk>null</jk>.
    *    <br>Must have an even number of elements (key/value pairs).
    *    <br>Null keys are ignored (parameter will not be created).
    *    <br>Null values are allowed.
    * @return This object.
    */
   public RestRequest pathDataPairs(String...pairs) {
      req(pairs.length % 2 == 0, "Odd number of parameters passed into pathDataPairs(String...)");
      var b = pathData;
      for (var i = 0; i < pairs.length; i += 2)
         b.set(pairs[i], pairs[i + 1]);
      return this;
   }

   /**
    * Convenience method for specifying Plain Text as the marshalling transmission media type for this request only.
    *
    * <p>
    * Plain text marshalling typically only works on simple POJOs that can be converted to and from strings using
    * swaps, swap methods, etc...
    *
    * <p>
    *    {@link PlainTextSerializer} will be used to serialize POJOs to request bodies unless overridden per request via {@link RestRequest#serializer(Serializer)}.
    *    <ul>
    *       <li>The serializer can be configured using any of the serializer property setters (e.g. {@link RestClient.Builder#sortCollections()}) or
    *          bean context property setters (e.g. {@link RestClient.Builder#swaps(Class...)}) defined on this builder class.
    *    </ul>
    * <p>
    *    {@link PlainTextParser} will be used to parse POJOs from response bodies unless overridden per request via {@link RestRequest#parser(Parser)}.
    *    <ul>
    *       <li>The parser can be configured using any of the parser property setters (e.g. {@link RestClient.Builder#ignoreUnknownBeanProperties()}) or
    *          bean context property setters (e.g. {@link RestClient.Builder#swaps(Class...)}) defined on this builder class.
    *    </ul>
    * <p>
    *    <c>Accept</c> request header will be set to <js>"text/plain"</js> unless overridden
    *       by {@link RestRequest#header(String,Object)} or {@link RestRequest#accept(String)}.
    * <p>
    *    <c>Content-Type</c> request header will be set to <js>"text/plain"</js> unless overridden
    *       by {@link RestRequest#header(String,Object)} or {@link RestRequest#contentType(String)}.
    * <p>
    *    Identical to calling <c>serializer(PlainTextSerializer.<jk>class</jk>).parser(PlainTextParser.<jk>class</jk>)</c>.
    *
    * @return This object.
    */
   public RestRequest plainText() {
      return serializer(PlainTextSerializer.class).parser(PlainTextParser.class);
   }

   /**
    * Sets the {@code X-Juneau-Serializer-Options} header for this request.
    *
    * <p>
    * The value is a JSON5 object whose keys are serializer session property names and values are the overrides.
    * Example: <js>"{escapeSolidus:true,maxIndent:4}"</js>.
    *
    * @param json5
    *    Serializer session options as JSON5. Can be <jk>null</jk> (header is not set).
    * @return This object.
    */
   public RestRequest serializerSessionOptionsHeader(String json5) {
      return header(HEADER_JuneauSerializerOptions, json5);
   }

   /**
    * Sets the {@code X-Juneau-Parser-Options} header for this request.
    *
    * <p>
    * The value is a JSON5 object whose keys are parser session property names and values are the overrides.
    *
    * @param json5
    *    Parser session options as JSON5. Can be <jk>null</jk> (header is not set).
    * @return This object.
    */
   public RestRequest parserSessionOptionsHeader(String json5) {
      return header(HEADER_JuneauParserOptions, json5);
   }

   /**
    * Convenience for {@link #serializerSessionOptionsHeader(String)} using a map serialized with {@link Json5#of(Object)}.
    *
    * @param properties
    *    Property map for serializer session options. Can be <jk>null</jk> (treated as empty).
    * @return This object.
    * @throws SerializeException If serializing {@code properties} to JSON5 fails.
    */
   public RestRequest serializerSessionOptionsHeader(Map<String,?> properties) {
      if (isEmpty(properties))
         return this;
      return header(HEADER_JuneauSerializerOptions, Json5.of(properties));
   }

   /**
    * Convenience for {@link #parserSessionOptionsHeader(String)} using a map serialized with {@link Json5#of(Object)}.
    *
    * @param properties
    *    Property map for parser session options. Can be <jk>null</jk> (treated as empty).
    * @return This object.
    * @throws SerializeException If serializing {@code properties} to JSON5 fails.
    */
   public RestRequest parserSessionOptionsHeader(Map<String,?> properties) {
      if (isEmpty(properties))
         return this;
      return header(HEADER_JuneauParserOptions, Json5.of(properties));
   }

   /**
    * Sets the {@code juneauSerializerOptions} query parameter for this request (UON-encoded map).
    *
    * <p>
    * Example: <js>"(escapeSolidus=true,maxIndent=4)"</js>.
    *
    * @param uon
    *    Serializer session options in UON form. Can be <jk>null</jk> (parameter is not set).
    * @return This object.
    */
   public RestRequest serializerSessionOptionsQuery(String uon) {
      return queryData(QUERY_juneauSerializerOptions, uon);
   }

   /**
    * Sets the {@code juneauParserOptions} query parameter for this request (UON-encoded map).
    *
    * @param uon
    *    Parser session options in UON form. Can be <jk>null</jk> (parameter is not set).
    * @return This object.
    */
   public RestRequest parserSessionOptionsQuery(String uon) {
      return queryData(QUERY_juneauParserOptions, uon);
   }

   /**
    * Convenience for {@link #serializerSessionOptionsQuery(String)} using {@link Uon#of(Object)}.
    *
    * @param properties
    *    Property map for serializer session options. Can be <jk>null</jk> (treated as empty).
    * @return This object.
    * @throws SerializeException If serializing {@code properties} to UON fails.
    */
   public RestRequest serializerSessionOptionsQuery(Map<String,?> properties) {
      if (isEmpty(properties))
         return this;
      return serializerSessionOptionsQuery(Uon.of(properties));
   }

   /**
    * Convenience for {@link #parserSessionOptionsQuery(String)} using {@link Uon#of(Object)}.
    *
    * @param properties
    *    Property map for parser session options. Can be <jk>null</jk> (treated as empty).
    * @return This object.
    * @throws SerializeException If serializing {@code properties} to UON fails.
    */
   public RestRequest parserSessionOptionsQuery(Map<String,?> properties) {
      if (isEmpty(properties))
         return this;
      return parserSessionOptionsQuery(Uon.of(properties));
   }

   /**
    * Sets the protocol version for this request.
    *
    * @param version The protocol version for this request.
    *    <br>Can be <jk>null</jk> (default protocol version will be used).
    * @return This object.
    */
   public RestRequest protocolVersion(ProtocolVersion version) {
      request.setProtocolVersion(version);
      return this;
   }

   /**
    * Adds a free-form custom query.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    <jc>// Adds query parameter "foo=bar&amp;baz=qux".</jc>
    *    <jv>client</jv>
    *       .get(<jsf>URI</jsf>)
    *       .queryCustom(<js>"foo=bar&amp;baz=qux"</js>)
    *       .run();
    * </p>
    *
    * @param value The parameter value.
    *    <br>Can be any of the following types:
    *    <ul>
    *       <li>
    *          {@link CharSequence}
    *       <li>
    *          {@link Reader} - Raw contents of {@code Reader} will be serialized to remote resource.
    *       <li>
    *          {@link InputStream} - Raw contents of {@code InputStream} will be serialized to remote resource.
    *       <li>
    *          {@link PartList} - Converted to a URL-encoded query.
    *    </ul>
    *    <br>Can be <jk>null</jk> (no custom query will be set).
    * @return This object.
    */
   public RestRequest queryCustom(Object value) {
      try {
         String q = null;
         if (value instanceof Reader value2)
            q = read(value2);
         else if (value instanceof InputStream value2)
            q = read(value2);
         else
            q = s(value);  // Works for NameValuePairs.
         uriBuilder.setCustomQuery(q);
      } catch (IOException e) {
         throw rex(e, "Could not read custom query.");
      }
      return this;
   }

   /**
    * Appends multiple query parameters to the request.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    <jc>// Appends two query parameters to the request.</jc>
    *    <jv>client</jv>
    *       .get(<jsf>URI</jsf>)
    *       .queryData(
    *          BasicStringPart.<jsm>of</jsm>(<js>"foo"</js>, <js>"bar"</js>),
    *          BasicBooleanPart.<jsm>of</jsm>(<js>"baz"</js>, <jk>true</jk>)
    *       )
    *       .run();
    * </p>
    *
    * @param parts
    *    The parameters to set.
    *    <jk>null</jk> values are ignored.
    * @return This object.
    */
   public RestRequest queryData(NameValuePair...parts) {
      queryData.append(parts);
      return this;
   }

   /**
    * Appends a query parameter to the URI of the request.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    <jc>// Adds query parameter "foo=bar".</jc>
    *    <jv>client</jv>
    *       .get(<jsf>URI</jsf>)
    *       .queryData(<js>"foo"</js>, <js>"bar"</js>)
    *       .run();
    * </p>
    *
    * @param name
    *    The parameter name.
    *    <br>Cannot be <jk>null</jk> or empty (parameter will not be created).
    * @param value
    *    The parameter value.
    *    <br>Non-string values are converted to strings using the {@link HttpPartSerializer} defined on the client.
    *    <br>Can be <jk>null</jk>.
    * @return This object.
    */
   public RestRequest queryData(String name, Object value) {
      queryData.append(createPart(QUERY, name, value));
      return this;
   }

   /**
    * Appends multiple query parameters to the request from properties defined on a Java bean.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    <jk>public class</jk> MyQuery {
    *       <jk>public</jk> String getFooBar() { <jk>return</jk> <js>"baz"</js>; }
    *       <jk>public</jk> Integer getQux() { <jk>return</jk> 123; }
    *    }
    *
    *    <jc>// Appends query "fooBar=baz&amp;qux=123".</jc>
    *    <jv>client</jv>
    *       .get(<jsf>URI</jsf>)
    *       .queryDataBean(<jk>new</jk> MyQuery())
    *       .run();
    * </p>
    *
    * @param value The bean containing the properties to set as query parameter values.
    *    <br>Cannot be <jk>null</jk>.
    * @return This object.
    */
   public RestRequest queryDataBean(Object value) {
      req(isBean(reqnn("value", value)), "Object passed into queryDataBean(Object) is not a bean.");
      var b = queryData;
      toBeanMap(value).forEach((k, v) -> b.append(createPart(QUERY, k, v)));
      return this;
   }

   /**
    * Adds query parameters to the URI query using free-form key/value pairs..
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    <jc>// Adds query parameters "foo=bar&amp;baz=qux".</jc>
    *    <jv>client</jv>
    *       .get(<jsf>URI</jsf>)
    *       .queryDataPairs(<js>"foo"</js>,<js>"bar"</js>,<js>"baz"</js>,<js>"qux"</js>)
    *       .run();
    * </p>
    *
    * @param pairs The query key/value pairs.
    *    <ul>
    *       <li>Values can be any POJO.
    *       <li>Values converted to a string using the configured part serializer.
    *    </ul>
    *    <br>Cannot be <jk>null</jk>.
    *    <br>Must have an even number of elements (key/value pairs).
    *    <br>Null keys are ignored (parameter will not be created).
    *    <br>Null values are allowed.
    * @return This object.
    * @throws RestCallException Invalid input.
    */
   public RestRequest queryDataPairs(String...pairs) throws RestCallException {
      req(pairs.length % 2 == 0, "Odd number of parameters passed into queryDataPairs(String...)");
      var b = queryData;
      for (var i = 0; i < pairs.length; i += 2)
         b.append(pairs[i], pairs[i + 1]);
      return this;
   }

   /**
    * Removes a header from this message.
    *
    * @param header The header to remove.
    *    <br>Can be <jk>null</jk> (no-op).
    */
   @Override /* Overridden from HttpMessage */
   public void removeHeader(Header header) {
      headerData.remove(header);
   }

   /**
    * Removes all headers with a certain name from this message.
    *
    * @param name The name of the headers to remove.
    *    <br>Cannot be <jk>null</jk>.
    */
   @Override /* Overridden from HttpMessage */
   public void removeHeaders(String name) {
      headerData.remove(name);
   }

   /**
    * Rethrow any of the specified exception types if a matching <c>Exception-Name</c> header is found.
    *
    * <p>
    * Rethrown exceptions will be set on the caused-by exception of {@link RestCallException} when
    * thrown from the {@link #run()} method.
    *
    * <p>
    * Can be called multiple times to append multiple rethrows.
    *
    * @param values The classes to rethrow.
    *    <br>Cannot be <jk>null</jk>.
    *    <br>Null elements are ignored (only non-null classes that extend {@link Throwable} are added).
    * @return This object.
    */
   public RestRequest rethrow(Class<?>...values) {
      if (rethrow == null)
         rethrow = list();
      for (var v : values) {
         if (nn(v) && Throwable.class.isAssignableFrom(v))
            rethrow.add((Class<? extends Throwable>)v);
      }
      return this;
   }

   /**
    * Runs this request and returns the resulting response object.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    <jk>try</jk> {
    *       <jk>int</jk> <jv>rc</jv> = <jv>client</jv>.get(<jsf>URI</jsf>).execute().getResponseStatus();
    *       <jc>// Succeeded!</jc>
    *    } <jk>catch</jk> (RestCallException <jv>e</jv>) {
    *       <jc>// Failed!</jc>
    *    }
    * </p>
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>Calling this method multiple times will return the same original response object.
    *    <li class='note'>You must close the returned object if you do not consume the response or execute a method that consumes
    *       the response.
    *    <li class='note'>If you are only interested in the response code, use the {@link #complete()} method which will automatically
    *       consume the response so that you don't need to call {@link InputStream#close()} on the response body.
    * </ul>
    *
    * @return The response object.
    * @throws RestCallException If an exception or non-200 response code occurred during the connection attempt.
    */
   @SuppressWarnings({
      "java:S3776", // Cognitive complexity acceptable for this specific logic
      "java:S6541", // Single-threaded context; synchronization unnecessary
      "null" // Null handling verified by context or framework
   })
   public RestResponse run() throws RestCallException {
      if (nn(response))
         throw new RestCallException(response, null, "run() already called.");

      try {

         queryData.stream().map(SimpleQuery::new).filter(SimplePart::isValid).forEach(x -> uriBuilder.addParameter(x.name, x.value));

         pathData.stream().map(SimplePath::new).forEach(x -> {
            var path = uriBuilder.getPath();
            var name = x.name;
            var value = x.value;
            var pathVar = "{" + name + "}";
            if (path.indexOf(pathVar) == -1 && neq(name, "/*"))
               throw isex("Path variable {%s} was not found in path.", name);
            if (eq(name, "/*"))
               path = path.replaceAll("\\/\\*$", URI_PATH_SEPARATOR + value);
            else
               path = path.replace(pathVar, String.valueOf(value));
            uriBuilder.setPath(path);
         });

         HttpEntityEnclosingRequestBase request2 = request instanceof HttpEntityEnclosingRequestBase request3 ? request3 : null;
         request.setURI(uriBuilder.build());

         // Pick the serializer if it hasn't been overridden.
         var hl = headerData;
         var h = hl.getLast(HEADER_CONTENT_TYPE);
         var contentType = h.isPresent() ? h.get().getValue() : null;
         var serializer2 = this.serializer;
         if (serializer2 == null)
            serializer2 = client.getMatchingSerializer(contentType);
         if (contentType == null && nn(serializer2))
            contentType = serializer2.getPrimaryMediaType().toString();

         // Pick the parser if it hasn't been overridden.
         h = hl.getLast(HEADER_ACCEPT);
         var accept = h.isPresent() ? h.get().getValue() : null;
         var parser2 = this.parser;
         if (parser2 == null)
            parser2 = client.getMatchingParser(accept);
         if (accept == null && nn(parser2))
            hl.set(Accept.of(parser2.getPrimaryMediaType()));

         headerData.stream().map(SimpleHeader::new).filter(SimplePart::isValid).forEach(request::addHeader);

         if (request2 == null && content != NO_BODY)
            throw new RestCallException(null, null, "Method does not support content entity.  Method=%s, URI=%s", getMethod(), getURI());

         if (nn(request2)) {

            Object input2 = null;
            if (content != NO_BODY) {
               input2 = content;
            } else {
               input2 = new UrlEncodedFormEntity(formData.stream().map(SimpleFormData::new).filter(SimplePart::isValid).toList());
            }

            if (input2 instanceof Supplier<?> s)
               input2 = s.get();

            HttpEntity entity = null;
            if (input2 instanceof PartList input3)
               entity = new UrlEncodedFormEntity(input3.stream().map(SimpleFormData::new).filter(SimplePart::isValid).toList());
            else if (input2 instanceof HttpResource input3) {
               input3.getHeaders().forEach(request::addHeader);
               entity = (HttpEntity)input2;
            } else if (input2 instanceof HttpEntity input3) {
               if (input3 instanceof SerializedEntity input4) {
                  entity = input4.copyWith(serializer2, contentSchema);
               } else {
                  entity = input3;
               }
            } else if (input2 instanceof Reader input3)
               entity = readerEntity(input3, getRequestContentType(TEXT_PLAIN));
            else if (input2 instanceof InputStream input3)
               entity = streamEntity(input3, -1, getRequestContentType(ContentType.APPLICATION_OCTET_STREAM));
            else if (input2 instanceof RecordStreamBody input3)
               entity = streamBodyEntity(input3, serializer2);
            else if (nn(serializer2))
               entity = serializedEntity(input2, serializer2, contentSchema).setContentType(contentType);
            else {
               if (client.hasSerializers()) {
                  if (contentType == null)
                     throw new RestCallException(null, null,
                        "Content-Type not specified on request.  Cannot match correct serializer.  Use contentType(String) or mediaType(String) to specify transport language.");
                  throw new RestCallException(null, null, "No matching serializer for media type '%s'", contentType);
               }
               entity = stringEntity(input2 == null ? "" : MarshallingContext.DEFAULT.getClassMetaForObject(input2).toString(input2), getRequestContentType(TEXT_PLAIN));
            }

            request2.setEntity(entity);
         }

         if (RemoteUrlPolicyState.isActive())
            ssrfGuarded = true;
         var httpResponse = ssrfGuarded ? runWithPolicyRedirects() : client.run(target, request, context);
         response = client.createResponse(this, httpResponse, parser2);

         if (isDebug() || client.logRequests == DetailLevel.FULL)
            response.cacheContent();

         for (var rci : interceptors)
            rci.onConnect(this, response);
         client.onCallConnect(this, response);

         var method = getMethod();
         var sc = response.getStatusCode();

         var thrown = response.getHeader("Thrown").asHeader(Thrown.class);
         if (thrown.isPresent() && nn(rethrow)) {
            var partsOpt = thrown.asParts();
            if (!partsOpt.isPresent() || partsOpt.get().isEmpty())
               return response;
            var thrownPart = partsOpt.get().get(0);
            var className = thrownPart.getClassName();
            var message = thrownPart.getMessage();
            for (var t : rethrow) {
               if (t.getName().equals(className)) {
                  ConstructorInfo c = null;
                  var ci = ClassInfo.of(t);
                  Throwable thrownInstance = null;
                  c = ci.getPublicConstructor(x -> x.hasParameterTypes(HttpResponse.class)).orElse(null);
                  if (nn(c))
                     thrownInstance = newThrownFromResponse(c);
                  if (thrownInstance == null) {
                     c = ci.getPublicConstructor(x -> x.hasParameterTypes(String.class)).orElse(null);
                     if (nn(c)) {
                        thrownInstance = c.<Throwable>newInstance(nn(message) ? message : response.getContent().asString());
                     } else {
                        c = ci.getPublicConstructor(x -> x.hasParameterTypes(String.class, Throwable.class)).orElse(null);
                        if (nn(c)) {
                           thrownInstance = c.<Throwable>newInstance(nn(message) ? message : response.getContent().asString(), null);
                        } else {
                           c = ci.getPublicConstructor(cons -> cons.getParameterCount() == 0).orElse(null);
                           if (nn(c)) {
                              thrownInstance = c.<Throwable>newInstance();
                           }
                        }
                     }
                  }
                  if (nn(thrownInstance)) {
                     if (thrownInstance instanceof Exception thrownInstance2)
                        throw thrownInstance2;
                     throw new RestCallException(response, thrownInstance, "Server threw non-Exception: %s", className);
                  }
               }
            }
         }

         if (errorCodes.test(sc) && ! ignoreErrors) {
            // Surface the server-reported exception detail from the Thrown header (authoritative and independent of the response body) so callers still see the original failure detail.
            throw new RestCallException(response, null, "HTTP method '%s' call to '%s' caused response code '%s, %s'.\nResponse: \n%s%s", method, getURI(), sc, response.getReasonPhrase(),
               response.getContent().asAbbreviatedString(1000), getThrownDetailSuffix(thrown));
         }

      } catch (RuntimeException | RestCallException e) {
         if (nn(response))
            response.close();
         throw e;
      } catch (Exception e) {
         if (nn(response))
            response.close();
         throw new RestCallException(response, e, "Call failed.");
      }

      return this.response;
   }

   // -----------------------------------------------------------------------------------------------------------------
   // SSRF-guard redirect revalidation (active only for a guarded request -- see SsrfGuardMarker)
   // -----------------------------------------------------------------------------------------------------------------

   // Marks this as the request of an SSRF-guard-active @Remote call.
   void ssrfGuard() {
      ssrfGuarded = true;
   }

   // Whether this is the request of an SSRF-guard-active @Remote call.
   boolean isSsrfGuarded() { return ssrfGuarded; }

   /**
    * Runs this request with Apache HttpClient's own automatic redirect-following disabled (see
    * {@code PolicyAwareRedirectStrategy}) and instead follows {@code 3xx} hops in a Juneau-controlled loop that
    * re-validates the {@code Location} of every hop against {@link RemoteUrlPolicy} &mdash; and, since every hop is
    * sent with the {@code SsrfGuardMarker} on its context, every hop leases its connection from the client's dedicated
    * pinned pool ({@code SsrfGuardConnectionManager}), which pin-on-connects each hop's resolved address and never hands
    * out a connection an ordinary request opened, on whichever thread the client runs it.  Only called for a guarded
    * request, i.e. for a {@code @Remote} call with the SSRF guard in effect.
    */
   private HttpResponse runWithPolicyRedirects() throws IOException {
      // A context set with context(...) carries the marker, and the redirect credential guard's origin, for the call only.
      var previousMarker = nn(context) ? SsrfGuardMarker.mark(context) : null;
      var previousOrigin = nn(context) ? ClassicRedirectCredentialGuard.origin(context) : null;
      try {
         return runWithPolicyRedirects2();
      } finally {
         if (nn(context)) {
            context.setAttribute(SsrfGuardMarker.ATTRIBUTE, previousMarker);
            ClassicRedirectCredentialGuard.origin(context, previousOrigin);
         }
      }
   }

   private HttpResponse runWithPolicyRedirects2() throws IOException {
      var currentTarget = target;
      HttpRequestBase currentRequest = request;
      URI firstOrigin = null;
      for (var hop = 0; hop < RemoteUrlPolicy.MAX_REDIRECT_HOPS; hop++) {
         // Hop 0's URI was already validated (or is the operator-configured client root, which the resolution
         // path intentionally does not re-check -- see RemoteUrlPolicy.requireAllowedUrl) before this request
         // was built; only a redirect Location -- a URL discovered at runtime -- needs a fresh pre-check here.
         if (hop > 0)
            requirePolicyAllowed(currentRequest.getURI());
         // Without a context(...) setting each hop gets a fresh context, as Apache HttpClient gives one to a request
         // sent with none: sharing one would carry the authentication state of a hop to the next host.
         var hopContext = context;
         if (hopContext == null) {
            hopContext = new BasicHttpContext();
            SsrfGuardMarker.mark(hopContext);
         }
         // The redirect credential guard compares every hop with the first hop's origin, as it does on the one context
         // of a redirect Apache HttpClient follows itself, and strips what the client's interceptors and default headers
         // add on another origin.  On hop 0 this clears an origin an earlier call left on a context(...) setting.
         ClassicRedirectCredentialGuard.origin(hopContext, firstOrigin);
         var httpResponse = client.run(currentTarget, currentRequest, hopContext);
         if (hop == 0)
            firstOrigin = ClassicRedirectCredentialGuard.origin(hopContext);
         var sc = httpResponse.getStatusLine().getStatusCode();
         if (! isRedirectStatus(sc))
            return httpResponse;
         var locationHeader = httpResponse.getFirstHeader("Location");
         EntityUtils.consumeQuietly(httpResponse.getEntity());
         if (locationHeader == null)
            throw new ClientProtocolException("Redirect response (status " + sc + ") is missing a Location header");
         URI target2;
         try {
            target2 = RemoteUrlPolicy.resolveRedirectLocation(currentRequest.getURI(), locationHeader.getValue());
         } catch (IllegalArgumentException e) {
            throw new ClientProtocolException(e.getMessage(), e);
         }
         // On a context(...) setting shared by all hops, the authentication state of the target is reset on a hop to
         // another origin, as Apache HttpClient's own redirect handling resets it on a change of host: otherwise the
         // credentials that answered one host's challenge are sent unasked to the next.  The credentials provider is
         // still asked per AuthScope, and the auth cache is keyed by host, so neither carries them across.
         if (nn(context) && crossesOrigin(currentRequest.getURI(), target2))
            resetTargetAuthState(context);
         currentRequest = buildRedirectRequest(currentRequest, target2, sc);
         currentTarget = null; // Recomputed by the connection route planner from the request's own absolute URI.
      }
      throw new ClientProtocolException("Redirect limit exceeded (" + RemoteUrlPolicy.MAX_REDIRECT_HOPS
         + " hops) while following a policy-covered @Remote redirect chain, starting at: " + request.getURI());
   }

   private void requirePolicyAllowed(URI uri) throws ClientProtocolException {
      try {
         RemoteUrlPolicy.requireAllowedUrl(uri.toString(), false, client.getAllowedAddressRanges());
      } catch (IllegalArgumentException e) {
         throw new ClientProtocolException(e.getMessage(), e);
      }
   }

   private static boolean isRedirectStatus(int statusCode) {
      return statusCode == 301 || statusCode == 302 || statusCode == 303 || statusCode == 307 || statusCode == 308;
   }

   /**
    * Constructs the server-thrown exception through its {@code (HttpResponse)} constructor.
    *
    * @param c The constructor.
    * @return The instance, or <jk>null</jk> if the constructor rejected the response's status code.
    */
   private Throwable newThrownFromResponse(ConstructorInfo c) {
      try {
         return c.<Throwable>newInstance(response);
      } catch (ExecutableException e) {
         // Only a status-code rejection (IllegalArgumentException from the Xxx(HttpResponse) status check) falls through to the remaining constructors; anything else propagates unchanged.
         if (! (e.getCause() instanceof IllegalArgumentException))
            throw e;
         return null;
      }
   }

   /**
    * Builds the request for the next hop of a policy-covered redirect chain, following conventional {@code 3xx}
    * semantics: {@code 301}/{@code 302}/{@code 303} rewrite the method to {@code GET} with no body unless the
    * original method was already {@code GET}/{@code HEAD}; {@code 307}/{@code 308} preserve the original method
    * and entity. A non-{@linkplain HttpEntity#isRepeatable() repeatable} entity cannot be safely re-sent, so such a
    * redirect is refused (fail closed) rather than risking a corrupt or partial replay.
    *
    * <p>
    * A hop to another origin (or an {@code https}&rarr;{@code http} downgrade) drops the caller-set credential headers
    * ({@link RedirectSecurity#stripOnCrossOrigin()}), as {@code ClassicRedirectCredentialGuard} does for a redirect
    * Apache HttpClient follows itself: that guard keys the first origin on the context, and here each hop may have a
    * context of its own.  Once dropped they stay dropped, even if a later hop comes back to the first origin.
    */
   private HttpRequestBase buildRedirectRequest(HttpRequestBase current, URI target2, int statusCode) throws ClientProtocolException {
      var method = current.getMethod();
      var preserveMethod = eqic(method, "GET") || eqic(method, "HEAD");
      var rewriteToGet = ! preserveMethod && (statusCode == 301 || statusCode == 302 || statusCode == 303);
      var entity = (! rewriteToGet && current instanceof HttpEntityEnclosingRequestBase e) ? e.getEntity() : null;

      HttpRequestBase next;
      if (entity != null) {
         if (! entity.isRepeatable())
            throw new ClientProtocolException("Redirect (status " + statusCode + ") requires re-sending a "
               + "non-repeatable request body, which cannot be safely replayed; refusing to follow (fail "
               + "closed) for a policy-covered @Remote redirect chain: " + target2);
         var next2 = new BasicHttpEntityRequestBase(this, method);
         next2.setEntity(entity);
         next = next2;
      } else {
         next = new BasicHttpRequestBase(this, rewriteToGet ? "GET" : method);
      }
      next.setURI(target2);
      var strip = crossesOrigin(current.getURI(), target2);
      for (var h : current.getAllHeaders())
         if (! (rewriteToGet && (eqic(h.getName(), "Content-Length") || eqic(h.getName(), HEADER_CONTENT_TYPE))) && ! (strip && isCredentialHeader(h.getName())))
            next.addHeader(h);
      return next;
   }

   // Whether a hop from one URI to the other leaves the origin, or cannot be told not to (either is not absolute).
   private static boolean crossesOrigin(URI from, URI to) {
      return from.getScheme() == null || from.getHost() == null || to.getScheme() == null || to.getHost() == null
         || RedirectSecurity.shouldStripCredentials(from, to);
   }

   // The shared RedirectSecurity set, plus Proxy-Authorization whatever that set holds: a guarded call never goes
   // through a proxy (one is refused), so on any hop it could only be a credential sent to the target itself.
   // Defense in depth: the shared set holds Proxy-Authorization today, so no test can tell this pin from it.
   private static boolean isCredentialHeader(String name) {
      return eqic(name, "Proxy-Authorization") || RedirectSecurity.stripOnCrossOrigin().stream().anyMatch(x -> eqic(x, name));
   }

   private static void resetTargetAuthState(HttpContext context) {
      var state = HttpClientContext.adapt(context).getTargetAuthState();
      if (nn(state))
         state.reset();
   }

   /**
    * Returns a message suffix describing the first entry of the given {@link Thrown} header, if present and
    * non-blank, or an empty string otherwise.
    *
    * @param thrown The parsed {@code Thrown} response header.
    * @return A <js>"\nThrown: &lt;className&gt;: &lt;message&gt;"</js> suffix, or an empty string.
    */
   private static String getThrownDetailSuffix(Thrown thrown) {
      if (thrown.isPresent()) {
         var partsOpt = thrown.asParts();
         if (partsOpt.isPresent() && ! partsOpt.get().isEmpty()) {
            var part = partsOpt.get().get(0);
            if (inb(part.getClassName()) && inb(part.getMessage()))
               return "\nThrown: " + part.getClassName() + ": " + part.getMessage();
         }
      }
      return "";
   }

   /**
    * Same as {@link #run()} but allows you to run the call asynchronously.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    Future&lt;RestResponse&gt; <jv>future</jv> = <jv>client</jv>.get(<jsf>URI</jsf>).runFuture();
    *
    *    <jc>// Do some other stuff</jc>
    *
    *    <jk>try</jk> {
    *       String <jv>body</jv> = <jv>future</jv>.get().getContent().asString();
    *       <jc>// Succeeded!</jc>
    *    } <jk>catch</jk> (RestCallException <jv>e</jv>) {
    *       <jc>// Failed!</jc>
    *    }
    * </p>
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>Use the {@link RestClient.Builder#executorService(ExecutorService, boolean)} method to customize the
    *       executor service used for creating {@link Future Futures}.
    * </ul>
    *
    * @return The HTTP status code.
    * @throws RestCallException If the executor service was not defined.
    */
   public Future<RestResponse> runFuture() throws RestCallException {
      return client.getExecutorService().submit(this::run);
   }

   /**
    * Specifies the serializer to use on the request body.
    *
    * <p>
    * Overrides the serializers specified on the {@link RestClient}.
    *
    * <p>
    *    The serializer can be configured using any of the serializer property setters (e.g. {@link RestClient.Builder#sortCollections()}) or
    *    bean context property setters (e.g. {@link RestClient.Builder#swaps(Class...)}) defined on this builder class.
    *
    * <p>
    * If the <c>Content-Type</c> header is not set on the request, it will be set to the media type of this serializer.
    *
    * @param serializer The serializer used to serialize POJOs to the body of the HTTP request.
    *    <br>Can be <jk>null</jk> (will use default serializer matching Content-Type).
    * @return This object.
    */
   public RestRequest serializer(Class<? extends Serializer> serializer) {
      this.serializer = serializer == null ? null : client.getInstance(serializer);
      return this;
   }

   /**
    * Specifies the serializer to use on the request body.
    *
    * <p>
    * Overrides the serializers specified on the {@link RestClient}.
    *
    * <p>
    *    The serializer is not modified by an of the serializer property setters (e.g. {@link RestClient.Builder#sortCollections()}) or
    *    bean context property setters (e.g. {@link RestClient.Builder#swaps(Class...)}) defined on this builder class.
    *
    * <p>
    * If the <c>Content-Type</c> header is not set on the request, it will be set to the media type of this serializer.
    *
    * @param serializer The serializer used to serialize POJOs to the body of the HTTP request.
    *    <br>Can be <jk>null</jk> (will use default serializer matching Content-Type).
    * @return This object.
    */
   public RestRequest serializer(Serializer serializer) {
      this.serializer = serializer;
      return this;
   }

   /**
    * Overwrites the first header with the same name.
    *
    * The new header will be appended to the end of the list, if no header with the given name can be found.
    *
    * @param header The header to set.
    *    <br>Can be <jk>null</jk> (ignored).
    */
   @Override /* Overridden from HttpMessage */
   public void setHeader(Header header) {
      headerData.set(header);
   }

   /**
    * Overwrites the first header with the same name.
    *
    * The new header will be appended to the end of the list, if no header with the given name can be found.
    *
    * @param name The name of the header.
    *    <br>Cannot be <jk>null</jk> or empty (header will not be created).
    * @param value The value of the header.
    *    <br>Can be <jk>null</jk>.
    */
   @Override /* Overridden from HttpMessage */
   public void setHeader(String name, String value) {
      headerData.set(stringHeader(name, value));
   }

   /**
    * Overwrites all the headers in the message.
    *
    * @param headers The array of headers to set.
    *    <br>Can be <jk>null</jk> (all headers will be cleared).
    *    <br>Can contain <jk>null</jk> values (ignored).
    */
   @Override /* Overridden from HttpMessage */
   public void setHeaders(Header[] headers) {
      headerData.set(headers);
   }

   /**
    * Provides parameters to be used for the processing of this message.
    *
    * @param params The parameters.
    *    <br>Can be <jk>null</jk> (default parameters will be used).
    * @deprecated Use constructor parameters of configuration API provided by HttpClient.
    */
   @Override /* Overridden from HttpMessage */
   @Deprecated(since = "10.0", forRemoval = true)
   public void setParams(HttpParams params) {
      request.setParams(params);
   }

   /**
    * Causes logging to be suppressed for the duration of this request.
    *
    * <p>
    * Overrides the {@link #debug()} setting on this request or client.
    *
    * @return This object.
    */
   public RestRequest suppressLogging() {
      this.suppressLogging = true;
      return this;
   }

   /**
    * Specifies the target host for the request.
    *
    * @param target The target host for the request.
    *    Implementations may accept <jk>null</jk> if they can still determine a route, for example to a default
    *    target or by inspecting the request.
    * @return This object.
    */
   public RestRequest target(HttpHost target) {
      this.target = target;
      return this;
   }

   /**
    * Convenience method for specifying UON as the marshalling transmission media type for this request only.
    *
    * <p>
    * UON is Url-Encoding Object notation that is equivalent to JSON but suitable for transmission as URL-encoded
    * query and form post values.
    *
    * <p>
    *    {@link UonSerializer} will be used to serialize POJOs to request bodies unless overridden per request via {@link RestRequest#serializer(Serializer)}.
    *    <ul>
    *       <li>The serializer can be configured using any of the serializer property setters (e.g. {@link RestClient.Builder#sortCollections()}) or
    *          bean context property setters (e.g. {@link RestClient.Builder#swaps(Class...)}) defined on this builder class.
    *    </ul>
    * <p>
    *    {@link UonParser} will be used to parse POJOs from response bodies unless overridden per request via {@link RestRequest#parser(Parser)}.
    *    <ul>
    *       <li>The parser can be configured using any of the parser property setters (e.g. {@link RestClient.Builder#ignoreUnknownBeanProperties()}) or
    *          bean context property setters (e.g. {@link RestClient.Builder#swaps(Class...)}) defined on this builder class.
    *    </ul>
    * <p>
    *    <c>Accept</c> request header will be set to <js>"text/uon"</js> unless overridden
    *       by {@link RestRequest#header(String,Object)} or {@link RestRequest#accept(String)}.
    * <p>
    *    <c>Content-Type</c> request header will be set to <js>"text/uon"</js> unless overridden
    *       by {@link RestRequest#header(String,Object)} or {@link RestRequest#contentType(String)}.
    * <p>
    *    Identical to calling <c>serializer(UonSerializer.<jk>class</jk>).parser(UonParser.<jk>class</jk>)</c>.
    *
    * @return This object.
    */
   public RestRequest uon() {
      return serializer(UonSerializer.class).parser(UonParser.class);
   }

   /**
    * Sets the URI for this request.
    *
    * <p>
    * Can be any of the following types:
    * <ul>
    *    <li>{@link URI}
    *    <li>{@link URL}
    *    <li>{@link URIBuilder}
    *    <li>Anything else converted to a string using {@link Object#toString()}.
    * </ul>
    *
    * <p>
    * Relative URI strings will be interpreted as relative to the root URI defined on the client.
    *
    * @param uri
    *    The URI of the remote REST resource.
    *    <br>This overrides the URI passed in from the client.
    *    <br>Can be any of the following types:
    *    <ul>
    *       <li>{@link URIBuilder}
    *       <li>{@link URI}
    *       <li>{@link URL}
    *       <li>{@link String}
    *       <li>{@link Object} - Converted to <c>String</c> using <c>toString()</c>
    *    </ul>
    *    <br>Cannot be <jk>null</jk>.
    * @return This object.
    * @throws RestCallException Invalid URI syntax detected.
    */
   public RestRequest uri(Object uri) throws RestCallException {
      var x = client.toUri(uri, null);
      if (nn(x.getScheme()))
         uriBuilder.setScheme(x.getScheme());
      if (nn(x.getHost()))
         uriBuilder.setHost(x.getHost());
      if (x.getPort() != -1)
         uriBuilder.setPort(x.getPort());
      if (nn(x.getUserInfo()))
         uriBuilder.setUserInfo(x.getUserInfo());
      if (nn(x.getFragment()))
         uriBuilder.setFragment(x.getFragment());
      if (nn(x.getQuery()))
         uriBuilder.setCustomQuery(x.getQuery());
      uriBuilder.setPath(x.getPath());
      return this;
   }

   /**
    * Sets the URI fragment.
    *
    * @param fragment The URI fragment.  The value is expected to be unescaped and may contain non ASCII characters.
    *    <br>Can be <jk>null</jk> (fragment will be cleared).
    * @return This object.
    */
   public RestRequest uriFragment(String fragment) {
      uriBuilder.setFragment(fragment);
      return this;
   }

   /**
    * Sets the URI host.
    *
    * @param host The new URI host.
    *    <br>Can be <jk>null</jk> (host will be cleared).
    * @return This object.
    */
   public RestRequest uriHost(String host) {
      uriBuilder.setHost(host);
      return this;
   }

   /**
    * Sets the URI port.
    *
    * @param port The new URI port.
    * @return This object.
    */
   public RestRequest uriPort(int port) {
      uriBuilder.setPort(port);
      return this;
   }

   /**
    * Sets the URI scheme.
    *
    * @param scheme The new URI scheme.
    *    <br>Can be <jk>null</jk> (scheme will be cleared).
    * @return This object.
    */
   public RestRequest uriScheme(String scheme) {
      uriBuilder.setScheme(scheme);
      return this;
   }

   /**
    * Sets the URI user info.
    *
    * @param userInfo The new URI user info.
    *    <br>Can be <jk>null</jk> (user info will be cleared).
    * @return This object.
    */
   public RestRequest uriUserInfo(String userInfo) {
      uriBuilder.setUserInfo(userInfo);
      return this;
   }

   /**
    * Sets the URI user info.
    *
    * @param username The new URI username.
    *    <br>Can be <jk>null</jk>.
    * @param password The new URI password.
    *    <br>Can be <jk>null</jk>.
    * @return This object.
    */
   public RestRequest uriUserInfo(String username, String password) {
      uriBuilder.setUserInfo(username, password);
      return this;
   }

   /**
    * Convenience method for specifying URL-Encoding as the marshalling transmission media type for this request only.
    *
    * <p>
    *    {@link UrlEncodingSerializer} will be used to serialize POJOs to request bodies unless overridden per request via {@link RestRequest#serializer(Serializer)}.
    *    <ul>
    *       <li>The serializer can be configured using any of the serializer property setters (e.g. {@link RestClient.Builder#sortCollections()}) or
    *          bean context property setters (e.g. {@link RestClient.Builder#swaps(Class...)}) defined on this builder class.
    *       <li>This serializer is NOT used when using the {@link RestRequest#formData(String, Object)} (and related) methods for constructing
    *          the request body.  Instead, the part serializer specified via {@link RestClient.Builder#partSerializer(Class)} is used.
    *    </ul>
    * <p>
    *    {@link UrlEncodingParser} will be used to parse POJOs from response bodies unless overridden per request via {@link RestRequest#parser(Parser)}.
    *    <ul>
    *       <li>The parser can be configured using any of the parser property setters (e.g. {@link RestClient.Builder#ignoreUnknownBeanProperties()}) or
    *          bean context property setters (e.g. {@link RestClient.Builder#swaps(Class...)}) defined on this builder class.
    *    </ul>
    * <p>
    *    <c>Accept</c> request header will be set to <js>"application/x-www-form-urlencoded"</js> unless overridden
    *       by {@link RestRequest#header(String,Object)} or {@link RestRequest#accept(String)}.
    * <p>
    *    <c>Content-Type</c> request header will be set to <js>"application/x-www-form-urlencoded"</js> unless overridden
    *       by {@link RestRequest#header(String,Object)} or {@link RestRequest#contentType(String)}.
    * <p>
    *    Identical to calling <c>serializer(UrlEncodingSerializer.<jk>class</jk>).parser(UrlEncodingParser.<jk>class</jk>)</c>.
    *
    * @return This object.
    */
   public RestRequest urlEnc() {
      return serializer(UrlEncodingSerializer.class).parser(UrlEncodingParser.class);
   }

   /**
    * Convenience method for specifying XML as the marshalling transmission media type for this request only.
    *
    * <p>
    * {@link XmlSerializer} will be used to serialize POJOs to request bodies unless overridden per request via {@link RestRequest#serializer(Serializer)}.
    *    <ul>
    *       <li>The serializer can be configured using any of the serializer property setters (e.g. {@link RestClient.Builder#sortCollections()}) or
    *          bean context property setters (e.g. {@link RestClient.Builder#swaps(Class...)}) defined on this builder class.
    *    </ul>
    * <p>
    *    {@link XmlParser} will be used to parse POJOs from response bodies unless overridden per request via {@link RestRequest#parser(Parser)}.
    *    <ul>
    *       <li>The parser can be configured using any of the parser property setters (e.g. {@link RestClient.Builder#ignoreUnknownBeanProperties()}) or
    *          bean context property setters (e.g. {@link RestClient.Builder#swaps(Class...)}) defined on this builder class.
    *    </ul>
    * <p>
    *    <c>Accept</c> request header will be set to <js>"text/xml"</js> unless overridden
    *       by {@link RestRequest#header(String,Object)} or {@link RestRequest#accept(String)}.
    * <p>
    *    <c>Content-Type</c> request header will be set to <js>"text/xml"</js> unless overridden
    *       by {@link RestRequest#header(String,Object)} or {@link RestRequest#contentType(String)}.
    * <p>
    *    Identical to calling <c>serializer(XmlSerializer.<jk>class</jk>).parser(XmlParser.<jk>class</jk>)</c>.
    *
    * @return This object.
    */
   public RestRequest xml() {
      return serializer(XmlSerializer.class).parser(XmlParser.class);
   }

   private Header createHeader(String name, Object value) {
      return createHeader(name, value, null, null, null);
   }

   private NameValuePair createPart(HttpPartType type, String name, Object value) {
      return createPart(name, value, type, null, null, null);
   }

   private HttpPartSerializerSession getPartSerializerSession(HttpPartSerializer serializer) {
      if (serializer == null)
         serializer = client.getPartSerializer();
      return partSerializerSessions.computeIfAbsent(serializer, HttpPartSerializer::getPartSession);
   }

   private ContentType getRequestContentType(ContentType def) {
      var h = request.getFirstHeader(HEADER_CONTENT_TYPE);
      if (nn(h)) {
         var s = h.getValue();
         if (ine(s))
            return ContentType.of(s);
      }
      return def;
   }

   /**
    * Creates a new header.
    *
    * @param name The header name.
    * @param value The header value.
    * @param serializer The part serializer to use, or <jk>null</jk> to use the part serializer defined on the client.
    * @param schema Optional HTTP part schema to provide to the part serializer.
    * @param skipIfEmpty If <jk>true</jk>, empty string values will be ignored on the request.
    * @return A new header.
    */
   protected Header createHeader(String name, Object value, HttpPartSerializer serializer, HttpPartSchema schema, Boolean skipIfEmpty) {
      if (ie(name))
         return null;
      if (skipIfEmpty == null)
         skipIfEmpty = client.isSkipEmptyHeaderData();
      if (serializer == null)
         serializer = client.getPartSerializer();
      return new SerializedHeader(name, value, getPartSerializerSession(serializer), schema, skipIfEmpty);
   }

   /**
    * Constructs the {@link HttpRequestBase} object that ends up being passed to the client execute method.
    *
    * <p>
    * Subclasses can override this method to create their own request base objects.
    *
    * @param method The HTTP method.
    * @param uri The HTTP URI.
    * @param hasBody Whether the HTTP request has a body.
    * @return A new {@link HttpRequestBase} object.
    */
   protected HttpRequestBase createInnerRequest(String method, URI uri, boolean hasBody) {
      var req = hasBody ? new BasicHttpEntityRequestBase(this, method) : new BasicHttpRequestBase(this, method);
      req.setURI(uri);
      return req;
   }

   /**
    * Creates a new query/form-data/path part.
    *
    * @param name The part name.
    * @param value The part value.
    * @param type The HTTP part type.
    * @param serializer The part serializer to use, or <jk>null</jk> to use the part serializer defined on the client.
    * @param schema Optional HTTP part schema to provide to the part serializer.
    * @param skipIfEmpty If <jk>true</jk>, empty string values will be ignored on the request.
    * @return A new part.
    */
   protected NameValuePair createPart(String name, Object value, HttpPartType type, HttpPartSerializer serializer, HttpPartSchema schema, Boolean skipIfEmpty) {
      if (ie(name))
         return null;
      if (skipIfEmpty == null) {
         if (type == QUERY)
            skipIfEmpty = client.isSkipEmptyQueryData();
         else if (type == FORMDATA)
            skipIfEmpty = client.isSkipEmptyFormData();
         else
            skipIfEmpty = false;
      }
      if (serializer == null)
         serializer = client.getPartSerializer();
      return new SerializedPart(name, value, type, getPartSerializerSession(serializer), schema, skipIfEmpty);
   }

   @Override /* Overridden from MarshallingSession */
   protected FluentMap<String,Object> properties() {
      return super.properties()
         .a("client", client.properties())
         .a("ignoreErrors", ignoreErrors)
         .a("interceptors", interceptors)
         .a("requestBodySchema", contentSchema)
         .a("response", response)
         .a("serializer", serializer);
   }

   RestRequest formDataArg(String name, Object value, HttpPartSchema schema, HttpPartSerializer serializer, boolean skipIfEmpty) {
      var isMulti = ie(name) || eq(name, "*") || value instanceof PartList || isNameValuePairArray(value);

      if (! isMulti) {
         if (! (skipIfEmpty && ie(s(value))))
            return formData(createPart(name, value, FORMDATA, serializer, schema, skipIfEmpty));
         return this;
      }

      List<NameValuePair> l = list();

      if (HttpParts.canCast(value)) {
         l.add(HttpParts.cast(value));
      } else if (value instanceof PartList value2) {
         value2.forEach(l::add);
      } else if (value instanceof Collection<?> value3) {
         value3.forEach(x -> l.add(HttpParts.cast(x)));
      } else if (isArray(value)) {
         for (var i = 0; i < Array.getLength(value); i++)
            l.add(HttpParts.cast(Array.get(value, i)));
      } else if (value instanceof Map value2) {
         toMap(value2).forEach((k, v) -> l.add(createPart(s(k), v, FORMDATA, serializer, schema, skipIfEmpty)));
      } else if (isBean(value)) {
         toBeanMap(value).forEach((k, v) -> l.add(createPart(k, v, FORMDATA, serializer, schema, skipIfEmpty)));
      } else if (nn(value)) {
         formDataCustom(value);
         return this;
      }

      if (skipIfEmpty)
         l.removeIf(x -> ie(x.getValue()));

      formData.append(l);

      return this;
   }

   HttpPartSerializerSession getPartSerializerSession() {
      if (partSerializerSession == null)
         partSerializerSession = getPartSerializerSession(null);
      return partSerializerSession;
   }

   RestRequest headerArg(String name, Object value, HttpPartSchema schema, HttpPartSerializer serializer, boolean skipIfEmpty) {
      var isMulti = ie(name) || eq(name, "*") || value instanceof HeaderList || isHeaderArray(value);

      if (! isMulti) {
         if (! (skipIfEmpty && ie(s(value))))
            return header(createHeader(name, value, serializer, schema, skipIfEmpty));
         return this;
      }

      List<Header> l = list();

      if (HttpHeaders.canCast(value)) {
         l.add(HttpHeaders.cast(value));
      } else if (value instanceof HeaderList value2) {
         value2.forEach(l::add);
      } else if (value instanceof Collection<?> value3) {
         value3.forEach(x -> l.add(HttpHeaders.cast(x)));
      } else if (isArray(value)) {
         for (var i = 0; i < Array.getLength(value); i++)
            l.add(HttpHeaders.cast(Array.get(value, i)));
      } else if (value instanceof Map value2) {
         toMap(value2).forEach((k, v) -> l.add(createHeader(s(k), v, serializer, schema, skipIfEmpty)));
      } else if (isBean(value)) {
         toBeanMap(value).forEach((k, v) -> l.add(createHeader(k, v, serializer, schema, skipIfEmpty)));
      } else if (nn(value)) {
         throw rex("Invalid value type for header arg '%s': %s", name, cn(value));
      }

      if (skipIfEmpty)
         l.removeIf(x -> ie(x.getValue()));

      headerData.append(l);

      return this;
   }

   boolean isLoggingSuppressed() { return suppressLogging; }

   /**
    * Returns <jk>true</jk> if the request body can be safely re-sent (required for a gated automatic retry).
    *
    * <p>
    * A missing body is trivially repeatable; a streaming body ({@link InputStream}/{@link Reader}/record-stream) is
    * not; an {@link HttpEntity} body defers to {@link HttpEntity#isRepeatable()}; any other (buffered POJO/String)
    * body is repeatable.
    *
    * @return <jk>true</jk> if the body can be safely re-sent.
    */
   boolean isBodyRepeatable() {
      var c = content;
      if (c == null || c == NO_BODY)
         return true;
      if (c instanceof InputStream || c instanceof Reader || c instanceof RecordStreamBody)
         return false;
      if (c instanceof HttpEntity e)
         return e.isRepeatable();
      return true;
   }

   RestRequest pathArg(String name, Object value, HttpPartSchema schema, HttpPartSerializer serializer) {
      var isMulti = ie(name) || eq(name, "*") || value instanceof PartList || isNameValuePairArray(value);

      if (! isMulti)
         return pathData(createPart(name, value, PATH, serializer, schema, false));

      List<NameValuePair> l = list();

      if (HttpParts.canCast(value)) {
         l.add(HttpParts.cast(value));
      } else if (value instanceof PartList value2) {
         value2.forEach(l::add);
      } else if (value instanceof Collection<?> value3) {
         value3.forEach(x -> l.add(HttpParts.cast(x)));
      } else if (isArray(value)) {
         for (var i = 0; i < Array.getLength(value); i++)
            l.add(HttpParts.cast(Array.get(value, i)));
      } else if (value instanceof Map value2) {
         toMap(value2).forEach((k, v) -> l.add(createPart(s(k), v, PATH, serializer, schema, false)));
      } else if (isBean(value)) {
         toBeanMap(value).forEach((k, v) -> l.add(createPart(k, v, PATH, serializer, schema, false)));
      } else if (nn(value)) {
         throw rex("Invalid value type for path arg '%s': %s", name, cn(value));
      }

      pathData.append(l);

      return this;
   }

   RestRequest queryArg(String name, Object value, HttpPartSchema schema, HttpPartSerializer serializer, boolean skipIfEmpty) {
      if (schema != null && schema.getCollectionFormat() == HttpPartCollectionFormat.MULTI) {
         if (value instanceof Collection<?> value2) {
            List<NameValuePair> l = list();
            value2.forEach(x -> l.add(createPart(name, x, QUERY, serializer, schema, skipIfEmpty)));
            if (skipIfEmpty)
               l.removeIf(x -> ie(x.getValue()));
            queryData.append(l);
            return this;
         }
         if (isArray(value) && ! isNameValuePairArray(value)) {
            List<NameValuePair> l = list();
            for (var i = 0; i < Array.getLength(value); i++)
               l.add(createPart(name, Array.get(value, i), QUERY, serializer, schema, skipIfEmpty));
            if (skipIfEmpty)
               l.removeIf(x -> ie(x.getValue()));
            queryData.append(l);
            return this;
         }
         if (value instanceof Map<?,?> value2) {
            List<NameValuePair> l = list();
            var sess = getPartSerializerSession(serializer);
            for (var e : value2.entrySet()) {
               try {
                  var uon = sess.write(QUERY, schema, e.getValue());
                  l.add(BasicPart.of(name, s(e.getKey()) + "=" + (uon == null ? "" : uon)));
               } catch (SerializeException | SchemaValidationException ex) {
                  throw rex(ex, "Serialization error on request query part '%s'", name);
               }
            }
            if (skipIfEmpty)
               l.removeIf(x -> ie(x.getValue()));
            queryData.append(l);
            return this;
         }
      }

      var isMulti = ie(name) || eq(name, "*") || value instanceof PartList || isNameValuePairArray(value);

      if (! isMulti) {
         if (! (skipIfEmpty && ie(s(value))))
            return queryData(createPart(name, value, QUERY, serializer, schema, skipIfEmpty));
         return this;
      }

      List<NameValuePair> l = list();

      if (HttpParts.canCast(value)) {
         l.add(HttpParts.cast(value));
      } else if (value instanceof PartList value2) {
         value2.forEach(l::add);
      } else if (value instanceof Collection<?> value3) {
         value3.forEach(x -> l.add(HttpParts.cast(x)));
      } else if (isArray(value)) {
         for (var i = 0; i < Array.getLength(value); i++)
            l.add(HttpParts.cast(Array.get(value, i)));
      } else if (value instanceof Map value2) {
         toMap(value2).forEach((k, v) -> l.add(createPart(s(k), v, QUERY, serializer, schema, skipIfEmpty)));
      } else if (isBean(value)) {
         toBeanMap(value).forEach((k, v) -> l.add(createPart(k, v, QUERY, serializer, schema, skipIfEmpty)));
      } else if (nn(value)) {
         queryCustom(value);
         return this;
      }

      if (skipIfEmpty)
         l.removeIf(x -> ie(x.getValue()));

      queryData.append(l);

      return this;
   }

   /**
    * Resolves a {@link RecordStreamBody} body by invoking the caller's consumer against a
    * cursor opened over a temporary buffer, then sending the buffered bytes as the request
    * body.
    */
   private HttpEntity streamBodyEntity(RecordStreamBody body, Serializer serializer) {
      if (serializer == null)
         throw iaex("No serializer registered for cursor-streamed request body.");
      try {
         var consumer = body.getConsumer();
         var writerKind = body.getWriterKind();

         if (writerKind == TokenWriter.class && !(serializer instanceof TokenWritable))
            throw iaex("Serializer '%s' does not support the token-writer surface.", serializer.getClass().getName());
         if (writerKind == RecordWriter.class && !(serializer instanceof RecordWritable))
            throw iaex("Serializer '%s' does not support the record-writer surface.", serializer.getClass().getName());

         var buf = new ByteArrayOutputStream();
         Object output = serializer.isWriterSerializer()
            ? new OutputStreamWriter(buf, java.nio.charset.StandardCharsets.UTF_8)
            : buf;

         writeCursor(serializer, writerKind, consumer, output);

         // Use the serializer's primary produces() media type if no explicit Content-Type set.
         var ct = serializer.getPrimaryMediaType();
         var contentType2 = ct != null ? ContentType.of(ct.toString()) : ContentType.APPLICATION_OCTET_STREAM;
         return byteArrayEntity(buf.toByteArray(), getRequestContentType(contentType2));
      } catch (IOException e) {
         throw rex(e, "I/O error streaming request body.");
      }
   }

   @SuppressWarnings({
      "rawtypes" // The body consumer's element type depends on the writer kind, so it is invoked through a raw Consumer.
   })
   private static void writeCursor(Serializer serializer, Class<?> writerKind, Object consumer, Object output) throws IOException {
      try (var w = (writerKind == TokenWriter.class)
            ? ((TokenWritable) serializer).writeTokens(output)
            : ((RecordWritable) serializer).writeRecords(output)) {
         ((Consumer) consumer).accept(w);
         w.flush();
      }
   }
}