/*
 * 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 java.lang.Character.isWhitespace;
import static java.util.logging.Level.*;
import static org.apache.juneau.commons.httppart.HttpPartType.*;
import static org.apache.juneau.commons.lang.StateEnum.*;
import static org.apache.juneau.commons.utils.CollectionUtils.*;
import static org.apache.juneau.commons.utils.CollectionUtils.isEmpty;
import static org.apache.juneau.commons.utils.Shorts.*;
import static org.apache.juneau.commons.utils.StringUtils.*;
import static org.apache.juneau.commons.utils.StringUtils.isEmpty;
import static org.apache.juneau.commons.utils.ThrowableUtils.*;
import static org.apache.juneau.http.HttpMethod.*;
import static org.apache.juneau.http.classic.HttpEntities.*;
import static org.apache.juneau.http.classic.HttpHeaders.*;
import static org.apache.juneau.http.classic.HttpParts.*;
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.lang.reflect.Proxy;
import java.net.*;
import java.nio.charset.*;
import java.util.*;
import java.util.concurrent.*;
import java.util.concurrent.atomic.*;
import java.util.function.*;
import java.util.logging.*;
import java.util.regex.*;

import javax.net.ssl.*;

import org.apache.http.*;
import org.apache.http.NameValuePair;
import org.apache.http.auth.*;
import org.apache.http.client.*;
import org.apache.http.client.CookieStore;
import org.apache.http.client.config.*;
import org.apache.http.client.entity.*;
import org.apache.http.client.methods.*;
import org.apache.http.client.utils.*;
import org.apache.http.config.*;
import org.apache.http.conn.*;
import org.apache.http.conn.routing.*;
import org.apache.http.conn.socket.*;
import org.apache.http.conn.ssl.*;
import org.apache.http.conn.util.*;
import org.apache.http.cookie.*;
import org.apache.http.impl.client.*;
import org.apache.http.impl.conn.*;
import org.apache.http.params.*;
import org.apache.http.protocol.*;
import org.apache.http.ssl.SSLContexts;
import org.apache.juneau.commons.*;
import org.apache.juneau.commons.collections.*;
import org.apache.juneau.commons.function.*;
import org.apache.juneau.commons.http.*;
import org.apache.juneau.commons.httppart.*;
import org.apache.juneau.commons.inject.*;
import org.apache.juneau.commons.reflect.*;
import org.apache.juneau.http.classic.entity.*;
import org.apache.juneau.http.classic.header.*;
import org.apache.juneau.http.classic.part.*;
import org.apache.juneau.http.classic.remote.RrpcInterfaceMeta;
import org.apache.juneau.http.classic.resource.*;
import org.apache.juneau.http.remote.*;
import org.apache.juneau.marshall.*;
import org.apache.juneau.marshall.bson.*;
import org.apache.juneau.marshall.cbor.*;
import org.apache.juneau.marshall.hjson.*;
import org.apache.juneau.marshall.hocon.*;
import org.apache.juneau.marshall.html.*;
import org.apache.juneau.marshall.httppart.*;
import org.apache.juneau.marshall.ini.*;
import org.apache.juneau.marshall.jcs.*;
import org.apache.juneau.marshall.json.*;
import org.apache.juneau.marshall.json5.*;
import org.apache.juneau.marshall.json5l.*;
import org.apache.juneau.marshall.jsonl.*;
import org.apache.juneau.marshall.markdown.*;
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.parquet.*;
import org.apache.juneau.marshall.parser.*;
import org.apache.juneau.marshall.parser.ParseException;
import org.apache.juneau.marshall.plaintext.*;
import org.apache.juneau.marshall.prototext.*;
import org.apache.juneau.marshall.serializer.*;
import org.apache.juneau.marshall.toml.*;
import org.apache.juneau.marshall.uon.*;
import org.apache.juneau.marshall.urlencoding.*;
import org.apache.juneau.marshall.xml.*;
import org.apache.juneau.rest.*;
import org.apache.juneau.rest.client.classic.assertion.*;
import org.apache.juneau.rest.client.classic.remote.*;

/**
 * Utility class for interfacing with remote REST interfaces.
 *
 * <p>
 * Built upon the feature-rich Apache HttpClient library, the Juneau RestClient API adds support for fluent-style
 * REST calls and the ability to perform marshalling of POJOs to and from HTTP parts.
 *
 * <h5 class='figure'>Example:</h5>
 * <p class='bjava'>
 *    <jc>// Create a basic REST client with JSON support and download a bean.</jc>
 *    MyBean <jv>bean</jv> = RestClient.<jsm>create</jsm>()
 *       .json5()
 *       .build()
 *       .get(<jsf>URI</jsf>)
 *       .run()
 *       .assertStatus().asCode().is(200)
 *       .assertHeader(<js>"Content-Type"</js>).matchesSimple(<js>"application/json*"</js>)
 *       .getContent().as(MyBean.<jk>class</jk>);
 * </p>
 *
 * <p>
 * Breaking apart the fluent call, we can see the classes being used:
 * <p class='bjava'>
 *    RestClient.Builder&lt;?&gt; <jv>builder</jv> = RestClient.<jsm>create</jsm>().json5();
 *    RestClient <jv>client</jv> = <jv>builder</jv>.build();
 *    RestRequest <jv>req</jv> = <jv>client</jv>.get(<jsf>URI</jsf>);
 *    RestResponse <jv>res</jv> = <jv>req</jv>.run();
 *    RestResponseStatusLineAssertion <jv>statusLineAssertion</jv> = <jv>res</jv>.assertStatus();
 *    FluentIntegerAssertion&lt;RestResponse&gt; <jv>codeAssertion</jv> = <jv>statusLineAssertion</jv>.asCode();
 *    <jv>res</jv> = <jv>codeAssertion</jv>.is(200);
 *    FluentStringAssertion&lt;RestResponse&gt; <jv>headerAssertion</jv> = <jv>res</jv>.assertHeader(<js>"Content-Type"</js>);
 *    <jv>res</jv> = <jv>headerAssertion</jv>.matchesSimple(<js>"application/json*"</js>);
 *    RestResponseBody <jv>content</jv> = <jv>res</jv>.getContent();
 *    MyBean <jv>bean</jv> = <jv>content</jv>.as(MyBean.<jk>class</jk>);
 * </p>
 *
 * <p>
 * It additionally provides support for creating remote proxy interfaces using REST as the transport medium.
 *
 * <h5 class='figure'>Example:</h5>
 * <p class='bjava'>
 *    <jc>// Define a Remote proxy for interacting with a REST interface.</jc>
 *    <ja>@Remote</ja>(path=<js>"/petstore"</js>)
 *    <jk>public interface</jk> PetStore {
 *
 *       <ja>@RemotePost</ja>(<js>"/pets"</js>)
 *       Pet addPet(
 *          <ja>@Content</ja> CreatePet <jv>pet</jv>,
 *          <ja>@Header</ja>(<js>"E-Tag"</js>) UUID <jv>etag</jv>,
 *          <ja>@Query</ja>(<js>"debug"</js>) <jk>boolean</jk> <jv>debug</jv>
 *       );
 *    }
 *
 *    <jc>// Use a RestClient with default JSON 5 support.</jc>
 *    RestClient <jv>client</jv> = RestClient.<jsm>create</jsm>().json5().build();
 *
 *    PetStore <jv>store</jv> = <jv>client</jv>.getRemote(PetStore.<jk>class</jk>, <js>"http://localhost:10000"</js>);
 *    CreatePet <jv>createPet</jv> = <jk>new</jk> CreatePet(<js>"Fluffy"</js>, 9.99);
 *    Pet <jv>pet</jv> = <jv>store</jv>.addPet(<jv>createPet</jv>, UUID.<jsm>randomUUID</jsm>(), <jk>true</jk>);
 * </p>
 *
 * <p>
 * The classes are closely tied to Apache HttpClient, yet provide lots of additional functionality:
 * <ul class='javatree'>
 *    <li class='jc'>{@link RestClient} <jk>extends</jk> {@link HttpClient}, creates {@link RestRequest} objects.
 *    <li class='jc'>{@link RestRequest} <jk>extends</jk> {@link HttpUriRequest}, creates {@link RestResponse} objects.
 *    <li class='jc'>{@link RestResponse} creates {@link ResponseContent} and {@link ResponseHeader} objects.
 *    <li class='jc'>{@link ResponseContent} <jk>extends</jk> {@link HttpEntity}
 *    <li class='jc'>{@link ResponseHeader} <jk>extends</jk> {@link Header}
 * </ul>
 *
 *
 * <p>
 * Instances of this class are built using the {@link Builder} class which can be constructed using
 * the {@link #create() RestClient.create()} method as shown above.
 *
 * <p>
 * Clients are typically created with a root URI so that relative URIs can be used when making requests.
 * This is done using the {@link Builder#rootUrl(Object)} method.
 *
 * <h5 class='figure'>Example:</h5>
 * <p class='bjava'>
 *    <jc>// Create a client where all URIs are relative to localhost.</jc>
 *    RestClient <jv>client</jv> = RestClient.<jsm>create</jsm>().json().rootUrl(<js>"http://localhost:5000"</js>).build();
 *
 *    <jc>// Use relative paths.</jc>
 *    String <jv>body</jv> = <jv>client</jv>.get(<js>"/subpath"</js>).run().getContent().asString();
 * </p>
 *
 * <p>
 * The {@link RestClient} class creates {@link RestRequest} objects using the following methods:
 *
 * <ul class='javatree'>
 *    <li class='jc'>{@link RestClient}
 *    <ul>
 *       <li class='jm'>{@link RestClient#get(Object) get(uri)} / {@link RestClient#get() get()}
 *       <li class='jm'>{@link RestClient#put(Object,Object) put(uri,body)} / {@link RestClient#put(Object) put(uri)}
 *       <li class='jm'>{@link RestClient#post(Object) post(uri,body)} / {@link RestClient#post(Object) post(uri)}
 *       <li class='jm'>{@link RestClient#patch(Object,Object) patch(uri,body)} / {@link RestClient#patch(Object) patch(uri)}
 *       <li class='jm'>{@link RestClient#delete(Object) delete(uri)}
 *       <li class='jm'>{@link RestClient#head(Object) head(uri)}
 *       <li class='jm'>{@link RestClient#options(Object) options(uri)}
 *       <li class='jm'>{@link RestClient#formPost(Object,Object) formPost(uri,body)} / {@link RestClient#formPost(Object) formPost(uri)}
 *       <li class='jm'>{@link RestClient#formPostPairs(Object,String...) formPostPairs(uri,parameters...)}
 *       <li class='jm'>{@link RestClient#request(String,Object,Object) request(method,uri,body)}
 *    </ul>
 * </ul>
 *
 * <p>
 * The {@link RestRequest} class creates {@link RestResponse} objects using the following methods:
 *
 * <ul class='javatree'>
 *    <li class='jc'>{@link RestRequest}
 *    <ul>
 *       <li class='jm'>{@link RestRequest#run() run()}
 *       <li class='jm'>{@link RestRequest#complete() complete()}
 *    </ul>
 * </ul>
 *
 * <p>
 * The distinction between the two methods is that {@link RestRequest#complete() complete()} automatically consumes the response body and
 * {@link RestRequest#run() run()} does not.  Note that you must consume response bodies in order for HTTP connections to be freed up
 * for reuse!  The {@link InputStream InputStreams} returned by the {@link ResponseContent} object are auto-closing once
 * they are exhausted, so it is often not necessary to explicitly close them.
 *
 * <p>
 * The following examples show the distinction between the two calls:
 *
 * <p class='bjava'>
 *    <jc>// Consuming the response, so use run().</jc>
 *    String <jv>body</jv> = <jv>client</jv>.get(<jsf>URI</jsf>).run().getContent().asString();
 *
 *    <jc>// Only interested in response status code, so use complete().</jc>
 *    <jk>int</jk> <jv>status</jv> = <jv>client</jv>.get(<jsf>URI</jsf>).complete().getStatusCode();
 * </p>
 *
 *
 * <h4 class='topic'>POJO Marshalling</h4>
 *
 * <p>
 * By default, JSON support is provided for HTTP request and response bodies.
 * Other languages can be specified using any of the following builder methods:
 * <ul class='javatree'>
 *    <li class='jc'>{@link Builder}
 *    <ul>
 *       <li class='jm'>{@link Builder#json() json()}
 *       <li class='jm'>{@link Builder#json5() json5()}
 *       <li class='jm'>{@link Builder#xml() xml()}
 *       <li class='jm'>{@link Builder#html() html()}
 *       <li class='jm'>{@link Builder#plainText() plainText()}
 *       <li class='jm'>{@link Builder#bson() bson()}
 *       <li class='jm'>{@link Builder#msgPack() msgPack()}
 *       <li class='jm'>{@link Builder#uon() uon()}
 *       <li class='jm'>{@link Builder#urlEnc() urlEnc()}
 *       <li class='jm'>{@link Builder#openApi() openApi()}
 *    </ul>
 * </ul>
 *
 * <h5 class='figure'>Example:</h5>
 * <p class='bjava'>
 *    <jc>// Create a basic REST client with JSON 5 support.</jc>
 *    <jc>// Typically easier to use when performing unit tests.</jc>
 *    RestClient <jv>client</jv> = RestClient.<jsm>create</jsm>().json5().build();
 * </p>
 *
 * <p>
 * Clients can also support multiple languages:
 *
 * <h5 class='figure'>Example:</h5>
 * <p class='bjava'>
 *    <jc>// Create a REST client with support for multiple languages.</jc>
 *    RestClient <jv>client1</jv> = RestClient.<jsm>create</jsm>().json().xml().openApi().build();
 *
 *    <jc>// Create a REST client with support for all supported languages.</jc>
 *    RestClient <jv>client2</jv> = RestClient.<jsm>create</jsm>().universal().build();
 * </p>
 *
 * <p>
 * When using clients with multiple language support, you must specify the <c>Content-Type</c> header on requests
 * with bodies to specify which serializer should be selected.
 *
 * <p class='bjava'>
 *    <jc>// Create a REST client with support for multiple languages.</jc>
 *    RestClient <jv>client</jv> = RestClient.<jsm>create</jsm>().universal().build();
 *
 *    <jv>client</jv>
 *       .post(<jsf>URI</jsf>, <jv>myBean</jv>)
 *       .contentType(<js>"application/json"</js>)
 *       .complete()
 *       .assertStatus().is(200);
 * </p>
 *
 * <p>
 * Languages can also be specified per-request.
 *
 * <p class='bjava'>
 *    <jc>// Create a REST client with no default languages supported.</jc>
 *    RestClient <jv>client</jv> = RestClient.<jsm>create</jsm>().build();
 *
 *    <jc>// Use JSON for this request.</jc>
 *    <jv>client</jv>
 *       .post(<jsf>URI</jsf>, <jv>myBean</jv>)
 *       .json()
 *       .complete()
 *       .assertStatus().is(200);
 * </p>
 *
 *
 * <p>
 * The {@link Builder} class provides convenience methods for setting common serializer and parser
 * settings.
 *
 * <h5 class='figure'>Example:</h5>
 * <p class='bjava'>
 *    <jc>// Create a basic REST client with JSON support.</jc>
 *    <jc>// Use single-quotes and whitespace.</jc>
 *    RestClient <jv>client</jv> = RestClient.<jsm>create</jsm>().json().sq().ws().build();
 * </p>
 *
 * <p>
 *    Other methods are also provided for specifying the serializers and parsers used for lower-level marshalling support:
 * <ul class='javatree'>
 *    <li class='jc'>{@link Builder}
 *    <ul>
 *       <li class='jm'>{@link Builder#serializer(Serializer) serializer(Serializer)}
 *       <li class='jm'>{@link Builder#parser(Parser) parser(Parser)}
 *       <li class='jm'>{@link Builder#marshaller(Marshaller) marshaller(Marshaller)}
 *    </ul>
 * </ul>
 *
 * <p>
 * HTTP parts (headers, query parameters, form data...) are serialized and parsed using the {@link HttpPartSerializer}
 * and {@link HttpPartParser} APIs.  By default, clients are configured to use {@link OpenApiSerializer} and
 * {@link OpenApiParser}.  These can be overridden using the following methods:
 * <ul class='javatree'>
 *    <li class='jc'>{@link Builder}
 *    <ul>
 *       <li class='jm'>{@link Builder#partSerializer(Class) partSerializer(Class&lt;? extends HttpPartSerializer>)}
 *       <li class='jm'>{@link Builder#partParser(Class) partParser(Class&lt;? extends HttpPartParser>)}
 *    </ul>
 * </ul>
 *
 *
 * <h4 class='topic'>Request Headers</h4>
 * <p>
 * Per-client or per-request headers can be specified using the following methods:
 * <ul class='javatree'>
 *    <li class='jc'>{@link Builder}
 *    <ul>
 *       <li class='jm'>{@link Builder#headers() headerData()}
 *       <li class='jm'>{@link Builder#header(String,String) header(String,Object)}
 *       <li class='jm'>{@link Builder#header(String,Supplier) header(String,Supplier&lt;?&gt;)}
 *       <li class='jm'>{@link Builder#headers(Header...) headers(Header...)}
 *       <li class='jm'>{@link Builder#headersDefault(Header...) defaultHeaders(Header...)}
 *    </ul>
 *    <li class='jc'>{@link RestRequest}
 *    <ul>
 *       <li class='jm'>{@link RestRequest#header(String,Object) header(String,Object)}
 *       <li class='jm'>{@link RestRequest#headers(Header...) headers(Header...)}
 *       <li class='jm'>{@link RestRequest#headersBean(Object) headersBean(Object)}
 *       <li class='jm'>{@link RestRequest#headerPairs(String...) headerPairs(String...)}
 *    </ul>
 * </ul>
 *
 * <p>
 * The supplier methods are particularly useful for header values whose values may change over time (such as <c>Authorization</c> headers
 * which may need to change every few minutes).
 * </p>
 *
 * <h5 class='figure'>Example:</h5>
 * <p class='bjava'>
 *    <jc>// Create a client that adds a dynamic Authorization header to every request.</jc>
 *    RestClient <jv>client</jv> = RestClient.<jsm>create</jsm>().header(<js>"Authorization"</js>, ()-&gt;getMyAuthToken()).build();
 * </p>
 *
 * <p>
 * The {@link HttpPartSchema} API allows you to define OpenAPI schemas to POJO data structures on both requests
 * and responses.
 *
 * <h5 class='figure'>Example:</h5>
 * <p class='bjava'>
 *    <jc>// Create a client that adds a header "Foo: bar|baz" to every request.</jc>
 *    RestClient <jv>client</jv> = RestClient.<jsm>create</jsm>()
 *       .header(<js>"Foo"</js>, AList.<jsm>of</jsm>(<js>"bar"</js>,<js>"baz"</js>), <jsf>T_ARRAY_PIPES</jsf>)
 *       .build();
 * </p>
 *
 * <p>
 * The methods with {@link ListOperation} parameters allow you to control whether new headers get appended, prepended, or
 * replace existing headers with the same name.
 *
 * <h5 class='section'>Notes:</h5><ul>
 *    <li class='note'>Methods that pass in POJOs convert values to strings using the part serializers.  Methods that pass in <c>Header</c> or
 *       <c>NameValuePair</c> objects use the values returned by that bean directly.
 * </ul>
 *
 *
 * <h4 class='topic'>Request Query Parameters</h4>
 * <p>
 * Per-client or per-request query parameters can be specified using the following methods:
 * <ul class='javatree'>
 *    <li class='jc'>{@link Builder}
 *    <ul>
 *       <li class='jm'>{@link Builder#queryData() queryData()}
 *       <li class='jm'>{@link Builder#queryData(String,String) queryData(String,String)}
 *       <li class='jm'>{@link Builder#queryData(String,Supplier) queryData(String,Supplier&lt;?&gt;)}
 *       <li class='jm'>{@link Builder#queryData(NameValuePair...) queryData(NameValuePair...)}
 *       <li class='jm'>{@link Builder#queryDataDefault(NameValuePair...) defaultQueryData(NameValuePair...)}
 *    </ul>
 *    <li class='jc'>{@link RestRequest}
 *    <ul>
 *       <li class='jm'>{@link RestRequest#queryData(String,Object) queryData(String,Object)}
 *       <li class='jm'>{@link RestRequest#queryData(NameValuePair...) queryData(NameValuePair...)}
 *       <li class='jm'>{@link RestRequest#queryDataBean(Object) queryDataBean(Object)}
 *       <li class='jm'>{@link RestRequest#queryCustom(Object) queryCustom(Object)}
 *       <li class='jm'>{@link RestRequest#queryDataPairs(String...) queryDataPairs(String...)}
 *    </ul>
 * </ul>
 *
 * <h5 class='figure'>Example:</h5>
 * <p class='bjava'>
 *    <jc>// Create a client that adds a ?foo=bar query parameter to every request.</jc>
 *    RestClient <jv>client</jv> = RestClient.<jsm>create</jsm>().query(<js>"foo"</js>, <js>"bar"</js>).build();
 *
 *    <jc>// Or do it on every request.</jc>
 *    String <jv>response</jv> = <jv>client</jv>.get(<jsf>URI</jsf>).query(<js>"foo"</js>, <js>"bar"</js>).run().getContent().asString();
 * </p>
 *
 * <h5 class='section'>Notes:</h5><ul>
 *    <li class='note'>Like header values, dynamic values and OpenAPI schemas are supported.
 *    <li class='note'>Methods that pass in POJOs convert values to strings using the part serializers.  Methods that pass in <c>NameValuePair</c>
 *       objects use the values returned by that bean directly.
 * </ul>
 *
 *
 * <h4 class='topic'>Request Form Data</h4>
 *
 * <p>
 * Per-client or per-request form-data parameters can be specified using the following methods:
 * <ul class='javatree'>
 *    <li class='jc'>{@link Builder}
 *    <ul>
 *       <li class='jm'>{@link Builder#formData() formData()}
 *       <li class='jm'>{@link Builder#formData(String,String) formData(String,String)}
 *       <li class='jm'>{@link Builder#formData(String,Supplier) formData(String,Supplier&lt;?&gt;)}
 *       <li class='jm'>{@link Builder#formData(NameValuePair...) formDatas(NameValuePair...)}
 *       <li class='jm'>{@link Builder#formDataDefault(NameValuePair...) defaultFormData(NameValuePair...)}
 *    </ul>
 *    <li class='jc'>{@link RestRequest}
 *    <ul>
 *       <li class='jm'>{@link RestRequest#formData(String,Object) formData(String,Object)}
 *       <li class='jm'>{@link RestRequest#formData(NameValuePair...) formData(NameValuePair...)}
 *       <li class='jm'>{@link RestRequest#formDataBean(Object) formDataBean(Object)}
 *       <li class='jm'>{@link RestRequest#formDataCustom(Object) formDataCustom(Object)}
 *       <li class='jm'>{@link RestRequest#formDataPairs(String...) formDataPairs(String...)}
 *    </ul>
 * </ul>
 *
 * <h5 class='section'>Notes:</h5><ul>
 *    <li class='note'>Like header values, dynamic values and OpenAPI schemas are supported.
 *    <li class='note'>Methods that pass in POJOs convert values to strings using the part serializers.  Methods that pass in <c>NameValuePair</c>
 *       objects use the values returned by that bean directly.
 * </ul>
 *
 *
 * <h4 class='topic'>Request Body</h4>
 *
 * <p>
 * The request body can either be passed in with the client creator method (e.g. {@link RestClient#post(Object,Object) post(uri,body)}),
 * or can be specified via the following methods:
 *
 * <ul class='javatree'>
 *    <li class='jc'>{@link RestRequest}
 *    <ul>
 *       <li class='jm'>{@link RestRequest#content(Object) body(Object)}
 *       <li class='jm'>{@link RestRequest#content(Object,HttpPartSchema) body(Object,HttpPartSchema)}
 *    </ul>
 * </ul>
 *
 * <p>
 * The request body can be any of the following types:
 * <ul class='javatree'>
 *       <li class='jc'>
 *          {@link Object} - POJO to be converted to text using the {@link Serializer} defined on the client or request.
 *       <li class='jc'>
 *          {@link Reader} - Raw contents of {@code Reader} will be serialized to remote resource.
 *       <li class='jc'>
 *          {@link InputStream} - Raw contents of {@code InputStream} will be serialized to remote resource.
 *       <li class='jc'>
 *          {@link HttpResource} - Raw contents will be serialized to remote resource.  Additional headers and media type will be set on request.
 *       <li class='jc'>
 *          {@link HttpEntity} - Bypass Juneau serialization and pass HttpEntity directly to HttpClient.
 *       <li class='jc'>
 *          {@link PartList} - Converted to a URL-encoded FORM post.
 *       <li class='jc'>
 *          {@link Supplier} - A supplier of anything on this list.
 *    </ul>
 *
 * <h5 class='section'>Notes:</h5><ul>
 *    <li class='note'>If the serializer on the client or request is explicitly set to <jk>null</jk>, POJOs will be converted to strings
 *       using the registered part serializer as content type <js>"text/plain</js>.  If the part serializer is also <jk>null</jk>,
 *       POJOs will be converted to strings using {@link ClassMeta#toString(Object)} which typically just calls {@link Object#toString()}.
 * </ul>
 *
 *
 * <h4 class='topic'>Response Status</h4>
 *
 * <p>
 * After execution using {@link RestRequest#run()} or {@link RestRequest#complete()}, the following methods can be used
 * to get the response status:
 *
 * <ul class='javatree'>
 *    <li class='jc'>{@link RestResponse}
 *    <ul>
 *       <li class='jm'><c>{@link RestResponse#getStatusLine() getStatusLine()} <jk>returns</jk> {@link StatusLine}</c>
 *       <li class='jm'><c>{@link RestResponse#getStatusCode() getStatusCode()} <jk>returns</jk> <jk>int</jk></c>
 *       <li class='jm'><c>{@link RestResponse#getReasonPhrase() getReasonPhrase()} <jk>returns</jk> String</c>
 *       <li class='jm'><c>{@link RestResponse#assertStatus() assertStatus()} <jk>returns</jk> {@link FluentResponseStatusLineAssertion}</c>
 *    </ul>
 * </ul>
 *
 * <h5 class='figure'>Example:</h5>
 * <p class='bjava'>
 *    <jc>// Only interested in status code.</jc>
 *    <jk>int</jk> <jv>statusCode</jv> = <jv>client</jv>.get(<jsf>URI</jsf>).complete().getStatusCode();
 * </p>
 *
 * <p>
 * Equivalent methods with mutable parameters are provided to allow access to status values without breaking fluent call chains.
 *
 * <h5 class='figure'>Example:</h5>
 * <p class='bjava'>
 *    <jc>// Interested in multiple values.</jc>
 *    Holder&lt;Integer&gt; <jv>statusCode</jv> = Holder.<jsm>create</jsm>();
 *    Holder&lt;String&gt; <jv>reasonPhrase</jv> = Holder.<jsm>create</jsm>();
 *
 *    <jv>client</jv>.get(<jsf>URI</jsf>).complete().getStatusCode(<jv>statusCode</jv>).getReasonPhrase(<jv>reasonPhrase</jv>);
 *    System.<jsf>err</jsf>.println(<js>"statusCode="</js>+<jv>statusCode</jv>.get()+<js>", reasonPhrase="</js>+<jv>reasonPhrase</jv>.get());
 * </p>
 *
 * <h5 class='section'>Notes:</h5><ul>
 *    <li class='note'>If you are only interested in the response status and not the response body, be sure to use {@link RestRequest#complete()} instead
 *       of {@link RestRequest#run()} to make sure the response body gets automatically cleaned up.  Otherwise you must
 *       consume the response yourself.
 * </ul>
 *
 * <p>
 * The assertion method is provided for quickly asserting status codes in fluent calls.
 *
 * <h5 class='figure'>Example:</h5>
 * <p class='bjava'>
 *    <jc>// Status assertion using a static value.</jc>
 *    String <jv>body</jv> = <jv>client</jv>.get(<jsf>URI</jsf>)
 *       .run()
 *       .assertStatus().asCode().isBetween(200,399)
 *       .getContent().asString();
 *
 *    <jc>// Status assertion using a predicate.</jc>
 *    String <jv>body</jv> = <jv>client</jv>.get(<jsf>URI</jsf>)
 *       .run()
 *       .assertStatus().asCode().is(<jv>x</jv> -&gt; <jv>x</jv>&lt;400)
 *       .getContent().asString();
 * </p>
 *
 *
 * <h4 class='topic'>Response Headers</h4>
 *
 * <p>
 * Response headers are accessed through the following methods:
 *
 * <ul class='javatree'>
 *    <li class='jc'>{@link RestResponse}
 *    <ul>
 *       <li class='jm'><c>{@link RestResponse#getHeaders(String) getHeaders(String)} <jk>returns</jk> {@link ResponseHeader}[]</c>
 *       <li class='jm'><c>{@link RestResponse#getFirstHeader(String) getFirstHeader(String)} <jk>returns</jk> {@link ResponseHeader}</c>
 *       <li class='jm'><c>{@link RestResponse#getLastHeader(String) getLastHeader(String)} <jk>returns</jk> {@link ResponseHeader}</c>
 *       <li class='jm'><c>{@link RestResponse#getAllHeaders() getAllHeaders()} <jk>returns</jk> {@link ResponseHeader}[]</c>
 *       <li class='jm'><c>{@link RestResponse#getStringHeader(String) getStringHeader(String)} <jk>returns</jk> String</c>
 *       <li class='jm'><c>{@link RestResponse#containsHeader(String) containsHeader(String)} <jk>returns</jk> <jk>boolean</jk></c>
 *    </ul>
 * </ul>
 *
 * <p>
 * The {@link RestResponse#getFirstHeader(String)} and {@link RestResponse#getLastHeader(String)} methods return an empty {@link ResponseHeader} object instead of<jk>null</jk>.
 * This allows it to be used more easily in fluent calls.
 *
 * <h5 class='figure'>Example:</h5>
 * <p class='bjava'>
 *    <jc>// See if response contains Location header.</jc>
 *    <jk>boolean</jk> <jv>hasLocationHeader</jv> = <jv>client</jv>.get(<jsf>URI</jsf>).complete().getLastHeader(<js>"Location"</js>).exists();
 * </p>
 *
 * <p>
 * The {@link ResponseHeader} class extends from the HttpClient {@link Header} class and provides several convenience
 * methods:
 *
 * <ul class='javatree'>
 *    <li class='jc'>{@link ResponseHeader}
 *    <ul>
 *       <li class='jm'><c>{@link ResponseHeader#isPresent() isPresent()} <jk>returns</jk> <jk>boolean</jk></c>
 *       <li class='jm'><c>{@link ResponseHeader#asString() asString()} <jk>returns</jk> String</c>
 *       <li class='jm'><c>{@link ResponseHeader#as(Type,Type...) as(Type,Type...)} <jk>returns</jk> T</c>
 *       <li class='jm'><c>{@link ResponseHeader#as(Class) as(Class&lt;T&gt;)} <jk>returns</jk> T</c>
 *       <li class='jm'><c>{@link ResponseHeader#asMatcher(Pattern) asMatcher(Pattern)} <jk>returns</jk> {@link Matcher}</c>
 *       <li class='jm'><c>{@link ResponseHeader#asMatcher(String) asMatcher(String)} <jk>returns</jk> {@link Matcher}</c>
 *       <li class='jm'><c>{@link ResponseHeader#asHeader(Class) asHeader(Class&lt;T <jk>extends</jk> BasicHeader&gt; c)} <jk>returns</jk> {@link BasicHeader}</c>
 *       <li class='jm'><c>{@link ResponseHeader#asStringHeader() asStringHeader()} <jk>returns</jk> {@link BasicStringHeader}</c>
 *       <li class='jm'><c>{@link ResponseHeader#asIntegerHeader() asIntegerHeader()} <jk>returns</jk> {@link BasicIntegerHeader}</c>
 *       <li class='jm'><c>{@link ResponseHeader#asLongHeader() asLongHeader()} <jk>returns</jk> {@link BasicLongHeader}</c>
 *       <li class='jm'><c>{@link ResponseHeader#asDateHeader() asDateHeader()} <jk>returns</jk> {@link BasicDateHeader}</c>
 *       <li class='jm'><c>{@link ResponseHeader#asCsvHeader() asCsvHeader()} <jk>returns</jk> {@link BasicCsvHeader}</c>
 *       <li class='jm'><c>{@link ResponseHeader#asEntityTagsHeader() asEntityTagsHeader()} <jk>returns</jk> {@link BasicEntityTagsHeader}</c>
 *       <li class='jm'><c>{@link ResponseHeader#asStringRangesHeader() asStringRangesHeader()} <jk>returns</jk> {@link BasicStringRangesHeader}</c>
 *       <li class='jm'><c>{@link ResponseHeader#asUriHeader() asUriHeader()} <jk>returns</jk> {@link BasicUriHeader}</c>
 *    </ul>
 * </ul>
 *
 * <p>
 * The {@link ResponseHeader#schema(HttpPartSchema)} method allows you to perform parsing of OpenAPI formats for
 * header parts.
 *
 * <h5 class='figure'>Example:</h5>
 * <p class='bjava'>
 *    <jc>// Parse the header "Foo: bar|baz".</jc>
 *    List&lt;String&gt; <jv>fooHeader</jv> = <jv>client</jv>
 *       .get(<jsf>URI</jsf>)
 *       .complete()
 *       .getHeader(<js>"Foo"</js>).schema(<jsf>T_ARRAY_PIPES</jsf>).as(List.<jk>class</jk>, String.<jk>class</jk>);
 * </p>
 *
 * <p>
 * Assertion methods are also provided for fluent-style calls:
 *
 * <ul class='javatree'>
 *    <li class='jc'>{@link ResponseHeader}
 *    <ul>
 *       <li class='jm'><c>{@link ResponseHeader#assertValue() assertValue()} <jk>returns</jk> {@link FluentResponseHeaderAssertion}</c>
 *    </ul>
 * </ul>
 *
 * <p>
 * Note how in the following example, the fluent assertion returns control to the {@link RestResponse} object after
 * the assertion has been completed:
 *
 * <h5 class='figure'>Example:</h5>
 * <p class='bjava'>
 *    <jc>// Assert the response content type is any sort of JSON.</jc>
 *    String <jv>body</jv> = <jv>client</jv>.get(<jsf>URI</jsf>)
 *       .run()
 *       .getHeader(<js>"Content-Type"</js>).assertValue().matchesSimple(<js>"application/json*"</js>)
 *       .getContent().asString();
 * </p>
 *
 *
 * <h4 class='topic'>Response Body</h4>
 *
 * <p>
 * The response body is accessed through the following method:
 *
 * <ul class='javatree'>
 *    <li class='jc'>{@link RestResponse}
 *    <ul>
 *       <li class='jm'><c>{@link RestResponse#getContent() getContent()} <jk>returns</jk> {@link ResponseContent}</c>
 *    </ul>
 * </ul>
 *
 * <p>
 * The {@link ResponseContent} class extends from the HttpClient {@link HttpEntity} class and provides several convenience
 * methods:
 *
 * <ul class='javatree'>
 *    <li class='jc'>{@link ResponseContent}
 *    <ul>
 *       <li class='jm'><c>{@link ResponseContent#asInputStream() asInputStream()} <jk>returns</jk> InputStream</c>
 *       <li class='jm'><c>{@link ResponseContent#asReader() asReader()} <jk>returns</jk> Reader</c>
 *       <li class='jm'><c>{@link ResponseContent#asReader(Charset) asReader(Charset)} <jk>returns</jk> Reader</c>
 *       <li class='jm'><c>{@link ResponseContent#pipeTo(OutputStream) pipeTo(OutputStream)} <jk>returns</jk> {@link RestResponse}</c>
 *       <li class='jm'><c>{@link ResponseContent#pipeTo(Writer) pipeTo(Writer)} <jk>returns</jk> {@link RestResponse}</c>
 *       <li class='jm'><c>{@link ResponseContent#as(Type,Type...) as(Type,Type...)} <jk>returns</jk> T</c>
 *       <li class='jm'><c>{@link ResponseContent#as(Class) as(Class&lt;T&gt;)} <jk>returns</jk> T</c>
 *       <li class='jm'><c>{@link ResponseContent#asFuture(Class) asFuture(Class&lt;T&gt;)} <jk>returns</jk> Future&lt;T&gt;</c>
 *       <li class='jm'><c>{@link ResponseContent#asFuture(Type,Type...) asFuture(Type,Type...)} <jk>returns</jk> Future&lt;T&gt;</c>
 *       <li class='jm'><c>{@link ResponseContent#asString() asString()} <jk>returns</jk> String</c>
 *       <li class='jm'><c>{@link ResponseContent#asStringFuture() asStringFuture()} <jk>returns</jk> Future&lt;String&gt;</c>
 *       <li class='jm'><c>{@link ResponseContent#asAbbreviatedString(int) asAbbreviatedString(int)} <jk>returns</jk> String</c>
 *       <li class='jm'><c>{@link ResponseContent#asMatcher(Pattern) asMatcher(Pattern)} <jk>returns</jk> {@link Matcher}</c>
 *       <li class='jm'><c>{@link ResponseContent#asMatcher(String) asMatcher(String)} <jk>returns</jk> {@link Matcher}</c>
 *    </ul>
 * </ul>
 *
 * <br>
 *
 * <h5 class='figure'>Examples:</h5>
 * <p class='bjava'>
 *    <jc>// Parse into a linked-list of strings.</jc>
 *    List&lt;String&gt; <jv>list1</jv> = <jv>client</jv>
 *       .get(<jsf>URI</jsf>)
 *       .run()
 *       .getContent().as(LinkedList.<jk>class</jk>, String.<jk>class</jk>);
 *
 *    <jc>// Parse into a linked-list of beans.</jc>
 *    List&lt;MyBean&gt; <jv>list2</jv> = <jv>client</jv>
 *       .get(<jsf>URI</jsf>)
 *       .run()
 *       .getContent().as(LinkedList.<jk>class</jk>, MyBean.<jk>class</jk>);
 *
 *    <jc>// Parse into a linked-list of linked-lists of strings.</jc>
 *    List&lt;List&lt;String&gt;&gt; <jv>list3</jv> = <jv>client</jv>
 *       .get(<jsf>URI</jsf>)
 *       .run()
 *       .getContent().as(LinkedList.<jk>class</jk>, LinkedList.<jk>class</jk>, String.<jk>class</jk>);
 *
 *    <jc>// Parse into a map of string keys/values.</jc>
 *    Map&lt;String,String&gt; <jv>map1</jv> = <jv>client</jv>
 *       .get(<jsf>URI</jsf>)
 *       .run()
 *       .getContent().as(TreeMap.<jk>class</jk>, String.<jk>class</jk>, String.<jk>class</jk>);
 *
 *    <jc>// Parse into a map containing string keys and values of lists containing beans.</jc>
 *    Map&lt;String,List&lt;MyBean&gt;&gt; <jv>map2</jv> = <jv>client</jv>
 *       .get(<jsf>URI</jsf>)
 *       .run()
 *       .getContent().as(TreeMap.<jk>class</jk>, String.<jk>class</jk>, List.<jk>class</jk>, MyBean.<jk>class</jk>);
 * </p>
 *
 * <p>
 * The response body can only be consumed once unless it has been cached into memory.  In many cases, the body is
 * automatically cached when using the assertions methods or methods such as {@link ResponseContent#asString()}.
 * However, methods that involve reading directly from the input stream cannot be called twice.
 * In these cases, the {@link RestResponse#cacheContent()} and {@link ResponseContent#cache()} methods are provided
 * to cache the response body in memory so that you can perform several operations against it.
 *
 * <p class='bjava'>
 *    <jc>// Cache the response body so we can access it twice.</jc>
 *    InputStream <jv>inputStream</jv> = <jv>client</jv>
 *       .get(<jsf>URI</jsf>)
 *       .run()
 *       .cacheBody()
 *       .getContent().pipeTo(<jv>someOtherStream</jv>)
 *       .getContent().asInputStream();
 * </p>
 *
 * <p>
 * Assertion methods are also provided for fluent-style calls:
 *
 * <ul class='javatree'>
 *    <li class='jc'>{@link ResponseContent}
 *    <ul>
 *       <li class='jm'><c>{@link ResponseContent#assertValue() assertValue()} <jk>returns</jk> {@link FluentResponseBodyAssertion}</c>
 *    </ul>
 * </ul>
 *
 * <br>
 *
 * <h5 class='figure'>Example:</h5>
 * <p class='bjava'>
 *    <jc>// Assert that the body contains the string "Success".</jc>
 *    String <jv>body</jv> = <jv>client</jv>
 *       .get(<jsf>URI</jsf>)
 *       .run()
 *       .getContent().assertString().contains(<js>"Success"</js>)
 *       .getContent().asString();
 * </p>
 *
 * <p>
 * Object assertions allow you to parse the response body into a POJO and then perform various tests on that resulting
 * POJO.
 *
 * <h5 class='figure'>Example:</h5>
 * <p class='bjava'>
 *    <jc>// Parse bean into POJO and then validate that it was parsed correctly.</jc>
 *    MyBean <jv>bean</jv> = <jv>client</jv>.get(<jsf>URI</jsf>)
 *       .run()
 *       .getContent().assertObject(MyBean.<jk>class</jk>).asJson().is(<js>"{foo:'bar'}"</js>)
 *       .getContent().as(MyBean.<jk>class</jk>);
 * </p>
 *
 *
 * <h4 class='topic'>Custom Call Handlers</h4>
 *
 * <p>
 * The {@link RestCallHandler} interface provides the ability to provide custom handling of requests.
 *
 * <ul class='javatree'>
 *    <li class='jc'>{@link Builder}
 *    <ul>
 *       <li class='jm'>{@link Builder#callHandler() callHandler()}
 *    </ul>
 *    <li class='jic'>{@link RestCallHandler}
 *    <ul>
 *       <li class='jm'><c>{@link RestCallHandler#run(HttpHost,HttpRequest,HttpContext) run(HttpHost,HttpRequest,HttpContext)} <jk>returns</jk> HttpResponse</c>
 *    </ul>
 * </ul>
 *
 * <p>
 * Note that there are other ways of accomplishing this such as extending the {@link RestClient} class and overriding
 * the {@link #run(HttpHost,HttpRequest,HttpContext)} method
 * or by defining your own {@link HttpRequestExecutor}.  Using this interface is often simpler though.
 *
 *
 * <h4 class='topic'>Interceptors</h4>
 *
 * <p>
 * The {@link RestCallInterceptor} API provides a quick way of intercepting and manipulating requests and responses beyond
 * the existing {@link HttpRequestInterceptor} and {@link HttpResponseInterceptor} APIs.
 *
 * <ul class='javatree'>
 *    <li class='jc'>{@link Builder}
 *    <ul>
 *       <li class='jm'>{@link Builder#interceptors(Object...) interceptors(Object...)}
 *    </ul>
 *    <li class='jc'>{@link RestRequest}
 *    <ul>
 *       <li class='jm'>{@link RestRequest#interceptors(RestCallInterceptor...) interceptors(RestCallInterceptor...)}
 *    </ul>
 *    <li class='jic'>{@link RestCallInterceptor}
 *    <ul>
 *       <li class='jm'>{@link RestCallInterceptor#onInit(RestRequest) onInit(RestRequest)}
 *       <li class='jm'>{@link RestCallInterceptor#onConnect(RestRequest,RestResponse) onConnect(RestRequest,RestResponse)}
 *       <li class='jm'>{@link RestCallInterceptor#onClose(RestRequest,RestResponse) onClose(RestRequest,RestResponse)}
 *    </ul>
 * </ul>
 *
 *
 * <h4 class='topic'>Logging / Debugging</h4>
 *
 * <p>
 * The following methods provide logging of requests and responses:
 *
 * <ul class='javatree'>
 *    <li class='jc'>{@link Builder}
 *    <ul>
 *       <li class='jm'>{@link Builder#logger(Logger) logger(Logger)}
 *       <li class='jm'>{@link Builder#logToConsole() logToConsole()}
 *       <li class='jm'>{@link Builder#logRequests(DetailLevel,Level,BiPredicate) logRequests(DetailLevel,Level,BiPredicate)}
 *    </ul>
 * </ul>
 *
 * <p>
 * The following example shows the results of logging all requests that end with <c>/bean</c>.
 *
 * <h5 class='figure'>Examples:</h5>
 * <p class='bjava'>
 *    MyBean <jv>bean</jv> = RestClient
 *       .<jsm>create</jsm>()
 *       .json5()
 *       .logRequests(DetailLevel.<jsf>FULL</jsf>, Level.<jsf>SEVERE</jsf>, (<jv>req</jv>,<jv>res</jv>)-&gt;<jv>req</jv>.getUri().endsWith(<js>"/bean"</js>))
 *       .logToConsole()
 *       .build()
 *       .post(<js>"http://localhost/bean"</js>, <jv>anotherBean</jv>)
 *       .run()
 *       .getContent().as(MyBean.<jk>class</jk>);
 * </p>
 *
 * <p>
 * This produces the following console output:
 *
 * <p class='bconsole'>
 *    === HTTP Call (outgoing) ======================================================
 *    === REQUEST ===
 *    POST http://localhost/bean
 *    ---request headers---
 *       Accept: application/json5
 *    ---request entity---
 *    Content-Type: application/json5
 *    ---request content---
 *    {f:1}
 *    === RESPONSE ===
 *    HTTP/1.1 200
 *    ---response headers---
 *       Content-Type: application/json
 *    ---response content---
 *    {f:1}
 *    === END =======================================================================",
 * </p>
 *
 *
 * <p class='notes'>
 * It should be noted that if you enable request logging detail level {@link DetailLevel#FULL}, response bodies will be cached by default which may introduce
 * a performance penalty.
 *
 * <p>
 * Additionally, the following method is also provided for enabling debug mode:
 *
 * <ul class='javatree'>
 *    <li class='jc'>{@link Builder}
 *    <ul>
 *       <li class='jm'>{@link Builder#debug() debug()}
 *    </ul>
 * </ul>
 *
 * <p>
 * Enabling debug mode has the following effects:
 * <ul>
 *    <li>{@link org.apache.juneau.marshall.Context.Builder#debug() Context.Builder#debug()} is enabled.
 *    <li>{@link Builder#detectLeaks()} is enabled.
 *    <li>{@link Builder#logToConsole()} is called.
 * </ul>
 *
 *
 * <h4 class='topic'>REST Proxies</h4>
 *
 * <p>
 * One of the more powerful features of the REST client class is the ability to produce Java interface proxies against
 * arbitrary remote REST resources.
 *
 * <h5 class='figure'>Example:</h5>
 * <p class='bjava'>
 *    <jc>// Define a Remote proxy for interacting with a REST interface.</jc>
 *    <ja>@Remote</ja>(path=<js>"/petstore"</js>)
 *    <jk>public interface</jk> PetStore {
 *
 *       <ja>@RemotePost</ja>(<js>"/pets"</js>)
 *       Pet addPet(
 *          <ja>@Content</ja> CreatePet <jv>pet</jv>,
 *          <ja>@Header</ja>(<js>"E-Tag"</js>) UUID <jv>etag</jv>,
 *          <ja>@Query</ja>(<js>"debug"</js>) <jk>boolean</jk> <jv>debug</jv>
 *       );
 *    }
 *
 *    <jc>// Use a RestClient with default JSON 5 support.</jc>
 *    RestClient <jv>client</jv> = RestClient.<jsm>create</jsm>().json5().build())
 *
 *    PetStore <jv>store</jv> = <jv>client</jv>.getRemote(PetStore.<jk>class</jk>, <js>"http://localhost:10000"</js>);
 *    CreatePet <jv>createPet</jv> = <jk>new</jk> CreatePet(<js>"Fluffy"</js>, 9.99);
 *    Pet <jv>pet</jv> = <jv>store</jv>.addPet(<jv>createPet</jv>, UUID.<jsm>randomUUID</jsm>(), <jk>true</jk>);
 * </p>
 *
 * <p>
 * The methods to retrieve remote interfaces are:
 *
 * <ul class='javatree'>
 *    <li class='jc'>{@link RestClient}
 *    <ul>
 *       <li class='jm'><c>{@link RestClient#getRemote(Class) getRemote(Class&lt;T&gt;)} <jk>returns</jk> T</c>
 *       <li class='jm'><c>{@link RestClient#getRemote(Class,Object) getRemote(Class&lt;T&gt;,Object)} <jk>returns</jk> T</c>
 *       <li class='jm'><c>{@link RestClient#getRemote(Class,Object,Serializer,Parser) getRemote(Class&lt;T&gt;,Object,Serializer,Parser)} <jk>returns</jk> T</c>
 *       <li class='jm'><c>{@link RestClient#getRrpcInterface(Class) getRrpcInterface(Class&lt;T&gt;)} <jk>returns</jk> T</c>
 *       <li class='jm'><c>{@link RestClient#getRrpcInterface(Class,Object) getRrpcInterface(Class&lt;T&gt;,Object)} <jk>returns</jk> T</c>
 *       <li class='jm'><c>{@link RestClient#getRrpcInterface(Class,Object,Serializer,Parser) getRrpcInterface(Class&lt;T&gt;,Object,Serializer,Parser)} <jk>returns</jk> T</c>
 *    </ul>
 * </ul>
 *
 * <p>
 * Two basic types of remote interfaces are provided:
 *
 * <ul class='spaced-list'>
 *    <li>{@link Remote @Remote}-annotated interfaces.  These can be defined against arbitrary external REST resources.
 *    <li>RPC-over-REST interfaces.  These are Java interfaces that allow you to make method calls on server-side POJOs.
 * </ul>
 *
 * <p>
 * Refer to the following documentation on both flavors:
 *
 * <ul class='doctree'>
 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestProxies">REST Proxies</a>
 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestRpc">REST/RPC</a>
 * </ul>
 *
 * <br>
 * <hr>
 * <h4 class='topic'>Customizing Apache HttpClient</h4>
 *
 * <p>
 * Several methods are provided for customizing the underlying HTTP client and client builder classes:
 * <ul class='javatree'>
 *    <li class='jc'>{@link Builder}
 *    <ul>
 *       <li class='jm'>{@link Builder#httpClientBuilder(HttpClientBuilder) httpClientBuilder(HttpClientBuilder)} - Set the client builder yourself.
 *       <li class='jm'>{@link Builder#createHttpClientBuilder() createHttpClientBuilder()} - Override to create the client builder.
 *       <li class='jm'>{@link Builder#createHttpClient() createHttpClient()} - Override to create the client.
 *       <li class='jm'>{@link Builder#createConnectionManager() createConnectionManager()} - Override to create the connection management.
 *    </ul>
 * </ul>
 *
 * <p>
 * Additionally, all methods on the <c>HttpClientBuilder</c> class have been extended with fluent setters.
 *
 * <h5 class='figure'>Example:</h5>
 * <p class='bjava'>
 *    <jc>// Create a client with customized HttpClient settings.</jc>
 *    MyBean <jv>bean</jv> = RestClient
 *       .<jsm>create</jsm>()
 *       .disableRedirectHandling()
 *       .connectionManager(<jv>myConnectionManager</jv>)
 *       .addInterceptorFirst(<jv>myHttpRequestInterceptor</jv>)
 *       .build();
 * </p>
 *
 * <p>
 * Refer to the {@link HttpClientBuilder HTTP Client Builder API} for more information.
 *
 *
 * <h4 class='topic'>Extending RestClient</h4>
 *
 * <p>
 * The <c>RestClient</c> API has been designed to allow for the ability to be easily extended.
 * The following example that overrides the primary run method shows how this can be done.
 *
 * <h5 class='figure'>Example:</h5>
 * <p class='bjava'>
 *    <jk>public class</jk> MyRestClient <jk>extends</jk> RestClient {
 *
 *       <jc>// Must provide this constructor!</jc>
 *       <jk>public</jk> MyRestClient(RestClient.Builder&lt;?&gt; <jv>builder</jv>) {
 *          <jk>super</jk>(<jv>builder</jv>);
 *       }
 *
 *       <jd>/** Optionally override to customize builder settings before initialization. </jd>
 *       <ja>@Override</ja>
 *       <jk>protected void</jk> init(RestClient.Builder&lt;?&gt;) {...}
 *
 *       <jd>/** Optionally override to provide post-initialization (e.g. setting up SAML handshakes, etc...). </jd>
 *       <ja>@Override</ja>
 *       <jk>protected void</jk> init() {...}
 *
 *       <jd>/** Optionally override to customize requests when they're created (e.g. add headers to each request). </jd>
 *       <ja>@Override</ja>
 *       <jk>protected</jk> RestRequest request(RestOperation) {...}
 *
 *       <jd>/** Optionally override to implement your own call handling. </jd>
 *       <ja>@Override</ja>
 *       <jk>protected</jk> HttpResponse run(HttpHost, HttpRequest, HttpContext) {...}
 *
 *       <jd>/** Optionally override to customize requests before they're executed. </jd>
 *       <ja>@Override</ja>
 *       <jk>protected void</jk> onCallInit(RestRequest) {...}
 *
 *       <jd>/** Optionally override to customize responses as soon as a connection is made. </jd>
 *       <ja>@Override</ja>
 *       <jk>protected void</jk> onCallConnect(RestRequest, RestResponse) {...}
 *
 *       <jd>/** Optionally override to perform any call cleanup. </jd>
 *       <ja>@Override</ja>
 *       <jk>protected void</jk> onCallClose(RestRequest, RestResponse) {...}
 *    }
 *
 *    <jc>// Instantiate your client.</jc>
 *    MyRestClient <jv>client</jv> = RestClient.<jsm>create</jsm>().json().build(MyRestClient.<jk>class</jk>);
 * </p>
 *
 * <p>
 * The {@link RestRequest} and {@link RestResponse} objects can also be extended and integrated by overriding the
 * {@link RestClient#createRequest(URI,String,boolean)} and {@link RestClient#createResponse(RestRequest,HttpResponse,Parser)} methods.
 *
 * <h5 class='section'>Notes:</h5><ul>
 *    <li class='note'>This class is thread safe and reusable.
 * </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:S106", // System.err is the intentional default fallback for the configurable console PrintStream
   "java:S112", // Builder.interceptors(Class...), executeRemoteWithRetry(), materializeRemote() and throwRemoteError() declare throws Exception because remote-proxy calls surface arbitrary checked exceptions
   "java:S115", // Constants use UPPER_snakeCase naming convention
   "java:S1133", // Deprecated override required by HttpClient interface
   "java:S1192", // Duplicated literals (argument/property names) read more clearly inline than as constants
   "java:S3776", // buildRemoteRequest(), executeRemoteWithRetry(), callback() and getRrpcInterface() are branch-heavy remote-call orchestration; splitting them would obscure the flow
   "java:S6539", // Monster class; RestClient is intentionally a single fluent builder/client aggregating config, call orchestration, and remote-proxy wiring
   "rawtypes", // Raw types necessary for generic type handling.
   "resource", // Resource management handled externally
   "unchecked" // Casts in getInstance() (Class<? extends Serializer/Parser>) and in the getRemote()/getRrpcInterface() Proxy.newProxyInstance results are guarded by isAssignableFrom checks and the proxied interface type
})
public class RestClient extends MarshallingContextable implements HttpClient, Closeable {

   // Argument name constants for reqnn
   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;

   /**
    * Builder class.
    */
   @SuppressWarnings({
      "java:S119" // 'SELF' (CRTP self-type) is intentional and clearer than a single-letter name.
   })
   public abstract static class Builder<SELF extends Builder<SELF>> extends MarshallingContextable.Builder<SELF> {

      private BeanInstantiator.Builder<RestCallHandler> callHandler;
      private final WritableBeanStore beanStore = new BasicBeanStore();
      private BiPredicate<RestRequest,RestResponse> logRequestsPredicate;
      private boolean detectLeaks;
      private boolean allowPrivateUrls;
      private final List<String> allowedAddressRanges = new ArrayList<>();
      private boolean executorServiceShutdownOnClose;
      private boolean ignoreErrors;
      private boolean keepHttpClientOpen;
      private boolean logToConsole;
      private boolean pooled;
      private boolean skipEmptyFormData;
      private boolean skipEmptyHeaderData;
      private boolean skipEmptyQueryData;
      private CloseableHttpClient httpClient;
      private DetailLevel logRequests;
      private ExecutorService executorService;
      private HeaderList headerData;
      private HttpClientBuilder httpClientBuilder;
      private HttpClientConnectionManager connectionManager;
      // The instance the default createConnectionManager() last returned; only that one can be given a pinned twin.
      private HttpClientConnectionManager defaultConnectionManager;
      // The socket-factory registry and pool settings of defaultConnectionManager, which its pinned twin shares.
      private Registry<ConnectionSocketFactory> defaultRegistry;
      private PoolSettings defaultPoolSettings;
      // TLS and pool settings, applied to both pools of the connection manager the default createConnectionManager()
      // builds (HttpClientBuilder ignores its own copies once a connection manager is set).
      private HostnameVerifier sslHostnameVerifier;
      private LayeredConnectionSocketFactory sslSocketFactory;
      private SSLContext sslContext;
      private int maxConnPerRoute;
      private int maxConnTotal;
      private ConnectionConfig defaultConnectionConfig;
      private SocketConfig defaultSocketConfig;
      private PublicSuffixMatcher publicSuffixMatcher;
      private long connTimeToLive;
      private TimeUnit connTimeToLiveTimeUnit;
      private boolean systemProperties;
      // Set by the default createHttpClient() to the two-pool router it installed for SSRF-guard-active @Remote calls.
      private SsrfGuardConnectionManager ssrfGuard;
      // Set by the default createHttpClient(): whether the default createConnectionManager() (not an override, which may
      // hand the same instance to several clients) created both of ssrfGuard's pools, which no caller can then reach,
      // so the client shuts them down on close() even when the connection manager is shared.
      private boolean ownsConnectionManager;
      private HttpPartParser.Creator partParser;
      private HttpPartSerializer.Creator partSerializer;
      private Level logRequestsLevel;
      private Logger logger;
      private PartList formData;
      private PartList pathData;
      private PartList queryData;
      private ParserSet.Builder parsers;
      private Predicate<Integer> errorCodes = x -> x <= 0 || x >= 400;
      private PrintStream console;
      private SerializerSet.Builder serializers;
      private Supplier<String> rootUrl;
      private UrlEncodingSerializer.Builder urlEncodingSerializer;
      List<RestCallInterceptor> interceptors;

      /**
       * Constructor.
       */
      protected Builder() {}

      /**
       * Appends an <c>Accept</c> header on this request.
       *
       * <p>
       * This is a shortcut for calling <c>headerData().append(Accept.<jsm>of</jsm>(<jv>value</jv>))</c>.
       *
       * @param value
       *    The new header value.
       *    <br>Can be <jk>null</jk> (no Accept header will be added).
       * @return This object.
       * @see #headers()
       */
      public SELF accept(String value) {
         return headers(Accept.of(value));
      }

      /**
       * Sets the value for the <c>Accept-Charset</c> request header on all requests.
       *
       * <p>
       * This is a shortcut for calling <c>headerData().append(AcceptCharset.<jsm>of</jsm>(<jv>value</jv>))</c>.
       *
       * @param value The new header value.
       *    <br>Can be <jk>null</jk> (no Accept-Charset header will be added).
       * @return This object.
       * @see #headers()
       */
      public SELF acceptCharset(String value) {
         return headers(AcceptCharset.of(value));
      }

      /**
       * <i><l>Serializer</l> configuration property:&emsp;</i>  Add <js>"_type"</js> properties when needed.
       *
       * <p>
       * When enabled, <js>"_type"</js> properties will be added to beans if their type cannot be inferred
       * through reflection.
       *
       * <p>
       * This is used to recreate the correct objects during parsing if the object types cannot be inferred.
       * <br>For example, when serializing a <c>Map&lt;String,Object&gt;</c> field where the bean class cannot be determined from
       * the type of the values.
       *
       * <p>
       * Note the differences between the following settings:
       * <ul class='javatree'>
       *    <li class='jf'>{@link #addRootType()} - Affects whether <js>'_type'</js> is added to root node.
       *    <li class='jf'>{@link #addBeanTypes()} - Affects whether <js>'_type'</js> is added to any nodes.
       * </ul>
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a JSON client that adds _type to nodes in the request body.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .json()
       *       .addBeanTypes()
       *       .build();
       *
       *    <jc>// Our map of beans to serialize.</jc>
       *    <ja>@Marshalled</ja>(typeName=<js>"mybean"</js>)
       *    <jk>public class</jk> MyBean {
       *       <jk>public</jk> String <jf>foo</jf> = <js>"bar"</js>;
       *    }
       *
       *    AMap <jv>map</jv> = AMap.of(<js>"foo"</js>, <jk>new</jk> MyBean());
       *
       *    <jc>// Request body will contain:  {"foo":{"_type":"mybean","foo":"bar"}}</jc>
       *    <jv>client</jv>
       *       .post(<js>"http://localhost:10000/foo"</js>, <jv>map</jv>)
       *       .run();
       * </p>
       *
       * <h5 class='section'>See Also:</h5><ul>
       *    <li class='jm'>{@link org.apache.juneau.marshall.serializer.Serializer.Builder#addBeanTypes() Serializer.Builder#addBeanTypes()}
       * </ul>
       *
       * @return This object.
       */
      public SELF addBeanTypes() {
         serializers().forEach(Serializer.Builder::addBeanTypes);
         return self();
      }

      /**
       * Adds this protocol interceptor to the head of the protocol processing list.
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='note'>This value can be overridden by the {@link #httpProcessor(HttpProcessor)} method.
       * </ul>
       *
       * @param itcp New property value.
       *    <br>Cannot be <jk>null</jk>.
       * @return This object.
       * @see HttpClientBuilder#addInterceptorFirst(HttpRequestInterceptor)
       */
      public SELF addInterceptorFirst(HttpRequestInterceptor itcp) {
         httpClientBuilder().addInterceptorFirst(reqnn("itcp", itcp));
         return self();
      }

      /**
       * Adds this protocol interceptor to the head of the protocol processing list.
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='note'>This value can be overridden by the {@link #httpProcessor(HttpProcessor)} method.
       * </ul>
       *
       * @param itcp New property value.
       *    <br>Cannot be <jk>null</jk>.
       * @return This object.
       * @see HttpClientBuilder#addInterceptorFirst(HttpResponseInterceptor)
       */
      public SELF addInterceptorFirst(HttpResponseInterceptor itcp) {
         httpClientBuilder().addInterceptorFirst(reqnn("itcp", itcp));
         return self();
      }

      /**
       * Adds this protocol interceptor to the tail of the protocol processing list.
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='note'>This value can be overridden by the {@link #httpProcessor(HttpProcessor)} method.
       * </ul>
       *
       * @param itcp New property value.
       *    <br>Cannot be <jk>null</jk>.
       * @return This object.
       * @see HttpClientBuilder#addInterceptorLast(HttpRequestInterceptor)
       */
      public SELF addInterceptorLast(HttpRequestInterceptor itcp) {
         httpClientBuilder().addInterceptorLast(reqnn("itcp", itcp));
         return self();
      }

      /**
       * Adds this protocol interceptor to the tail of the protocol processing list.
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='note'>This value can be overridden by the {@link #httpProcessor(HttpProcessor)} method.
       * </ul>
       *
       * @param itcp New property value.
       *    <br>Cannot be <jk>null</jk>.
       * @return This object.
       * @see HttpClientBuilder#addInterceptorLast(HttpResponseInterceptor)
       */
      public SELF addInterceptorLast(HttpResponseInterceptor itcp) {
         httpClientBuilder().addInterceptorLast(reqnn("itcp", itcp));
         return self();
      }

      /**
       * <i><l>Serializer</l> configuration property:&emsp;</i>  Add type attribute to root nodes.
       *
       * <p>
       * When enabled, <js>"_type"</js> properties will be added to top-level beans.
       *
       * <p>
       * When disabled, it is assumed that the parser knows the exact Java POJO type being parsed, and therefore top-level
       * type information that might normally be included to determine the data type will not be serialized.
       *
       * <p>
       * For example, when serializing a top-level POJO with a {@link Marshalled#typeName() @Marshalled(typeName)} value, a
       * <js>'_type'</js> attribute will only be added when this setting is enabled.
       *
       * <p>
       * Note the differences between the following settings:
       * <ul class='javatree'>
       *    <li class='jf'>{@link #addRootType()} - Affects whether <js>'_type'</js> is added to root node.
       *    <li class='jf'>{@link #addBeanTypes()} - Affects whether <js>'_type'</js> is added to any nodes.
       * </ul>
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a JSON client that adds _type to root node.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .json()
       *       .addRootType()
       *       .build();
       *
       *    <jc>// Our bean to serialize.</jc>
       *    <ja>@Marshalled</ja>(typeName=<js>"mybean"</js>)
       *    <jk>public class</jk> MyBean {
       *       <jk>public</jk> String <jf>foo</jf> = <js>"bar"</js>;
       *    }
       *
       *    <jc>// Request body will contain:  {"_type":"mybean","foo":"bar"}</jc>
       *    <jv>client</jv>
       *       .post(<js>"http://localhost:10000/foo"</js>, <jk>new</jk> MyBean())
       *       .run();
       * </p>
       *
       * <h5 class='section'>See Also:</h5><ul>
       *    <li class='jm'>{@link org.apache.juneau.marshall.serializer.Serializer.Builder#addRootType() Serializer.Builder#addRootType()}
       * </ul>
       *
       * @return This object.
       */
      public SELF addRootType() {
         serializers().forEach(Serializer.Builder::addRootType);
         return self();
      }

      /**
       * Assigns {@link BackoffManager} instance.
       *
       * @param backoffManager New property value.
       *    <br>Can be <jk>null</jk> (value will not be set, default behavior will be used).
       * @return This object.
       * @see HttpClientBuilder#setBackoffManager(BackoffManager)
       */
      public SELF backoffManager(BackoffManager backoffManager) {
         httpClientBuilder().setBackoffManager(backoffManager);
         return self();
      }

      /**
       * Set up this client to use BASIC auth.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Construct a client that uses BASIC authentication.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .basicAuth(<js>"http://localhost"</js>, 80, <js>"me"</js>, <js>"mypassword"</js>)
       *       .build();
       * </p>
       *
       * @param host The auth scope hostname.
       *    <br>Can be <jk>null</jk> (will use <js>"*"</js> as the hostname).
       * @param port The auth scope port.
       * @param user The username.
       *    <br>Can be <jk>null</jk> (will use empty string).
       * @param pw The password.
       *    <br>Can be <jk>null</jk> (will use empty string).
       * @return This object.
       */
      public SELF basicAuth(String host, int port, String user, String pw) {
         var scope = new AuthScope(host, port);
         var up = new UsernamePasswordCredentials(user, pw);
         var p = new BasicCredentialsProvider();
         p.setCredentials(scope, up);
         defaultCredentialsProvider(p);
         return self();
      }

      @Override /* Overridden from Context.Builder<?> */
      public RestClient build() {
         // Validated here, ahead of the reflective construction, so a bad entry surfaces as the IllegalArgumentException itself.
         RemoteUrlPolicy.AllowedRanges.of(allowedAddressRanges.toArray(new String[0]));
         return build(RestClient.class);
      }

      /**
       * Returns the creator for the rest call handler.
       *
       * <p>
       * Allows you to provide a custom handler for making HTTP calls.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a client that handles processing of requests using a custom handler.</jc>
       *    <jk>public class</jk> MyRestCallHandler <jk>implements</jk> RestCallHandler {
       *
       *       <ja>@Override</ja>
       *       <jk>public</jk> HttpResponse run(HttpHost <jv>target</jv>, HttpRequest <jv>request</jv>, HttpContext <jv>context</jv>) <jk>throws</jk> IOException {
       *          <jc>// Custom handle requests.</jc>
       *       }
       *    }
       *
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .callHandler(MyRestCallHandler.<jk>class</jk>)
       *       .build();
       * </p>
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='warn'>The SSRF guard of {@code @Remote} calls travels on the request's {@link HttpContext}, and a
       *       custom handler may copy the request, or send it with another context, without it.  So a client with any handler other than
       *       {@link BasicRestCallHandler} itself, or with a {@code BasicRestCallHandler} bound to a different client
       *       (through {@code impl(...)}), refuses every SSRF-guard-active {@code @Remote} call (one without the
       *       {@link #allowPrivateUrls(boolean) allowPrivateUrls} opt-in).  Ordinary requests are unaffected.
       *    <li class='note'>
       *       The {@link RestClient#run(HttpHost, HttpRequest, HttpContext)} method can also be overridden to produce the same results.
       *       The same SSRF restriction applies: a client whose class overrides that method or either
       *       {@code execute(...)} overload it dispatches to refuses SSRF-guard-active {@code @Remote} calls too.
       *    <li class='note'>
       *       Use {@link org.apache.juneau.commons.inject.BeanInstantiator.Builder BeanInstantiator.Builder} <c>impl(Object)</c> to specify an already instantiated instance.
       *    <li class='note'>
       *       Use {@link org.apache.juneau.commons.inject.BeanInstantiator.Builder BeanInstantiator.Builder} <c>type(Class)</c> to specify a subtype to instantiate.
       *       <br>Subclass must have a public constructor that takes in any args available
       *       in the bean store of this builder (including {@link RestClient} itself).
       * </ul>
       *
       * <h5 class='section'>See Also:</h5><ul>
       *    <li class='jic'>{@link RestCallHandler}
       * </ul>
       *
       * @return The instantiator for the rest call handler.
       */
      public final BeanInstantiator.Builder<RestCallHandler> callHandler() {
         if (callHandler == null)
            callHandler = createCallHandler();
         return callHandler;
      }

      /**
       * REST call handler class.
       *
       * <p>
       * Specifies a custom handler for making HTTP calls.
       *
       * <p>
       * This is a shortcut for <c>callHandler().type(<jv>value</jv>)</c>.
       *
       * @param value
       *    The new value for this setting.
       *    <br>Cannot be <jk>null</jk>.
       * @return This object.
       * @see #callHandler()
       */
      public SELF callHandler(Class<? extends RestCallHandler> value) {
         callHandler().type(reqnn("value", value));
         return self();
      }

      /**
       * Sets the client version by setting the value for the <js>"Client-Version"</js> header.
       *
       * <p>
       * This is a shortcut for calling <c>headerData().append(ClientVersion.<jsm>of</jsm>(<jv>value</jv>))</c>.
       *
       * @param value The version string (e.g. <js>"1.2.3"</js>)
       *    <br>Can be <jk>null</jk> (no Client-Version header will be added).
       * @return This object.
       * @see #headers()
       */
      public SELF clientVersion(String value) {
         return headers(ClientVersion.of(value));
      }

      /**
       * Assigns {@link ConnectionBackoffStrategy} instance.
       *
       * @param connectionBackoffStrategy New property value.
       *    <br>Can be <jk>null</jk> (value will not be set, default behavior will be used).
       * @return This object.
       * @see HttpClientBuilder#setConnectionBackoffStrategy(ConnectionBackoffStrategy)
       */
      public SELF connectionBackoffStrategy(ConnectionBackoffStrategy connectionBackoffStrategy) {
         httpClientBuilder().setConnectionBackoffStrategy(connectionBackoffStrategy);
         return self();
      }

      /**
       * Assigns {@link HttpClientConnectionManager} instance.
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='warn'>This client cannot pin the connections of a connection manager it did not create, so a
       *       client built with one refuses every SSRF-guard-active {@code @Remote} call (one without the
       *       {@link #allowPrivateUrls(boolean) allowPrivateUrls} opt-in).  Ordinary requests are unaffected.
       * </ul>
       *
       * @param value New property value.
       *    <br>Can be <jk>null</jk> (value will not be set, a default connection manager will be created).
       * @return This object.
       * @see HttpClientBuilder#setConnectionManager(HttpClientConnectionManager)
       */
      public SELF connectionManager(HttpClientConnectionManager value) {
         connectionManager = value;
         httpClientBuilder().setConnectionManager(value);
         return self();
      }

      /**
       * Defines the connection manager is to be shared by multiple client instances.
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='note'>If the connection manager is shared its life-cycle is expected to be managed by the caller and it will not be shut down if the client is closed.
       *       This applies to a connection manager supplied through {@link #connectionManager(HttpClientConnectionManager)}
       *       or returned by an overridden {@link #createConnectionManager()} (even one that calls {@code super}, since the
       *       override may hand the same instance to several clients).  The connection manager the default
       *       {@link #createConnectionManager()} builds for a client cannot be reached by the caller, so it is never
       *       shared: {@link RestClient#close()} shuts it down.
       *    <li class='note'>The client's internal pool for SSRF-guard-active {@code @Remote} calls (see {@link #createConnectionManager()})
       *       is never shared, and {@link RestClient#close()} still shuts it down.  Combined with {@link #keepHttpClientOpen()},
       *       though, nothing shuts that internal pool (or the default connection manager) down; their connections stay
       *       open until they are closed as idle or the JVM exits.
       * </ul>
       *
       * @param shared New property value.
       * @return This object.
       * @see HttpClientBuilder#setConnectionManagerShared(boolean)
       */
      public SELF connectionManagerShared(boolean shared) {
         httpClientBuilder().setConnectionManagerShared(shared);
         return self();
      }

      /**
       * Assigns {@link ConnectionReuseStrategy} instance.
       *
       * @param reuseStrategy New property value.
       *    <br>Can be <jk>null</jk> (value will not be set, default behavior will be used).
       * @return This object.
       * @see HttpClientBuilder#setConnectionReuseStrategy(ConnectionReuseStrategy)
       */
      public SELF connectionReuseStrategy(ConnectionReuseStrategy reuseStrategy) {
         httpClientBuilder().setConnectionReuseStrategy(reuseStrategy);
         return self();
      }

      /**
       * Sets maximum time to live for persistent connections.
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='note'>It is applied to both pools of the connection manager the default {@link #createConnectionManager()}
       *       builds.  It has no effect on a connection manager supplied through
       *       {@link #connectionManager(HttpClientConnectionManager)} or an overridden {@link #createConnectionManager()}.
       *    <li class='note'>A positive value makes that connection manager a {@link PoolingHttpClientConnectionManager}, as
       *       {@link #pooled()} does: {@link BasicHttpClientConnectionManager} has no time-to-live.
       * </ul>
       *
       * @param connTimeToLive New property value.
       * @param connTimeToLiveTimeUnit New property value.
       *    <br>Cannot be <jk>null</jk>.
       * @return This object.
       * @see HttpClientBuilder#setConnectionTimeToLive(long,TimeUnit)
       */
      public SELF connectionTimeToLive(long connTimeToLive, TimeUnit connTimeToLiveTimeUnit) {
         this.connTimeToLive = connTimeToLive;
         this.connTimeToLiveTimeUnit = connTimeToLiveTimeUnit;
         httpClientBuilder().setConnectionTimeToLive(connTimeToLive, connTimeToLiveTimeUnit);
         return self();
      }

      /**
       * Console print stream
       *
       * <p>
       * Allows you to redirect the console output to a different print stream.
       *
       * @param value
       *    The new value for this setting.
       *    <br>Can be <jk>null</jk> (defaults to <c>System.err</c>).
       * @return This object.
       */
      public SELF console(PrintStream value) {
         console = value;
         return self();
      }

      /**
       * Assigns a map of {@link org.apache.http.client.entity.InputStreamFactory InputStreamFactories} to be used for automatic content decompression.
       *
       * @param contentDecoderMap New property value.
       *    <br>Can be <jk>null</jk> (value will not be set, default behavior will be used).
       * @return This object.
       * @see HttpClientBuilder#setContentDecoderRegistry(Map)
       */
      public SELF contentDecoderRegistry(Map<String,InputStreamFactory> contentDecoderMap) {
         httpClientBuilder().setContentDecoderRegistry(contentDecoderMap);
         return self();
      }

      /**
       * Sets the value for the <c>Content-Type</c> request header on all requests.
       *
       * <p>
       * This is a shortcut for calling <c>headerData().append(ContentType.<jsm>of</jsm>(<jv>value</jv>))</c>.
       *
       * <p>
       * This overrides the media type specified on the serializer.
       *
       * @param value The new header value.
       *    <br>Can be <jk>null</jk> (no Content-Type header will be added).
       * @return This object.
       * @see #headers()
       */
      public SELF contentType(String value) {
         return headers(ContentType.of(value));
      }

      @Override /* Overridden from Context.Builder<?> */
      public SELF copy() {
         throw new NoSuchMethodError("Not implemented.");
      }

      /**
       * Sets the value for the <c>Debug</c> request header on all requests.
       *
       * <p>
       * This is a shortcut for calling <c>headerData().append(Debug.<jsm>of</jsm>(<jv>value</jv>))</c>.
       *
       * @return This object.
       * @see #headers()
       */
      @Override
      public SELF debug() {
         super.debug();
         serializers().forEach(Serializer.Builder::debug);
         return headers(Debug.TRUE);
      }

      /**
       * <i><l>Parser</l> configuration property:&emsp;</i>  Debug output lines.
       *
       * <p>
       * When parse errors occur, this specifies the number of lines of input before and after the
       * error location to be printed as part of the exception message.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a parser whose exceptions print out 100 lines before and after the parse error location.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .json()
       *       .debug()  <jc>// Enable debug mode to capture Reader contents as strings.</jc>
       *       .debugOuputLines(100)
       *       .build();
       *
       *    <jc>// Try to parse some bad JSON.</jc>
       *    <jk>try</jk> {
       *       <jv>client</jv>
       *          .get(<js>"/pathToBadJson"</js>)
       *          .run()
       *          .getContent().as(Object.<jk>class</jk>);  <jc>// Try to parse it.</jc>
       *    } <jk>catch</jk> (RestCallException <jv>e</jv>) {
       *       System.<jsf>err</jsf>.println(<jv>e</jv>.getMessage());  <jc>// Will display 200 lines of the output.</jc>
       *    }
       * </p>
       *
       * <h5 class='section'>See Also:</h5><ul>
       *    <li class='jm'>{@link org.apache.juneau.marshall.parser.Parser.Builder#debugOutputLines(int) Parser.Builder#debugOutputLines(int)}
       * </ul>
       *
       * @param value
       *    The new value for this property.
       *    <br>The default value is <c>5</c>.
       * @return This object.
       */
      public SELF debugOutputLines(int value) {
         parsers().forEach(x -> x.debugOutputLines(value));
         return self();
      }

      /**
       * Assigns default {@link org.apache.http.auth.AuthScheme} registry which will be used for request execution if not explicitly set in the client execution context.
       *
       * @param authSchemeRegistry New property value.
       *    <br>Can be <jk>null</jk> (value will not be set, default behavior will be used).
       * @return This object.
       * @see HttpClientBuilder#setDefaultAuthSchemeRegistry(Lookup)
       */
      public SELF defaultAuthSchemeRegistry(Lookup<AuthSchemeProvider> authSchemeRegistry) {
         httpClientBuilder().setDefaultAuthSchemeRegistry(authSchemeRegistry);
         return self();
      }

      /**
       * Assigns default {@link ConnectionConfig}.
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='note'>It is applied to both pools of the connection manager the default {@link #createConnectionManager()}
       *       builds.  It has no effect on a connection manager supplied through
       *       {@link #connectionManager(HttpClientConnectionManager)} or an overridden {@link #createConnectionManager()}.
       * </ul>
       *
       * @param config New property value.
       *    <br>Can be <jk>null</jk> (value will not be set, default behavior will be used).
       * @return This object.
       * @see HttpClientBuilder#setDefaultConnectionConfig(ConnectionConfig)
       */
      public SELF defaultConnectionConfig(ConnectionConfig config) {
         this.defaultConnectionConfig = config;
         httpClientBuilder().setDefaultConnectionConfig(config);
         return self();
      }

      /**
       * Assigns default {@link CookieSpec} registry which will be used for request execution if not explicitly set in the client execution context.
       *
       * @param cookieSpecRegistry New property value.
       *    <br>Can be <jk>null</jk> (value will not be set, default behavior will be used).
       * @return This object.
       * @see HttpClientBuilder#setDefaultCookieSpecRegistry(Lookup)
       */
      public SELF defaultCookieSpecRegistry(Lookup<CookieSpecProvider> cookieSpecRegistry) {
         httpClientBuilder().setDefaultCookieSpecRegistry(cookieSpecRegistry);
         return self();
      }

      /**
       * Assigns default {@link CookieStore} instance which will be used for request execution if not explicitly set in the client execution context.
       *
       * @param cookieStore New property value.
       *    <br>Can be <jk>null</jk> (value will not be set, default behavior will be used).
       * @return This object.
       * @see HttpClientBuilder#setDefaultCookieStore(CookieStore)
       */
      public SELF defaultCookieStore(CookieStore cookieStore) {
         httpClientBuilder().setDefaultCookieStore(cookieStore);
         return self();
      }

      /**
       * Assigns default {@link CredentialsProvider} instance which will be used for request execution if not explicitly set in the client execution context.
       *
       * @param credentialsProvider New property value.
       *    <br>Can be <jk>null</jk> (value will not be set, default behavior will be used).
       * @return This object.
       * @see HttpClientBuilder#setDefaultCredentialsProvider(CredentialsProvider)
       */
      public SELF defaultCredentialsProvider(CredentialsProvider credentialsProvider) {
         httpClientBuilder().setDefaultCredentialsProvider(credentialsProvider);
         return self();
      }

      /**
       * Assigns default {@link RequestConfig} instance which will be used for request execution if not explicitly set in the client execution context.
       *
       * @param config New property value.
       *    <br>Can be <jk>null</jk> (value will not be set, default behavior will be used).
       * @return This object.
       * @see HttpClientBuilder#setDefaultRequestConfig(RequestConfig)
       */
      public SELF defaultRequestConfig(RequestConfig config) {
         httpClientBuilder().setDefaultRequestConfig(config);
         return self();
      }

      /**
       * Assigns default {@link SocketConfig}.
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='note'>It is applied to both pools of the connection manager the default {@link #createConnectionManager()}
       *       builds.  It has no effect on a connection manager supplied through
       *       {@link #connectionManager(HttpClientConnectionManager)} or an overridden {@link #createConnectionManager()}.
       * </ul>
       *
       * @param config New property value.
       *    <br>Can be <jk>null</jk> (value will not be set, default behavior will be used).
       * @return This object.
       * @see HttpClientBuilder#setDefaultSocketConfig(SocketConfig)
       */
      public SELF defaultSocketConfig(SocketConfig config) {
         this.defaultSocketConfig = config;
         httpClientBuilder().setDefaultSocketConfig(config);
         return self();
      }

      /**
       * <i><l>RestClient</l> configuration property:&emsp;</i>  Enable leak detection.
       *
       * <p>
       * Enable client and request/response leak detection.
       *
       * <p>
       * Causes messages to be logged to the console if clients or request/response objects are not properly closed
       * when the <c>finalize</c> methods are invoked.
       *
       * <p>
       * Automatically enabled with {@link org.apache.juneau.marshall.Context.Builder#debug() Context.Builder#debug()}.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a client that logs a message if </jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .detectLeaks()
       *       .logToConsole()  <jc>// Also log the error message to System.err</jc>
       *       .build();
       *
       *    <jv>client</jv>.closeQuietly();  <jc>// Customized HttpClient won't be closed.</jc>
       * </p>
       *
       * @return This object.
       */
      public SELF detectLeaks() {
         detectLeaks = true;
         return self();
      }

      /**
       * Opts every {@code @Remote}/{@code @Url} call made through this client out of the default deny-private SSRF
       * guardrail (see {@code org.apache.juneau.http.remote.RemoteUrlPolicy}), for local-dev/intranet targets that
       * are intentionally private.
       *
       * <p>
       * The effective per-call value is the logical OR of this setting, the
       * {@code RestClient.allowPrivateUrls} system property, and the {@code @Remote}/{@code @RemoteOp}
       * {@code allowPrivateUrls} annotation attribute: any one of the three opting in is sufficient. The {@code http}/
       * {@code https} scheme requirement is unaffected.
       *
       * @param value {@code true} to allow private/loopback/link-local/metadata {@code @Remote} targets. Default {@code false}.
       * @return This object.
       */
      public SELF allowPrivateUrls(boolean value) {
         allowPrivateUrls = value;
         return self();
      }

      /**
       * Allows this client's SSRF-guarded {@code @Remote}/{@code @Url} calls to reach hosts inside the given
       * special-purpose address ranges that the default policy denies (see {@code org.apache.juneau.http.remote.RemoteUrlPolicy}).
       *
       * <p>
       * Same narrow semantics and validation as the JVM-wide {@code RestClient.allowAddressRanges} system property: each
       * entry is a CIDR range or single address (parsed without DNS) that must lie inside {@code 192.0.0.0/24},
       * {@code 198.18.0.0/15}, {@code 224.0.0.0/4}, {@code 240.0.0.0/4} or {@code ff00::/8}.  It never re-opens
       * loopback, link-local/cloud-metadata, private, unspecified or any other deny.
       *
       * <p>
       * The effective allow-list is the union of this setting and the system property.  Repeated calls accumulate.
       * An invalid entry fails {@link #build()} with an {@link IllegalArgumentException}.
       *
       * @param value The CIDR ranges or addresses to allow.  Can be <jk>null</jk> or empty (no effect).
       * @return This object.
       */
      public SELF allowAddressRanges(String...value) {
         if (nn(value))
            Collections.addAll(allowedAddressRanges, value);
         return self();
      }

      /**
       * <i><l>BeanTraverse</l> configuration property:&emsp;</i>  Automatically detect POJO recursions.
       *
       * <p>
       * When enabled, specifies that recursions should be checked for during traversal.
       *
       * <p>
       * Recursions can occur when traversing models that aren't true trees but rather contain loops.
       * <br>In general, unchecked recursions cause stack-overflow-errors.
       * <br>These show up as {@link MarshallingRecursionException MarshallingRecursionException} with the message <js>"Depth too deep.  Stack overflow occurred."</js>.
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='note'>
       *       Checking for recursion can cause a small performance penalty.
       * </ul>
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a JSON client that automatically checks for recursions.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .json()
       *       .detectRecursions()
       *       .build();
       *
       *    <jc>// Create a POJO model with a recursive loop.</jc>
       *    <jk>public class</jk> A {
       *       <jk>public</jk> Object <jf>f</jf>;
       *    }
       *    A <jv>a</jv> = <jk>new</jk> A();
       *    <jv>a</jv>.<jf>f</jf> = <jv>a</jv>;
       *
       * <jk>try</jk> {
       *       <jc>// Throws a RestCallException with an inner SerializeException and not a StackOverflowError</jc>
       *       <jv>client</jv>
       *          .post(<js>"http://localhost:10000/foo"</js>, <jv>a</jv>)
       *          .run();
       * } <jk>catch</jk> (RestCallException <jv>e</jv>} {
       *    <jc>// Handle exception.</jc>
       * }
       * </p>
       *
       * <h5 class='section'>See Also:</h5><ul>
       *    <li class='jm'>{@link org.apache.juneau.marshall.MarshallingTraverseContext.Builder#detectRecursions() MarshallingTraverseContext.Builder#detectRecursions()}
       * </ul>
       *
       * @return This object.
       */
      public SELF detectRecursions() {
         serializers().forEach(Serializer.Builder::detectRecursions);
         return self();
      }

      /**
       * Disables authentication scheme caching.
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='note'>This value can be overridden by the {@link #httpProcessor(HttpProcessor)} method.
       * </ul>
       *
       * @return This object.
       * @see HttpClientBuilder#disableAuthCaching()
       */
      public SELF disableAuthCaching() {
         httpClientBuilder().disableAuthCaching();
         return self();
      }

      /**
       * Disables automatic request recovery and re-execution.
       *
       * @return This object.
       * @see HttpClientBuilder#disableAutomaticRetries()
       */
      public SELF disableAutomaticRetries() {
         httpClientBuilder().disableAutomaticRetries();
         return self();
      }

      /**
       * Disables connection state tracking.
       *
       * @return This object.
       * @see HttpClientBuilder#disableConnectionState()
       */
      public SELF disableConnectionState() {
         httpClientBuilder().disableConnectionState();
         return self();
      }

      /**
       * Disables automatic content decompression.
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='note'>This value can be overridden by the {@link #httpProcessor(HttpProcessor)} method.
       * </ul>
       *
       * @return This object.
       * @see HttpClientBuilder#disableContentCompression()
       */
      public SELF disableContentCompression() {
         httpClientBuilder().disableContentCompression();
         return self();
      }

      /**
       * Disables state (cookie) management.
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='note'>This value can be overridden by the {@link #httpProcessor(HttpProcessor)} method.
       * </ul>
       *
       * @return This object.
       * @see HttpClientBuilder#disableCookieManagement()
       */
      public SELF disableCookieManagement() {
         httpClientBuilder().disableCookieManagement();
         return self();
      }

      /**
       * Disables automatic redirect handling.
       *
       * @return This object.
       * @see HttpClientBuilder#disableRedirectHandling()
       */
      public SELF disableRedirectHandling() {
         httpClientBuilder().disableRedirectHandling();
         return self();
      }

      /**
       * Errors codes predicate.
       *
       * <p>
       * Defines a predicate to test for error codes.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a client that considers any 300+ responses to be errors.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .errorCodes(<jv>x</jv> -&gt; <jv>x</jv>&gt;=300)
       *       .build();
       * </p>
       *
       * @param value
       *    The new value for this setting.
       *    <br>The default value is <code>x -&gt; x &gt;= 400</code>.
       *    <br>Cannot be <jk>null</jk>.
       * @return This object.
       */
      public SELF errorCodes(Predicate<Integer> value) {
         errorCodes = reqnn("value", value);
         return self();
      }

      /**
       * Makes this instance of {@link HttpClient} proactively evict expired connections from the connection pool using a background thread.
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='note'>One MUST explicitly close HttpClient with {@link CloseableHttpClient#close()} in order to stop and release the background thread.
       *    <li class='note'>This method has no effect if the instance of {@link HttpClient} is configured to use a shared connection manager.
       *    <li class='note'>This method may not be used when the instance of {@link HttpClient} is created inside an EJB container.
       * </ul>
       *
       * @return This object.
       * @see HttpClientBuilder#evictExpiredConnections()
       */
      public SELF evictExpiredConnections() {
         httpClientBuilder().evictExpiredConnections();
         return self();
      }

      /**
       * Makes this instance of {@link HttpClient} proactively evict idle connections from the connection pool using a background thread.
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='note'>One MUST explicitly close HttpClient with {@link CloseableHttpClient#close()} in order to stop and release the background thread.
       *    <li class='note'>This method has no effect if the instance of {@link HttpClient} is configured to use a shared connection manager.
       *    <li class='note'>This method may not be used when the instance of {@link HttpClient} is created inside an EJB container.
       * </ul>
       *
       * @param maxIdleTime New property value.
       * @param maxIdleTimeUnit New property value.
       *    <br>Cannot be <jk>null</jk>.
       * @return This object.
       * @see HttpClientBuilder#evictIdleConnections(long,TimeUnit)
       */
      public SELF evictIdleConnections(long maxIdleTime, TimeUnit maxIdleTimeUnit) {
         httpClientBuilder().evictIdleConnections(maxIdleTime, maxIdleTimeUnit);
         return self();
      }

      /**
       * <i><l>RestClient</l> configuration property:&emsp;</i>  Executor service.
       *
       * <p>
       * Defines the executor service to use when calling future methods on the {@link RestRequest} class.
       *
       * <p>
       * This executor service is used to create {@link Future} objects on the following methods:
       * <ul>
       *    <li class='jm'>{@link RestRequest#runFuture()}
       *    <li class='jm'>{@link RestRequest#completeFuture()}
       *    <li class='jm'>{@link ResponseContent#asFuture(Class)} (and similar methods)
       * </ul>
       *
       * <p>
       * The default executor service is a single-threaded {@link ThreadPoolExecutor} with a 30 second timeout
       * and a queue size of 10.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a client with a customized executor service.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .executorService(<jk>new</jk> ThreadPoolExecutor(1, 1, 30, TimeUnit.<jsf>SECONDS</jsf>, <jk>new</jk> ArrayBlockingQueue&lt;Runnable&gt;(10)), <jk>true</jk>)
       *       .build();
       *
       *    <jc>// Use it to asynchronously run a request.</jc>
       *    Future&lt;RestResponse&gt; <jv>responseFuture</jv> = <jv>client</jv>.get(<jsf>URI</jsf>).runFuture();
       *
       *    <jc>// Do some other stuff.</jc>
       *
       *    <jc>// Now read the response.</jc>
       *    String <jv>body</jv> = <jv>responseFuture</jv>.get().getContent().asString();
       *
       *    <jc>// Use it to asynchronously retrieve a response.</jc>
       *    Future&lt;MyBean&gt; <jv>myBeanFuture</jv> = <jv>client</jv>
       *       .get(<jsf>URI</jsf>)
       *       .run()
       *       .getContent().asFuture(MyBean.<jk>class</jk>);
       *
       *    <jc>// Do some other stuff.</jc>
       *
       *    <jc>// Now read the response.</jc>
       *    MyBean <jv>bean</jv> = <jv>myBeanFuture</jv>.get();
       * </p>
       *
       * @param executorService The executor service.
       *    <br>Can be <jk>null</jk> (a default executor service will be created if needed).
       * @param shutdownOnClose Call {@link ExecutorService#shutdown()} when {@link RestClient#close()} is called.
       * @return This object.
       */
      public SELF executorService(ExecutorService executorService, boolean shutdownOnClose) {
         this.executorService = executorService;
         this.executorServiceShutdownOnClose = shutdownOnClose;
         return self();
      }

      /**
       * Returns the builder for the list of form data parameters that get applied to all requests created by this builder.
       *
       * <p>
       * This is the primary method for accessing the form data parameter list.
       * On first call, the builder is created via the method {@link #createFormData()}.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a client that adds a "foo=bar" form-data parameter on every request.</jc>
       *    RestClient.Builder&lt;?&gt; <jv>builder</jv> = RestClient.<jsm>create</jsm>();
       *    <jv>builder</jv>.formData().setDefault(<js>"foo"</js>, <js>"bar"</js>));
       *    RestClient <jv>client</jv> = <jv>builder</jv>.build();
       * </p>
       *
       * <p>
       * The following convenience methods are also provided for updating the parameters:
       * <ul>
       *    <li class='jm'>{@link #formData(NameValuePair...)}
       *    <li class='jm'>{@link #formDataDefault(NameValuePair...)}
       *    <li class='jm'>{@link #formData(String,String)}
       *    <li class='jm'>{@link #formData(String,Supplier)}
       * </ul>
       *
       * @return The form data list builder.
       */
      public final PartList formData() {
         if (formData == null)
            formData = createFormData();
         return formData;
      }

      /**
       * Appends multiple form-data parameters to the request bodies of all URL-encoded form posts.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jk>import static</jk> org.apache.juneau.http.HttpParts.*;
       *
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .formData(
       *          <jsm>stringPart</jsm>(<js>"foo"</js>, <js>"bar"</js>),
       *          <jsm>booleanPart</jsm>(<js>"baz"</js>, <jk>true</jk>)
       *       )
       *       .build();
       * </p>
       *
       * <p>
       * This is a shortcut for calling <c>formData().append(<jv>parts</jv>)</c>.
       *
       * @param parts
       *    The form-data parameters.
       *    <br>Can contain <jk>null</jk> values (ignored).
       * @return This object.
       * @see #formData()
       */
      public SELF formData(NameValuePair...parts) {
         formData().append(parts);
         return self();
      }

      /**
       * Appends a form-data parameter to all request bodies.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .formData(<js>"foo"</js>, <js>"bar"</js>)
       *       .build();
       * </p>
       *
       * <p>
       * This is a shortcut for calling <c>formData().append(<jv>name</jv>,<jv>value</jv>)</c>.
       *
       * @param name The parameter name.
       *    <br>Cannot be <jk>null</jk>.
       * @param value The parameter value.
       *    <br>Can be <jk>null</jk> (null value will be serialized).
       * @return This object.
       * @see #formData()
       */
      public SELF formData(String name, String value) {
         formData().append(name, value);
         return self();
      }

      /**
       * Appends a form-data parameter with a dynamic value to all request bodies.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .formData(<js>"foo"</js>, ()-&gt;<js>"bar"</js>)
       *       .build();
       * </p>
       *
       * <p>
       * This is a shortcut for calling <c>formData().append(<jv>name</jv>,<jv>value</jv>)</c>.
       *
       * @param name The parameter name.
       *    <br>Cannot be <jk>null</jk>.
       * @param value The parameter value supplier.
       *    <br>Can be <jk>null</jk> (null value will be serialized).
       * @return This object.
       * @see #formData()
       */
      public SELF formData(String name, Supplier<String> value) {
         formData().append(name, value);
         return self();
      }

      /**
       * Sets default form-data parameter values.
       *
       * <p>
       * Uses default values for specified parameters if not otherwise specified on the outgoing requests.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .formDataDefault(<jsm>stringPart</jsm>(<js>"foo"</js>, ()-&gt;<js>"bar"</js>));
       *       .build();
       * </p>
       *
       * <p>
       * This is a shortcut for calling <c>formData().setDefault(<jv>parts</jv>)</c>.
       *
       * @param parts The parts.
       *    <br>Can contain <jk>null</jk> values (ignored).
       * @return This object.
       * @see #formData()
       */
      public SELF formDataDefault(NameValuePair...parts) {
         formData().setDefault(parts);
         return self();
      }

      /**
       * Returns the root URI defined for this client.
       *
       * <p>
       * Returns <jk>null</jk> in lieu of an empty string.
       * Trailing slashes are trimmed.
       *
       * @return The root URI defined for this client.
       */
      public String getRootUri() { return rootUrl != null ? rootUrl.get() : null; }

      /**
       * Returns the root URL supplier set on this builder.
       *
       * @return The root URL supplier, or <jk>null</jk> if not set.
       */
      public Supplier<String> getRootUrlSupplier() { return rootUrl; }

      /**
       * Appends a header to all requests.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .header(<js>"Foo"</js>, <js>"bar"</js>);
       *       .build();
       * </p>
       *
       * <p>
       * This is a shortcut for calling <c>headerData().append(<jv>name</jv>,<jv>value</jv>)</c>.
       *
       * @param name The header name.
       *    <br>Cannot be <jk>null</jk>.
       * @param value The header value.
       *    <br>Can be <jk>null</jk> (null value will be serialized).
       * @return This object.
       * @see #headers()
       */
      public SELF header(String name, String value) {
         headers().append(name, value);
         return self();
      }

      /**
       * Appends a header to all requests using a dynamic value.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .header(<js>"Foo"</js>, ()-&gt;<js>"bar"</js>);
       *       .build();
       * </p>
       *
       * <p>
       * This is a shortcut for calling <c>headerData().append(<jv>name</jv>,<jv>value</jv>)</c>.
       *
       * @param name The header name.
       *    <br>Cannot be <jk>null</jk>.
       * @param value The header value supplier.
       *    <br>Can be <jk>null</jk> (null value will be serialized).
       * @return This object.
       * @see #headers()
       */
      public SELF header(String name, Supplier<String> value) {
         headers().append(name, value);
         return self();
      }

      /**
       * Returns the builder for the list of headers that get applied to all requests created by this builder.
       *
       * <p>
       * This is the primary method for accessing the request header list.
       * On first call, the builder is created via the method {@link #createHeaderData()}.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a client that adds a "Foo: bar" header on every request.</jc>
       *    RestClient.Builder&lt;?&gt; <jv>builder</jv> = RestClient.<jsm>create</jsm>();
       *    <jv>builder</jv>.headerData().setDefault(<js>"Foo"</js>, <js>"bar"</js>));
       *    RestClient <jv>client</jv> = <jv>builder</jv>.build();
       * </p>
       *
       * <p>
       * The following convenience methods are also provided for updating the headers:
       * <ul>
       *    <li class='jm'>{@link #headers(Header...)}
       *    <li class='jm'>{@link #headersDefault(Header...)}
       *    <li class='jm'>{@link #header(String,String)}
       *    <li class='jm'>{@link #header(String,Supplier)}
       *    <li class='jm'>{@link #mediaType(String)}
       *    <li class='jm'>{@link #mediaType(MediaType)}
       *    <li class='jm'>{@link #accept(String)}
       *    <li class='jm'>{@link #acceptCharset(String)}
       *    <li class='jm'>{@link #clientVersion(String)}
       *    <li class='jm'>{@link #contentType(String)}
       *    <li class='jm'>{@link #debug()}
       *    <li class='jm'>{@link #noTrace()}
       * </ul>
       *
       * @return The header list builder.
       */
      public final HeaderList headers() {
         if (headerData == null)
            headerData = createHeaderData();
         return headerData;
      }

      /**
       * Appends multiple headers to all requests.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jk>import static</jk> org.apache.juneau.http.HttpHeaders.*;
       *
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .headers(
       *          <jsf>ACCEPT_TEXT_XML</jsf>,
       *          <jsm>stringHeader</jsm>(<js>"Foo"</js>, <js>"bar"</js>)
       *       )
       *       .build();
       * </p>
       *
       * <p>
       * This is a shortcut for calling <c>headerData().append(<jv>parts</jv>)</c>.
       *
       * @param parts
       *    The header to set.
       *    <br>Can contain <jk>null</jk> values (ignored).
       * @return This object.
       * @see #headers()
       */
      public SELF headers(Header...parts) {
         headers().append(parts);
         return self();
      }

      /**
       * Sets default header values.
       *
       * <p>
       * Uses default values for specified headers if not otherwise specified on the outgoing requests.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .headersDefault(<jsm>stringHeader</jsm>(<js>"Foo"</js>, ()-&gt;<js>"bar"</js>));
       *       .build();
       * </p>
       *
       * <p>
       * This is a shortcut for calling <c>headerData().setDefault(<jv>parts</jv>)</c>.
       *
       * @param parts The header values.
       *    <br>Can contain <jk>null</jk> values (ignored).
       * @return This object.
       * @see #headers()
       */
      public SELF headersDefault(Header...parts) {
         headers().setDefault(parts);
         return self();
      }

      /**
       * Sets a default request header with serializer session options (JSON5 map) for all requests.
       *
       * <p>
       * This is a shortcut for <c>headersDefault(basicHeader({@link RestSharedConstants#HEADER_JuneauSerializerOptions}, <jv>json5</jv>))</c>.
       *
       * @param json5
       *    Serializer session options in JSON5 form.
       *    <br>Can be <jk>null</jk> (default is not set by this method).
       * @return This object.
       */
      public SELF serializerSessionOptionsHeader(String json5) {
         if (json5 != null)
            headersDefault(basicHeader(HEADER_JuneauSerializerOptions, json5));
         return self();
      }

      /**
       * Sets a default request header with parser session options (JSON5 map) for all requests.
       *
       * <p>
       * This is a shortcut for <c>headersDefault(basicHeader({@link RestSharedConstants#HEADER_JuneauParserOptions}, <jv>json5</jv>))</c>.
       *
       * @param json5
       *    Parser session options in JSON5 form.
       *    <br>Can be <jk>null</jk> (default is not set by this method).
       * @return This object.
       */
      public SELF parserSessionOptionsHeader(String json5) {
         if (json5 != null)
            headersDefault(basicHeader(HEADER_JuneauParserOptions, json5));
         return self();
      }

      /**
       * Convenience for {@link #serializerSessionOptionsHeader(String)} using a map serialized with JSON5.
       *
       * @param properties
       *    Property names and values for serializer session options.
       *    <br>Can be <jk>null</jk> (treated as an empty map).
       * @return This object.
       */
      public SELF serializerSessionOptionsHeader(Map<String,?> properties) {
         try {
            return serializerSessionOptionsHeader(isEmpty(properties) ? null : Json5.of(properties));
         } catch (SerializeException e) {
            throw rex(e, "Could not serialize serializer session options header");
         }
      }

      /**
       * Convenience for {@link #parserSessionOptionsHeader(String)} using a map serialized with JSON5.
       *
       * @param properties
       *    Property names and values for parser session options.
       *    <br>Can be <jk>null</jk> (treated as an empty map).
       * @return This object.
       */
      public SELF parserSessionOptionsHeader(Map<String,?> properties) {
         try {
            return parserSessionOptionsHeader(isEmpty(properties) ? null : Json5.of(properties));
         } catch (SerializeException e) {
            throw rex(e, "Could not serialize parser session options header");
         }
      }

      /**
       * Convenience method for specifying HTML as the marshalling transmission media type.
       *
       * <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 #sortCollections()}) or
       *          bean context property setters (e.g. {@link #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 #ignoreUnknownBeanProperties()}) or
       *          bean context property setters (e.g. {@link #swaps(Class...)}) defined on this builder class.
       *    </ul>
       * <p>
       *    <c>Accept</c> request header will be set to <js>"text/html"</js> unless overridden
       *       via {@link #headers()}, or per-request via {@link RestRequest#header(Header)}.
       * <p>
       *    <c>Content-Type</c> request header will be set to <js>"text/html"</js> unless overridden
       *       via {@link #headers()}, or per-request via {@link RestRequest#header(Header)}.
       * <p>
       *    Can be combined with other marshaller setters such as {@link #json()} 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(HtmlSerializer.<jk>class</jk>).parser(HtmlParser.<jk>class</jk>)</c>.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Construct a client that uses HTML marshalling.</jc>
       *    RestClient <jv>client</jv> = RestClient.<jsm>create</jsm>().html().build();
       * </p>
       *
       * @return This object.
       */
      public SELF html() {
         return serializer(HtmlSerializer.class).parser(HtmlParser.class);
      }

      /**
       * Convenience method for specifying HTML DOC as the marshalling transmission media type.
       *
       * <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 #sortCollections()} or
       *          bean context property setters (e.g. {@link #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 #ignoreUnknownBeanProperties()}) or
       *          bean context property setters (e.g. {@link #swaps(Class...)}) defined on this builder class.
       *    </ul>
       * <p>
       *    <c>Accept</c> request header will be set to <js>"text/html"</js> unless overridden
       *       via {@link #headers()}, or per-request via {@link RestRequest#header(Header)}.
       * <p>
       *    <c>Content-Type</c> request header will be set to <js>"text/html"</js> unless overridden
       *       via {@link #headers()}, or per-request via {@link RestRequest#header(Header)}.
       * <p>
       *    Can be combined with other marshaller setters such as {@link #json()} 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(HtmlDocSerializer.<jk>class</jk>).parser(HtmlParser.<jk>class</jk>)</c>.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Construct a client that uses HTML Doc marshalling.</jc>
       *    RestClient <jv>client</jv> = RestClient.<jsm>create</jsm>().htmlDoc().build();
       * </p>
       *
       * @return This object.
       */
      public SELF htmlDoc() {
         return serializer(HtmlDocSerializer.class).parser(HtmlParser.class);
      }

      /**
       * Convenience method for specifying Stripped HTML DOC as the marshalling transmission media type.
       *
       * <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 #sortCollections()}) or
       *          bean context property setters (e.g. {@link #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 #ignoreUnknownBeanProperties()}) or
       *          bean context property setters (e.g. {@link #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
       *       via {@link #headers()}, or per-request via {@link RestRequest#header(Header)}.
       * <p>
       *    <c>Content-Type</c> request header will be set to <js>"text/html+stripped"</js> unless overridden
       *       via {@link #headers()}, or per-request via {@link RestRequest#header(Header)}.
       * <p>
       *    Can be combined with other marshaller setters such as {@link #json()} 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(HtmlStrippedDocSerializer.<jk>class</jk>).parser(HtmlParser.<jk>class</jk>)</c>.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Construct a client that uses HTML Stripped Doc marshalling.</jc>
       *    RestClient <jv>client</jv> = RestClient.<jsm>create</jsm>().htmlStrippedDoc().build();
       * </p>
       *
       * @return This object.
       */
      public SELF htmlStrippedDoc() {
         return serializer(HtmlStrippedDocSerializer.class).parser(HtmlParser.class);
      }

      /**
       * Sets the {@link HttpClient} to be used to handle all HTTP communications with the target server.
       *
       * <p>
       * This can be used to bypass the client created by {@link #createHttpClient()} method.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Construct a client that uses a customized HttpClient.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .httpClient(HttpClientBuilder.<jsm>create</jsm>().build())
       *       .build();
       * </p>
       *
       * @param value The {@link HttpClient} to be used to handle all HTTP communications with the target server.
       *    <br>Can be <jk>null</jk> (a default client will be created).
       * @return This object.
       */
      public SELF httpClient(CloseableHttpClient value) {
         httpClient = value;
         return self();
      }

      /**
       * Returns the HTTP client builder.
       *
       * @return The HTTP client builder.
       */
      public final HttpClientBuilder httpClientBuilder() {
         if (httpClientBuilder == null)
            httpClientBuilder = createHttpClientBuilder();
         return httpClientBuilder;
      }

      /**
       * Sets the {@link HttpClientBuilder} that will be used to create the {@link HttpClient} used by {@link RestClient}.
       *
       * <p>
       * This can be used to bypass the builder created by {@link #createHttpClientBuilder()} method.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Construct a client that uses a customized HttpClientBuilder.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .httpClientBuilder(HttpClientBuilder.<jsm>create</jsm>())
       *       .build();
       * </p>
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='note'>The TLS and connection-pool settings Apache {@link HttpClientBuilder} applies only to a
       *       connection manager it builds itself
       *       ({@link HttpClientBuilder#setSSLContext(SSLContext) setSSLContext},
       *       {@link HttpClientBuilder#setSSLSocketFactory(LayeredConnectionSocketFactory) setSSLSocketFactory},
       *       {@link HttpClientBuilder#setSSLHostnameVerifier(HostnameVerifier) setSSLHostnameVerifier},
       *       {@link HttpClientBuilder#setPublicSuffixMatcher(PublicSuffixMatcher) setPublicSuffixMatcher},
       *       {@link HttpClientBuilder#setMaxConnTotal(int) setMaxConnTotal},
       *       {@link HttpClientBuilder#setMaxConnPerRoute(int) setMaxConnPerRoute},
       *       {@link HttpClientBuilder#setConnectionTimeToLive(long, TimeUnit) setConnectionTimeToLive},
       *       {@link HttpClientBuilder#setDefaultSocketConfig(SocketConfig) setDefaultSocketConfig},
       *       {@link HttpClientBuilder#setDefaultConnectionConfig(ConnectionConfig) setDefaultConnectionConfig},
       *       {@link HttpClientBuilder#setDnsResolver(DnsResolver) setDnsResolver} and
       *       {@link HttpClientBuilder#useSystemProperties() useSystemProperties}) are read from the given builder and
       *       applied to the connection manager the default {@link #createConnectionManager()} builds (see there).
       *    <li class='note'>These connection-manager settings, made through a method of this builder before this method is
       *       called, are applied too, and win over the same setting on the given builder:
       *       {@link #sslContext(SSLContext) sslContext},
       *       {@link #sslSocketFactory(LayeredConnectionSocketFactory) sslSocketFactory},
       *       {@link #sslHostnameVerifier(HostnameVerifier) sslHostnameVerifier},
       *       {@link #publicSuffixMatcher(PublicSuffixMatcher) publicSuffixMatcher} (for the default hostname verifier only:
       *       its use for cookies is lost with the replaced builder),
       *       {@link #maxConnTotal(int) maxConnTotal}, {@link #maxConnPerRoute(int) maxConnPerRoute}, {@link #pooled() pooled},
       *       {@link #connectionTimeToLive(long, TimeUnit) connectionTimeToLive},
       *       {@link #defaultSocketConfig(SocketConfig) defaultSocketConfig},
       *       {@link #defaultConnectionConfig(ConnectionConfig) defaultConnectionConfig} and the TLS and
       *       {@code http.maxConnections} system properties of {@link #useSystemProperties()}.  Every other setting made
       *       through this builder before this method is called (interceptors, proxy, the rest of
       *       {@code useSystemProperties()}, and so on) was made on the replaced builder and is lost.
       *    <li class='note'>For these connection-manager settings, a value set through a method of this builder always wins
       *       over the same setting on the {@code HttpClientBuilder}, whichever was set last: unlike Apache's own
       *       last-write-wins, a later {@code httpClientBuilder().setDefaultSocketConfig(...)} (and so on) does not
       *       override an earlier {@link #defaultSocketConfig(SocketConfig) defaultSocketConfig(...)}.
       *    <li class='note'>As in Apache {@code HttpClientBuilder}, an SSL socket factory wins over an SSL context wherever
       *       each was set: a {@link HttpClientBuilder#setSSLSocketFactory(LayeredConnectionSocketFactory) setSSLSocketFactory}
       *       on the given builder wins over an earlier {@link #sslContext(SSLContext) sslContext}.
       *    <li class='warn'>A socket factory set with {@code setSSLSocketFactory} on the given builder is used for
       *       SSRF-guard-active {@code @Remote} calls too, and must connect to exactly the address it is given (see
       *       {@link #sslSocketFactory(LayeredConnectionSocketFactory)}).
       *    <li class='warn'>A client built by an {@code HttpClientBuilder} subclass that overrides (or inherits an override
       *       of) {@code build()}, {@code createMainExec(...)}, {@code decorateMainExec(...)} or
       *       {@code decorateProtocolExec(...)} refuses every SSRF-guard-active {@code @Remote} call: the override may
       *       build the client around another connection manager or request executor.
       * </ul>
       *
       * @param value The {@link HttpClientBuilder} that will be used to create the {@link HttpClient} used by {@link RestClient}.
       *    <br>Can be <jk>null</jk> (a default builder will be created).
       * @return This object.
       */
      public SELF httpClientBuilder(HttpClientBuilder value) {
         httpClientBuilder = value;
         return self();
      }

      /**
       * Assigns {@link HttpProcessor} instance.
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='warn'>The processor replaces all of the client's request interceptors, among them the ones that
       *       enforce the SSRF guard and strip credentials on cross-origin redirects.  So a client with one refuses every
       *       SSRF-guard-active {@code @Remote} call (one without the {@link #allowPrivateUrls(boolean) allowPrivateUrls}
       *       opt-in).  Add interceptors with {@link HttpClientBuilder#addInterceptorLast(HttpRequestInterceptor)} on the
       *       {@link #httpClientBuilder() HttpClientBuilder} instead.
       * </ul>
       *
       * @param httpprocessor New property value.
       * @return This object.
       * @see HttpClientBuilder#setHttpProcessor(HttpProcessor)
       */
      public SELF httpProcessor(HttpProcessor httpprocessor) {
         httpClientBuilder().setHttpProcessor(httpprocessor);
         return self();
      }

      /**
       * Ignore errors.
       *
       * <p>
       * When enabled, HTTP error response codes (e.g. <l>&gt;=400</l>) will not cause a {@link RestCallException} to
       * be thrown.
       * <p>
       * Note that this is equivalent to <c>builder.errorCodes(x -&gt; <jk>false</jk>);</c>
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a client that doesn't throws a RestCallException when a 500 error occurs.</jc>
       *    RestClient
       *       .<jsm>create</jsm>()
       *       .ignoreErrors()
       *       .build()
       *       .get(<js>"/error"</js>)  <jc>// Throws a 500 error</jc>
       *       .run()
       *       .assertStatus().is(500);
       * </p>
       *
       * @return This object.
       */
      public SELF ignoreErrors() {
         ignoreErrors = true;
         return self();
      }

      /**
       * <i><l>BeanTraverse</l> configuration property:&emsp;</i>  Ignore recursion errors.
       *
       * <p>
       * When enabled, when we encounter the same object when traversing a tree, we set the value to <jk>null</jk>.
       *
       * <p>
       * For example, if a model contains the links A-&gt;B-&gt;C-&gt;A, then the JSON generated will look like
       *    the following when <jsf>BEANTRAVERSE_ignoreRecursions</jsf> is <jk>true</jk>...
       *
       * <p class='bjson'>
       *    {A:{B:{C:<jk>null</jk>}}}
       * </p>
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='note'>
       *       Checking for recursion can cause a small performance penalty.
       * </ul>
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a JSON client that ignores recursions.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .json()
       *       .ignoreRecursions()
       *       .build();
       *
       *    <jc>// Create a POJO model with a recursive loop.</jc>
       *    <jk>public class</jk> A {
       *       <jk>public</jk> Object <jf>f</jf>;
       *    }
       *    A <jv>a</jv> = <jk>new</jk> A();
       *    <jv>a</jv>.<jf>f</jf> = <jv>a</jv>;
       *
       *    <jc>// Produces request body "{f:null}"</jc>
       *    <jv>client</jv>
       *       .post(<js>"http://localhost:10000/foo"</js>, <jv>a</jv>)
       *       .run();
       * </p>
       *
       * <h5 class='section'>See Also:</h5><ul>
       *    <li class='jm'>{@link org.apache.juneau.marshall.MarshallingTraverseContext.Builder#ignoreRecursions() MarshallingTraverseContext.Builder#ignoreRecursions()}
       * </ul>
       *
       * @return This object.
       */
      public SELF ignoreRecursions() {
         serializers().forEach(Serializer.Builder::ignoreRecursions);
         return self();
      }

      /**
       * <i><l>BeanTraverse</l> configuration property:&emsp;</i>  Initial depth.
       *
       * <p>
       * The initial indentation level at the root.
       *
       * <p>
       * Useful when constructing document fragments that need to be indented at a certain level when whitespace is enabled.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a REST client with JSON serializer with whitespace enabled and an initial depth of 2.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .json()
       *       .ws()
       *       .initialDepth(2)
       *       .build();
       *
       *    <jc>// Our bean to serialize.</jc>
       *    <jk>public class</jk> MyBean {
       *       <jk>public</jk> String <jf>foo</jf> = <jk>null</jk>;
       *    }
       *
       *    <jc>// Produces request body "\t\t{\n\t\t\t'foo':'bar'\n\t\t}\n"</jc>
       *    <jv>client</jv>
       *       .post(<js>"http://localhost:10000/foo"</js>, <jk>new</jk> MyBean())
       *       .run();
       * </p>
       *
       * <h5 class='section'>See Also:</h5><ul>
       *    <li class='jm'>{@link org.apache.juneau.marshall.MarshallingTraverseContext.Builder#initialDepth(int) MarshallingTraverseContext.Builder#initialDepth(int)}
       * </ul>
       *
       * @param value
       *    The new value for this property.
       *    <br>The default is <c>0</c>.
       * @return This object.
       */
      public SELF initialDepth(int value) {
         serializers().forEach(x -> x.initialDepth(value));
         return self();
      }

      /**
       * <i><l>RestClient</l> configuration property:&emsp;</i>  Call interceptors.
       *
       * <p>
       * Adds an interceptor that can be called to hook into specified events in the lifecycle of a single request.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *   <jc>// Customized interceptor (note you can also extend from BasicRestCallInterceptor as well.</jc>
       *    <jk>public class</jk> MyRestCallInterceptor <jk>implements</jk> RestCallInterceptor {
       *
       *       <ja>@Override</ja>
       *       <jk>public void</jk> onInit(RestRequest <jv>req</jv>) <jk>throws</jk> Exception {
       *       <jc>// Intercept immediately after RestRequest object is created and all headers/query/form-data has been
       *       // set on the request from the client.</jc>
       *    }
       *
       *    <ja>@Override</ja>
       *    <jk>public void</jk> onConnect(RestRequest <jv>req</jv>, RestResponse <jv>res</jv>) <jk>throws</jk> Exception {
       *       <jc>// Intercept immediately after an HTTP response has been received.</jc>
       *    }
       *
       *    <ja>@Override</ja>
       *    <jk>public void</jk> onClose(RestRequest <jv>req</jv>, RestResponse <jv>res</jv>) <jk>throws</jk> Exception {
       *          <jc>// Intercept when the response body is consumed.</jc>
       *       }
       *    }
       *
       *    <jc>// Create a client with a customized interceptor.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .interceptors(MyRestCallInterceptor.<jk>class</jk>)
       *       .build();
       * </p>
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='note'>The {@link RestClient#onCallInit(RestRequest)}, {@link RestClient#onCallConnect(RestRequest,RestResponse)}, and
       * {@link RestClient#onCallClose(RestRequest,RestResponse)} methods can also be overridden to produce the same results.
       * </ul>
       *
       * @param values
       *    The values to add to this setting.
       *    <br>Can be implementations of any of the following:
       *    <ul>
       *       <li class='jic'>{@link RestCallInterceptor}
       *       <li class='jic'>{@link HttpRequestInterceptor}
       *       <li class='jic'>{@link HttpResponseInterceptor}
       *    </ul>
       *    <br>Can contain <jk>null</jk> values (ignored).
       * @return This object.
       * @throws Exception If one or more interceptors could not be created.
       */
      public SELF interceptors(Class<?>...values) throws Exception {
         for (var c : values) {
            if (c == null)
               continue;
            var ci = ClassInfo.of(c);
            if (nn(ci)) {
               if (ci.isAssignableToAny(RestCallInterceptor.class, HttpRequestInterceptor.class, HttpResponseInterceptor.class))
                  interceptors(ci.newInstance());
               else
                  throw new ConfigException("Invalid class of type '%s' passed to interceptors().", ci.getName());
            }
         }
         return self();
      }

      /**
       * Call interceptors.
       *
       * <p>
       * Adds an interceptor that gets called immediately after a connection is made.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a client with a customized interceptor.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .interceptors(
       *          <jk>new</jk> RestCallInterceptor() {
       *
       *             <ja>@Override</ja>
       *             <jk>public void</jk> onInit(RestRequest <jv>req</jv>) <jk>throws</jk> Exception {
       *             <jc>// Intercept immediately after RestRequest object is created and all headers/query/form-data has been
       *             // set on the request from the client.</jc>
       *          }
       *
       *          <ja>@Override</ja>
       *          <jk>public void</jk> onConnect(RestRequest <jv>req</jv>, RestResponse <jv>res</jv>) <jk>throws</jk> Exception {
       *             <jc>// Intercept immediately after an HTTP response has been received.</jc>
       *          }
       *
       *          <ja>@Override</ja>
       *          <jk>public void</jk> onClose(RestRequest <jv>req</jv>, RestResponse <jv>res</jv>) <jk>throws</jk> Exception {
       *                <jc>// Intercept when the response body is consumed.</jc>
       *             }
       *          }
       *       )
       *       .build();
       * </p>
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='note'>The {@link RestClient#onCallInit(RestRequest)}, {@link RestClient#onCallConnect(RestRequest,RestResponse)}, and
       * {@link RestClient#onCallClose(RestRequest,RestResponse)} methods can also be overridden to produce the same results.
       * </ul>
       *
       * @param value
       *    The values to add to this setting.
       *    <br>Can be implementations of any of the following:
       *    <ul>
       *       <li class='jic'>{@link RestCallInterceptor}
       *       <li class='jic'>{@link HttpRequestInterceptor}
       *       <li class='jic'>{@link HttpResponseInterceptor}
       *    </ul>
       *    <br>Can contain <jk>null</jk> values (ignored).
       * @return This object.
       */
      public SELF interceptors(Object...value) {
         List<RestCallInterceptor> l = list();
         for (var o : value) {
            if (o == null)
               continue;
            ClassInfo ci = ClassInfo.of(o);
            if (nn(ci)) {
               if (! ci.isAssignableToAny(HttpRequestInterceptor.class, HttpResponseInterceptor.class, RestCallInterceptor.class))
                  throw new ConfigException("Invalid object of type '%s' passed to interceptors().", ci.getName());
               if (o instanceof HttpRequestInterceptor o2)
                  addInterceptorLast(o2);
               if (o instanceof HttpResponseInterceptor o2)
                  addInterceptorLast(o2);
               if (o instanceof RestCallInterceptor o2)
                  l.add(o2);
            }
         }
         if (interceptors == null)
            interceptors = l;
         else
            interceptors.addAll(0, l);
         return self();
      }

      /**
       * Convenience method for specifying JSON as the marshalling transmission media type.
       *
       * <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 #sortCollections()}) or
       *          bean context property setters (e.g. {@link #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 #ignoreUnknownBeanProperties()}) or
       *          bean context property setters (e.g. {@link #swaps(Class...)}) defined on this builder class.
       *    </ul>
       * <p>
       *    <c>Accept</c> request header will be set to <js>"application/json"</js> unless overridden
       *       via {@link #headers()}, or per-request via {@link RestRequest#header(Header)}}.
       * <p>
       *    <c>Content-Type</c> request header will be set to <js>"application/json"</js> unless overridden
       *       via {@link #headers()}, or per-request via {@link RestRequest#header(Header)}.
       * <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(JsonSerializer.<jk>class</jk>).parser(JsonParser.<jk>class</jk>)</c>.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Construct a client that uses JSON marshalling.</jc>
       *    RestClient <jv>client</jv> = RestClient.<jsm>create</jsm>().json().build();
       * </p>
       *
       * @return This object.
       */
      public SELF json() {
         return serializer(JsonSerializer.class).parser(JsonParser.class);
      }

      /**
       * Convenience method for specifying Simplified JSON as the marshalling transmission media type.
       *
       * <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 #sortCollections()}) or
       *          bean context property setters (e.g. {@link #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 #ignoreUnknownBeanProperties()}) or
       *          bean context property setters (e.g. {@link #swaps(Class...)}) defined on this builder class.
       *    </ul>
       * <p>
       *    <c>Accept</c> request header will be set to <js>"application/json5"</js> unless overridden
       *       via {@link #headers()}, or per-request via {@link RestRequest#header(Header)}.
       * <p>
       *    <c>Content-Type</c> request header will be set to <js>"application/json5"</js> unless overridden
       *       via {@link #headers()}, or per-request via {@link RestRequest#header(Header)}.
       * <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>.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Construct a client that uses Simplified JSON marshalling.</jc>
       *    RestClient <jv>client</jv> = RestClient.<jsm>create</jsm>().json5().build();
       * </p>
       *
       * @return This object.
       */
      public SELF json5() {
         return serializer(Json5Serializer.class).parser(Json5Parser.class);
      }

      /**
       * Convenience method for specifying JCS (JSON Canonicalization Scheme, RFC 8785) as the marshalling transmission media type.
       *
       * <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 SELF jcs() {
         return serializer(JcsSerializer.class).parser(JsonParser.class);
      }

      /**
       * Assigns {@link ConnectionKeepAliveStrategy} instance.
       *
       * @param keepAliveStrategy New property value.
       *    <br>Can be <jk>null</jk> (value will not be set, default behavior will be used).
       * @return This object.
       * @see HttpClientBuilder#setKeepAliveStrategy(ConnectionKeepAliveStrategy)
       */
      public SELF keepAliveStrategy(ConnectionKeepAliveStrategy keepAliveStrategy) {
         httpClientBuilder().setKeepAliveStrategy(keepAliveStrategy);
         return self();
      }

      /**
       * <i><l>RestClient</l> configuration property:&emsp;</i>  Keep HttpClient open.
       *
       * <p>
       * Don't close this client when the {@link RestClient#close()} method is called.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a client with a customized client and don't close the client  service.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .httpClient(<jv>myHttpClient</jv>)
       *       .keepHttpClientOpen()
       *       .build();
       *
       *    <jv>client</jv>.closeQuietly();  <jc>// Customized HttpClient won't be closed.</jc>
       * </p>
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='note'>When combined with {@link #connectionManagerShared(boolean) connectionManagerShared(true)}, the
       *       client's internal pool for SSRF-guard-active {@code @Remote} calls (see {@link #createConnectionManager()}) and
       *       the connection manager the default {@code createConnectionManager()} built are not shut down either, and
       *       nothing else shuts them down; their connections stay open until they are closed as idle or the JVM exits.
       * </ul>
       *
       * @return This object.
       */
      public SELF keepHttpClientOpen() {
         keepHttpClientOpen = true;
         return self();
      }

      /**
       * <i><l>Serializer</l> configuration property:&emsp;</i>  Don't trim null bean property values.
       *
       * <p>
       * When enabled, null bean values will be serialized to the output.
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='note'>Not enabling this setting will cause <c>Map</c>s with <jk>null</jk> values to be lost during parsing.
       * </ul>
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a REST client with JSON serializer that serializes null properties.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .json()
       *       .keepNullProperties()
       *       .build();
       *
       *    <jc>// Our bean to serialize.</jc>
       *    <jk>public class</jk> MyBean {
       *       <jk>public</jk> String <jf>foo</jf> = <jk>null</jk>;
       *    }
       *
       *    <jc>// Request body will contain:  {foo:null}</jc>
       *    <jv>client</jv>
       *       .post(<js>"http://localhost:10000/foo"</js>, <jk>new</jk> MyBean())
       *       .run();
       * </p>
       *
       * <h5 class='section'>See Also:</h5><ul>
       *    <li class='jm'>{@link org.apache.juneau.marshall.serializer.Serializer.Builder#keepNullProperties() Serializer.Builder#keepNullProperties()}
       * </ul>
       *
       * @return This object.
       */
      public SELF keepNullProperties() {
         serializers().forEach(Serializer.Builder::keepNullProperties);
         return self();
      }

      /**
       * Logger.
       *
       * <p>
       * Specifies the logger to use for logging.
       *
       * <p>
       * If not specified, uses the following logger:
       * <p class='bjava'>
       *    Logger.<jsm>getLogger</jsm>(RestClient.<jk>class</jk>.getName());
       * </p>
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Construct a client that logs messages to a special logger.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .logger(Logger.<jsm>getLogger</jsm>(<js>"MyLogger"</js>))  <jc>// Log to MyLogger logger.</jc>
       *       .logToConsole()  <jc>// Also log to console.</jc>
       *       .logRequests(<jsf>FULL</jsf>, <jsf>WARNING</jsf>)  <jc>// Log requests with full detail at WARNING level.</jc>
       *       .build();
       * </p>
       *
       * @param value The logger to use for logging.
       *    <br>Can be <jk>null</jk> (defaults to <c>Logger.getLogger(RestClient.class.getName())</c>).
       * @return This object.
       */
      public SELF logger(Logger value) {
         logger = value;
         return self();
      }

      /**
       * Log requests.
       *
       * <p>
       * Causes requests/responses to be logged at the specified log level at the end of the request.
       *
       * <p>
       * <jsf>SIMPLE</jsf> detail produces a log message like the following:
       * <p class='bconsole'>
       *    POST http://localhost:10000/testUrl, HTTP/1.1 200 OK
       * </p>
       *
       * <p>
       * <jsf>FULL</jsf> detail produces a log message like the following:
       * <p class='bconsole'>
       *    === HTTP Call (outgoing) =======================================================
       *    === REQUEST ===
       *    POST http://localhost:10000/testUrl
       *    ---request headers---
       *       Debug: true
       *       No-Trace: true
       *       Accept: application/json
       *    ---request entity---
       *       Content-Type: application/json
       *    ---request content---
       *    {"foo":"bar","baz":123}
       *    === RESPONSE ===
       *    HTTP/1.1 200 OK
       *    ---response headers---
       *       Content-Type: application/json;charset=utf-8
       *       Content-Length: 21
       *       Server: Jetty(8.1.0.v20120127)
       *    ---response content---
       *    {"message":"OK then"}
       *    === END ========================================================================
       * </p>
       *
       * <p>
       * By default, the message is logged to the default logger.  It can be logged to a different logger via the
       * {@link #logger(Logger)} method or logged to the console using the
       * {@link #logToConsole()} method.
       *
       * @param detail The detail level of logging.
       * @param level The log level.
       * @param test A predicate to use per-request to see if the request should be logged.  If <jk>null</jk>, always logs.
       * @return This object.
       */
      public SELF logRequests(DetailLevel detail, Level level, BiPredicate<RestRequest,RestResponse> test) {
         logRequests = detail;
         logRequestsLevel = level;
         logRequestsPredicate = test;
         return self();
      }

      /**
       * Log to console.
       *
       * <p>
       * Specifies to log messages to the console.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Construct a client that logs messages to a special logger.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .logToConsole()
       *       .logRequests(<jsf>FULL</jsf>, <jsf>INFO</jsf>)  <jc>// Level is ignored when logging to console.</jc>
       *       .build();
       * </p>
       *
       * @return This object.
       */
      public SELF logToConsole() {
         logToConsole = true;
         return self();
      }

      /**
       * <i><l>RestClient</l> configuration property:&emsp;</i>  Marshaller
       *
       * <p>
       * Shortcut for specifying the serializers and parsers
       * using the serializer and parser defined in a marshaller.
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='note'>When using this method that takes in a pre-instantiated serializers and parsers, the serializer property setters (e.g. {@link #sortCollections()}),
       *    parser property setters (e.g. {@link #ignoreUnknownBeanProperties()}), or bean context property setters (e.g. {@link #swaps(Class...)}) defined on this builder class have no effect.
       * </ul>
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a client that uses Simplified-JSON transport using an existing marshaller.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .marshaller(Json5.<jsf>DEFAULT_READABLE</jsf>)
       *       .build();
       * </p>
       *
       * @param value The values to add to this setting.
       *    <br>Can be <jk>null</jk> (value will not be set, existing serializers and parsers will be kept).
       * @return This object.
       */
      public SELF marshaller(Marshaller value) {
         if (nn(value))
            serializer(value.getSerializer()).parser(value.getParser());
         return self();
      }

      /**
       * <i><l>RestClient</l> configuration property:&emsp;</i>  Marshalls
       *
       * <p>
       * Shortcut for specifying the serializers and parsers
       * using the serializer and parser defined in a marshaller.
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='note'>When using this method that takes in a pre-instantiated serializers and parsers, the serializer property setters (e.g. {@link #sortCollections()}),
       *    parser property setters (e.g. {@link #ignoreUnknownBeanProperties()}), or bean context property setters (e.g. {@link #swaps(Class...)}) defined on this builder class have no effect.
       * </ul>
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a client that uses JSON and XML transport using existing marshalls.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .marshaller(Json.<jsf>DEFAULT_READABLE</jsf>, Xml.<jsf>DEFAULT_READABLE</jsf>)
       *       .build();
       * </p>
       *
       * @param value The values to add to this setting.
       *    <br>Can contain <jk>null</jk> values (ignored).
       * @return This object.
       */
      public SELF marshallers(Marshaller...value) {
         for (var m : value)
            if (nn(m))
               serializer(m.getSerializer()).parser(m.getParser());
         return self();
      }

      /**
       * Assigns maximum connection per route value.
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='note'>A positive value is applied to the connection manager the default
       *       {@link #createConnectionManager()} builds, which is then always a {@link PoolingHttpClientConnectionManager}
       *       (as if {@link #pooled()} had been called), and to its internal pool for SSRF-guard-active {@code @Remote} calls.
       *    <li class='note'>It has no effect on a connection manager supplied through
       *       {@link #connectionManager(HttpClientConnectionManager)} or an overridden {@link #createConnectionManager()}.
       * </ul>
       *
       * @param maxConnPerRoute New property value.
       * @return This object.
       * @see HttpClientBuilder#setMaxConnPerRoute(int)
       */
      public SELF maxConnPerRoute(int maxConnPerRoute) {
         this.maxConnPerRoute = maxConnPerRoute;
         httpClientBuilder().setMaxConnPerRoute(maxConnPerRoute);
         return self();
      }

      /**
       * Assigns maximum total connection value.
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='note'>A positive value is applied to the connection manager the default
       *       {@link #createConnectionManager()} builds, which is then always a {@link PoolingHttpClientConnectionManager}
       *       (as if {@link #pooled()} had been called), and to its internal pool for SSRF-guard-active {@code @Remote} calls.
       *       Each pool applies the limit on its own (see {@link #createConnectionManager()}).
       *    <li class='note'>It has no effect on a connection manager supplied through
       *       {@link #connectionManager(HttpClientConnectionManager)} or an overridden {@link #createConnectionManager()}.
       * </ul>
       *
       * @param maxConnTotal New property value.
       * @return This object.
       * @see HttpClientBuilder#setMaxConnTotal(int)
       */
      public SELF maxConnTotal(int maxConnTotal) {
         this.maxConnTotal = maxConnTotal;
         httpClientBuilder().setMaxConnTotal(maxConnTotal);
         return self();
      }

      /**
       * <i><l>BeanTraverse</l> configuration property:&emsp;</i>  Max serialization depth.
       *
       * <p>
       * When enabled, abort traversal if specified depth is reached in the POJO tree.
       *
       * <p>
       * If this depth is exceeded, an exception is thrown.
       *
       * <p>
       * This prevents stack overflows from occurring when trying to traverse models with recursive references.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a REST client with JSON serializer that throws an exception if the depth reaches greater than 20.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .json()
       *       .maxDepth(20)
       *       .build();
       * </p>
       *
       * <h5 class='section'>See Also:</h5><ul>
       *    <li class='jm'>{@link org.apache.juneau.marshall.MarshallingTraverseContext.Builder#maxDepth(int) MarshallingTraverseContext.Builder#maxDepth(int)}
       * </ul>
       *
       * @param value
       *    The new value for this property.
       *    <br>The default is <c>100</c>.
       * @return This object.
       */
      public SELF maxDepth(int value) {
         serializers().forEach(x -> x.maxDepth(value));
         return self();
      }

      /**
       * <i><l>WriterSerializer</l> configuration property:&emsp;</i>  Maximum indentation.
       *
       * <p>
       * Specifies the maximum indentation level in the serialized document.
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='note'>This setting does not apply to the RDF serializers.
       * </ul>
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a REST client with JSON serializer that indents a maximum of 20 tabs.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .json()
       *       .ws()  <jc>// Enable whitespace</jc>
       *       .maxIndent(20)
       *       .build();
       * </p>
       *
       * <h5 class='section'>See Also:</h5><ul>
       *    <li class='jm'>{@link org.apache.juneau.marshall.serializer.WriterSerializer.Builder#maxIndent(int) WriterSerializer.Builder#maxIndent(int)}
       * </ul>
       *
       * @param value
       *    The new value for this property.
       *    <br>The default is <c>100</c>.
       * @return This object.
       */
      public SELF maxIndent(int value) {
         serializers().forEachWS(x -> x.maxIndent(value));
         return self();
      }

      /**
       * Appends the <c>Accept</c> and <c>Content-Type</c> headers on all requests made by this client.
       *
       * <p>
       * Headers are appended to the end of the current header list.
       *
       * <p>
       * This is a shortcut for calling <c>headerData().append(Accept.<jsm>of</jsm>(<jv>value</jv>), ContentType.<jsm>of</jsm>(<jv>value</jv>))</c>.
       *
       * @param value The new header values.
       *    <br>Can be <jk>null</jk> (no Accept or Content-Type headers will be added).
       * @return This object.
       * @see #headers()
       */
      @Override
      public SELF mediaType(MediaType value) {
         super.mediaType(value);
         return headers(Accept.of(value), ContentType.of(value));
      }

      /**
       * Appends the <c>Accept</c> and <c>Content-Type</c> headers on all requests made by this client.
       *
       * <p>
       * Headers are appended to the end of the current header list.
       *
       * <p>
       * This is a shortcut for calling <c>headerData().append(Accept.<jsm>of</jsm>(<jv>value</jv>), ContentType.<jsm>of</jsm>(<jv>value</jv>))</c>.
       *
       * @param value The new header values.
       *    <br>Can be <jk>null</jk> (no Accept or Content-Type headers will be added).
       * @return This object.
       * @see #headers()
       */
      public SELF mediaType(String value) {
         super.mediaType(MediaType.of(value));
         return headers(Accept.of(value), ContentType.of(value));
      }

      /**
       * Convenience method for specifying BSON as the marshalling transmission media type.
       *
       * <p>
       * BSON (Binary JSON) is the format used by MongoDB. Identical to calling
       * <c>serializer(BsonSerializer.<jk>class</jk>).parser(BsonParser.<jk>class</jk>)</c>.
       *
       * @return This object.
       */
      public SELF bson() {
         return serializer(BsonSerializer.class).parser(BsonParser.class);
      }

      /**
       * Convenience method for specifying MessagePack as the marshalling transmission media type.
       *
       * <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 #sortCollections()}) or
       *          bean context property setters (e.g. {@link #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 #ignoreUnknownBeanProperties()}) or
       *          bean context property setters (e.g. {@link #swaps(Class...)}) defined on this builder class.
       *    </ul>
       * <p>
       *    <c>Accept</c> request header will be set to <js>"application/msgpack"</js> unless overridden
       *       via {@link #headers()}, or per-request via {@link RestRequest#header(Header)}.
       * <p>
       *    <c>Content-Type</c> request header will be set to <js>"application/msgpack"</js> unless overridden
       *       via {@link #headers()}, or per-request via {@link RestRequest#header(Header)}.
       * <p>
       *    Can be combined with other marshaller setters such as {@link #json()} 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(MsgPackSerializer.<jk>class</jk>).parser(MsgPackParser.<jk>class</jk>)</c>.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Construct a client that uses MessagePack marshalling.</jc>
       *    RestClient <jv>client</jv> = RestClient.<jsm>create</jsm>().msgPack().build();
       * </p>
       *
       * @return This object.
       */
      public SELF 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.
       *
       * <p>
       * It's up to the server to decide whether to allow for this.
       * The <c>BasicTestRestLogger</c> class watches for this header and prevents logging of status 400+ responses to
       * prevent needless logging of test scenarios.
       *
       * @return This object.
       * @see #headers()
       */
      public SELF noTrace() {
         return headers(NoTrace.of(true));
      }

      /**
       * <i><l>OpenApiCommon</l> configuration property:&emsp;</i>  Default collection format for HTTP parts.
       *
       * <p>
       * Specifies the collection format to use for HTTP parts when not otherwise specified via {@link Schema#collectionFormat()} for the
       * OpenAPI serializer and parser on this client.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a REST client with CSV format for http parts.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .collectionFormat(<jsf>CSV</jsf>)
       *       .build();
       *
       *    <jc>// An arbitrary data structure.</jc>
       *    AList <jv>list</jv> = AList.<jsm>of</jsm>(
       *       <js>"foo"</js>,
       *       <js>"bar"</js>,
       *       AMap.<jsm>of</jsm>(
       *          <js>"baz"</js>, AList.<jsm>of</jsm>(<js>"qux"</js>,<js>"true"</js>,<js>"123"</js>)
       *    )
       * );
       *
       *    <jc>// Set a header with a comma-separated list.</jc>
       *    <jv>client</jv>
       *       .get(<js>"/uri"</js>)
       *       .header(<js>"Foo"</js>, <jv>list</jv>)  <jc>// Will be serialized as: foo=bar,baz=qux\,true\,123</jc>
       *       .run();
       * </p>
       *
       * <ul class='values javatree'>
       *    <li class='jc'>{@link HttpPartCollectionFormat}
       *    <ul>
       *       <li class='jf'>{@link HttpPartCollectionFormat#CSV CSV} - (default) Comma-separated values (e.g. <js>"foo,bar"</js>).
       *       <li class='jf'>{@link HttpPartCollectionFormat#SSV SSV} - Space-separated values (e.g. <js>"foo bar"</js>).
       *       <li class='jf'>{@link HttpPartCollectionFormat#TSV TSV} - Tab-separated values (e.g. <js>"foo\tbar"</js>).
       *       <li class='jf'>{@link HttpPartCollectionFormat#PIPES PIPES} - Pipe-separated values (e.g. <js>"foo|bar"</js>).
       *       <li class='jf'>{@link HttpPartCollectionFormat#MULTI MULTI} - Corresponds to multiple parameter instances instead of multiple values for a single instance (e.g. <js>"foo=bar&amp;foo=baz"</js>).
       *       <li class='jf'>{@link HttpPartCollectionFormat#UONC UONC} - UON collection notation (e.g. <js>"@(foo,bar)"</js>).
       *    </ul>
       * </ul>
       *
       * <h5 class='section'>See Also:</h5><ul>
       *    <li class='jm'>{@link org.apache.juneau.marshall.oapi.OpenApiSerializer.Builder#collectionFormat(HttpPartCollectionFormat) OpenApiSerializer.Builder#collectionFormat(HttpPartCollectionFormat)}
       *    <li class='jm'>{@link org.apache.juneau.marshall.oapi.OpenApiParser.Builder#collectionFormat(HttpPartCollectionFormat) OpenApiParser.Builder#collectionFormat(HttpPartCollectionFormat)}
       * </ul>
       *
       * @param value
       *    The new value for this property.
       *    <br>The default value is {@link HttpPartCollectionFormat#NO_COLLECTION_FORMAT}.
       *    <br>Cannot be <jk>null</jk>.
       * @return This object.
       */
      public SELF oapiCollectionFormat(HttpPartCollectionFormat value) {
         serializers().forEach(OpenApiSerializer.Builder.class, x -> x.collectionFormat(value));
         parsers().forEach(OpenApiParser.Builder.class, x -> x.collectionFormat(value));
         partSerializer().builder(OpenApiSerializer.Builder.class, x -> x.collectionFormat(value));
         partParser().builder(OpenApiParser.Builder.class, x -> x.collectionFormat(value));
         return self();
      }

      /**
       * <i><l>OpenApiCommon</l> configuration property:&emsp;</i>  Default OpenAPI format for HTTP parts.
       *
       * <p>
       * Specifies the format to use for HTTP parts when not otherwise specified via {@link Schema#format()} for
       * the OpenAPI serializer and parser on this client.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a REST client with UON part serialization and parsing.</jc>
       *    RestClient <jv>client</jv>  = RestClient
       *       .<jsm>create</jsm>()
       *       .oapiFormat(<jsf>UON</jsf>)
       *       .build();
       *
       *    <jc>// Set a header with a value in UON format.</jc>
       *    <jv>client</jv>
       *       .get(<js>"/uri"</js>)
       *       .header(<js>"Foo"</js>, <js>"bar baz"</js>)  <jc>// Will be serialized as:  'bar baz'</jc>
       *       .run();
       * </p>
       *
       * <ul class='values javatree'>
       *    <li class='jc'>{@link HttpPartFormat}
       *    <ul>
       *       <li class='jf'>{@link HttpPartFormat#UON UON} - UON notation (e.g. <js>"'foo bar'"</js>).
       *       <li class='jf'>{@link HttpPartFormat#INT32 INT32} - Signed 32 bits.
       *       <li class='jf'>{@link HttpPartFormat#INT64 INT64} - Signed 64 bits.
       *       <li class='jf'>{@link HttpPartFormat#FLOAT FLOAT} - 32-bit floating point number.
       *       <li class='jf'>{@link HttpPartFormat#DOUBLE DOUBLE} - 64-bit floating point number.
       *       <li class='jf'>{@link HttpPartFormat#BYTE BYTE} - BASE-64 encoded characters.
       *       <li class='jf'>{@link HttpPartFormat#BINARY BINARY} - Hexadecimal encoded octets (e.g. <js>"00FF"</js>).
       *       <li class='jf'>{@link HttpPartFormat#BINARY_SPACED BINARY_SPACED} - Spaced-separated hexadecimal encoded octets (e.g. <js>"00 FF"</js>).
       *       <li class='jf'>{@link HttpPartFormat#DATE DATE} - An <a href='http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14'>RFC3339 full-date</a>.
       *       <li class='jf'>{@link HttpPartFormat#DATE_TIME DATE_TIME} - An <a href='http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14'>RFC3339 date-time</a>.
       *       <li class='jf'>{@link HttpPartFormat#PASSWORD PASSWORD} - Used to hint UIs the input needs to be obscured.
       *       <li class='jf'>{@link HttpPartFormat#NO_FORMAT NO_FORMAT} - (default) Not specified.
       *    </ul>
       * </ul>
       *
       * <h5 class='section'>See Also:</h5><ul>
       *    <li class='jm'>{@link org.apache.juneau.marshall.oapi.OpenApiSerializer.Builder#format(HttpPartFormat) OpenApiSerializer.Builder#format(HttpPartFormat)}
       *    <li class='jm'>{@link org.apache.juneau.marshall.oapi.OpenApiParser.Builder#format(HttpPartFormat) OpenApiParser.Builder#format(HttpPartFormat)}
       * </ul>
       *
       * @param value
       *    The new value for this property.
       *    <br>The default value is {@link HttpPartFormat#NO_FORMAT}.
       *    <br>Cannot be <jk>null</jk>.
       * @return This object.
       */
      public SELF oapiFormat(HttpPartFormat value) {
         serializers().forEach(OpenApiSerializer.Builder.class, x -> x.format(value));
         parsers().forEach(OpenApiParser.Builder.class, x -> x.format(value));
         partSerializer().builder(OpenApiSerializer.Builder.class).ifPresent(x -> x.format(value));
         partParser().builder(OpenApiParser.Builder.class).ifPresent(x -> x.format(value));
         return self();
      }

      /**
       * Convenience method for specifying OpenAPI as the marshalling transmission media type.
       *
       * <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 #sortCollections()}) or
       *          bean context property setters (e.g. {@link #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 #ignoreUnknownBeanProperties()}) or
       *          bean context property setters (e.g. {@link #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
       *       via {@link #headers()}, or per-request via {@link RestRequest#header(Header)}.
       * <p>
       *    <c>Content-Type</c> request header will be set to <js>"text/openapi"</js> unless overridden
       *       via {@link #headers()}, or per-request via {@link RestRequest#header(Header)}.
       * <p>
       *    Can be combined with other marshaller setters such as {@link #json()} 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(OpenApiSerializer.<jk>class</jk>).parser(OpenApiParser.<jk>class</jk>)</c>.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Construct a client that uses OpenAPI marshalling.</jc>
       *    RestClient <jv>client</jv> = RestClient.<jsm>create</jsm>().openApi().build();
       * </p>
       *
       * @return This object.
       */
      public SELF openApi() {
         return serializer(OpenApiSerializer.class).parser(OpenApiParser.class);
      }

      /**
       * <i><l>UonSerializer</l> configuration property:&emsp;</i>  Parameter format.
       *
       * <p>
       * Specifies the format of parameters when using the {@link UrlEncodingSerializer} to serialize Form Posts.
       *
       * <p>
       * Specifies the format to use for GET parameter keys and values.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a REST client with URL-Encoded serializer that serializes values in plain-text format.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .urlEnc()
       *       .paramFormat(<jsf>PLAINTEXT</jsf>)
       *       .build();
       *
       *    <jc>// An arbitrary data structure.</jc>
       *    AMap <jv>map</jv> = AMap.<jsm>of</jsm>(
       *       <js>"foo"</js>, <js>"bar"</js>,
       *       <js>"baz"</js>, <jk>new</jk> String[]{<js>"qux"</js>, <js>"true"</js>, <js>"123"</js>}
       *    );
       *
       *    <jc>// Request body will be serialized as:  foo=bar,baz=qux,true,123</jc>
       *    <jv>client</jv>
       *       .post(<js>"/uri"</js>, <jv>map</jv>)
       *       .run();
       * </p>
       *
       * <ul class='values javatree'>
       *    <li class='jf'>{@link ParamFormat#UON} (default) - Use UON notation for parameters.
       *    <li class='jf'>{@link ParamFormat#PLAINTEXT} - Use plain text for parameters.
       * </ul>
       *
       * <h5 class='section'>See Also:</h5><ul>
       *    <li class='jm'>{@link org.apache.juneau.marshall.uon.UonSerializer.Builder#paramFormat(ParamFormat) UonSerializer.Builder#paramFormat(ParamFormat)}
       * </ul>
       *
       * @param value The new value for this property.
       *    <br>Cannot be <jk>null</jk>.
       * @return This object.
       */
      public SELF paramFormat(ParamFormat value) {
         serializers().forEach(UonSerializer.Builder.class, x -> x.paramFormat(value));
         return self();
      }

      /**
       * <i><l>UonSerializer</l> configuration property:&emsp;</i>  Parameter format.
       *
       * <p>
       * Specifies the format of parameters when using the {@link UrlEncodingSerializer} to serialize Form Posts.
       *
       * <p>
       * Specifies plaintext as the format to use for GET parameter keys and values.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a REST client with URL-Encoded serializer that serializes values in plain-text format.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .urlEnc()
       *       .build();
       *
       *    <jc>// An arbitrary data structure.</jc>
       *    AMap <jv>map</jv> = AMap.<jsm>of</jsm>(
       *       <js>"foo"</js>, <js>"bar"</js>,
       *       <js>"baz"</js>, <jk>new</jk> String[]{<js>"qux"</js>, <js>"true"</js>, <js>"123"</js>}
       *    );
       *
       *    <jc>// Request body will be serialized as:  foo=bar,baz=qux,true,123</jc>
       *    <jv>client</jv>
       *       .post(<js>"/uri"</js>, <jv>map</jv>)
       *       .run();
       * </p>
       *
       * <h5 class='section'>See Also:</h5><ul>
       *    <li class='jm'>{@link org.apache.juneau.marshall.uon.UonSerializer.Builder#paramFormatPlain() UonSerializer.Builder#paramFormatPlain()}
       * </ul>
       *
       * @return This object.
       */
      public SELF paramFormatPlain() {
         serializers().forEach(UonSerializer.Builder.class, UonSerializer.Builder::paramFormatPlain);
         return self();
      }

      /**
       * Parser.
       *
       * <p>
       * Associates the specified {@link Parser Parser} with the HTTP client.
       *
       * <p>
       * The parser is used to parse the HTTP response body into a POJO.
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='note'>When using this method that takes in a class, the parser can be configured using any of the parser property setters (e.g. {@link #ignoreUnknownBeanProperties()}) or
       *    bean context property setters (e.g. {@link #swaps(Class...)}) defined on this builder class.
       * </ul>
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a client that uses JSON transport for response bodies.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .parser(JsonParser.<jk>class</jk>)
       *       .build();
       * </p>
       *
       * @param value
       *    The new value for this setting.
       *    <br>The default value is {@link JsonParser#DEFAULT}.
       * @return This object.
       */
      public SELF parser(Class<? extends Parser> value) {
         return parsers(value);
      }

      /**
       * Parser.
       *
       * <p>
       * Associates the specified {@link Parser Parser} with the HTTP client.
       *
       * <p>
       * The parser is used to parse the HTTP response body into a POJO.
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='note'>When using this method that takes in a pre-instantiated parser, the parser property setters (e.g. {@link #ignoreUnknownBeanProperties()}) or
       *    bean context property setters (e.g. {@link #swaps(Class...)}) defined
       *    on this builder class have no effect.
       * </ul>
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a client that uses a predefined JSON parser for response bodies.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .parser(JsonParser.<jsf>DEFAULT</jsf>)
       *       .build();
       * </p>
       *
       * @param value
       *    The new value for this setting.
       *    <br>The default value is {@link JsonParser#DEFAULT}.
       *    <br>Cannot be <jk>null</jk>.
       * @return This object.
       */
      public SELF parser(Parser value) {
         return parsers(value);
      }

      /**
       * Returns the parser group sub-builder.
       *
       * @return The parser group sub-builder.
       */
      public final ParserSet.Builder parsers() {
         if (parsers == null)
            parsers = createParsers();
         return parsers;
      }

      /**
       * Parsers.
       *
       * <p>
       * Associates the specified {@link Parser Parsers} with the HTTP client.
       *
       * <p>
       * The parsers are used to parse the HTTP response body into a POJO.
       *
       * <p>
       * The parser that best matches the <c>Accept</c> header will be used to parse the response body.
       * <br>If no <c>Accept</c> header is specified, the first parser in the list will be used.
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='note'>When using this method that takes in classes, the parsers can be configured using any of the parser property setters (e.g. {@link #ignoreUnknownBeanProperties()}) or
       *    bean context property setters (e.g. {@link #swaps(Class...)}) defined on this builder class.
       * </ul>
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a client that uses JSON and XML transport for response bodies.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .parser(JsonParser.<jk>class</jk>, XmlParser.<jk>class</jk>)
       *       .build();
       * </p>
       *
       * @param value
       *    The new value for this setting.
       *    <br>The default value is {@link JsonParser#DEFAULT}.
       * @return This object.
       */
      public SELF parsers(Class<? extends Parser>...value) {
         reqnns("value", value);
         parsers().add(value);
         return self();
      }

      /**
       * Parsers.
       *
       * <p>
       * Associates the specified {@link Parser Parsers} with the HTTP client.
       *
       * <p>
       * The parsers are used to parse the HTTP response body into a POJO.
       *
       * <p>
       * The parser that best matches the <c>Accept</c> header will be used to parse the response body.
       * <br>If no <c>Accept</c> header is specified, the first parser in the list will be used.
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='note'>When using this method that takes in pre-instantiated parsers, the parser property setters (e.g. {@link #ignoreUnknownBeanProperties()}) or
       *    bean context property setters (e.g. {@link #swaps(Class...)}) defined
       *    on this builder class have no effect.
       * </ul>
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a client that uses JSON and XML transport for response bodies.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .parser(JsonParser.<jsf>DEFAULT</jsf>, XmlParser.<jsf>DEFAULT</jsf>)
       *       .build();
       * </p>
       *
       * @param value
       *    The new value for this setting.
       *    <br>The default value is {@link JsonParser#DEFAULT}.
       * @return This object.
       */
      public SELF parsers(Parser...value) {
         reqnns("value", value);
         parsers().add(value);
         return self();
      }

      /**
       * Returns the part parser sub-builder.
       *
       * @return The part parser sub-builder.
       */
      public final HttpPartParser.Creator partParser() {
         if (partParser == null)
            partParser = createPartParser();
         return partParser;
      }

      /**
       * Part parser.
       *
       * <p>
       * The parser to use for parsing POJOs from form data, query parameters, headers, and path variables.
       *
       * <p>
       * The default part parser is {@link OpenApiParser} which allows for schema-driven marshalling.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a client that uses UON format by default for incoming HTTP parts.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .partParser(UonParser.<jk>class</jk>)
       *       .build();
       * </p>
       *
       * @param value
       *    The new value for this setting.
       *    <br>The default value is {@link OpenApiParser}.
       *    <br>Cannot be <jk>null</jk>.
       * @return This object.
       */
      public SELF partParser(Class<? extends HttpPartParser> value) {
         partParser().type(reqnn("value", value));
         return self();
      }

      /**
       * Part parser.
       *
       * <p>
       * The parser to use for parsing POJOs from form data, query parameters, headers, and path variables.
       *
       * <p>
       * The default part parser is {@link OpenApiParser} which allows for schema-driven marshalling.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a client that uses UON format by default for incoming HTTP parts.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .partParser(UonParser.<jsf>DEFAULT</jsf>)
       *       .build();
       * </p>
       *
       * @param value
       *    The new value for this setting.
       *    <br>The default value is {@link OpenApiParser}.
       *    <br>Cannot be <jk>null</jk>.
       * @return This object.
       */
      public SELF partParser(HttpPartParser value) {
         partParser().impl(reqnn("value", value));
         return self();
      }

      /**
       * Returns the part serializer sub-builder.
       *
       * @return The part serializer sub-builder.
       */
      public final HttpPartSerializer.Creator partSerializer() {
         if (partSerializer == null)
            partSerializer = createPartSerializer();
         return partSerializer;
      }

      /**
       * Part serializer.
       *
       * <p>
       * The serializer to use for serializing POJOs in form data, query parameters, headers, and path variables.
       *
       * <p>
       * The default part serializer is {@link OpenApiSerializer} which allows for schema-driven marshalling.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a client that uses UON format by default for outgoing HTTP parts.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .partSerializer(UonSerializer.<jk>class</jk>)
       *       .build();
       * </p>
       *
       * @param value
       *    The new value for this setting.
       *    <br>The default value is {@link OpenApiSerializer}.
       *    <br>Cannot be <jk>null</jk>.
       * @return This object.
       */
      public SELF partSerializer(Class<? extends HttpPartSerializer> value) {
         partSerializer().type(reqnn("value", value));
         return self();
      }

      /**
       * Part serializer.
       *
       * <p>
       * The serializer to use for serializing POJOs in form data, query parameters, headers, and path variables.
       *
       * <p>
       * The default part serializer is {@link OpenApiSerializer} which allows for schema-driven marshalling.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a client that uses UON format by default for outgoing HTTP parts.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .partSerializer(UonSerializer.<jsf>DEFAULT</jsf>)
       *       .build();
       * </p>
       *
       * @param value
       *    The new value for this setting.
       *    <br>The default value is {@link OpenApiSerializer}.
       *    <br>Cannot be <jk>null</jk>.
       * @return This object.
       */
      public SELF partSerializer(HttpPartSerializer value) {
         partSerializer().impl(reqnn("value", value));
         return self();
      }

      /**
       * Returns the builder for the list of path data parameters that get applied to all requests created by this builder.
       *
       * <p>
       * This is the primary method for accessing the path data parameter list.
       * On first call, the builder is created via the method {@link #createFormData()}.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a client that uses "bar" for the "{foo}" path variable on every request.</jc>
       *    RestClient.Builder&lt;?&gt; <jv>builder</jv> = RestClient.<jsm>create</jsm>();
       *    <jv>builder</jv>.pathData().setDefault(<js>"foo"</js>, <js>"bar"</js>));
       *    RestClient <jv>client</jv> = <jv>builder</jv>.build();
       * </p>
       *
       * <p>
       * The following convenience methods are also provided for updating the parameters:
       * <ul>
       *    <li class='jm'>{@link #pathData(NameValuePair...)}
       *    <li class='jm'>{@link #pathDataDefault(NameValuePair...)}
       *    <li class='jm'>{@link #pathData(String,String)}
       *    <li class='jm'>{@link #pathData(String,Supplier)}
       * </ul>
       *
       * @return The form data list builder.
       */
      public final PartList pathData() {
         if (pathData == null)
            pathData = createPathData();
         return pathData;
      }

      /**
       * Sets multiple path parameters on all requests.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jk>import static</jk> org.apache.juneau.http.HttpParts.*;
       *
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .pathData(
       *          <jsm>stringPart</jsm>(<js>"foo"</js>, <js>"bar"</js>),
       *          <jsm>booleanPart</jsm>(<js>"baz"</js>, <jk>true</jk>)
       *       )
       *       .build();
       * </p>
       *
       * <p>
       * This is a shortcut for calling <c>pathData().append(<jv>parts</jv>)</c>.
       *
       * @param parts
       *    The path parameters.
       *    <br>Can contain <jk>null</jk> values (ignored).
       * @return This object.
       * @see #pathData()
       */
      public SELF pathData(NameValuePair...parts) {
         pathData().append(parts);
         return self();
      }

      /**
       * Appends a path parameter to all request bodies.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .pathData(<js>"foo"</js>, <js>"bar"</js>)
       *       .build();
       * </p>
       *
       * <p>
       * This is a shortcut for calling <c>pathData().append(<jv>name</jv>,<jv>value</jv>)</c>.
       *
       * @param name The parameter name.
       *    <br>Cannot be <jk>null</jk>.
       * @param value The parameter value.
       *    <br>Can be <jk>null</jk> (null value will be serialized).
       * @return This object.
       * @see #pathData()
       */
      public SELF pathData(String name, String value) {
         pathData().append(name, value);
         return self();
      }

      /**
       * Sets a path parameter with a dynamic value to all request bodies.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .pathData(<js>"foo"</js>, ()-&gt;<js>"bar"</js>)
       *       .build();
       * </p>
       *
       * <p>
       * This is a shortcut for calling <c>pathData().append(<jv>name</jv>,<jv>value</jv>)</c>.
       *
       * @param name The parameter name.
       *    <br>Cannot be <jk>null</jk>.
       * @param value The parameter value supplier.
       *    <br>Can be <jk>null</jk> (null value will be serialized).
       * @return This object.
       * @see #pathData()
       */
      public SELF pathData(String name, Supplier<String> value) {
         pathData().set(name, value);
         return self();
      }

      /**
       * Sets default path parameter values.
       *
       * <p>
       * Uses default values for specified parameters if not otherwise specified on the outgoing requests.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .pathDataDefault(<jsm>stringPart</jsm>(<js>"foo"</js>, ()-&gt;<js>"bar"</js>));
       *       .build();
       * </p>
       *
       * <p>
       * This is a shortcut for calling <c>pathData().setDefault(<jv>parts</jv>)</c>.
       *
       * @param parts The parts.
       *    <br>Can contain <jk>null</jk> values (ignored).
       * @return This object.
       * @see #pathData()
       */
      public SELF pathDataDefault(NameValuePair...parts) {
         pathData().setDefault(parts);
         return self();
      }

      /**
       * Convenience method for specifying Plain Text as the marshalling transmission media type.
       *
       * <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 #sortCollections()}) or
       *          bean context property setters (e.g. {@link #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 #ignoreUnknownBeanProperties()}) or
       *          bean context property setters (e.g. {@link #swaps(Class...)}) defined on this builder class.
       *    </ul>
       * <p>
       *    <c>Accept</c> request header will be set to <js>"text/plain"</js> unless overridden
       *       via {@link #headers()}, or per-request via {@link RestRequest#header(Header)}.
       * <p>
       *    <c>Content-Type</c> request header will be set to <js>"text/plain"</js> unless overridden
       *       via {@link #headers()}, or per-request via {@link RestRequest#header(Header)}.
       * <p>
       *    Can be combined with other marshaller setters such as {@link #json()} 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(PlainTextSerializer.<jk>class</jk>).parser(PlainTextParser.<jk>class</jk>)</c>.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Construct a client that uses Plain Text marshalling.</jc>
       *    RestClient <jv>client</jv> = RestClient.<jsm>create</jsm>().plainText().build();
       * </p>
       *
       * @return This object.
       */
      public SELF plainText() {
         return serializer(PlainTextSerializer.class).parser(PlainTextParser.class);
      }

      /**
       * When called, the {@link #createConnectionManager()} method will return a {@link PoolingHttpClientConnectionManager}
       * instead of a {@link BasicHttpClientConnectionManager}.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Construct a client that uses pooled connections.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .pooled()
       *       .build();
       * </p>
       *
       * @return This object.
       */
      public SELF pooled() {
         this.pooled = true;
         return self();
      }

      /**
       * Assigns default proxy value.
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='note'>This value can be overridden by the {@link #routePlanner(HttpRoutePlanner)} method.
       *    <li class='warn'>Through a proxy, the SSRF guard's pin-on-connect would check the proxy's address rather than
       *       the target's, so an SSRF-guard-active {@code @Remote} call (one without the
       *       {@link #allowPrivateUrls(boolean) allowPrivateUrls} opt-in) on a proxy route is refused.  This applies to any
       *       proxy route, including one chosen by a {@link #routePlanner(HttpRoutePlanner) route planner} or the proxy
       *       system properties ({@link #useSystemProperties()}).  Ordinary requests are unaffected.
       * </ul>
       *
       * @param proxy New property value.
       *    <br>Can be <jk>null</jk> (value will not be set, default behavior will be used).
       * @return This object.
       * @see HttpClientBuilder#setProxy(HttpHost)
       */
      public SELF proxy(HttpHost proxy) {
         httpClientBuilder().setProxy(proxy);
         return self();
      }

      /**
       * Assigns {@link AuthenticationStrategy} instance for proxy authentication.
       *
       * @param proxyAuthStrategy New property value.
       *    <br>Can be <jk>null</jk> (value will not be set, default behavior will be used).
       * @return This object.
       * @see HttpClientBuilder#setProxyAuthenticationStrategy(AuthenticationStrategy)
       */
      public SELF proxyAuthenticationStrategy(AuthenticationStrategy proxyAuthStrategy) {
         httpClientBuilder().setProxyAuthenticationStrategy(proxyAuthStrategy);
         return self();
      }

      /**
       * Assigns file containing public suffix matcher.
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='note'>Instances of this class can be created with {@link PublicSuffixMatcherLoader}.
       *    <li class='note'>It is used for cookies and, in both pools of the connection manager the default
       *       {@link #createConnectionManager()} builds, by the default hostname verifier (one is used unless
       *       {@link #sslHostnameVerifier(HostnameVerifier)} or {@link #sslSocketFactory(LayeredConnectionSocketFactory)}
       *       is set).
       * </ul>
       *
       * @param publicSuffixMatcher New property value.
       *    <br>Can be <jk>null</jk> (value will not be set, default behavior will be used).
       * @return This object.
       * @see HttpClientBuilder#setPublicSuffixMatcher(PublicSuffixMatcher)
       */
      public SELF publicSuffixMatcher(PublicSuffixMatcher publicSuffixMatcher) {
         this.publicSuffixMatcher = publicSuffixMatcher;
         httpClientBuilder().setPublicSuffixMatcher(publicSuffixMatcher);
         return self();
      }

      /**
       * Returns the builder for the list of query parameters that get applied to all requests created by this builder.
       *
       * <p>
       * This is the primary method for accessing the query parameter list.
       * On first call, the builder is created via the method {@link #createQueryData()}.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a client that adds a "foo=bar" query parameter on every request.</jc>
       *    RestClient.Builder&lt;?&gt; <jv>builder</jv> = RestClient.<jsm>create</jsm>();
       *    <jv>builder</jv>.queryData().setDefault(<js>"foo"</js>, <js>"bar"</js>));
       *    RestClient <jv>client</jv> = <jv>builder</jv>.build();
       * </p>
       *
       * <p>
       * The following convenience methods are also provided for updating the parameters:
       * <ul>
       *    <li class='jm'>{@link #queryData(NameValuePair...)}
       *    <li class='jm'>{@link #queryDataDefault(NameValuePair...)}
       *    <li class='jm'>{@link #queryData(String,String)}
       *    <li class='jm'>{@link #queryData(String,Supplier)}
       * </ul>
       *
       * @return The query data list builder.
       */
      public final PartList queryData() {
         if (queryData == null)
            queryData = createQueryData();
         return queryData;
      }

      /**
       * Appends multiple query parameters to the URI of all requests.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jk>import static</jk> org.apache.juneau.http.HttpParts.*;
       *
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .queryData(
       *          <jsm>stringPart</jsm>(<js>"foo"</js>, <js>"bar"</js>),
       *          <jsm>booleanPart</jsm>(<js>"baz"</js>, <jk>true</jk>)
       *       )
       *       .build();
       * </p>
       *
       * <p>
       * This is a shortcut for calling <c>queryData().append(<jv>parts</jv>)</c>.
       *
       * @param parts
       *    The query parameters.
       *    <br>Can contain <jk>null</jk> values (ignored).
       * @return This object.
       * @see #queryData()
       */
      public SELF queryData(NameValuePair...parts) {
         queryData().append(parts);
         return self();
      }

      /**
       * Appends a query parameter to the URI.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .queryData(<js>"foo"</js>, <js>"bar"</js>)
       *       .build();
       * </p>
       *
       * <p>
       * This is a shortcut for calling <c>queryData().append(<jv>name</jv>,<jv>value</jv>)</c>.
       *
       * @param name The parameter name.
       *    <br>Cannot be <jk>null</jk>.
       * @param value The parameter value.
       *    <br>Can be <jk>null</jk> (null value will be serialized).
       * @return This object.
       * @see #queryData()
       */
      public SELF queryData(String name, String value) {
         queryData().append(name, value);
         return self();
      }

      /**
       * Appends a query parameter with a dynamic value to the URI.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .queryData(<js>"foo"</js>, ()-&gt;<js>"bar"</js>)
       *       .build();
       * </p>
       *
       * <p>
       * This is a shortcut for calling <c>queryData().append(<jv>name</jv>,<jv>value</jv>)</c>.
       *
       * @param name The parameter name.
       *    <br>Cannot be <jk>null</jk>.
       * @param value The parameter value supplier.
       *    <br>Can be <jk>null</jk> (null value will be serialized).
       * @return This object.
       * @see #queryData()
       */
      public SELF queryData(String name, Supplier<String> value) {
         queryData().append(name, value);
         return self();
      }

      /**
       * Sets default query parameter values.
       *
       * <p>
       * Uses default values for specified parameters if not otherwise specified on the outgoing requests.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .queryDataDefault(<jsm>stringPart</jsm>(<js>"foo"</js>, ()-&gt;<js>"bar"</js>));
       *       .build();
       * </p>
       *
       * <p>
       * This is a shortcut for calling <c>queryData().setDefault(<jv>parts</jv>)</c>.
       *
       * @param parts The parts.
       *    <br>Can contain <jk>null</jk> values (ignored).
       * @return This object.
       * @see #queryData()
       */
      public SELF queryDataDefault(NameValuePair...parts) {
         queryData().setDefault(parts);
         return self();
      }

      /**
       * Sets a default query parameter with serializer session options (UON map) for all requests.
       *
       * <p>
       * This is a shortcut for <c>queryDataDefault(stringPart({@link RestSharedConstants#QUERY_juneauSerializerOptions}, <jv>uon</jv>))</c>.
       *
       * @param uon
       *    Serializer session options in UON form.
       *    <br>Can be <jk>null</jk> (default is not set by this method).
       * @return This object.
       */
      public SELF serializerSessionOptionsQueryDefault(String uon) {
         if (uon != null)
            queryDataDefault(stringPart(QUERY_juneauSerializerOptions, uon));
         return self();
      }

      /**
       * Sets a default query parameter with parser session options (UON map) for all requests.
       *
       * <p>
       * This is a shortcut for <c>queryDataDefault(stringPart({@link RestSharedConstants#QUERY_juneauParserOptions}, <jv>uon</jv>))</c>.
       *
       * @param uon
       *    Parser session options in UON form.
       *    <br>Can be <jk>null</jk> (default is not set by this method).
       * @return This object.
       */
      public SELF parserSessionOptionsQueryDefault(String uon) {
         if (uon != null)
            queryDataDefault(stringPart(QUERY_juneauParserOptions, uon));
         return self();
      }

      /**
       * Convenience for {@link #serializerSessionOptionsQueryDefault(String)} using {@link Uon#of(Object)}.
       *
       * @param properties
       *    Property names and values for serializer session options.
       *    <br>Can be <jk>null</jk> (treated as an empty map).
       * @return This object.
       */
      public SELF serializerSessionOptionsQueryDefault(Map<String,?> properties) {
         try {
            return serializerSessionOptionsQueryDefault(isEmpty(properties) ? null : Uon.of(properties));
         } catch (SerializeException e) {
            throw rex(e, "Could not serialize serializer session options query default");
         }
      }

      /**
       * Convenience for {@link #parserSessionOptionsQueryDefault(String)} using {@link Uon#of(Object)}.
       *
       * @param properties
       *    Property names and values for parser session options.
       *    <br>Can be <jk>null</jk> (treated as an empty map).
       * @return This object.
       */
      public SELF parserSessionOptionsQueryDefault(Map<String,?> properties) {
         try {
            return parserSessionOptionsQueryDefault(isEmpty(properties) ? null : Uon.of(properties));
         } catch (SerializeException e) {
            throw rex(e, "Could not serialize parser session options query default");
         }
      }

      /**
       * <i><l>WriterSerializer</l> configuration property:&emsp;</i>  Quote character.
       *
       * <p>
       * Specifies the character to use for quoting attributes and values.
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='note'>This setting does not apply to the RDF serializers.
       * </ul>
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a REST client with JSON serializer that uses single quotes.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .json()
       *       .quoteChar(<js>'\''</js>)
       *       .build();
       *
       *    <jc>// A bean with a single property</jc>
       *    <jk>public class</jk> MyBean {
       *       <jk>public</jk> String <jf>foo</jf> = <js>"bar"</js>;
       *    }
       *
       *    <jc>// Request body will contain:  {'foo':'bar'}</jc>
       *    <jv>client</jv>
       *       .post(<js>"http://localhost:10000/foo"</js>, <jk>new</jk> MyBean())
       *       .run();
       * </p>
       *
       * <h5 class='section'>See Also:</h5><ul>
       *    <li class='jm'>{@link org.apache.juneau.marshall.serializer.WriterSerializer.Builder#quoteChar(char) WriterSerializer.Builder#quoteChar(char)}
       * </ul>
       *
       * @param value
       *    The new value for this property.
       *    <br>The default is <js>'"'</js>.
       * @return This object.
       */
      public SELF quoteChar(char value) {
         serializers().forEachWS(x -> x.quoteChar(value));
         return self();
      }

      /**
       * Assigns {@link RedirectStrategy} instance.
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='note'>This value can be overridden by the {@link #disableRedirectHandling()} method.
       * </ul>
       *
       * @param redirectStrategy New property value.
       *    <br>Can be <jk>null</jk> (value will not be set, default behavior will be used).
       * @return This object.
       * @see HttpClientBuilder#setRedirectStrategy(RedirectStrategy)
       */
      public SELF redirectStrategy(RedirectStrategy redirectStrategy) {
         httpClientBuilder().setRedirectStrategy(redirectStrategy);
         return self();
      }

      /**
       * Assigns {@link HttpRequestExecutor} instance.
       *
       * @param requestExec New property value.
       *    <br>Can be <jk>null</jk> (value will not be set, default behavior will be used).
       * @return This object.
       * @see HttpClientBuilder#setRequestExecutor(HttpRequestExecutor)
       */
      public SELF requestExecutor(HttpRequestExecutor requestExec) {
         httpClientBuilder().setRequestExecutor(requestExec);
         return self();
      }

      /**
       * Assigns {@link HttpRequestRetryHandler} instance.
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='note'>This value can be overridden by the {@link #disableAutomaticRetries()} method.
       * </ul>
       *
       * @param retryHandler New property value.
       *    <br>Can be <jk>null</jk> (value will not be set, default behavior will be used).
       * @return This object.
       * @see HttpClientBuilder#setRetryHandler(HttpRequestRetryHandler)
       */
      public SELF retryHandler(HttpRequestRetryHandler retryHandler) {
         httpClientBuilder().setRetryHandler(retryHandler);
         return self();
      }

      /**
       * <i><l>RestClient</l> configuration property:&emsp;</i>  Root URI.
       *
       * <p>
       * When set, relative URI strings passed in through the various rest call methods (e.g. {@link RestClient#get(Object)}
       * will be prefixed with the specified root.
       * <br>This root URI is ignored on those methods if you pass in a {@link URL}, {@link URI}, or an absolute URI string.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a client that uses UON format by default for HTTP parts.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .rootUrl(<js>"http://localhost:10000/foo"</js>)
       *       .build();
       *
       *    Bar <jv>bar</jv> = <jv>client</jv>
       *       .get(<js>"/bar"</js>)  <jc>// Relative to http://localhost:10000/foo</jc>
       *       .run()
       *       .getContent().as(Bar.<jk>class</jk>);
       * </p>
       *
       * @param value
       *    The root URI to prefix to relative URI strings.
       *    <br>Trailing slashes are trimmed.
       *    <br>Usually a <c>String</c> but you can also pass in <c>URI</c> and <c>URL</c> objects as well.
       *    <br>Can be <jk>null</jk> (no root URL will be set).
       * @return This object.
       */
      public SELF rootUrl(Object value) {
         var s = s(value);
         if (ine(s))
            s = s.replaceAll("\\/$", "");
         if (isEmpty(s))
            rootUrl = null;
         else if (s.indexOf("://") == -1)
            throw rex("Invalid rootUrl value: '%s'.  Must be a valid absolute URL.", value);
         else {
            final var url = s;
            rootUrl = () -> url;
         }
         return self();
      }

      /**
       * Sets the root URL using a supplier, allowing the URL to be computed dynamically at request time.
       *
       * <p>
       * The supplier is called on every request, so the URL can change between requests.
       * No build-time validation is performed; invalid values will surface as errors when requests are made.
       *
       * <p>
       * Three common patterns are supported:
       * <ul>
       *    <li>
       *       <b>Swappable reference</b> &mdash; Use an {@link AtomicReference AtomicReference}
       *       when you need to point the client at a different host at any time:
       *       <p class='bjava'>
       *          AtomicReference&lt;String&gt; <jv>urlRef</jv> = <jk>new</jk> AtomicReference&lt;&gt;(<js>"https://host1"</js>);
       *          RestClient <jv>client</jv> = RestClient.<jsm>create</jsm>().rootUrl(<jv>urlRef</jv>::get).build();
       *
       *          <jc>// Switch to a different host at runtime.</jc>
       *          <jv>urlRef</jv>.set(<js>"https://host2"</js>);
       *       </p>
       *    <li>
       *       <b>Refreshable cached value</b> &mdash; Use {@link Memoizer Memoizer}
       *       (via {@link Suppliers#memoizer(Supplier) Suppliers.memoizer()})
       *       when computing the URL is expensive (e.g. service discovery) and you want it cached until explicitly refreshed:
       *       <p class='bjava'>
       *          Memoizer&lt;String&gt; <jv>url</jv> = <jsm>memoizer</jsm>(() -&gt; serviceDiscovery.<jsm>findUrl</jsm>(<js>"my-service"</js>));
       *          RestClient <jv>client</jv> = RestClient.<jsm>create</jsm>().rootUrl(<jv>url</jv>).build();
       *
       *          <jc>// Force re-evaluation on the next request (e.g. after a failover).</jc>
       *          <jv>url</jv>.reset();
       *       </p>
       *    <li>
       *       <b>Purely dynamic</b> &mdash; Use a plain lambda when the URL must be re-evaluated on every request:
       *       <p class='bjava'>
       *          RestClient <jv>client</jv> = RestClient.<jsm>create</jsm>().rootUrl(() -&gt; config.<jsm>getRootUrl</jsm>()).build();
       *       </p>
       * </ul>
       *
       * @param value
       *    A supplier that returns the root URI to prefix to relative URI strings.
       *    <br>Can be <jk>null</jk> (no root URL will be set).
       * @return This object.
       */
      public SELF rootUrl(Supplier<String> value) {
         rootUrl = value;
         return self();
      }

      /**
       * Assigns {@link HttpRoutePlanner} instance.
       *
       * @param routePlanner New property value.
       *    <br>Can be <jk>null</jk> (value will not be set, default behavior will be used).
       * @return This object.
       * @see HttpClientBuilder#setRoutePlanner(HttpRoutePlanner)
       */
      public SELF routePlanner(HttpRoutePlanner routePlanner) {
         httpClientBuilder().setRoutePlanner(routePlanner);
         return self();
      }

      /**
       * Assigns {@link SchemePortResolver} instance.
       *
       * @param schemePortResolver New property value.
       *    <br>Can be <jk>null</jk> (value will not be set, default behavior will be used).
       * @return This object.
       * @see HttpClientBuilder#setSchemePortResolver(SchemePortResolver)
       */
      public SELF schemePortResolver(SchemePortResolver schemePortResolver) {
         httpClientBuilder().setSchemePortResolver(schemePortResolver);
         return self();
      }

      /**
       * Serializer.
       *
       * <p>
       * Associates the specified {@link Serializer Serializer} with the HTTP client.
       *
       * <p>
       * The serializer is used to serialize POJOs into the HTTP request body.
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='note'>When using this method that takes in a class, the serializer can be configured using any of the serializer property setters (e.g. {@link #sortCollections()}) or
       *    bean context property setters (e.g. {@link #swaps(Class...)}) defined on this builder class.
       * </ul>
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a client that uses JSON transport for request bodies.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .serializer(JsonSerializer.<jk>class</jk>)
       *       .sortCollections()  <jc>// Sort any collections being serialized.</jc>
       *       .build();
       * </p>
       *
       * @param value
       *    The new value for this setting.
       *    <br>The default is {@link JsonSerializer}.
       * @return This object.
       */
      public SELF serializer(Class<? extends Serializer> value) {
         return serializers(value);
      }

      /**
       * Serializer.
       *
       * <p>
       * Associates the specified {@link Serializer Serializer} with the HTTP client.
       *
       * <p>
       * The serializer is used to serialize POJOs into the HTTP request body.
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='note'>When using this method that takes in a pre-instantiated serializer, the serializer property setters (e.g. {@link #sortCollections()}) or
       *    bean context property setters (e.g. {@link #swaps(Class...)}) defined
       *    on this builder class have no effect.
       * </ul>
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a client that uses a predefined JSON serializer request bodies.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .serializer(JsonSerializer.<jsf>DEFAULT_READABLE</jsf>)
       *       .build();
       * </p>
       *
       * @param value
       *    The new value for this setting.
       *    <br>The default is {@link JsonSerializer}.
       *    <br>Cannot be <jk>null</jk>.
       * @return This object.
       */
      public SELF serializer(Serializer value) {
         return serializers(value);
      }

      /**
       * Returns the serializer group sub-builder.
       *
       * @return The serializer group sub-builder.
       */
      public final SerializerSet.Builder serializers() {
         if (serializers == null)
            serializers = createSerializers();
         return serializers;
      }

      /**
       * Serializers.
       *
       * <p>
       * Associates the specified {@link Serializer Serializers} with the HTTP client.
       *
       * <p>
       * The serializer is used to serialize POJOs into the HTTP request body.
       *
       * <p>
       * The serializer that best matches the <c>Content-Type</c> header will be used to serialize the request body.
       * <br>If no <c>Content-Type</c> header is specified, the first serializer in the list will be used.
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='note'>When using this method that takes in classes, the serializers can be configured using any of the serializer property setters (e.g. {@link #sortCollections()}) or
       *    bean context property setters (e.g. {@link #swaps(Class...)}) defined on this builder class.
       * </ul>
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a client that uses JSON and XML transport for request bodies.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .serializers(JsonSerializer.<jk>class</jk>, XmlSerializer.<jk>class</jk>)
       *       .sortCollections()  <jc>// Sort any collections being serialized.</jc>
       *       .build();
       * </p>
       *
       * @param value
       *    The new value for this setting.
       *    <br>The default is {@link JsonSerializer}.
       * @return This object.
       */
      public SELF serializers(Class<? extends Serializer>...value) {
         reqnns("value", value);
         serializers().add(value);
         return self();
      }

      /**
       * Serializers.
       *
       * <p>
       * Associates the specified {@link Serializer Serializers} with the HTTP client.
       *
       * <p>
       * The serializer is used to serialize POJOs into the HTTP request body.
       *
       * <p>
       * The serializer that best matches the <c>Content-Type</c> header will be used to serialize the request body.
       * <br>If no <c>Content-Type</c> header is specified, the first serializer in the list will be used.
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='note'>When using this method that takes in a pre-instantiated serializers, the serializer property setters (e.g. {@link #sortCollections()}) or
       *    bean context property setters (e.g. {@link #swaps(Class...)}) defined
       *    on this builder class have no effect.
       * </ul>
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a client that uses predefined JSON and XML serializers for request bodies.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .serializers(JsonSerializer.<jsf>DEFAULT_READABLE</jsf>, XmlSerializer.<jsf>DEFAULT_READABLE</jsf>)
       *       .build();
       * </p>
       *
       * @param value
       *    The new value for this setting.
       *    <br>The default is {@link JsonSerializer}.
       * @return This object.
       */
      public SELF serializers(Serializer...value) {
         reqnns("value", value);
         serializers().add(value);
         return self();
      }

      /**
       * Assigns {@link ServiceUnavailableRetryStrategy} instance.
       *
       * @param serviceUnavailStrategy New property value.
       *    <br>Can be <jk>null</jk> (value will not be set, default behavior will be used).
       * @return This object.
       * @see HttpClientBuilder#setServiceUnavailableRetryStrategy(ServiceUnavailableRetryStrategy)
       */
      public SELF serviceUnavailableRetryStrategy(ServiceUnavailableRetryStrategy serviceUnavailStrategy) {
         httpClientBuilder().setServiceUnavailableRetryStrategy(serviceUnavailStrategy);
         return self();
      }

      /**
       * Skip empty form data.
       *
       * <p>
       * When enabled, form data consisting of empty strings will be skipped on requests.
       * Note that <jk>null</jk> values are already skipped.
       *
       * <p>
       * The {@link Schema#skipIfEmpty()} annotation overrides this setting.
       *
       * @return This object.
       */
      public SELF skipEmptyFormData() {
         return skipEmptyFormData(true);
      }

      /**
       * Skip empty form data.
       *
       * <p>
       * When enabled, form data consisting of empty strings will be skipped on requests.
       * Note that <jk>null</jk> values are already skipped.
       *
       * <p>
       * The {@link Schema#skipIfEmpty()} annotation overrides this setting.
       *
       * @param value
       *    The new value for this setting.
       *    <br>The default is <jk>false</jk>.
       * @return This object.
       */
      public SELF skipEmptyFormData(boolean value) {
         skipEmptyFormData = value;
         return self();
      }

      /**
       * Skip empty header data.
       *
       * <p>
       * When enabled, headers consisting of empty strings will be skipped on requests.
       * Note that <jk>null</jk> values are already skipped.
       *
       * <p>
       * The {@link Schema#skipIfEmpty()} annotation overrides this setting.
       *
       * @return This object.
       */
      public SELF skipEmptyHeaderData() {
         return skipEmptyHeaderData(true);
      }

      /**
       * Skip empty header data.
       *
       * <p>
       * When enabled, headers consisting of empty strings will be skipped on requests.
       * Note that <jk>null</jk> values are already skipped.
       *
       * <p>
       * The {@link Schema#skipIfEmpty()} annotation overrides this setting.
       *
       * @param value
       *    The new value for this setting.
       *    <br>The default is <jk>false</jk>.
       * @return This object.
       */
      public SELF skipEmptyHeaderData(boolean value) {
         skipEmptyHeaderData = value;
         return self();
      }

      /**
       * Skip empty query data.
       *
       * <p>
       * When enabled, query parameters consisting of empty strings will be skipped on requests.
       * Note that <jk>null</jk> values are already skipped.
       *
       * <p>
       * The {@link Schema#skipIfEmpty()} annotation overrides this setting.
       *
       * @return This object.
       */
      public SELF skipEmptyQueryData() {
         return skipEmptyQueryData(true);
      }

      /**
       * Skip empty query data.
       *
       * <p>
       * When enabled, query parameters consisting of empty strings will be skipped on requests.
       * Note that <jk>null</jk> values are already skipped.
       *
       * <p>
       * The {@link Schema#skipIfEmpty()} annotation overrides this setting.
       *
       * @param value
       *    The new value for this setting.
       *    <br>The default is <jk>false</jk>.
       * @return This object.
       */
      public SELF skipEmptyQueryData(boolean value) {
         skipEmptyQueryData = value;
         return self();
      }

      /**
       * <i><l>Serializer</l> configuration property:&emsp;</i>  Sort arrays and collections alphabetically.
       *
       * <p>
       * When enabled, copies and sorts the contents of arrays and collections before serializing them.
       *
       * <p>
       * Note that this introduces a performance penalty since it requires copying the existing collection.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a REST client with JSON serializer that sorts arrays and collections before serialization.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .json()
       *       .sortCollections()
       *       .build();
       *
       *    <jc>// An unsorted array</jc>
       *    String[] <jv>array</jv> = {<js>"foo"</js>,<js>"bar"</js>,<js>"baz"</js>}
       *
       *    <jc>// Request body will contain:  ["bar","baz","foo"]</jc>
       *    <jv>client</jv>
       *       .post(<js>"http://localhost:10000/foo"</js>, <jv>array</jv>)
       *       .run();
       * </p>
       *
       * <h5 class='section'>See Also:</h5><ul>
       *    <li class='jm'>{@link org.apache.juneau.marshall.serializer.Serializer.Builder#sortCollections() Serializer.Builder#sortCollections()}
       * </ul>
       *
       * @return This object.
       */
      public SELF sortCollections() {
         serializers().forEach(Serializer.Builder::sortCollections);
         return self();
      }

      /**
       * <i><l>Serializer</l> configuration property:&emsp;</i>  Sort maps alphabetically.
       *
       * <p>
       * When enabled, copies and sorts the contents of maps by their keys before serializing them.
       *
       * <p>
       * Note that this introduces a performance penalty.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a REST client with JSON serializer that sorts maps before serialization.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .json()
       *       .sortMaps()
       *       .build();
       *
       *    <jc>// An unsorted map.</jc>
       *    AMap <jv>map</jv> = AMap.<jsm>of</jsm>(<js>"foo"</js>,1,<js>"bar"</js>,2,<js>"baz"</js>,3);
       *
       *    <jc>// Request body will contain:  {"bar":2,"baz":3,"foo":1}</jc>
       *    <jv>client</jv>
       *       .post(<js>"http://localhost:10000/foo"</js>, <jv>map</jv>)
       *       .run();
       * </p>
       *
       * <h5 class='section'>See Also:</h5><ul>
       *    <li class='jm'>{@link org.apache.juneau.marshall.serializer.Serializer.Builder#sortMaps() Serializer.Builder#sortMaps()}
       * </ul>
       *
       * @return This object.
       */
      public SELF sortMaps() {
         serializers().forEach(Serializer.Builder::sortMaps);
         return self();
      }

      /**
       * <i><l>WriterSerializer</l> configuration property:&emsp;</i>  Quote character.
       *
       * <p>
       * Specifies to use single quotes for quoting attributes and values.
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='note'>This setting does not apply to the RDF serializers.
       * </ul>
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a REST client with JSON serializer that uses single quotes.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .json()
       *       .sq()
       *       .build();
       *
       *    <jc>// A bean with a single property</jc>
       *    <jk>public class</jk> MyBean {
       *       <jk>public</jk> String <jf>foo</jf> = <js>"bar"</js>;
       *    }
       *
       *    <jc>// Request body will contain:  {'foo':'bar'}</jc>
       *    <jv>client</jv>
       *       .post(<js>"http://localhost:10000/foo"</js>, <jk>new</jk> MyBean())
       *       .run();
       * </p>
       *
       * <h5 class='section'>See Also:</h5><ul>
       *    <li class='jm'>{@link org.apache.juneau.marshall.serializer.WriterSerializer.Builder#quoteChar(char) WriterSerializer.Builder#quoteChar(char)}
       * </ul>
       *
       * @return This object.
       */
      public SELF sq() {
         serializers().forEachWS(WriterSerializer.Builder::sq);
         return self();
      }

      /**
       * Assigns {@link SSLContext} instance.
       *
       * <p>
       * The context (for example one initialized with a custom trust store) is used for {@code https} connections, with
       * the {@link #sslHostnameVerifier(HostnameVerifier) hostname verifier} if one is set, or the default one.
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='note'>It is applied to the connection manager the default {@link #createConnectionManager()} builds, for
       *       both ordinary requests and the internal pool for SSRF-guard-active {@code @Remote} calls.  It has no effect on
       *       a connection manager supplied through {@link #connectionManager(HttpClientConnectionManager)} or an overridden
       *       {@link #createConnectionManager()}, which carries its own socket factories.
       *    <li class='note'>An {@link #sslSocketFactory(LayeredConnectionSocketFactory) SSL socket factory} takes precedence
       *       over this value, including one set with
       *       {@link HttpClientBuilder#setSSLSocketFactory(LayeredConnectionSocketFactory) setSSLSocketFactory} on a builder
       *       passed to {@link #httpClientBuilder(HttpClientBuilder)} after this value was set (as in Apache
       *       {@code HttpClientBuilder}).
       * </ul>
       *
       * @param sslContext New property value.
       *    <br>Can be <jk>null</jk> (value will not be set, default behavior will be used).
       * @return This object.
       * @see HttpClientBuilder#setSSLContext(SSLContext)
       */
      public SELF sslContext(SSLContext sslContext) {
         this.sslContext = sslContext;
         httpClientBuilder().setSSLContext(sslContext);
         return self();
      }

      /**
       * Assigns {@link HostnameVerifier} instance.
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='note'>It is applied to the connection manager the default {@link #createConnectionManager()} builds, for
       *       both ordinary requests and the internal pool for SSRF-guard-active {@code @Remote} calls.  It has no effect on
       *       a connection manager supplied through {@link #connectionManager(HttpClientConnectionManager)} or an overridden
       *       {@link #createConnectionManager()}, which carries its own socket factories.
       *    <li class='note'>An {@link #sslSocketFactory(LayeredConnectionSocketFactory) SSL socket factory} takes precedence
       *       over this value, including one set with
       *       {@link HttpClientBuilder#setSSLSocketFactory(LayeredConnectionSocketFactory) setSSLSocketFactory} on a builder
       *       passed to {@link #httpClientBuilder(HttpClientBuilder)} after this value was set (as in Apache
       *       {@code HttpClientBuilder}).
       * </ul>
       *
       * @param hostnameVerifier New property value.
       *    <br>Can be <jk>null</jk> (value will not be set, default behavior will be used).
       * @return This object.
       * @see HttpClientBuilder#setSSLHostnameVerifier(HostnameVerifier)
       */
      public SELF sslHostnameVerifier(HostnameVerifier hostnameVerifier) {
         this.sslHostnameVerifier = hostnameVerifier;
         httpClientBuilder().setSSLHostnameVerifier(hostnameVerifier);
         return self();
      }

      /**
       * Assigns {@link LayeredConnectionSocketFactory} instance.
       *
       * <p>
       * The factory is used for {@code https} connections, in place of one built from the
       * {@link #sslContext(SSLContext) SSL context} and {@link #sslHostnameVerifier(HostnameVerifier) hostname verifier}.
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='note'>It is applied to the connection manager the default {@link #createConnectionManager()} builds, for
       *       both ordinary requests and the internal pool for SSRF-guard-active {@code @Remote} calls.  It has no effect on
       *       a connection manager supplied through {@link #connectionManager(HttpClientConnectionManager)} or an overridden
       *       {@link #createConnectionManager()}, which carries its own socket factories.
       *    <li class='warn'>For SSRF-guard-active {@code @Remote} calls, the factory is given the address the SSRF pin has
       *       already checked (the {@code remoteAddress} of
       *       {@link ConnectionSocketFactory#connectSocket(int, Socket, HttpHost, InetSocketAddress, InetSocketAddress, HttpContext) connectSocket}).
       *       It must connect to exactly that address: a factory that ignores it and connects by host name (resolving
       *       the name again) bypasses the pin.  The same holds for a factory set with
       *       {@link HttpClientBuilder#setSSLSocketFactory(LayeredConnectionSocketFactory) setSSLSocketFactory} on a
       *       builder passed to {@link #httpClientBuilder(HttpClientBuilder)}.
       * </ul>
       *
       * @param sslSocketFactory New property value.
       *    <br>Can be <jk>null</jk> (value will not be set, default behavior will be used).
       * @return This object.
       * @see HttpClientBuilder#setSSLSocketFactory(LayeredConnectionSocketFactory)
       */
      public SELF sslSocketFactory(LayeredConnectionSocketFactory sslSocketFactory) {
         this.sslSocketFactory = sslSocketFactory;
         httpClientBuilder().setSSLSocketFactory(sslSocketFactory);
         return self();
      }

      /**
       * Assigns {@link AuthenticationStrategy} instance for target host authentication.
       *
       * @param targetAuthStrategy New property value.
       *    <br>Can be <jk>null</jk> (value will not be set, default behavior will be used).
       * @return This object.
       * @see HttpClientBuilder#setTargetAuthenticationStrategy(AuthenticationStrategy)
       */
      public SELF targetAuthenticationStrategy(AuthenticationStrategy targetAuthStrategy) {
         httpClientBuilder().setTargetAuthenticationStrategy(targetAuthStrategy);
         return self();
      }

      /**
       * <i><l>Serializer</l> configuration property:&emsp;</i>  Trim empty lists and arrays.
       *
       * <p>
       * When enabled, empty lists and arrays will not be serialized.
       *
       * <p>
       * Note that enabling this setting has the following effects on parsing:
       * <ul class='spaced-list'>
       *    <li>
       *       Map entries with empty list values will be lost.
       *    <li>
       *       Bean properties with empty list values will not be set.
       * </ul>
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a serializer that skips empty arrays and collections.</jc>
       *    WriterSerializer <jv>serializer</jv> = JsonSerializer
       *       .<jsm>create</jsm>()
       *       .trimEmptyCollections()
       *       .build();
       *
       *    <jc>// A bean with a field with an empty array.</jc>
       *    <jk>public class</jk> MyBean {
       *       <jk>public</jk> String[] <jf>foo</jf> = {};
       *    }
       *
       *    <jc>// Request body will contain:  {}</jc>
       *    <jv>client</jv>
       *       .post(<js>"http://localhost:10000/foo"</js>, <jk>new</jk> MyBean())
       *       .run();
       * </p>
       *
       * <h5 class='section'>See Also:</h5><ul>
       *    <li class='jm'>{@link org.apache.juneau.marshall.serializer.Serializer.Builder#trimEmptyCollections() Serializer.Builder#trimEmptyCollections()}
       * </ul>
       *
       * @return This object.
       */
      public SELF trimEmptyCollections() {
         serializers().forEach(Serializer.Builder::trimEmptyCollections);
         return self();
      }

      /**
       * <i><l>Serializer</l> configuration property:&emsp;</i>  Trim empty maps.
       *
       * <p>
       * When enabled, empty map values will not be serialized to the output.
       *
       * <p>
       * Note that enabling this setting has the following effects on parsing:
       * <ul class='spaced-list'>
       *    <li>
       *       Bean properties with empty map values will not be set.
       * </ul>
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a REST client with JSON serializer that skips empty maps.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .json()
       *       .trimEmptyMaps()
       *       .build();
       *
       *    <jc>// A bean with a field with an empty map.</jc>
       *    <jk>public class</jk> MyBean {
       *       <jk>public</jk> AMap <jf>foo</jf> = AMap.<jsm>of</jsm>();
       *    }
       *
       *    <jc>// Request body will contain:  {}</jc>
       *    <jv>client</jv>
       *       .post(<js>"http://localhost:10000/foo"</js>, <jk>new</jk> MyBean())
       *       .run();
       * </p>
       *
       * <h5 class='section'>See Also:</h5><ul>
       *    <li class='jm'>{@link org.apache.juneau.marshall.serializer.Serializer.Builder#trimEmptyMaps() Serializer.Builder#trimEmptyMaps()}
       * </ul>
       *
       * @return This object.
       */
      public SELF trimEmptyMaps() {
         serializers().forEach(Serializer.Builder::trimEmptyMaps);
         return self();
      }

      /**
       * <i><l>Parser</l> configuration property:&emsp;</i>  Trim parsed strings.
       *
       * <p>
       * When enabled, string values will be trimmed of whitespace using {@link String#trim()} before being added to
       * the POJO.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a REST client with JSON parser with trim-strings enabled.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .json()
       *       .trimStringsOnRead()
       *       .build();
       *
       *    <jc>// Try to parse JSON containing {" foo ":" bar "}.</jc>
       *    Map&lt;String,String&gt; <jv>map</jv> = <jv>client</jv>
       *       .get(<js>"/pathToJson"</js>)
       *       .run()
       *       .getContent().as(HashMap.<jk>class</jk>, String.<jk>class</jk>, String.<jk>class</jk>);
       *
       *    <jc>// Make sure strings are trimmed.</jc>
       *    <jsm>assertEquals</jsm>(<js>"bar"</js>, <jv>map</jv>.get(<js>"foo"</js>));
       * </p>
       *
       * <h5 class='section'>See Also:</h5><ul>
       *    <li class='jm'>{@link org.apache.juneau.marshall.parser.Parser.Builder#trimStrings() Parser.Builder#trimStrings()}
       * </ul>
       *
       * @return This object.
       */
      public SELF trimStringsOnRead() {
         parsers().forEach(Parser.Builder::trimStrings);
         return self();
      }

      /**
       * <i><l>Serializer</l> configuration property:&emsp;</i>  Trim strings.
       *
       * <p>
       * When enabled, string values will be trimmed of whitespace using {@link String#trim()} before being serialized.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a REST client with JSON serializer that trims strings before serialization.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .json()
       *       .trimStrings()
       *       .build();
       *
       * <jc>// A map with space-padded keys/values</jc>
       *    AMap <jv>map</jv> = AMap.<jsm>of</jsm>(<js>" foo "</js>, <js>" bar "</js>);
       *
       *    <jc>// Request body will contain:  {"foo":"bar"}</jc>
       *    <jv>client</jv>
       *       .post(<js>"http://localhost:10000/foo"</js>, <jv>map</jv>)
       *       .run();
       * </p>
       *
       * <h5 class='section'>See Also:</h5><ul>
       *    <li class='jm'>{@link org.apache.juneau.marshall.serializer.Serializer.Builder#trimStrings() Serializer.Builder#trimStrings()}
       * </ul>
       *
       * @return This object.
       */
      public SELF trimStringsOnWrite() {
         serializers().forEach(Serializer.Builder::trimStrings);
         return self();
      }

      /**
       * Convenience method for specifying all available transmission types.
       *
       * <p>
       *    All basic Juneau serializers will be used to serialize POJOs to request bodies unless overridden per request via {@link RestRequest#serializer(Serializer)}.
       *    <ul>
       *       <li>The serializers can be configured using any of the serializer property setters (e.g. {@link #sortCollections()}) or
       *          bean context property setters (e.g. {@link #swaps(Class...)}) defined on this builder class.
       *    </ul>
       * <p>
       *    All basic Juneau parsers will be used to parse POJOs from response bodies unless overridden per request via {@link RestRequest#parser(Parser)}.
       *    <ul>
       *       <li>The parsers can be configured using any of the parser property setters (e.g. {@link #ignoreUnknownBeanProperties()}) or
       *          bean context property setters (e.g. {@link #swaps(Class...)}) defined on this builder class.
       *    </ul>
       * <p>
       *    <c>Accept</c> request header must be set via {@link #headers()}, or per-request
       *       via {@link RestRequest#header(Header)} in order for the correct parser to be selected.
       * <p>
       *    <c>Content-Type</c> request header must be set via {@link #headers()},
       *       or per-request via {@link RestRequest#header(Header)} in order for the correct serializer to be selected.
       * <p>
       *    Similar to calling <c>json().json5().html().xml().uon().urlEnc().openApi().msgPack().plainText()</c>.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Construct a client that uses universal marshalling.</jc>
       *    RestClient <jv>client</jv> = RestClient.<jsm>create</jsm>().universal().build();
       * </p>
       *
       * @return This object.
       */
      public SELF universal() {
         // @formatter:off
         return
            serializers(
               JsonSerializer.class,
               JcsSerializer.class,
               Json5Serializer.class,
               Json5lSerializer.class,
               JsonlSerializer.class,
               HtmlSerializer.class,
               XmlSerializer.class,
               UonSerializer.class,
               UrlEncodingSerializer.class,
               OpenApiSerializer.class,
               BsonSerializer.class,
               CborSerializer.class,
               MsgPackSerializer.class,
               ParquetSerializer.class,
               PlainTextSerializer.class,
               TomlSerializer.class,
               HjsonSerializer.class,
               HoconSerializer.class,
               IniSerializer.class,
               PrototextSerializer.class,
               MarkdownSerializer.class
            )
            .parsers(
               JsonParser.class,
               Json5Parser.class,
               Json5lParser.class,
               JsonlParser.class,
               XmlParser.class,
               HtmlParser.class,
               UonParser.class,
               UrlEncodingParser.class,
               OpenApiParser.class,
               BsonParser.class,
               CborParser.class,
               MsgPackParser.class,
               ParquetParser.class,
               PlainTextParser.class,
               TomlParser.class,
               HjsonParser.class,
               HoconParser.class,
               IniParser.class,
               PrototextParser.class,
               MarkdownParser.class
            );
         // @formatter:on
      }

      /**
       * Convenience method for specifying UON as the marshalling transmission media type.
       *
       * <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 #sortCollections()}) or
       *          bean context property setters (e.g. {@link #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 #ignoreUnknownBeanProperties()}) or
       *          bean context property setters (e.g. {@link #swaps(Class...)}) defined on this builder class.
       *    </ul>
       * <p>
       *    <c>Accept</c> request header will be set to <js>"text/uon"</js> unless overridden
       *       via {@link #headers()}, or per-request via {@link RestRequest#header(Header)}.
       * <p>
       *    <c>Content-Type</c> request header will be set to <js>"text/uon"</js> unless overridden
       *       via {@link #headers()}, or per-request via {@link RestRequest#header(Header)}.
       * <p>
       *    Can be combined with other marshaller setters such as {@link #json()} 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(UonSerializer.<jk>class</jk>).parser(UonParser.<jk>class</jk>)</c>.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Construct a client that uses UON marshalling.</jc>
       *    RestClient <jv>client</jv> = RestClient.<jsm>create</jsm>().uon().build();
       * </p>
       *
       * @return This object.
       */
      public SELF uon() {
         return serializer(UonSerializer.class).parser(UonParser.class);
      }

      /**
       * <i><l>Serializer</l> configuration property:&emsp;</i>  URI context bean.
       *
       * <p>
       * Bean used for resolution of URIs to absolute or root-relative form.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Our URI contextual information.</jc>
       *    String <jv>authority</jv> = <js>"http://localhost:10000"</js>;
       *    String <jv>contextRoot</jv> = <js>"/myContext"</js>;
       *    String <jv>servletPath</jv> = <js>"/myServlet"</js>;
       *    String <jv>pathInfo</jv> = <js>"/foo"</js>;
       *
       *    <jc>// Create a UriContext object.</jc>
       *    UriContext <jv>uriContext</jv> = <jk>new</jk> UriContext(<jv>authority</jv>, <jv>contextRoot</jv>, <jv>servletPath</jv>, <jv>pathInfo</jv>);
       *
       *    <jc>// Create a REST client with JSON serializer and associate our context.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .json()
       *       .uriContext(<jv>uriContext</jv>)
       *       .uriRelativity(<jsf>RESOURCE</jsf>)  <jc>// Assume relative paths are relative to servlet.</jc>
       *       .uriResolution(<jsf>ABSOLUTE</jsf>)  <jc>// Serialize URIs as absolute paths.</jc>
       *       .build();
       *
       *    <jc>// A relative URI</jc>
       *    URI <jv>uri</jv> = <jk>new</jk> URI(<js>"bar"</js>);
       *
       *    <jc>// Request body will contain:  "http://localhost:10000/myContext/myServlet/foo/bar"</jc>
       *    <jv>client</jv>
       *       .post(<js>"http://localhost:10000/foo"</js>, <jv>uri</jv>)
       *       .run();
       * </p>
       *
       * <h5 class='section'>See Also:</h5><ul>
       *    <li class='jm'>{@link org.apache.juneau.marshall.serializer.Serializer.Builder#uriContext(UriContext) Serializer.Builder#uriContext(UriContext)}
       *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/MarshallingUris">URIs</a>
       * </ul>
       *
       * @param value The new value for this property.
       *    <br>Cannot be <jk>null</jk>.
       * @return This object.
       */
      public SELF uriContext(UriContext value) {
         serializers().forEach(x -> x.uriContext(reqnn("value", value)));
         return self();
      }

      /**
       * <i><l>Serializer</l> configuration property:&emsp;</i>  URI relativity.
       *
       * <p>
       * Defines what relative URIs are relative to when serializing any of the following:
       * <ul>
       *    <li>{@link URI}
       *    <li>{@link URL}
       *    <li>Properties and classes annotated with {@link Uri @Uri}
       * </ul>
       *
       * <p>
       * See {@link #uriContext(UriContext)} for examples.
       *
       * <ul class='values javatree'>
       *    <li class='jf'>{@link UriRelativity#RESOURCE}
       *       - Relative URIs should be considered relative to the servlet URI.
       *    <li class='jf'>{@link UriRelativity#PATH_INFO}
       *       - Relative URIs should be considered relative to the request URI.
       * </ul>
       *
       * <h5 class='section'>See Also:</h5><ul>
       *    <li class='jm'>{@link org.apache.juneau.marshall.serializer.Serializer.Builder#uriRelativity(UriRelativity) Serializer.Builder#uriRelativity(UriRelativity)}
       *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/MarshallingUris">URIs</a>
       * </ul>
       *
       * @param value
       *    The new value for this property.
       *    <br>The default is {@link UriRelativity#RESOURCE}
       *    <br>Cannot be <jk>null</jk>.
       * @return This object.
       */
      public SELF uriRelativity(UriRelativity value) {
         serializers().forEach(x -> x.uriRelativity(reqnn("value", value)));
         return self();
      }

      /**
       * <i><l>Serializer</l> configuration property:&emsp;</i>  URI resolution.
       *
       * <p>
       * Defines the resolution level for URIs when serializing any of the following:
       * <ul>
       *    <li>{@link URI}
       *    <li>{@link URL}
       *    <li>Properties and classes annotated with {@link Uri @Uri}
       * </ul>
       *
       * <p>
       * See {@link #uriContext(UriContext)} for examples.
       *
       * <ul class='values'>
       *    <li class='jf'>{@link UriResolution#ABSOLUTE}
       *       - Resolve to an absolute URI (e.g. <js>"http://host:port/context-root/servlet-path/path-info"</js>).
       *    <li class='jf'>{@link UriResolution#ROOT_RELATIVE}
       *       - Resolve to a root-relative URI (e.g. <js>"/context-root/servlet-path/path-info"</js>).
       *    <li class='jf'>{@link UriResolution#NONE}
       *       - Don't do any URI resolution.
       * </ul>
       *
       * <h5 class='section'>See Also:</h5><ul>
       *    <li class='jm'>{@link org.apache.juneau.marshall.serializer.Serializer.Builder#uriResolution(UriResolution) Serializer.Builder#uriResolution(UriResolution)}
       *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/MarshallingUris">URIs</a>
       * </ul>
       *
       * @param value
       *    The new value for this property.
       *    <br>The default is {@link UriResolution#NONE}
       *    <br>Cannot be <jk>null</jk>.
       * @return This object.
       */
      public SELF uriResolution(UriResolution value) {
         serializers().forEach(x -> x.uriResolution(reqnn("value", value)));
         return self();
      }

      /**
       * Convenience method for specifying URL-Encoding as the marshalling transmission media type.
       *
       * <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 #sortCollections()}) or
       *          bean context property setters (e.g. {@link #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 #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 #ignoreUnknownBeanProperties()}) or
       *          bean context property setters (e.g. {@link #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
       *       via {@link #headers()}, or per-request via {@link RestRequest#header(Header)}.
       * <p>
       *    <c>Content-Type</c> request header will be set to <js>"application/x-www-form-urlencoded"</js> unless overridden
       *       via {@link #headers()}, or per-request via {@link RestRequest#header(Header)}.
       * <p>
       *    Can be combined with other marshaller setters such as {@link #json()} 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(UrlEncodingSerializer.<jk>class</jk>).parser(UrlEncodingParser.<jk>class</jk>)</c>.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Construct a client that uses URL-Encoded marshalling.</jc>
       *    RestClient <jv>client</jv> = RestClient.<jsm>create</jsm>().urlEnc().build();
       * </p>
       *
       * @return This object.
       */
      public SELF urlEnc() {
         return serializer(UrlEncodingSerializer.class).parser(UrlEncodingParser.class);
      }

      /**
       * Returns the URL-encoding serializer sub-builder.
       *
       * @return The URL-encoding serializer sub-builder.
       */
      public final UrlEncodingSerializer.Builder urlEncodingSerializer() {
         if (urlEncodingSerializer == null)
            urlEncodingSerializer = createUrlEncodingSerializer();
         return urlEncodingSerializer;
      }


      /**
       * Assigns {@link UserTokenHandler} instance.
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='note'>This value can be overridden by the {@link #disableConnectionState()} method.
       * </ul>
       *
       * @param userTokenHandler New property value.
       *    <br>Can be <jk>null</jk> (value will not be set, default behavior will be used).
       * @return This object.
       * @see HttpClientBuilder#setUserTokenHandler(UserTokenHandler)
       */
      public SELF userTokenHandler(UserTokenHandler userTokenHandler) {
         httpClientBuilder().setUserTokenHandler(userTokenHandler);
         return self();
      }

      /**
       * Use system properties when creating and configuring default implementations.
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='note'>The system properties Apache {@link HttpClientBuilder} reads for its own connection manager
       *       apply to both pools of the connection manager the default {@link #createConnectionManager()} builds, as
       *       Apache applies them: with no {@link #sslContext(SSLContext) sslContext} or
       *       {@link #sslSocketFactory(LayeredConnectionSocketFactory) sslSocketFactory}, {@code https} uses the JVM's
       *       default SSL socket factory (the {@code javax.net.ssl.*} trust and key stores); {@code https.protocols} and
       *       {@code https.cipherSuites} restrict the TLS versions and cipher suites (unless an {@code sslSocketFactory}
       *       is set); and unless {@code http.keepAlive} is {@code false}, {@code http.maxConnections} (default 5) limits
       *       the connections per route, and twice that in total, which makes the connection manager a pooling one.
       *       {@link #maxConnTotal(int)} and {@link #maxConnPerRoute(int)} win over that limit.
       *    <li class='note'>The proxy system properties apply too (see {@link #proxy(HttpHost)}).
       * </ul>
       *
       * @return This object.
       * @see HttpClientBuilder#useSystemProperties()
       */
      public SELF useSystemProperties() {
         this.systemProperties = true;
         httpClientBuilder().useSystemProperties();
         return self();
      }

      /**
       * <i><l>WriterSerializer</l> configuration property:&emsp;</i>  Use whitespace.
       *
       * <p>
       * When enabled, whitespace is added to the output to improve readability.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a REST client with JSON serializer with whitespace enabled.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .json()
       *       .useWhitespace()
       *       .build();
       *
       *    <jc>// A bean with a single property</jc>
       *    <jk>public class</jk> MyBean {
       *       <jk>public</jk> String <jf>foo</jf> = <js>"bar"</js>;
       *    }
       *
       *    <jc>// Request body will contain:  {\n\t"foo": "bar"\n\}\n</jc>
       *    <jv>client</jv>
       *       .post(<js>"http://localhost:10000/foo"</js>, <jk>new</jk> MyBean())
       *       .run();
       * </p>
       *
       * <h5 class='section'>See Also:</h5><ul>
       *    <li class='jm'>{@link org.apache.juneau.marshall.serializer.WriterSerializer.Builder#useWhitespace() WriterSerializer.Builder#useWhitespace()}
       * </ul>
       * @return This object.
       */
      public SELF useWhitespace() {
         serializers().forEachWS(WriterSerializer.Builder::useWhitespace);
         return self();
      }

      /**
       * <i><l>WriterSerializer</l> configuration property:&emsp;</i>  Use whitespace.
       *
       * <p>
       * When enabled, whitespace is added to the output to improve readability.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Create a REST client with JSON serializer with whitespace enabled.</jc>
       *    RestClient <jv>client</jv> = RestClient
       *       .<jsm>create</jsm>()
       *       .json()
       *       .ws()
       *       .build();
       *
       *    <jc>// A bean with a single property</jc>
       *    <jk>public class</jk> MyBean {
       *       <jk>public</jk> String <jf>foo</jf> = <js>"bar"</js>;
       *    }
       *
       *    <jc>// Request body will contain:  {\n\t"foo": "bar"\n\}\n</jc>
       *    <jv>client</jv>
       *       .post(<js>"http://localhost:10000/foo"</js>, <jk>new</jk> MyBean())
       *       .run();
       * </p>
       *
       * <h5 class='section'>See Also:</h5><ul>
       *    <li class='jm'>{@link org.apache.juneau.marshall.serializer.WriterSerializer.Builder#useWhitespace() WriterSerializer.Builder#useWhitespace()}
       * </ul>
       *
       * @return This object.
       */
      public SELF ws() {
         serializers().forEachWS(WriterSerializer.Builder::ws);
         return self();
      }

      /**
       * Convenience method for specifying XML as the marshalling transmission media type.
       *
       * <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 #sortCollections()}) or
       *          bean context property setters (e.g. {@link #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 #ignoreUnknownBeanProperties()}) or
       *          bean context property setters (e.g. {@link #swaps(Class...)}) defined on this builder class.
       *    </ul>
       * <p>
       *    <c>Accept</c> request header will be set to <js>"text/xml"</js> unless overridden
       *       via {@link #headers()}, or per-request via {@link RestRequest#header(Header)}.
       * <p>
       *    <c>Content-Type</c> request header will be set to <js>"text/xml"</js> unless overridden
       *       via {@link #headers()}, or per-request via {@link RestRequest#header(Header)}.
       * <p>
       *    Can be combined with other marshaller setters such as {@link #json()} 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(XmlSerializer.<jk>class</jk>).parser(XmlParser.<jk>class</jk>)</c>.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// Construct a client that uses XML marshalling.</jc>
       *    RestClient <jv>client</jv> = RestClient.<jsm>create</jsm>().xml().build();
       * </p>
       *
       * @return This object.
       */
      public SELF xml() {
         return serializer(XmlSerializer.class).parser(XmlParser.class);
      }

      /**
       * Creates the creator for the rest call handler.
       *
       * <p>
       * Subclasses can override this method to provide their own implementation.
       *
       * <p>
       * The default behavior creates a bean instantiator initialized to return a {@link BasicRestCallHandler}.
       *
       * @return The creator for the rest call handler.
       * @see #callHandler()
       */
      protected BeanInstantiator.Builder<RestCallHandler> createCallHandler() {
         return BeanInstantiator.of(RestCallHandler.class, beanStore).type(BasicRestCallHandler.class);
      }

      /**
       * Creates the {@link HttpClientConnectionManager} returned by {@link #createConnectionManager()}.
       *
       * <p>
       * Subclasses can override this method to provide their own connection manager.
       *
       * <p>
       * The default implementation returns a new {@link PoolingHttpClientConnectionManager} if {@link #pooled()},
       * {@link #maxConnTotal(int)}, {@link #maxConnPerRoute(int)} or a positive
       * {@link #connectionTimeToLive(long, TimeUnit) connectionTimeToLive} was set, or the {@code http.maxConnections}
       * limit of {@link #useSystemProperties()} applies (unless {@code http.keepAlive} is {@code false}), or a new
       * {@link BasicHttpClientConnectionManager} if not.  It applies the {@link #sslContext(SSLContext) sslContext},
       * {@link #sslSocketFactory(LayeredConnectionSocketFactory) sslSocketFactory},
       * {@link #sslHostnameVerifier(HostnameVerifier) sslHostnameVerifier}, {@code maxConnTotal} and {@code maxConnPerRoute}
       * settings, which Apache {@link HttpClientBuilder} ignores once a connection manager is set.  It also applies, to
       * both pools, the other settings Apache {@code HttpClientBuilder} applies only to a connection manager it builds
       * itself, whether made through this builder or directly on the {@link #httpClientBuilder() HttpClientBuilder}:
       * {@link #publicSuffixMatcher(PublicSuffixMatcher) publicSuffixMatcher} (for the default hostname verifier),
       * {@link #defaultSocketConfig(SocketConfig) defaultSocketConfig},
       * {@link #defaultConnectionConfig(ConnectionConfig) defaultConnectionConfig},
       * {@link #connectionTimeToLive(long, TimeUnit) connectionTimeToLive} (which, like {@code maxConnTotal} and
       * {@code maxConnPerRoute}, makes it a {@code PoolingHttpClientConnectionManager}) and the TLS and
       * {@code http.maxConnections} system properties of {@link #useSystemProperties()}.  A
       * {@link HttpClientBuilder#setDnsResolver(DnsResolver) DNS resolver} set on the {@code HttpClientBuilder} is used
       * for ordinary requests only: SSRF-guard-active {@code @Remote} calls always resolve through the SSRF pin.
       * Each of these settings made through this builder also survives {@link #httpClientBuilder(HttpClientBuilder)}
       * replacing the {@code HttpClientBuilder}, and always wins over the same setting on the {@code HttpClientBuilder},
       * whichever was set last (unlike Apache's own last-write-wins).  An SSL socket factory wins over any SSL context,
       * wherever each was set.  The {@code HttpClientBuilder}'s settings are read from its fields (it has no getters);
       * if they cannot be read, this method throws an {@link IllegalStateException} rather than ignore them.
       *
       * <p>
       * Each {@link #build()} calls this method again, so a builder reused after {@code build()} gives every client its
       * own connection manager (closing one client does not shut down another's).  A connection manager supplied through
       * {@link #connectionManager(HttpClientConnectionManager)} is used as is by every client built.
       *
       * <p>
       * SSRF-guard-active {@code @Remote} calls do not use this connection manager: the default
       * {@link #createHttpClient()} pairs it with a second, dedicated one whose connections are all opened through the
       * SSRF pin, so that a guarded call never reuses a connection an ordinary request opened.  It can only do that
       * for the instance this default implementation returns.  If an override returns any other connection manager,
       * the client refuses every SSRF-guard-active {@code @Remote} call (one without the
       * {@link #allowPrivateUrls(boolean) allowPrivateUrls} opt-in).
       *
       * <p>
       * The dedicated connection manager copies this one's settings before each guarded call, but it is a separate pool:
       * limits such as {@link PoolingHttpClientConnectionManager#setMaxTotal(int) maxTotal} apply to each pool on its
       * own, so a client that mixes ordinary and guarded calls can hold up to twice as many open connections.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// A Builder that provides it's own customized HttpClientConnectionManager.</jc>
       *    <jk>public class</jk> MyBuilder <jk>extends</jk> Builder {
       *       <ja>@Override</ja>
       *       <jk>protected</jk> HttpClientConnectionManager createConnectionManager() {
       *          <jk>return new</jk> PoolingHttpClientConnectionManager();
       *       }
       *    }
       *
       *    <jc>// Instantiate.</jc>
       *    RestClient <jv>client</jv> = <jk>new</jk> MyBuilder().build();
       * </p>
       *
       * @return The connection manager to use.
       */
      protected HttpClientConnectionManager createConnectionManager() {
         var s = HttpClientBuilderSettings.of(httpClientBuilder());
         defaultRegistry = socketFactoryRegistry(s);
         defaultPoolSettings = poolSettings(s);
         defaultConnectionManager = newConnectionManager(defaultRegistry, or(s.dnsResolver(), SystemDefaultDnsResolver.INSTANCE), defaultPoolSettings);
         return defaultConnectionManager;
      }

      // The socket factories for the TLS settings, chosen as Apache HttpClientBuilder chooses them when it builds its own
      // connection manager: the SSL socket factory, else one on the SSL context (else the JVM's default socket factory
      // under useSystemProperties(), else a default context) with the hostname verifier (else the default verifier on
      // the public suffix matcher) and, under useSystemProperties(), the https.protocols and https.cipherSuites.
      // A setting made through this builder always wins over the same setting read from the HttpClientBuilder, whichever
      // was set last.  The two differ when httpClientBuilder(...) replaced the builder after the setting was made, or when
      // the setting was later made again directly on httpClientBuilder().  As in Apache, a socket factory wins over any
      // SSL context, wherever each was set.
      private Registry<ConnectionSocketFactory> socketFactoryRegistry(HttpClientBuilderSettings s) {
         var https = or(sslSocketFactory, s.sslSocketFactory());
         if (https == null) {
            var sysProps = systemProperties || s.systemProperties();
            var protocols = sysProps ? splitSystemProperty("https.protocols") : null;
            var cipherSuites = sysProps ? splitSystemProperty("https.cipherSuites") : null;
            var verifier = or(sslHostnameVerifier, s.hostnameVerifier());
            if (verifier == null)
               verifier = new DefaultHostnameVerifier(or(publicSuffixMatcher, s.publicSuffixMatcher(), PublicSuffixMatcherLoader.getDefault()));
            var context = or(sslContext, s.sslContext());
            if (nn(context))
               https = new SSLConnectionSocketFactory(context, protocols, cipherSuites, verifier);
            else if (sysProps)
               https = new SSLConnectionSocketFactory((javax.net.ssl.SSLSocketFactory)javax.net.ssl.SSLSocketFactory.getDefault(), protocols, cipherSuites, verifier);
            else
               https = new SSLConnectionSocketFactory(SSLContexts.createDefault(), verifier);
         }
         return RegistryBuilder.<ConnectionSocketFactory>create()
            .register("http", PlainConnectionSocketFactory.getSocketFactory())
            .register("https", https)
            .build();
      }

      private static String[] splitSystemProperty(String name) {
         var v = System.getProperty(name);
         return ib(v) ? null : splita(v);
      }

      // The pool settings, applied as Apache HttpClientBuilder applies them to its own connection manager.  The
      // http.maxConnections limit (default 5) of useSystemProperties() applies per route, and twice that in total,
      // unless http.keepAlive is off; maxConnTotal and maxConnPerRoute win over it.  Any limit or a time-to-live
      // makes the manager a pooling one: BasicHttpClientConnectionManager has neither.
      private PoolSettings poolSettings(HttpClientBuilderSettings s) {
         var systemMax = (systemProperties || s.systemProperties()) && "true".equalsIgnoreCase(System.getProperty("http.keepAlive", "true"))
            ? Integer.parseInt(System.getProperty("http.maxConnections", "5")) : 0;
         var settingsTotal = s.maxConnTotal() > 0 ? s.maxConnTotal() : 2 * systemMax;
         var settingsPerRoute = s.maxConnPerRoute() > 0 ? s.maxConnPerRoute() : systemMax;
         var maxTotal = maxConnTotal > 0 ? maxConnTotal : settingsTotal;
         var maxPerRoute = maxConnPerRoute > 0 ? maxConnPerRoute : settingsPerRoute;
         var ownTtl = connTimeToLive > 0;
         var ttl = ownTtl ? connTimeToLive : s.connTimeToLive();
         var ttlUnit = ownTtl ? connTimeToLiveTimeUnit : s.connTimeToLiveTimeUnit();
         var pooling = pooled || maxTotal > 0 || maxPerRoute > 0 || ttl > 0;
         return new PoolSettings(pooling, maxTotal, maxPerRoute, ttl, or(ttlUnit, TimeUnit.MILLISECONDS),
            or(defaultSocketConfig, s.socketConfig()), or(defaultConnectionConfig, s.connectionConfig()));
      }

      private static boolean overridesCreateConnectionManager(Class<?> c) {
         for (var x = c; x != Builder.class; x = x.getSuperclass()) {
            try {
               x.getDeclaredMethod("createConnectionManager");
               return true;
            } catch (@SuppressWarnings("unused") NoSuchMethodException e) { /* Not declared here. */ }
         }
         return false;
      }

      // Why guarded @Remote calls cannot be sent through a client built by b, or null if they can.  The checks of the
      // client RestClient makes afterwards only see the connection manager the client stores, so they cannot tell:
      // - an HttpClientBuilder subclass whose build() or exec-chain factory may build the client around another
      //   connection manager or request executor, or put a step in front of them that sends the request elsewhere;
      // - an HttpProcessor, which replaces the client's request interceptors (the SSRF guard's lease hand-over and the
      //   redirect credential guard among them).
      private static String ssrfBuilderRefusal(HttpClientBuilder b) {
         var optOut = "or set allowPrivateUrls(true) if this is an intentional local-dev/intranet target.";
         if (! HttpClientBuilderSettings.isReadable())
            // HTT: only an HttpClient release without the HttpClientBuilder fields, or a JVM that denies reflective access
            // to them, gets here (and then the default createConnectionManager() has already failed).
            return "Refusing to send a policy-covered @Remote request: the settings of " + HttpClientBuilder.class.getName()
               + " cannot be read, so whether the client it built honors the SSRF guardrail's connect-time contract "
               + "(pin-on-connect + redirect revalidation) cannot be confirmed.  Use an HttpClient 4.5.x release, " + optOut;
         var override = overriddenBuilderMethod(b.getClass());
         if (nn(override))
            return "Refusing to send a policy-covered @Remote request through a client built by an HttpClientBuilder "
               + "subclass (" + override + "): the override may build the client around another connection manager or "
               + "request executor, so the SSRF guardrail's connect-time contract (pin-on-connect + redirect "
               + "revalidation) cannot be confirmed.  Remove the override (configure the builder through its setters "
               + "instead), " + optOut;
         if (HttpClientBuilderSettings.hasHttpProcessor(b))
            return "Refusing to send a policy-covered @Remote request through a client whose HttpProcessor was set: "
               + "httpProcessor(...) replaces the client's request interceptors, among them the SSRF guardrail's own and "
               + "the redirect credential guard, so its connect-time contract (pin-on-connect + redirect revalidation) "
               + "cannot be confirmed.  Remove the httpProcessor(...) setting (add interceptors with "
               + "addInterceptorFirst(...) or addInterceptorLast(...) instead), " + optOut;
         var change = lateBuilderChange(b);
         if (nn(change))
            return "Refusing to send a policy-covered @Remote request through a client whose HttpClientBuilder was changed "
               + "after the SSRF guard was wired into it (" + change + "), as an override of createHttpClient() does that "
               + "changes the builder after super.createHttpClient() and builds again.  The change may add credentials to "
               + "a redirect hop on another origin, follow redirects without revalidation or send the request past the "
               + "guard's executor, so the SSRF guardrail's connect-time contract (pin-on-connect + redirect revalidation) "
               + "cannot be confirmed.  Make the change before super.createHttpClient() (on httpClientBuilder() or through "
               + "this builder's setters), " + optOut;
         return null;
      }

      // What was changed on b after the default createHttpClient() wired the SSRF guard into it, or null if nothing it
      // wired was: the guard's two request interceptors must still be the last ones (the redirect credential guard strips
      // what every interceptor before it added), and its redirect strategy and request executor must still be set.
      private static String lateBuilderChange(HttpClientBuilder b) {
         var last = HttpClientBuilderSettings.lastRequestInterceptors(b);
         var n = last.size();
         if (n < 2 || ! (last.get(n - 2) instanceof ClassicRedirectCredentialGuard) || ! (last.get(n - 1) instanceof SsrfGuardConnectionManager.GuardInterceptor))
            return "a request interceptor was added after the SSRF guard's own";
         if (! (HttpClientBuilderSettings.redirectStrategy(b) instanceof PolicyAwareRedirectStrategy))
            return "the redirect strategy was replaced";
         if (! (HttpClientBuilderSettings.requestExecutor(b) instanceof SsrfGuardConnectionManager.GuardedRequestExecutor))
            return "the request executor was replaced";
         return null;
      }

      // The HttpClientBuilder methods that decide which connection manager and request executor a built client uses.
      private static final List<Method> BUILDER_EXEC_METHODS = Arrays.stream(HttpClientBuilder.class.getDeclaredMethods())
         .filter(m -> Set.of("build", "createMainExec", "decorateMainExec", "decorateProtocolExec").contains(m.getName()))
         .toList();

      // Returns "<class> overrides <method>(<params>)" for the first of BUILDER_EXEC_METHODS a class between c and
      // HttpClientBuilder declares, or null if there is none.
      private static String overriddenBuilderMethod(Class<?> c) {
         for (var x = c; nn(x) && x != HttpClientBuilder.class; x = x.getSuperclass()) {
            for (var m : BUILDER_EXEC_METHODS) {
               try {
                  x.getDeclaredMethod(m.getName(), m.getParameterTypes());
                  return cn(x) + " overrides " + m.getName() + "(" + String.join(",", Arrays.stream(m.getParameterTypes()).map(Class::getSimpleName).toList()) + ")";
               } catch (@SuppressWarnings("unused") NoSuchMethodException e) { /* Not declared here. */ }
            }
         }
         return null;
      }

      private static HttpClientConnectionManager newConnectionManager(Registry<ConnectionSocketFactory> registry, DnsResolver dnsResolver, PoolSettings p) {
         if (! p.pooling()) {
            var cm = new BasicHttpClientConnectionManager(registry, null, null, dnsResolver);
            if (nn(p.socketConfig()))
               cm.setSocketConfig(p.socketConfig());
            if (nn(p.connectionConfig()))
               cm.setConnectionConfig(p.connectionConfig());
            return cm;
         }
         var cm = new PoolingHttpClientConnectionManager(registry, null, null, dnsResolver, p.timeToLive(), p.timeToLiveUnit());
         if (nn(p.socketConfig()))
            cm.setDefaultSocketConfig(p.socketConfig());
         if (nn(p.connectionConfig()))
            cm.setDefaultConnectionConfig(p.connectionConfig());
         if (p.maxTotal() > 0)
            cm.setMaxTotal(p.maxTotal());
         if (p.maxPerRoute() > 0)
            cm.setDefaultMaxPerRoute(p.maxPerRoute());
         return cm;
      }

      // The settings both pools of the default connection manager are built with.
      private record PoolSettings(boolean pooling, int maxTotal, int maxPerRoute, long timeToLive, TimeUnit timeToLiveUnit,
         SocketConfig socketConfig, ConnectionConfig connectionConfig) {}

      /**
       * Creates the builder for the form data list.
       *
       * <p>
       * Subclasses can override this method to provide their own implementation.
       *
       * <p>
       * The default behavior creates an empty builder.
       *
       * @return The form data list builder.
       * @see #formData()
       */
      protected PartList createFormData() {
         return PartList.create();
      }

      /**
       * Creates the builder for the header list.
       *
       * <p>
       * Subclasses can override this method to provide their own implementation.
       *
       * <p>
       * The default behavior creates an empty builder.
       *
       * @return The header list builder.
       * @see #headers()
       */
      protected HeaderList createHeaderData() {
         return HeaderList.create();
      }

      /**
       * Creates an instance of an {@link HttpClient} to be used to handle all HTTP communications with the target server.
       *
       * <p>
       * This HTTP client is used when the HTTP client is not specified through one of the constructors or the
       * {@link #httpClient(CloseableHttpClient)} method.
       *
       * <p>
       * Subclasses can override this method to provide specially-configured HTTP clients to handle stuff such as
       * SSL/TLS certificate handling, authentication, etc.
       *
       * <p>
       * The default implementation returns an instance of {@link HttpClient} using the client builder returned by
       * {@link #createHttpClientBuilder()}.
       *
       * <h5 class='section'>Notes:</h5><ul>
       *    <li class='warn'>SSRF-guard-active {@code @Remote} calls (ones without the
       *       {@link #allowPrivateUrls(boolean) allowPrivateUrls} opt-in) are only sent through the client this default
       *       implementation builds, which it wires to the connection manager that pins them.  The client refuses every
       *       such call if an override returns any other client (including a wrapper around the one it built), or after
       *       {@code super.createHttpClient()} sets an {@link HttpProcessor} on the {@link HttpClientBuilder}, adds a request
       *       interceptor with {@code addInterceptorLast(...)}, or replaces its redirect strategy or request executor (make
       *       such changes before calling {@code super}), or if the builder is a
       *       subclass that overrides {@link HttpClientBuilder#build()} or one of its exec-chain methods
       *       ({@code createMainExec}, {@code decorateMainExec}, {@code decorateProtocolExec}), even an override that
       *       returns or decorates nothing but what {@code super} built.  Ordinary requests are unaffected.
       * </ul>
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// A Builder that provides it's own customized HttpClient.</jc>
       *    <jk>public class</jk> MyBuilder <jk>extends</jk> Builder {
       *       <ja>@Override</ja>
       *       <jk>protected</jk> HttpClientBuilder createHttpClient() {
       *          <jk>return</jk> HttpClientBuilder.<jsm>create</jsm>().build();
       *       }
       *    }
       *
       *    <jc>// Instantiate.</jc>
       *    RestClient <jv>client</jv> = <jk>new</jk> MyBuilder().build();
       * </p>
       *
       * @return The HTTP client to use.
       */
      protected CloseableHttpClient createHttpClient() {
         // A new connection manager for each client unless the caller supplied one: closing a client shuts its
         // connection manager down, so a reused builder must not hand an earlier client's to the next one.
         var cm = nn(connectionManager) ? connectionManager : createConnectionManager();
         // Only a connection manager this builder created can be given a pinned twin; for any other one, the client
         // reports the SSRF guard as unsupported and refuses guarded remote calls.  The twin is built from the same
         // socket factories and pool settings as the connection manager, so it is the same kind; settings an
         // override applied to that instance afterwards reach it before each guarded lease.
         ssrfGuard = nn(cm) && cm == defaultConnectionManager ? new SsrfGuardConnectionManager(cm, newConnectionManager(defaultRegistry, pinningResolver(), defaultPoolSettings)) : null;
         ownsConnectionManager = nn(ssrfGuard) && connectionManager == null && ! overridesCreateConnectionManager(getClass());
         if (nn(ssrfGuard))
            cm = ssrfGuard;
         httpClientBuilder().setConnectionManager(cm);
         // Once per HttpClientBuilder: a builder reused after build() keeps the interceptors earlier builds added.
         if (! HttpClientBuilderSettings.hasLastRequestInterceptor(httpClientBuilder(), ClassicRedirectCredentialGuard.class))
            httpClientBuilder().addInterceptorLast(new ClassicRedirectCredentialGuard());
         if (nn(ssrfGuard) && HttpClientBuilderSettings.isReadable()) {
            // The guard of a request travels on its context (see SsrfGuardMarker): the interceptor reads it before the
            // connection lease, and the executor refuses a guarded request on a connection of the ordinary pool.
            if (! HttpClientBuilderSettings.hasLastRequestInterceptor(httpClientBuilder(), SsrfGuardConnectionManager.GuardInterceptor.class))
               httpClientBuilder().addInterceptorLast(new SsrfGuardConnectionManager.GuardInterceptor());
            httpClientBuilder().setRequestExecutor(new SsrfGuardConnectionManager.GuardedRequestExecutor(HttpClientBuilderSettings.requestExecutor(httpClientBuilder()), ssrfGuard));
         }
         httpClientBuilder().setRedirectStrategy(new PolicyAwareRedirectStrategy());
         return httpClientBuilder().build();
      }

      // The shared pinning resolver unless this builder set per-client allowed address ranges, which need a resolver of their own.
      private PolicyPinningDnsResolver pinningResolver() {
         var ranges = RemoteUrlPolicy.AllowedRanges.of(allowedAddressRanges.toArray(new String[0]));
         return ranges.isEmpty() ? PolicyPinningDnsResolver.INSTANCE : new PolicyPinningDnsResolver(ranges);
      }

      /**
       * Creates an instance of an {@link HttpClientBuilder} to be used to create the {@link HttpClient}.
       *
       * <p>
       * Subclasses can override this method to provide their own client builder.
       * The builder can also be specified using the {@link #httpClientBuilder(HttpClientBuilder)} method.
       *
       * <h5 class='section'>Example:</h5>
       * <p class='bjava'>
       *    <jc>// A Builder that provides it's own customized HttpClientBuilder.</jc>
       *    <jk>public class</jk> MyBuilder <jk>extends</jk> Builder {
       *       <ja>@Override</ja>
       *       <jk>protected</jk> HttpClientBuilder createHttpClientBuilder() {
       *          <jk>return</jk> HttpClientBuilder.<jsm>create</jsm>();
       *       }
       *    }
       *
       *    <jc>// Instantiate.</jc>
       *    RestClient <jv>client</jv> = <jk>new</jk> MyBuilder().build();
       * </p>
       *
       * @return The HTTP client builder to use to create the HTTP client.
       */
      protected HttpClientBuilder createHttpClientBuilder() {
         return HttpClientBuilder.create();
      }

      /**
       * Instantiates the parser group sub-builder.
       *
       * @return A new parser group sub-builder.
       */
      protected ParserSet.Builder createParsers() {
         return ParserSet.create().marshallingContext(marshallingContext());
      }

      /**
       * Instantiates the part parser sub-builder.
       *
       * @return A new part parser sub-builder.
       */
      protected HttpPartParser.Creator createPartParser() {
         return HttpPartParser.creator().type(OpenApiParser.class).marshallingContext(marshallingContext());
      }

      /**
       * Instantiates the part serializer sub-builder.
       *
       * @return A new part serializer sub-builder.
       */
      protected HttpPartSerializer.Creator createPartSerializer() {
         return HttpPartSerializer.creator().type(OpenApiSerializer.class).marshallingContext(marshallingContext());
      }

      /**
       * Creates the builder for the path data list.
       *
       * <p>
       * Subclasses can override this method to provide their own implementation.
       *
       * <p>
       * The default behavior creates an empty builder.
       *
       * @return The path data list builder.
       * @see #pathData()
       */
      protected PartList createPathData() {
         return PartList.create();
      }

      /**
       * Creates the builder for the query data list.
       *
       * <p>
       * Subclasses can override this method to provide their own implementation.
       *
       * <p>
       * The default behavior creates an empty builder.
       *
       * @return The query data list builder.
       * @see #queryData()
       */
      protected PartList createQueryData() {
         return PartList.create();
      }

      /**
       * Instantiates the serializer group sub-builder.
       *
       * @return A new serializer group sub-builder.
       */
      protected SerializerSet.Builder createSerializers() {
         return SerializerSet.create().marshallingContext(marshallingContext());
      }

      /**
       * Instantiates the URL-encoding serializer sub-builder.
       *
       * @return A new URL-encoding serializer sub-builder.
       */
      protected UrlEncodingSerializer.Builder createUrlEncodingSerializer() {
         return UrlEncodingSerializer.create().marshallingContext(marshallingContext());
      }

      final CloseableHttpClient getHttpClient() { return nn(httpClient) ? httpClient : createHttpClient(); }
   }

   /**
    * Concrete default builder leaf for the non-subclassed {@link RestClient#create()} / {@link RestClient#copy()} path.
    */
   public static final class DefaultBuilder extends Builder<DefaultBuilder> {

      DefaultBuilder() {}
   }

   private static final RestCallInterceptor[] EMPTY_REST_CALL_INTERCEPTORS = {};
   private static final ConcurrentHashMap<Class<?>,Context> requestContexts = new ConcurrentHashMap<>();
   private static final BiPredicate<RestRequest,RestResponse> LOG_REQUESTS_PREDICATE_DEFAULT = (req, res) -> true;

   /**
    * Instantiates a new clean-slate {@link Builder} object.
    *
    * @return A new {@link Builder} object.
    */
   public static <T extends Builder<T>> Builder<T> create() {
      return (Builder<T>) new DefaultBuilder();
   }

   protected final boolean detectLeaks;
   protected final boolean allowPrivateUrls;
   private final RemoteUrlPolicy.AllowedRanges allowedAddressRanges;
   protected final boolean ignoreErrors;
   protected final boolean keepHttpClientOpen;
   protected final boolean skipEmptyFormData;
   protected final boolean skipEmptyHeaderData;
   protected final boolean skipEmptyQueryData;
   protected final BiPredicate<RestRequest,RestResponse> logRequestsPredicate;
   protected final CloseableHttpClient httpClient;
   protected final DetailLevel logRequests;
   protected final HeaderList headerData;
   protected final HttpPartParser partParser;
   protected final HttpPartSerializer partSerializer;
   protected final Level logRequestsLevel;
   protected final PartList formData;
   protected final PartList pathData;
   protected final PartList queryData;
   protected final ParserSet parsers;
   protected final RestCallInterceptor[] interceptors;
   protected final SerializerSet serializers;
   protected final UrlEncodingSerializer urlEncodingSerializer;  // Used for form posts only.
   Predicate<Integer> errorCodes;
   private final WritableBeanStore beanStore;
   private final HttpClientConnectionManager connectionManager;
   private final Logger logger;
   private final Map<Class<?>,HttpPartParser> partParsers = new ConcurrentHashMap<>();
   private final Map<Class<?>,HttpPartSerializer> partSerializers = new ConcurrentHashMap<>();
   private final Pattern absUrlPattern = Pattern.compile("^\\w++://.*");
   private final PrintStream console;
   private final RestCallHandler callHandler;
   private StackTraceElement[] closedStack;
   private final StackTraceElement[] creationStack;
   private final Supplier<String> rootUrl;
   private final boolean executorServiceShutdownOnClose;
   private final boolean logToConsole;
   private final boolean ssrfPolicySupported;

   // Why SSRF-guard-active @Remote calls are refused, or null if they are supported.
   private final String ssrfRefusal;
   // The two-pool router this client's HttpClient uses, or null when the SSRF guard is unsupported.
   private final SsrfGuardConnectionManager ssrfGuard;

   private final boolean ownsConnectionManager;
   private final AtomicBoolean isClosed = new AtomicBoolean(false);
   private final AtomicReference<ExecutorService> executorService = new AtomicReference<>();

   /**
    * Constructor.
    *
    * @param builder The builder for this client.
    */
   public RestClient(Builder<?> builder) {
      super(builder);

      beanStore = builder.beanStore.addBean(RestClient.class, this);

      callHandler = builder.callHandler().run();
      connectionManager = builder.connectionManager;
      console = nn(builder.console) ? builder.console : System.err;
      creationStack = isDebug() ? Thread.currentThread().getStackTrace() : null;
      detectLeaks = builder.detectLeaks;
      allowPrivateUrls = builder.allowPrivateUrls || Boolean.getBoolean(RemoteUrlPolicy.ALLOW_PRIVATE_URLS_PROPERTY);
      allowedAddressRanges = RemoteUrlPolicy.AllowedRanges.of(builder.allowedAddressRanges.toArray(new String[0]));
      errorCodes = builder.errorCodes;
      formData = builder.formData().copy();
      headerData = builder.headers().copy();
      httpClient = builder.getHttpClient();
      // Read after getHttpClient(): the default createHttpClient() sets ssrfGuard.  It wires it into the client it
      // builds, but an override of createHttpClient() or of HttpClientBuilder.build() may return another client.
      var builtGuard = builder.httpClient == null ? builder.ssrfGuard : null;
      ssrfGuard = nn(builtGuard) && builtGuard.isConnectionManagerOf(httpClient) ? builtGuard : null;
      ownsConnectionManager = nn(ssrfGuard) && builder.ownsConnectionManager;
      // The HttpClientBuilder is checked as it is now, not when the default createHttpClient() built from it: an override
      // may call super, change the builder and build again.  What is checked: a builder subclass override, an
      // HttpProcessor, and whether what createHttpClient() wired (the guard's interceptors last, its redirect strategy and
      // request executor) is still in place.  One of these changes made after the client was built is refused too (fail
      // closed): which client it went into cannot be told.  A change undone before the override returns is not seen.
      ssrfRefusal = ssrfRefusal(builtGuard, nn(builtGuard) ? Builder.ssrfBuilderRefusal(builder.httpClientBuilder()) : null);
      ssrfPolicySupported = ssrfRefusal == null;
      ignoreErrors = builder.ignoreErrors;
      interceptors = nn(builder.interceptors) ? builder.interceptors.toArray(EMPTY_REST_CALL_INTERCEPTORS) : EMPTY_REST_CALL_INTERCEPTORS;
      keepHttpClientOpen = builder.keepHttpClientOpen;
      logger = nn(builder.logger) ? builder.logger : Logger.getLogger(cn(RestClient.class));
      if (nn(builder.logRequests)) {
         logRequests = builder.logRequests;
      } else {
         logRequests = isDebug() ? DetailLevel.FULL : DetailLevel.NONE;
      }
      if (nn(builder.logRequestsLevel)) {
         logRequestsLevel = builder.logRequestsLevel;
      } else {
         logRequestsLevel = isDebug() ? Level.WARNING : Level.OFF;
      }
      logRequestsPredicate = nn(builder.logRequestsPredicate) ? builder.logRequestsPredicate : LOG_REQUESTS_PREDICATE_DEFAULT;
      logToConsole = builder.logToConsole || isDebug();
      parsers = builder.parsers().build();
      partParser = builder.partParser().create();
      partSerializer = builder.partSerializer().create();
      pathData = builder.pathData().copy();
      queryData = builder.queryData().copy();
      rootUrl = builder.rootUrl;
      serializers = builder.serializers().build();
      skipEmptyFormData = builder.skipEmptyFormData;
      skipEmptyHeaderData = builder.skipEmptyHeaderData;
      skipEmptyQueryData = builder.skipEmptyQueryData;
      urlEncodingSerializer = builder.urlEncodingSerializer().build();
      if (builder.executorService != null)
         executorService.set(builder.executorService);
      executorServiceShutdownOnClose = builder.executorServiceShutdownOnClose;

      init();
   }

   /**
    * Returns the root URL set on this client.
    *
    * @return The root URL, or <jk>null</jk> if not set.
    */
   public String getRootUrl() {
      return rootUrl != null ? rootUrl.get() : null;
   }

   /**
    * Returns the effective builder/settings-level {@code allowPrivateUrls} opt-in for this client (the logical OR
    * of {@code Builder#allowPrivateUrls(boolean)} and the {@value RemoteUrlPolicy#ALLOW_PRIVATE_URLS_PROPERTY}
    * system property).
    *
    * <p>
    * The fully effective per-call value additionally ORs in the {@code @Remote}/{@code @RemoteOp}
    * {@code allowPrivateUrls} annotation attribute (see {@link Remote#allowPrivateUrls()}).
    *
    * @return {@code true} if this client opts into allowing private/loopback/link-local/metadata {@code @Remote} targets.
    */
   public boolean isAllowPrivateUrls() {
      return allowPrivateUrls;
   }

   /**
    * Returns the per-client allowed address ranges set through {@link Builder#allowAddressRanges(String...)}.
    *
    * @return The ranges; never <jk>null</jk>, empty when none were set.
    */
   public RemoteUrlPolicy.AllowedRanges getAllowedAddressRanges() {
      return allowedAddressRanges;
   }

   /**
    * Performs a REST call where the entire call is specified in a simple string.
    *
    * <p>
    * This method is useful for performing callbacks when the target of a callback is passed in
    * on an initial request, for example to signal when a long-running process has completed.
    *
    * <p>
    * The call string can be any of the following formats:
    * <ul class='spaced-list'>
    *    <li>
    *       <js>"[method] [uri]"</js> - e.g. <js>"GET http://localhost/callback"</js>
    *    <li>
    *       <js>"[method] [uri] [payload]"</js> - e.g. <js>"POST http://localhost/callback some text payload"</js>
    *    <li>
    *       <js>"[method] [headers] [uri] [payload]"</js> - e.g. <js>"POST {'Content-Type':'text/json'} http://localhost/callback {'some':'json'}"</js>
    * </ul>
    * <p>
    * The payload will always be sent using a simple {@link StringEntity}.
    *
    * @param callString The call string.
    *    <br>Can be <jk>null</jk> or empty (treated as empty string, will result in an invalid request).
    * @return
    *    A {@link RestRequest} object that can be further tailored before executing the request and getting the response
    *    as a parsed object.
    * @throws RestCallException REST call failed.
    */
   @SuppressWarnings({
      "java:S1854", // state = S5 is a necessary state machine transition; SonarLint false positive
      "java:S4165" // state already holds S5 in some paths, but the assignment is a deliberate state machine transition
   })
   public RestRequest callback(String callString) throws RestCallException {
      callString = emptyIfNull(callString);

      // S1 - Looking for end of method.
      // S2 - Found end of method, looking for beginning of URI or headers.
      // S3 - Found beginning of headers, looking for end of headers.
      // S4 - Found end of headers, looking for beginning of URI.
      // S5 - Found beginning of URI, looking for end of URI.

      var state = S1;

      var mark = 0;
      String method = null;
      String headers = null;
      String uri = null;
      String content = null;
      for (var i = 0; i < callString.length(); i++) {
         var c = callString.charAt(i);
         if (state == S1) {
            if (isWhitespace(c)) {
               method = callString.substring(mark, i);
               state = S2;
            }
         } else if (state == S2) {
            if (! isWhitespace(c)) {
               mark = i;
               state = (c == '{') ? S3 : S5;
            }
         } else if (state == S3) {
            if (c == '}') {
               headers = callString.substring(mark, i + 1);
               state = S4;
            }
         } else if (state == S4) {
            if (! isWhitespace(c)) {
               mark = i;
               state = S5;
            }
         } else /* (state == S5) */ {
            if (isWhitespace(c)) {
               uri = callString.substring(mark, i);
               content = callString.substring(i).trim();
               break;
            }
         }
      }

      if (state != S5)
         throw new RestCallException(null, null, "Invalid format for call string.  State=%s", state);

      try {
         var req = request(method, uri, ine(content));
         if (nn(headers))
            Json5Map.ofString(headers).forEach((k, v) -> req.header(stringHeader(k, s(v))));
         if (ine(content))
            req.contentString(content);
         return req;
      } catch (ParseException e) {
         throw new RestCallException(null, e, "Invalid format for call string.");
      }
   }

   /**
    * Calls {@link CloseableHttpClient#close()} on the underlying {@link CloseableHttpClient}.
    *
    * <p>
    * It's good practice to call this method after the client is no longer used.
    *
    * @throws IOException Thrown by underlying stream.
    */
   @Override
   public void close() throws IOException {
      isClosed.set(true);
      ExecutorService es = executorService.get();
      if (! keepHttpClientOpen) {
         try {
            httpClient.close();
         } finally {
            shutdownPinnedPool();
         }
      }
      if (nn(es) && executorServiceShutdownOnClose)
         es.shutdown();
      // If executorServiceShutdownOnClose is false, executor service remains open for reuse
      if (nn(creationStack))
         closedStack = Thread.currentThread().getStackTrace();
   }

   // The pinned pool is always this client's own (nothing else can reach it), and so is the ordinary pool when this
   // client's build() created it, so they are shut down with the client even when the connection manager is shared
   // and the HttpClient therefore leaves it open.
   private void shutdownPinnedPool() {
      if (ownsConnectionManager)
         ssrfGuard.shutdown();
      else if (nn(ssrfGuard))
         ssrfGuard.shutdownPinned();
   }

   /**
    * Same as {@link #close()}, but ignores any exceptions.
    */
   public void closeQuietly() {
      isClosed.set(true);
      try {
         if (! keepHttpClientOpen) {
            try {
               httpClient.close();
            } finally {
               shutdownPinnedPool();
            }
         }
         ExecutorService es = executorService.get();
         if (nn(es) && executorServiceShutdownOnClose)
            es.shutdown();
      } catch (@SuppressWarnings("unused") Exception t) { /* Suppress close/shutdown exceptions during cleanup */ }
      if (nn(creationStack))
         closedStack = Thread.currentThread().getStackTrace();
   }

   @Override /* Overridden from Context */
   public Builder copy() {
      throw new NoSuchMethodError("Not implemented.");
   }

   /**
    * Creates a mutable copy of the form data defined on this client.
    *
    * <p>
    * Used during the construction of {@link RestRequest} objects.
    *
    * <p>
    * Subclasses can override this method to provide their own builder.
    *
    * @return A new builder.
    */
   public PartList createFormData() {
      return formData.copy();
   }

   /**
    * Creates a mutable copy of the header data defined on this client.
    *
    * <p>
    * Used during the construction of {@link RestRequest} objects.
    *
    * <p>
    * Subclasses can override this method to provide their own builder.
    *
    * @return A new builder.
    */
   public HeaderList createHeaderData() {
      return headerData.copy();
   }

   /**
    * Creates a mutable copy of the path data defined on this client.
    *
    * <p>
    * Used during the construction of {@link RestRequest} objects.
    *
    * <p>
    * Subclasses can override this method to provide their own builder.
    *
    * @return A new builder.
    */
   public PartList createPathData() {
      return pathData.copy();
   }

   /**
    * Creates a mutable copy of the query data defined on this client.
    *
    * <p>
    * Used during the construction of {@link RestRequest} objects.
    *
    * <p>
    * Subclasses can override this method to provide their own builder.
    *
    * @return A new builder.
    */
   public PartList createQueryData() {
      return queryData.copy();
   }

   /**
    * Perform a <c>DELETE</c> request against the specified URI.
    *
    * @param uri
    *    The URI of the remote REST resource.
    *    <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>
    * @return
    *    A {@link RestRequest} object that can be further tailored before executing the request and getting the response
    *    as a parsed object.
    * @throws RestCallException If any authentication errors occurred.
    */
   public RestRequest delete(Object uri) throws RestCallException {
      return request(op("DELETE", uri, NO_BODY));
   }

   /**
    * Executes HTTP request using the default context.
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>This method gets passed on directly to the underlying {@link HttpClient} class.
    * </ul>
    *
    * @param target The target host for the request.
    *    <br>Implementations may accept <jk>null</jk> if they can still determine a route, for example to a default
    *       target or by inspecting the request.
    * @param request The request to execute.
    * @return The response to the request.
    *    <br>This is always a final response, never an intermediate response with an 1xx status code.
    *    <br>Whether redirects or authentication challenges will be returned or handled automatically depends on the
    *       implementation and configuration of this client.
    * @throws IOException In case of a problem or the connection was aborted.
    * @throws ClientProtocolException In case of an http protocol error.
    */
   @Override /* Overridden from HttpClient */
   public HttpResponse execute(HttpHost target, HttpRequest request) throws IOException {
      return httpClient.execute(target, request);
   }

   /**
    * Executes HTTP request using the given context.
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>This method gets passed on directly to the underlying {@link HttpClient} class.
    *    <li class='note'>The {@link #run(HttpHost,HttpRequest,HttpContext)} method has been provided as a wrapper around this method.
    *       Subclasses can override these methods for handling requests with and without bodies separately.
    *    <li class='note'>The {@link RestCallHandler} interface can also be implemented to intercept this method.
    * </ul>
    *
    * @param target The target host for the request.
    *    <br>Implementations may accept <jk>null</jk> if they can still determine a route, for example to a default
    *       target or by inspecting the request.
    * @param request The request to execute.
    * @param context The context to use for the execution, or <jk>null</jk> to use the default context.
    * @return
    *    The response to the request.
    *    <br>This is always a final response, never an intermediate response with an 1xx status code.
    *    <br>Whether redirects or authentication challenges will be returned or handled automatically depends on the
    *       implementation and configuration of this client.
    * @throws IOException In case of a problem or the connection was aborted.
    * @throws ClientProtocolException In case of an http protocol error.
    */
   @Override /* Overridden from HttpClient */
   public HttpResponse execute(HttpHost target, HttpRequest request, HttpContext context) throws IOException {
      return httpClient.execute(target, request, context);
   }

   /**
    * Executes HTTP request to the target using the default context and processes the response using the given response handler.
    *
    * <p>
    * The content entity associated with the response is fully consumed and the underlying connection is released back
    * to the connection manager automatically in all cases relieving individual {@link ResponseHandler ResponseHandlers}
    * from having to manage resource deallocation internally.
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>This method gets passed on directly to the underlying {@link HttpClient} class.
    * </ul>
    *
    * @param target
    *    The target host for the request.
    *    <br>Implementations may accept <jk>null</jk> if they can still determine a route, for example to a default target or by inspecting the request.
    * @param request The request to execute.
    * @param responseHandler The response handler.
    * @return The response object as generated by the response handler.
    * @throws IOException In case of a problem or the connection was aborted.
    * @throws ClientProtocolException In case of an http protocol error.
    */
   @Override /* Overridden from HttpClient */
   public <T> T execute(HttpHost target, HttpRequest request, ResponseHandler<? extends T> responseHandler) throws IOException {
      return httpClient.execute(target, request, responseHandler);
   }

   /**
    * Executes a request using the default context and processes the response using the given response handler.
    *
    * <p>
    * The content entity associated with the response is fully consumed and the underlying connection is released back
    * to the connection manager automatically in all cases relieving individual {@link ResponseHandler ResponseHandlers}
    * from having to manage resource deallocation internally.
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>This method gets passed on directly to the underlying {@link HttpClient} class.
    * </ul>
    *
    * @param target
    *    The target host for the request.
    *    <br>Implementations may accept <jk>null</jk> if they can still determine a route, for example to a default target or by inspecting the request.
    * @param request The request to execute.
    * @param responseHandler The response handler.
    * @param context The context to use for the execution, or <jk>null</jk> to use the default context.
    * @return The response object as generated by the response handler.
    * @throws IOException In case of a problem or the connection was aborted.
    * @throws ClientProtocolException In case of an http protocol error.
    */
   @Override /* Overridden from HttpClient */
   public <T> T execute(HttpHost target, HttpRequest request, ResponseHandler<? extends T> responseHandler, HttpContext context) throws IOException {
      return httpClient.execute(target, request, responseHandler, context);
   }

   /**
    * Executes HTTP request using the default context.
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>This method gets passed on directly to the underlying {@link HttpClient} class.
    * </ul>
    *
    * @param request The request to execute.
    * @return
    *    The response to the request.
    *    <br>This is always a final response, never an intermediate response with an 1xx status code.
    *    <br>Whether redirects or authentication challenges will be returned or handled automatically depends on the
    *       implementation and configuration of this client.
    * @throws IOException In case of a problem or the connection was aborted.
    * @throws ClientProtocolException In case of an http protocol error.
    */
   @Override /* Overridden from HttpClient */
   public HttpResponse execute(HttpUriRequest request) throws IOException {
      return httpClient.execute(request);
   }

   /**
    * Executes HTTP request using the given context.
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>This method gets passed on directly to the underlying {@link HttpClient} class.
    * </ul>
    *
    * @param request The request to execute.
    * @param context The context to use for the execution, or <jk>null</jk> to use the default context.
    * @return
    *    The response to the request.
    *    <br>This is always a final response, never an intermediate response with an 1xx status code.
    *    <br>Whether redirects or authentication challenges will be returned or handled automatically depends on the
    *       implementation and configuration of this client.
    * @throws IOException In case of a problem or the connection was aborted.
    * @throws ClientProtocolException In case of an http protocol error.
    */
   @Override /* Overridden from HttpClient */
   public HttpResponse execute(HttpUriRequest request, HttpContext context) throws IOException {
      return httpClient.execute(request, context);
   }

   /**
    * Executes HTTP request using the default context and processes the response using the given response handler.
    *
    * <p>
    * The content entity associated with the response is fully consumed and the underlying connection is released back
    * to the connection manager automatically in all cases relieving individual {@link ResponseHandler ResponseHandlers}
    * from having to manage resource deallocation internally.
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>This method gets passed on directly to the underlying {@link HttpClient} class.
    * </ul>
    *
    * @param request The request to execute.
    * @param responseHandler The response handler.
    * @return Object returned by response handler.
    * @throws IOException In case of a problem or the connection was aborted.
    * @throws ClientProtocolException In case of an http protocol error.
    */
   @Override /* Overridden from HttpClient */
   public <T> T execute(HttpUriRequest request, ResponseHandler<? extends T> responseHandler) throws IOException {
      return httpClient.execute(request, responseHandler);
   }

   /**
    * Executes HTTP request using the given context and processes the response using the given response handler.
    *
    * <p>
    * The content entity associated with the response is fully consumed and the underlying connection is released back
    * to the connection manager automatically in all cases relieving individual {@link ResponseHandler ResponseHandlers}
    * from having to manage resource deallocation internally.
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>This method gets passed on directly to the underlying {@link HttpClient} class.
    * </ul>
    *
    * @param request The request to execute.
    * @param responseHandler The response handler.
    * @param context The context to use for the execution, or <jk>null</jk> to use the default context.
    * @return The response object as generated by the response handler.
    * @throws IOException In case of a problem or the connection was aborted.
    * @throws ClientProtocolException In case of an http protocol error.
    */
   @Override /* Overridden from HttpClient */
   public <T> T execute(HttpUriRequest request, ResponseHandler<? extends T> responseHandler, HttpContext context) throws IOException {
      return httpClient.execute(request, responseHandler, context);
   }

   /**
    * Same as {@link #formPost(Object, Object)} but doesn't specify the input yet.
    *
    * @param uri
    *    The URI of the remote REST resource.
    *    <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>
    * @return
    *    A {@link RestRequest} object that can be further tailored before executing the request and getting the response
    *    as a parsed object.
    * @throws RestCallException If any authentication errors occurred.
    */
   public RestRequest formPost(Object uri) throws RestCallException {
      return request(op("POST", uri, NO_BODY));
   }

   /**
    * Perform a <c>POST</c> request with a content type of <c>application/x-www-form-urlencoded</c>
    * against the specified URI.
    *
    * @param uri
    *    The URI of the remote REST resource.
    *    <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>
    * @param body
    *    The object to serialize and transmit to the URI as the body of the request.
    *    <ul class='spaced-list'>
    *       <li>{@link NameValuePair} - URL-encoded as a single name-value pair.
    *       <li>{@link NameValuePair} array - URL-encoded as name value pairs.
    *       <li>{@link PartList} - URL-encoded as name value pairs.
    *       <li>{@link Reader}/{@link InputStream}- Streamed directly and <l>Content-Type</l> set to <js>"application/x-www-form-urlencoded"</js>
    *       <li>{@link HttpResource} - Raw contents will be serialized to remote resource.  Additional headers and media type will be set on request.
    *       <li>{@link HttpEntity} - Bypass Juneau serialization and pass HttpEntity directly to HttpClient.
    *       <li>{@link Object} - Converted to a {@link SerializedEntity} using {@link UrlEncodingSerializer} to serialize.
    *       <li>{@link Supplier} - A supplier of anything on this list.
    *    </ul>
    * @return
    *    A {@link RestRequest} object that can be further tailored before executing the request and getting the response
    *    as a parsed object.
    * @throws RestCallException If any authentication errors occurred.
    */
   public RestRequest formPost(Object uri, Object body) throws RestCallException {
      var req = request(op("POST", uri, NO_BODY));
      try {
         if (body instanceof Supplier<?> body2)
            body = body2.get();
         if (body instanceof NameValuePair body2)
            return req.content(new UrlEncodedFormEntity(l(body2)));
         if (body instanceof NameValuePair[] namevaluepairArray)
            return req.content(new UrlEncodedFormEntity(l(namevaluepairArray)));
         if (body instanceof PartList body2)
            return req.content(new UrlEncodedFormEntity(body2));
         if (body instanceof HttpResource body2)
            body2.getHeaders().forEach(req::header);
         if (body instanceof HttpEntity body2) {
            if (body2.getContentType() == null)
               req.header(ContentType.APPLICATION_FORM_URLENCODED);
            return req.content(body2);
         }
         if (body instanceof Reader || body instanceof InputStream)
            return req.header(ContentType.APPLICATION_FORM_URLENCODED).content(body);
         return req.content(serializedEntity(body, urlEncodingSerializer, null));
      } catch (IOException e) {
         throw new RestCallException(null, e, "Could not read form post body.");
      }
   }

   /**
    * Perform a <c>POST</c> request with a content type of <c>application/x-www-form-urlencoded</c>
    * against the specified URI.
    *
    * @param uri
    *    The URI of the remote REST resource.
    *    <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>
    * @param parameters
    *    The parameters of the form post.
    *    <br>The parameters represent name/value pairs and must be an even number of arguments.
    *    <br>Parameters are converted to {@link BasicPart} objects.
    * @return
    *    A {@link RestRequest} object that can be further tailored before executing the request and getting the response
    *    as a parsed object.
    * @throws RestCallException If any authentication errors occurred.
    */
   public RestRequest formPostPairs(Object uri, String...parameters) throws RestCallException {
      return formPost(uri, partList(parameters));
   }

   /**
    * Perform a <c>GET</c> request against the root URI.
    *
    * @return
    *    A {@link RestRequest} object that can be further tailored before executing the request and getting the response
    *    as a parsed object.
    * @throws RestCallException If any authentication errors occurred.
    */
   public RestRequest get() throws RestCallException {
      return request(op("GET", null, NO_BODY));
   }

   /**
    * Perform a <c>GET</c> request against the specified URI.
    *
    * @param uri
    *    The URI of the remote REST resource.
    *    <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>
    * @return
    *    A {@link RestRequest} object that can be further tailored before executing the request and getting the response
    *    as a parsed object.
    * @throws RestCallException If any authentication errors occurred.
    */
   public RestRequest get(Object uri) throws RestCallException {
      return request(op("GET", uri, NO_BODY));
   }

   /**
    * Obtains the connection manager used by this client.
    *
    * @return The connection manager.
    * @deprecated Use {@link HttpClientBuilder}.
    */
   @Deprecated(since = "10.0", forRemoval = true)
   @Override /* Overridden from HttpClient */
   public ClientConnectionManager getConnectionManager() { return httpClient.getConnectionManager(); }

   /**
    * Returns the connection manager if one was specified in the client builder.
    *
    * @return The connection manager.  May be <jk>null</jk>.
    */
   public HttpClientConnectionManager getHttpClientConnectionManager() { return connectionManager; }

   /**
    * Obtains the parameters for this client.
    *
    * These parameters will become defaults for all requests being executed with this client, and for the parameters of dependent objects in this client.
    *
    * @return The default parameters.
    * @deprecated Use {@link RequestConfig}.
    */
   @Deprecated(since = "10.0", forRemoval = true)
   @Override /* Overridden from HttpClient */
   public HttpParams getParams() { return httpClient.getParams(); }

   /**
    * Create a new proxy interface against a 3rd-party REST interface.
    *
    * <p>
    * The URI to the REST interface is based on the following values:
    * <ul>
    *    <li>The {@link Remote#path() @Remote(path)} annotation on the interface (<c>remote-path</c>).
    *    <li>The {@link Builder#rootUrl(Object) rootUrl} on the client (<c>root-url</c>).
    *    <li>The fully-qualified class name of the interface (<c>class-name</c>).
    * </ul>
    *
    * <p>
    * The URI calculation is as follows:
    * <ul>
    *    <li><c>remote-path</c> - If remote path is absolute.
    *    <li><c>root-uri/remote-path</c> - If remote path is relative and root-uri has been specified.
    *    <li><c>root-uri/class-name</c> - If remote path is not specified.
    * </ul>
    *
    * <p>
    * If the information is not available to resolve to an absolute URI, a {@link RemoteMetadataException} is thrown.
    *
    * <h5 class='section'>Examples:</h5>
    * <p class='bjava'>
    *    <jk>package</jk> org.apache.foo;
    *
    *    <ja>@RemoteResource</ja>(path=<js>"http://hostname/resturi/myinterface1"</js>)
    *    <jk>public interface</jk> MyInterface1 { ... }
    *
    *    <ja>@RemoteResource</ja>(path=<js>"/myinterface2"</js>)
    *    <jk>public interface</jk> MyInterface2 { ... }
    *
    *    <jk>public interface</jk> MyInterface3 { ... }
    *
    *    <jc>// Resolves to "http://localhost/resturi/myinterface1"</jc>
    *    MyInterface1 <jv>interface1</jv> = RestClient
    *       .<jsm>create</jsm>()
    *       .build()
    *       .getRemote(MyInterface1.<jk>class</jk>);
    *
    *    <jc>// Resolves to "http://hostname/resturi/myinterface2"</jc>
    *    MyInterface2 <jv>interface2</jv> = RestClient
    *       .<jsm>create</jsm>()
    *       .rootUrl(<js>"http://hostname/resturi"</js>)
    *       .build()
    *       .getRemote(MyInterface2.<jk>class</jk>);
    *
    *    <jc>// Resolves to "http://hostname/resturi/org.apache.foo.MyInterface3"</jc>
    *    MyInterface3 <jv>interface3</jv> = RestClient
    *       .<jsm>create</jsm>()
    *       .rootUrl(<js>"http://hostname/resturi"</js>)
    *       .build()
    *       .getRemote(MyInterface3.<jk>class</jk>);
    * </p>
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>
    *       If you plan on using your proxy in a multi-threaded environment, you'll want to use an underlying
    *       pooling client connection manager.
    * </ul>
    *
    * <h5 class='section'>See Also:</h5><ul>
    *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestProxies">REST Proxies</a>
    * </ul>
    *
    * @param <T> The interface to create a proxy for.
    * @param interfaceClass The interface to create a proxy for.
    *    <br>Cannot be <jk>null</jk>.
    * @return The new proxy interface.
    * @throws RemoteMetadataException If the REST URI cannot be determined based on the information given.
    */
   public <T> T getRemote(Class<T> interfaceClass) {
      return getRemote(interfaceClass, null);
   }

   /**
    * Same as {@link #getRemote(Class)} except explicitly specifies the URI of the REST interface.
    *
    * <h5 class='section'>See Also:</h5><ul>
    *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestProxies">REST Proxies</a>
    * </ul>
    *
    * @param <T> The interface to create a proxy for.
    * @param interfaceClass The interface to create a proxy for.
    *    <br>Cannot be <jk>null</jk>.
    * @param rootUrl The URI of the REST interface.
    *    <br>Can be <jk>null</jk> (will use the root URL from the client builder if set).
    * @return The new proxy interface.
    */
   public <T> T getRemote(Class<T> interfaceClass, Object rootUrl) {
      return getRemote(interfaceClass, rootUrl, null, null);
   }

   /**
    * Same as {@link #getRemote(Class, Object)} but allows you to override the serializer and parser used.
    *
    * <h5 class='section'>See Also:</h5><ul>
    *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestProxies">REST Proxies</a>
    * </ul>

    * @param <T> The interface to create a proxy for.
    * @param interfaceClass The interface to create a proxy for.
    *    <br>Cannot be <jk>null</jk>.
    * @param rootUrl The URI of the REST interface.
    *    <br>Can be <jk>null</jk> (will use the root URL from the client builder if set).
    * @param serializer The serializer used to serialize POJOs to the body of the HTTP request.
    *    <br>Can be <jk>null</jk> (will use the default serializer from the client).
    * @param parser The parser used to parse POJOs from the body of the HTTP response.
    *    <br>Can be <jk>null</jk> (will use the default parser from the client).
    * @return The new proxy interface.
    */
   @SuppressWarnings({
      "java:S6541" // Brain method acceptable - remote proxy creation requires complex initialization logic
   })
   public <T> T getRemote(Class<T> interfaceClass, Object rootUrl, Serializer serializer, Parser parser) {

      reqnn("interfaceClass", interfaceClass);

      if (rootUrl == null)
         rootUrl = this.rootUrl != null ? this.rootUrl.get() : null;

      final String restUrl2 = trimSlashes(emptyIfNull(rootUrl));

      return (T)Proxy.newProxyInstance(interfaceClass.getClassLoader(), a(interfaceClass), new InvocationHandler() {

         final RemoteMeta rm = new RemoteMeta(interfaceClass);

         @Override /* Overridden from InvocationHandler */
      public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
            var rom = rm.getOperationMeta(method);

            // Resolve the effective request URL (interface/method baseUrl + @Url overrides, with the SSRF guard).
            var uri = resolveRemoteUri(interfaceClass, restUrl2, method, rom, rm, args);

            var ror = rom.getReturns();
            if (ror.isFuture()) {
               return getExecutorService().submit(() -> {
                  try {
                     return executeRemoteWithRetry(uri, serializer, parser, method, rom, rm, args);
                  } catch (Exception e) {
                     throw toRex(e);
                  }
               });
            } else if (ror.isCompletableFuture()) {
               var cf = new CompletableFuture<>();
               getExecutorService().submit(() -> {
                  try {
                     cf.complete(executeRemoteWithRetry(uri, serializer, parser, method, rom, rm, args));
                  } catch (Exception e) {
                     cf.completeExceptionally(e);
                  }
                  return null;
               });
               return cf;
            }

            try {
               return executeRemoteWithRetry(uri, serializer, parser, method, rom, rm, args);
            } catch (Exception e) {
               // Check if this is a RuntimeException wrapping a RestCallException with an Error cause
               if (e instanceof RuntimeException e2 && e2.getCause() instanceof RestCallException rce) {
                  var t = rce.getCause();
                  if (nn(t)) {
                     // Check if the cause matches the method's declared exception types
                     for (var t2 : method.getExceptionTypes())
                        if (t2.isInstance(t))
                           throw t; // Rethrow the original Throwable (can be Error)
                  }
               }
               throw e;
            }
         }
      });
   }

   /**
    * Create a new proxy interface against an RRPC-style service.
    *
    * <p>
    * Remote interfaces are interfaces exposed on the server side using either the <c>RrpcServlet</c>
    * or <c>RRPC</c> REST methods.
    *
    * <p>
    * The URI to the REST interface is based on the following values:
    * <ul>
    *    <li>The {@link Remote#path() @Remote(path)} annotation on the interface (<c>remote-path</c>).
    *    <li>The {@link Builder#rootUrl(Object) rootUrl} on the client (<c>root-url</c>).
    *    <li>The fully-qualified class name of the interface (<c>class-name</c>).
    * </ul>
    *
    * <p>
    * The URI calculation is as follows:
    * <ul>
    *    <li><c>remote-path</c> - If remote path is absolute.
    *    <li><c>root-url/remote-path</c> - If remote path is relative and root-url has been specified.
    *    <li><c>root-url/class-name</c> - If remote path is not specified.
    * </ul>
    *
    * <p>
    * If the information is not available to resolve to an absolute URI, a {@link RemoteMetadataException} is thrown.
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>
    *       If you plan on using your proxy in a multi-threaded environment, you'll want to use an underlying
    *       pooling client connection manager.
    * </ul>
    *
    * <h5 class='section'>See Also:</h5><ul>
    *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestRpc">REST/RPC</a>
    * </ul>
    *
    * @param <T> The interface to create a proxy for.
    * @param interfaceClass The interface to create a proxy for.
    *    <br>Cannot be <jk>null</jk>.
    * @return The new proxy interface.
    * @throws RemoteMetadataException If the REST URI cannot be determined based on the information given.
    */
   public <T> T getRrpcInterface(Class<T> interfaceClass) {
      return getRrpcInterface(interfaceClass, null);
   }

   /**
    * Same as {@link #getRrpcInterface(Class)} except explicitly specifies the URI of the REST interface.
    *
    * <h5 class='section'>See Also:</h5><ul>
    *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestRpc">REST/RPC</a>
    * </ul>
    *
    * @param <T> The interface to create a proxy for.
    * @param interfaceClass The interface to create a proxy for.
    *    <br>Cannot be <jk>null</jk>.
    * @param uri The URI of the REST interface.
    *    <br>Can be <jk>null</jk> (will use the root URL from the client builder if set).
    * @return The new proxy interface.
    */
   public <T> T getRrpcInterface(Class<T> interfaceClass, Object uri) {
      return getRrpcInterface(interfaceClass, uri, null, null);
   }

   /**
    * Same as {@link #getRrpcInterface(Class, Object)} but allows you to override the serializer and parser used.
    *
    * <h5 class='section'>See Also:</h5><ul>
    *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestRpc">REST/RPC</a>
    * </ul>
    *
    * @param <T> The interface to create a proxy for.
    * @param interfaceClass The interface to create a proxy for.
    *    <br>Cannot be <jk>null</jk>.
    * @param uri The URI of the REST interface.
    *    <br>Can be <jk>null</jk> (will use the root URL from the client builder if set).
    * @param serializer The serializer used to serialize POJOs to the body of the HTTP request.
    *    <br>Can be <jk>null</jk> (will use the default serializer from the client).
    * @param parser The parser used to parse POJOs from the body of the HTTP response.
    *    <br>Can be <jk>null</jk> (will use the default parser from the client).
    * @return The new proxy interface.
    */
   public <T> T getRrpcInterface(Class<T> interfaceClass, Object uri, Serializer serializer, Parser parser) {

      if (uri == null) {
         var rm = new RrpcInterfaceMeta(interfaceClass, "");
         var path = rm.getPath();
         if (path.indexOf("://") == -1) {
            var rootUrlValue = rootUrl != null ? rootUrl.get() : null;
            if (isEmpty(rootUrlValue))
               throw new RemoteMetadataException(interfaceClass, "Root URI has not been specified.  Cannot construct absolute path to remote interface.");
            path = trimSlashes(rootUrlValue) + '/' + path;
         }
         uri = path;
      }

      final String restUrl2 = s(uri);

      return (T)Proxy.newProxyInstance(interfaceClass.getClassLoader(), a(interfaceClass), new InvocationHandler() {

         final RrpcInterfaceMeta rm = new RrpcInterfaceMeta(interfaceClass, restUrl2);

         @Override /* Overridden from InvocationHandler */
         public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
            var rim = rm.getMethodMeta(method);

            var uri = rim.getUri();
            RestResponse res;

            try {
               // @formatter:off
               RestRequest rc = request("POST", uri, true)
                  .serializer(serializer)
                  .content(args)
                  .rethrow(RuntimeException.class)
                  .rethrow(method.getExceptionTypes());
               // @formatter:on

               res = rc.run();

               var v = res.getContent().as(method.getGenericReturnType());
               if (v == null && method.getReturnType().isPrimitive())
                  v = ClassInfo.of(method.getReturnType()).getPrimitiveDefault();
               return v;

            } catch (Exception e) {
               // Check if this is a RuntimeException wrapping a RestCallException with an Error cause
               if (e instanceof RuntimeException e2 && e2.getCause() instanceof RestCallException rce) {
                  var t = rce.getCause();
                  if (nn(t)) {
                     // Check if the cause matches the method's declared exception types
                     for (var t2 : method.getExceptionTypes())
                        if (t2.isInstance(t))
                           throw t; // Rethrow the original Throwable (can be Error)
                  }
               }
               if (e instanceof RestCallException e2) {
                  var t = e2.getCause();
                  if (nn(t)) {
                     // Check if the cause matches the method's declared exception types
                     for (var t2 : method.getExceptionTypes())
                        if (t2.isInstance(t))
                           throw t; // Rethrow the original Throwable (can be Error)
                     if (t instanceof Exception t2)
                        e = t2;
                  }
               }
               if (e instanceof RuntimeException e2)
                  throw e2;
               for (var t2 : method.getExceptionTypes())
                  if (t2.isInstance(e))
                     throw e;
               throw toRex(e);
            }
         }
      });
   }

   /**
    * Perform a <c>HEAD</c> request against the specified URI.
    *
    * @param uri
    *    The URI of the remote REST resource.
    *    <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>
    * @return
    *    A {@link RestRequest} object that can be further tailored before executing the request and getting the response
    *    as a parsed object.
    * @throws RestCallException If any authentication errors occurred.
    */
   public RestRequest head(Object uri) throws RestCallException {
      return request(op("HEAD", uri, NO_BODY));
   }

   /**
    * Perform an <c>OPTIONS</c> request against the specified URI.
    *
    * @param uri
    *    The URI of the remote REST resource.
    *    <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>
    * @return
    *    A {@link RestRequest} object that can be further tailored before executing the request and getting the response
    *    as a parsed object.
    * @throws RestCallException If any authentication errors occurred.
    */
   public RestRequest options(Object uri) throws RestCallException {
      return request(op("OPTIONS", uri, NO_BODY));
   }

   /**
    * Same as {@link #patch(Object, Object)} but don't specify the input yet.
    *
    * <p>
    * You must call {@link RestRequest#content(Object)} to set the contents on the result object.
    *
    * @param uri
    *    The URI of the remote REST resource.
    *    <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>
    * @return
    *    A {@link RestRequest} object that can be further tailored before executing the request and getting the response
    *    as a parsed object.
    * @throws RestCallException REST call failed.
    */
   public RestRequest patch(Object uri) throws RestCallException {
      return request(op(PATCH, uri, NO_BODY));
   }

   /**
    * Perform a <c>PATCH</c> request against the specified URI.
    *
    * @param uri
    *    The URI of the remote REST resource.
    *    <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>
    * @param body
    *    The object to serialize and transmit to the URI as the body of the request.
    *    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} - 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>
    *          {@link Supplier} - A supplier of anything on this list.
    *    </ul>
    * @return
    *    A {@link RestRequest} object that can be further tailored before executing the request and getting the response
    *    as a parsed object.
    * @throws RestCallException If any authentication errors occurred.
    */
   public RestRequest patch(Object uri, Object body) throws RestCallException {
      return request(op(PATCH, uri, body));
   }

   /**
    * Perform a <c>PATCH</c> request against the specified URI as a plain text body bypassing the serializer.
    *
    * @param uri
    *    The URI of the remote REST resource.
    *    <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>
    * @param body
    *    The object to serialize and transmit to the URI as the body of the request bypassing the serializer.
    * @param contentType
    *    The content type of the request.
    * @return
    *    A {@link RestRequest} object that can be further tailored before executing the request and getting the response
    *    as a parsed object.
    * @throws RestCallException If any authentication errors occurred.
    */
   public RestRequest patch(Object uri, String body, ContentType contentType) throws RestCallException {
      return request(op(PATCH, uri, stringBody(body))).header(contentType);
   }

   /**
    * Same as {@link #post(Object, Object)} but don't specify the input yet.
    *
    * <p>
    * You must call either {@link RestRequest#content(Object)} or {@link RestRequest#formData(String, Object)} to set the
    * contents on the result object.
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>Use {@link #formPost(Object, Object)} for <c>application/x-www-form-urlencoded</c> form posts.
    * </ul>
    *
    * @param uri
    *    The URI of the remote REST resource.
    *    <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>
    * @return
    *    A {@link RestRequest} object that can be further tailored before executing the request and getting the response
    *    as a parsed object.
    * @throws RestCallException REST call failed.
    */
   public RestRequest post(Object uri) throws RestCallException {
      return request(op("POST", uri, NO_BODY));
   }

   /**
    * Perform a <c>POST</c> request against the specified URI.
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>Use {@link #formPost(Object, Object)} for <c>application/x-www-form-urlencoded</c> form posts.
    * </ul>
    *
    * @param uri
    *    The URI of the remote REST resource.
    *    <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>
    * @param body
    *    The object to serialize and transmit to the URI as the body of the request.
    *    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 Object} - POJO to be converted to text using the {@link Serializer} registered with the
    *          {@link RestClient}.
    *       <li>
    *          {@link HttpEntity} / {@link HttpResource} - Bypass Juneau serialization and pass HttpEntity directly to HttpClient.
    *       <li>
    *          {@link PartList} - Converted to a URL-encoded FORM post.
    *       <li>
    *          {@link Supplier} - A supplier of anything on this list.
    *    </ul>
    * @return
    *    A {@link RestRequest} object that can be further tailored before executing the request and getting the response
    *    as a parsed object.
    * @throws RestCallException If any authentication errors occurred.
    */
   public RestRequest post(Object uri, Object body) throws RestCallException {
      return request(op("POST", uri, body));
   }

   /**
    * Perform a <c>POST</c> request against the specified URI as a plain text body bypassing the serializer.
    *
    * @param uri
    *    The URI of the remote REST resource.
    *    <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>
    * @param body
    *    The object to serialize and transmit to the URI as the body of the request bypassing the serializer.
    * @param contentType
    *    The content type of the request.
    * @return
    *    A {@link RestRequest} object that can be further tailored before executing the request and getting the response
    *    as a parsed object.
    * @throws RestCallException If any authentication errors occurred.
    */
   public RestRequest post(Object uri, String body, ContentType contentType) throws RestCallException {
      return request(op("POST", uri, stringBody(body))).header(contentType);
   }

   /**
    * Same as {@link #put(Object, Object)} but don't specify the input yet.
    *
    * <p>
    * You must call either {@link RestRequest#content(Object)} or {@link RestRequest#formData(String, Object)}
    * to set the contents on the result object.
    *
    * @param uri
    *    The URI of the remote REST resource.
    *    <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>
    * @return
    *    A {@link RestRequest} object that can be further tailored before executing the request and getting the response
    *    as a parsed object.
    * @throws RestCallException REST call failed.
    */
   public RestRequest put(Object uri) throws RestCallException {
      return request(op("PUT", uri, NO_BODY));
   }

   /**
    * Perform a <c>PUT</c> request against the specified URI.
    *
    * @param uri
    *    The URI of the remote REST resource.
    *    <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>
    * @param body
    *    The object to serialize and transmit to the URI as the body of the request.
    *    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 Object} - POJO to be converted to text using the {@link Serializer} registered with the
    *          {@link RestClient}.
    *       <li>
    *          {@link HttpEntity} / {@link HttpResource} - Bypass Juneau serialization and pass HttpEntity directly to HttpClient.
    *       <li>
    *          {@link PartList} - Converted to a URL-encoded FORM post.
    *       <li>
    *          {@link Supplier} - A supplier of anything on this list.
    *    </ul>
    * @return
    *    A {@link RestRequest} object that can be further tailored before executing the request
    *    and getting the response as a parsed object.
    * @throws RestCallException If any authentication errors occurred.
    */
   public RestRequest put(Object uri, Object body) throws RestCallException {
      return request(op("PUT", uri, body));
   }

   /**
    * Perform a <c>PUT</c> request against the specified URI using a plain text body bypassing the serializer.
    *
    * @param uri
    *    The URI of the remote REST resource.
    *    <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>
    * @param body
    *    The object to serialize and transmit to the URI as the body of the request bypassing the serializer.
    * @param contentType The content type of the request.
    * @return
    *    A {@link RestRequest} object that can be further tailored before executing the request
    *    and getting the response as a parsed object.
    * @throws RestCallException If any authentication errors occurred.
    */
   public RestRequest put(Object uri, String body, ContentType contentType) throws RestCallException {
      return request(op("PUT", uri, stringBody(body))).header(contentType);
   }

   /**
    * Perform a generic REST call.
    *
    * @param method The HTTP method.
    *    <br>Cannot be <jk>null</jk>.
    * @param uri
    *    The URI of the remote REST resource.
    *    <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>Can be <jk>null</jk> (will result in an invalid request).
    * @return
    *    A {@link RestRequest} object that can be further tailored before executing the request and getting the response
    *    as a parsed object.
    * @throws RestCallException If any authentication errors occurred.
    */
   public RestRequest request(String method, Object uri) throws RestCallException {
      return request(op(method, uri, NO_BODY));
   }

   /**
    * Perform a generic REST call.
    *
    * <p>
    * Typically you're going to use {@link #request(String, Object)} or {@link #request(String, Object, Object)},
    * but this method is provided to allow you to perform non-standard HTTP methods (e.g. HTTP FOO).
    *
    * @param method The method name (e.g. <js>"GET"</js>, <js>"OPTIONS"</js>).
    *    <br>Cannot be <jk>null</jk>.
    * @param uri
    *    The URI of the remote REST resource.
    *    <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>Can be <jk>null</jk> (will result in an invalid request).
    * @param hasBody Boolean flag indicating if the specified request has content associated with it.
    * @return
    *    A {@link RestRequest} object that can be further tailored before executing the request and getting the response
    *    as a parsed object.
    * @throws RestCallException If any authentication errors occurred.
    */
   public RestRequest request(String method, Object uri, boolean hasBody) throws RestCallException {
      return request(op(method, uri, NO_BODY).hasContent(hasBody));
   }

   /**
    * Perform a generic REST call.
    *
    * @param method The HTTP method.
    *    <br>Cannot be <jk>null</jk>.
    * @param uri
    *    The URI of the remote REST resource.
    *    <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>Can be <jk>null</jk> (will result in an invalid request).
    * @param body
    *    The HTTP body content.
    *    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} - 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>
    *          {@link Supplier} - A supplier of anything on this list.
    *    </ul>
    *    This parameter is IGNORED if the method type normally does not have content.
    * @return
    *    A {@link RestRequest} object that can be further tailored before executing the request and getting the response
    *    as a parsed object.
    * @throws RestCallException If any authentication errors occurred.
    */
   public RestRequest request(String method, Object uri, Object body) throws RestCallException {
      return request(op(method, uri, body));
   }

   private static RestOperation op(String method, Object url, Object body) {
      return RestOperation.of(method, url, body);
   }

   private static Reader stringBody(String body) {
      return body == null ? null : new StringReader(s(body));
   }

   /**
    * Creates a {@link RestRequest} object from the specified {@link HttpRequest} object.
    *
    * <p>
    * Subclasses can override this method to provide their own specialized {@link RestRequest} objects.
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='warn'>The SSRF guard of {@code @Remote} calls travels on the request's {@link HttpContext}, which an
    *       override of {@link RestRequest#run()} in the returned request's class may drop (by copying the request, or
    *       sending it with another context), and depends on this client's connection manager, which a request bound to a different client does not use.  So an SSRF-guard-active
    *       {@code @Remote} call (one without the {@link Builder#allowPrivateUrls(boolean) allowPrivateUrls} opt-in) is
    *       refused through such a request, whether this method or {@link #request(String, Object, boolean)} returns it.
    *       Ordinary requests are unaffected.
    * </ul>
    *
    * @param uri The target.
    * @param method The HTTP method (uppercase).
    * @param hasBody Whether this method has a request entity.
    * @return A new {@link RestRequest} object.
    * @throws RestCallException If an exception or non-200 response code occurred during the connection attempt.
    */
   protected RestRequest createRequest(URI uri, String method, boolean hasBody) throws RestCallException {
      return new RestRequest(this, uri, method, hasBody);
   }

   /**
    * Creates a {@link RestResponse} object from the specified {@link HttpResponse} object.
    *
    * <p>
    * Subclasses can override this method to provide their own specialized {@link RestResponse} objects.
    *
    * @param request The request creating this response.
    * @param httpResponse The response object to wrap.
    * @param parser The parser to use to parse the response.
    *
    * @return A new {@link RestResponse} object.
    * @throws RestCallException If an exception or non-200 response code occurred during the connection attempt.
    */
   protected RestResponse createResponse(RestRequest request, HttpResponse httpResponse, Parser parser) throws RestCallException {
      return new RestResponse(this, request, httpResponse, parser);
   }

   /**
    * @deprecated Object.finalize() is deprecated. Use try-with-resources or explicit close() calls instead.
    */
   @Override
   @Deprecated(since = "9", forRemoval = true) // Object.finalize() is deprecated
   @SuppressWarnings({
      "java:S1113" // Kept for detectLeaks; logs warning when RestClient is GC'd without close
   })
   protected void finalize() throws Throwable {
      if (detectLeaks && ! isClosed.get() && ! keepHttpClientOpen) {
         var sb = new StringBuilder("WARNING:  RestClient garbage collected before it was finalized.");  // NOT DEBUG
         if (nn(creationStack)) {
            sb.append("\nCreation Stack:");  // NOT DEBUG
            for (var e : creationStack) {
               sb.append("\n\t").append(e);  // NOT DEBUG
            }
         }
         log(WARNING, sb.toString());
      }
   }

   /**
    * Returns the part parser associated with this client.
    *
    * @return The part parser associated with this client.
    */
   protected HttpPartParser getPartParser() { return partParser; }

   /**
    * Returns the part parser instance of the specified type.
    *
    * @param c The part parser class.
    * @return The part parser.
    */
   protected HttpPartParser getPartParser(Class<? extends HttpPartParser> c) {
      var x = partParsers.get(c);
      if (x == null) {
         try {
            x = BeanInstantiator.of(c, beanStore).run();
         } catch (ExecutableException e) {
            throw toRex(e);
         }
         partParsers.put(c, x);
      }
      return x;
   }

   /**
    * Returns the part serializer associated with this client.
    *
    * @return The part serializer associated with this client.
    */
   protected HttpPartSerializer getPartSerializer() { return partSerializer; }

   /**
    * Returns the part serializer instance of the specified type.
    *
    * @param c The part serializer class.
    * @return The part serializer.
    */
   protected HttpPartSerializer getPartSerializer(Class<? extends HttpPartSerializer> c) {
      var x = partSerializers.get(c);
      if (x == null) {
         try {
            x = BeanInstantiator.of(c, beanStore).run();
         } catch (ExecutableException e) {
            throw toRex(e);
         }
         partSerializers.put(c, x);
      }
      return x;
   }

   /**
    * Gets called add the end of the constructor call to perform any post-initialization.
    */
   protected void init() {
      // No-op: Intentional empty implementation for optional override method
   }

   /**
    * Returns <jk>true</jk> if empty request form-data parameter values should be ignored.
    *
    * @return <jk>true</jk> if empty request form-data parameter values should be ignored.
    */
   protected boolean isSkipEmptyFormData() { return skipEmptyFormData; }

   /**
    * Returns <jk>true</jk> if empty request header values should be ignored.
    *
    * @return <jk>true</jk> if empty request header values should be ignored.
    */
   protected boolean isSkipEmptyHeaderData() { return skipEmptyHeaderData; }

   /**
    * Returns <jk>true</jk> if empty request query parameter values should be ignored.
    *
    * @return <jk>true</jk> if empty request query parameter values should be ignored.
    */
   protected boolean isSkipEmptyQueryData() { return skipEmptyQueryData; }

   /**
    * Logs a message.
    *
    * @param level The log level.
    * @param msg The message with {@link String#format(String, Object...) String.format}-style (<c>%s</c>) arguments.
    * @param args The arguments.
    */
   protected void log(Level level, String msg, Object...args) {
      if (logger.isLoggable(level)) {
         String formattedMsg = f(msg, args);
         logger.log(level, formattedMsg);
         if (logToConsole)
            console.println(formattedMsg);
      } else if (logToConsole) {
         console.println(f(msg, args));
      }
   }

   /**
    * Logs a message.
    *
    * @param level The log level.
    * @param t Thrown exception.
    *    <br>Can be <jk>null</jk> (no exception stack trace will be logged).
    * @param msg The message.
    * @param args Optional message arguments.
    */
   protected void log(Level level, Throwable t, String msg, Object...args) {
      if (logger.isLoggable(level)) {
         String formattedMsg = f(msg, args);
         logger.log(level, formattedMsg, t);
         if (logToConsole) {
            console.println(f(msg, args));
            if (nn(t))
               t.printStackTrace(console);
         }
      } else if (logToConsole) {
         console.println(f(msg, args));
         if (nn(t))
            t.printStackTrace(console);
      }
   }

   /**
    * Interceptor method called immediately after the RestRequest object is created and all headers/query/form-data has been set on the request from the client.
    *
    * <p>
    * Subclasses can override this method to handle any cleanup operations.
    *
    * <h5 class='section'>See Also:</h5><ul>
    *    <li class='jm'>{@link Builder#interceptors(Object...)}
    * </ul>
    *
    * @param req The HTTP request.
    * @param res The HTTP response.
    * @throws RestCallException If any of the interceptors threw an exception.
    */
   protected void onCallClose(RestRequest req, RestResponse res) throws RestCallException {
      try {
         for (var rci : interceptors)
            rci.onClose(req, res);
      } catch (RuntimeException | RestCallException e) {
         throw e;
      } catch (Exception e) {
         throw new RestCallException(res, e, "Interceptor threw an exception on close.");
      }
   }

   /**
    * Interceptor method called immediately after an HTTP response has been received.
    *
    * <p>
    * Subclasses can override this method to intercept the response and perform special modifications.
    *
    * <h5 class='section'>See Also:</h5><ul>
    *    <li class='jm'>{@link Builder#interceptors(Object...)}
    * </ul>
    *
    * @param req The HTTP request.
    * @param res The HTTP response.
    * @throws RestCallException If any of the interceptors threw an exception.
    */
   protected void onCallConnect(RestRequest req, RestResponse res) throws RestCallException {
      try {
         for (var rci : interceptors)
            rci.onConnect(req, res);
      } catch (RuntimeException | RestCallException e) {
         throw e;
      } catch (Exception e) {
         throw new RestCallException(res, e, "Interceptor threw an exception on connect.");
      }
   }

   /**
    * Interceptor method called immediately after the RestRequest object is created and all headers/query/form-data has been copied from the client.
    *
    * <p>
    * Subclasses can override this method to intercept the request and perform special modifications.
    *
    * <h5 class='section'>See Also:</h5><ul>
    *    <li class='jm'>{@link Builder#interceptors(Object...)}
    * </ul>
    *
    * @param req The HTTP request.
    * @throws RestCallException If any of the interceptors threw an exception.
    */
   protected void onCallInit(RestRequest req) throws RestCallException {
      try {
         for (var rci : interceptors)
            rci.onInit(req);
      } catch (RuntimeException | RestCallException e) {
         throw e;
      } catch (Exception e) {
         throw new RestCallException(null, e, "Interceptor threw an exception on init.");
      }
   }

   @Override /* Overridden from MarshallingContextable */
   protected FluentMap<String,Object> properties() {
      return super.properties()
         .a("errorCodes", errorCodes)
         .a("executorService", executorService.get())
         .a("executorServiceShutdownOnClose", executorServiceShutdownOnClose)
         .a("headerData", headerData)
         .a("interceptors", interceptors)
         .a("keepHttpClientOpen", keepHttpClientOpen)
         .a("partParser", partParser)
         .a("partSerializer", partSerializer)
         .a("queryData", queryData)
         .a("rootUrl", rootUrl != null ? rootUrl.get() : null);
   }

   /**
    * Perform an arbitrary request against the specified URI.
    *
    * <p>
    * All requests feed through this method so it can be used to intercept request creations and make modifications
    * (such as add headers).
    *
    * @param op The operation that identifies the HTTP method, URL, and optional payload.
    * @return
    *    A {@link RestRequest} object that can be further tailored before executing the request and getting the response
    *    as a parsed object.
    * @throws RestCallException If any authentication errors occurred.
    */
   protected RestRequest request(RestOperation op) throws RestCallException {
      if (isClosed.get()) {
         Exception e2 = null;
         if (nn(closedStack)) {
            e2 = new Exception("Creation stack:");
            e2.setStackTrace(closedStack);
            throw new RestCallException(null, e2, "RestClient.close() has already been called.  This client cannot be reused.");
         }
         throw new RestCallException(null, null,
            "RestClient.close() has already been called.  This client cannot be reused.  Closed location stack trace can be displayed by setting the system property 'org.apache.juneau.rest.client2.RestClient.trackCreation' to true.");
      }

      var req = createRequest(toUri(op.getUri(), rootUrl != null ? rootUrl.get() : null), op.getMethod(), op.hasContent());

      onCallInit(req);

      req.content(op.getContent());

      return req;
   }

   /**
    * Entrypoint for executing all requests and returning a response.
    *
    * <p>
    * Subclasses can override this method to provide specialized handling.
    *
    * <p>
    * The behavior of this method can also be modified by specifying a different {@link RestCallHandler}.
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='warn'>The SSRF guard of {@code @Remote} calls travels on the request's {@code HttpContext}, which this
    *       client cannot guarantee an override passes on unchanged.  So a client whose class overrides this method,
    *       {@link #execute(HttpHost, HttpRequest, HttpContext)} or {@link #execute(HttpUriRequest, HttpContext)} refuses every
    *       SSRF-guard-active {@code @Remote} call (one without the {@link Builder#allowPrivateUrls(boolean) allowPrivateUrls}
    *       opt-in).  Ordinary requests are unaffected.
    * </ul>
    *
    * <h5 class='section'>See Also:</h5><ul>
    *    <li class='jm'>{@link Builder#callHandler()}
    * </ul>
    *
    * @param target The target host for the request.
    *    <br>Implementations may accept <jk>null</jk> if they can still determine a route, for example to a default
    *       target or by inspecting the request.
    * @param request The request to execute.
    * @param context The context to use for the execution, or <jk>null</jk> to use the default context.
    * @return
    *    The response to the request.
    *    <br>This is always a final response, never an intermediate response with an 1xx status code.
    *    <br>Whether redirects or authentication challenges will be returned or handled automatically depends on the
    *       implementation and configuration of this client.
    * @throws IOException In case of a problem or the connection was aborted.
    * @throws ClientProtocolException In case of an http protocol error.
    */
   protected HttpResponse run(HttpHost target, HttpRequest request, HttpContext context) throws IOException {
      return callHandler.run(target, request, context);
   }

   // The methods a request is dispatched through on its way from RestRequest to the HttpClient (run(...), then the two
   // execute(...) overloads BasicRestCallHandler calls).
   private static final List<Method> DISPATCH_METHODS = dispatchMethods();

   private static List<Method> dispatchMethods() {
      try {
         return List.of(
            RestClient.class.getDeclaredMethod("run", HttpHost.class, HttpRequest.class, HttpContext.class),
            RestClient.class.getDeclaredMethod("execute", HttpHost.class, HttpRequest.class, HttpContext.class),
            RestClient.class.getDeclaredMethod("execute", HttpUriRequest.class, HttpContext.class));
      } catch (NoSuchMethodException e) {
         throw new ExceptionInInitializerError(e);
      }
   }

   // Why this client cannot guarantee the SSRF guard of @Remote calls, or null if it can.  A connection manager this
   // client did not build has no pinned pool, an HttpClient other than the one the default createHttpClient() wired to
   // it (builtGuard) does not use it, and builderRefusal says why the HttpClientBuilder may have built the client around
   // something else.  The guard travels on each request's context, so it holds on another thread as long as the request
   // that carries it is the one sent; but anything that may send a different request (a custom call handler, a handler
   // bound to another client, a subclass that overrides the request dispatch: each may copy the request, or send it with
   // another context) is refused, and these refusals are what keep such paths from going out unpinned.
   private String ssrfRefusal(SsrfGuardConnectionManager builtGuard, String builderRefusal) {
      var tail = "the SSRF guardrail's connect-time contract (pin-on-connect + redirect revalidation) is not in force.  ";
      var optOut = "or set allowPrivateUrls(true) if this is an intentional local-dev/intranet target.";
      if (ssrfGuard == null && nn(builtGuard) && ! SsrfGuardConnectionManager.canCheckWiring())
         // HTT: only an HttpClient release whose InternalHttpClient has no connManager field, or a JVM that denies
         // reflective access to it, gets here.
         return "Refusing to send a policy-covered @Remote request: this RestClient cannot read the connection manager of "
            + "the HttpClient it built (org.apache.http.impl.client.InternalHttpClient.connManager), so it cannot confirm "
            + "that the client uses its SSRF-guard connection manager, and " + tail + "Use an HttpClient 4.5.x release, "
            + optOut;
      if (ssrfGuard == null && nn(builtGuard))
         return "Refusing to send a policy-covered @Remote request through an HttpClient that is not the one this RestClient "
            + "wired to its SSRF-guard connection manager: an overridden createHttpClient() or HttpClientBuilder.build() "
            + "returned another client, or a wrapper around one, which may send the request without the pinned pool, so "
            + tail + "Return the client super.createHttpClient() or HttpClientBuilder.build() built, unwrapped (customize it "
            + "through httpClientBuilder(...) instead), " + optOut;
      if (nn(builderRefusal))
         return builderRefusal;
      if (ssrfGuard == null)
         return "Refusing to send a policy-covered @Remote request through a caller-supplied HttpClient or connection "
            + "manager that cannot be guaranteed to honor the SSRF guardrail's connect-time contract (pin-on-connect + "
            + "redirect revalidation): the client was supplied via httpClient(...) or an overridden createHttpClient(), "
            + "or the connection manager via connectionManager(...) or an overridden createConnectionManager(), instead "
            + "of being built by this RestClient.  Let this RestClient build its own HttpClient and connection manager, "
            + optOut;
      if (callHandler.getClass() != BasicRestCallHandler.class)
         return "Refusing to send a policy-covered @Remote request through a custom RestCallHandler (" + cn(callHandler)
            + "): it may copy the request, or send it with another context, without the SSRF guard the request carries, so "
            + tail + "Remove the callHandler(...) setting, " + optOut;
      if (((BasicRestCallHandler)callHandler).client() != this)
         return "Refusing to send a policy-covered @Remote request through a BasicRestCallHandler bound to a different "
            + "RestClient: it sends the request through that client's connection manager, where " + tail
            + "Remove the callHandler(...) setting, " + optOut;
      var dispatch = overriddenDispatch(getClass());
      if (nn(dispatch))
         return "Refusing to send a policy-covered @Remote request through a RestClient subclass (" + dispatch
            + "): the override may copy the request, or send it with another context, without the SSRF guard the request "
            + "carries, so " + tail + "Remove the override, " + optOut;
      return null;
   }

   // Why a guarded call cannot be sent through rc (the request createRequest(...) returned), or null if it can: a request
   // bound to another client goes out through that client's HttpClient, and an override of RestRequest.run() may copy
   // the request, or send it with another context, without the guard it carries.
   private String requestRefusal(RestRequest rc) {
      if (rc.client != this)
         return "Refusing to send a policy-covered @Remote request through a RestRequest bound to a different "
            + "RestClient: it sends the request through that client's HttpClient, where the SSRF guardrail's "
            + "connect-time contract (pin-on-connect + redirect revalidation) is not in force.  Remove the "
            + "createRequest(...) or request(...) override that returns it, or set allowPrivateUrls(true) if this is "
            + "an intentional local-dev/intranet target.";
      for (Class<?> x = rc.getClass(); x != RestRequest.class; x = x.getSuperclass()) {
         try {
            x.getDeclaredMethod("run");
            return "Refusing to send a policy-covered @Remote request through a RestRequest subclass (" + cn(x)
               + " overrides run()): the override may copy the request, or send it with another context, without the "
               + "SSRF guard the request carries, so the SSRF guardrail's connect-time contract (pin-on-connect + redirect revalidation) is not in force.  Remove the override "
               + "(or the createRequest(...) override that returns it), or set allowPrivateUrls(true) if this is an "
               + "intentional local-dev/intranet target.";
         } catch (@SuppressWarnings("unused") NoSuchMethodException e) { /* Not declared here. */ }
      }
      return null;
   }

   // Returns "<class>.<method>(<params>)" for the first dispatch method a subclass between c and RestClient declares,
   // or null if there is none.
   private static String overriddenDispatch(Class<?> c) {
      for (var x = c; x != RestClient.class; x = x.getSuperclass()) {
         for (var m : DISPATCH_METHODS) {
            try {
               x.getDeclaredMethod(m.getName(), m.getParameterTypes());
               return cn(x) + " overrides " + m.getName() + "(" + String.join(",", Arrays.stream(m.getParameterTypes()).map(Class::getSimpleName).toList()) + ")";
            } catch (@SuppressWarnings("unused") NoSuchMethodException e) { /* Not declared here. */ }
         }
      }
      return null;
   }

   /**
    * Resolves the effective request URL for a remote-proxy call, applying the dynamic-URL overrides
    * ({@code @Url} parameter, then method-level {@code baseUrl}, then interface-level {@code baseUrl}) over the
    * statically-computed interface-base + method path, with the http/https SSRF guardrail.
    *
    * <p>
    * Ported from the next-generation engine's {@code RemoteInvocationHandler.resolveEffectiveUrl(...)}.
    */
   String resolveRemoteUri(Class<?> interfaceClass, String restUrl2, Method method, RemoteOperationMeta rom, RemoteMeta rm, Object[] args) {
      var fullPath = rom.getFullPath();
      var allowPrivate = isAllowPrivateUrls() || rm.isAllowPrivateUrls();
      String uri;

      // Option A: a call-time @Url parameter wins over everything (endpoint replacement).
      var urlIdx = rom.getUrlParamIndex();
      if (urlIdx >= 0) {
         var arg = (args == null || urlIdx >= args.length) ? null : args[urlIdx];
         var v = arg == null ? null : arg.toString();
         if (ib(v))
            throw new RemoteMetadataException(interfaceClass, "@Url parameter on " + method.getDeclaringClass().getName() + "." + method.getName() + " must not be null or blank.");
         uri = RemoteProxyUtils.requireHttpScheme(v.trim(), allowPrivate, allowedAddressRanges);
         // A scheme-less @Url value is relative and resolved against the client root URL only.
         if (uri.indexOf("://") == -1)
            uri = restUrl2 + '/' + trimSlashes(uri);
      } else {
         // Option B: a declarative base/host override (method-level wins over interface-level).
         var baseUrl = firstNonEmpty(rom.getBaseUrl(), rm.getBaseUrl());
         if (ine(baseUrl)) {
            uri = RemoteProxyUtils.requireHttpScheme(RemoteProxyUtils.combinePaths(baseUrl, fullPath), allowPrivate, allowedAddressRanges);
         } else {
            uri = fullPath;
            if (uri.indexOf("://") == -1)
               uri = restUrl2 + '/' + uri;
         }
      }

      if (uri.indexOf("://") == -1)
         throw new RemoteMetadataException(interfaceClass, "Root URI has not been specified.  Cannot construct absolute path to remote resource.");

      // SSRF guardrail (parity with juneau-rest-client RemoteClient.resolveEffectiveUrl): the fully-resolved
      // absolute URI -- including a scheme-less @Url/default-path combined with the client root above -- must pass
      // the full deny-private policy, not just the http/https scheme check (Review R4: the default (no-override)
      // path is policy-covered too once it is absolute).
      try {
         RemoteUrlPolicy.requireAllowedUrl(uri, allowPrivate, allowedAddressRanges);
      } catch (IllegalArgumentException e) {
         throw new RemoteMetadataException(interfaceClass, e.getMessage());
      }

      return uri;
   }

   /**
    * Builds a fresh {@link RestRequest} for a remote-proxy call, binding constant parts (interface + method level),
    * content-negotiation overrides ({@code accept}/{@code contentType}), the method-argument parts, and the per-call
    * timeout.  Re-invoked per retry attempt so a (gated) retry resends a freshly-bound request.
    *
    * <p>
    * Ported from the next-generation engine's {@code RemoteInvocationHandler.buildRequest(...)}.  Unlike the NG
    * version, argument binding here is driven entirely by the pre-resolved {@link RemoteOperationMeta} (<c>rom</c>)
    * rather than live reflection over the interface {@link Method}, and any misconfiguration that needs to identify
    * the offending interface/method is already reported earlier by {@link #resolveRemoteUri}; neither the interface
    * class nor the {@link Method} is needed here.
    */
   RestRequest buildRemoteRequest(String uri, Serializer serializer, Parser parser, RemoteOperationMeta rom, RemoteMeta rm, Object[] args) throws RestCallException {
      var httpMethod = rom.getHttpMethod();
      var rc = request(httpMethod, uri, hasContent(httpMethod));

      if (serializer != null) rc.serializer(serializer);
      if (parser != null) rc.parser(parser);

      // contentType override: select the matching registered serializer (else the client default) and send the
      // overridden media type as the Content-Type label (mirrors NG resolveBodyFormat()).
      var effContentType = firstNonEmpty(rom.getContentType(), rm.getContentType());
      if (ine(effContentType)) {
         var s = getMatchingSerializer(effContentType);
         if (s == null) {
            var all = serializers.getSerializers();
            if (! all.isEmpty())
               s = all.get(0);
         }
         if (nn(s))
            rc.serializer(s);
         rc.contentType(effContentType);
      }

      var effAccept = firstNonEmpty(rom.getAccept(), rm.getAccept());

      // Constant headers (interface-level then method-level, method-level wins on name collisions).  A constant
      // Content-Type/Accept is dropped when the dedicated contentType/accept attribute is in effect.
      var methodHeaderNames = new HashSet<String>();
      rom.getConstantHeaders().forEach(e -> methodHeaderNames.add(e.getKey()));
      var skipContentType = ine(effContentType);
      var skipAccept = ine(effAccept);
      rm.getHeaders().forEach(h -> {
         var n = h.getName();
         if (methodHeaderNames.contains(n))
            return;
         if (skipContentType && eqic(HEADER_CONTENT_TYPE, n))
            return;
         if (skipAccept && eqic(HEADER_ACCEPT, n))
            return;
         rc.header(h);
      });
      rom.getConstantHeaders().forEach(e -> {
         if (skipContentType && eqic(HEADER_CONTENT_TYPE, e.getKey()))
            return;
         if (skipAccept && eqic(HEADER_ACCEPT, e.getKey()))
            return;
         rc.header(e.getKey(), e.getValue());
      });

      // Constant query/form-data (interface-level then method-level, method-level wins on name collisions).
      RemoteProxyUtils.mergeConstants(rm.getQueryData(), rom.getConstantQueryData()).forEach(rc::queryData);
      RemoteProxyUtils.mergeConstants(rm.getFormData(), rom.getConstantFormData()).forEach(rc::formData);

      // Apply method-level defaults if parameter values are not provided (9.2.0)
      rom.forEachPathArg(a -> {
         var val = args[a.getIndex()];
         if (val == null) {
            var def = a.getSchema().getDefault();
            if (def == null)
               def = rom.getPathDefault(a.getName());
            if (nn(def))
               val = def;
         }
         rc.pathArg(a.getName(), val, a.getSchema(), a.getSerializer().orElse(partSerializer));
      });
      rom.forEachQueryArg(a -> {
         var val = args[a.getIndex()];
         if (val == null) {
            var def = a.getSchema().getDefault();
            if (def == null)
               def = rom.getQueryDefault(a.getName());
            if (nn(def))
               val = def;
         }
         rc.queryArg(a.getName(), val, a.getSchema(), a.getSerializer().orElse(partSerializer), a.isSkipIfEmpty());
      });
      rom.forEachFormDataArg(a -> {
         var val = args[a.getIndex()];
         if (val == null) {
            var def = a.getSchema().getDefault();
            if (def == null)
               def = rom.getFormDataDefault(a.getName());
            if (nn(def))
               val = def;
         }
         rc.formDataArg(a.getName(), val, a.getSchema(), a.getSerializer().orElse(partSerializer), a.isSkipIfEmpty());
      });
      rom.forEachHeaderArg(a -> {
         var val = args[a.getIndex()];
         if (val == null) {
            var def = a.getSchema().getDefault();
            if (def == null)
               def = rom.getHeaderDefault(a.getName());
            if (nn(def))
               val = def;
         }
         rc.headerArg(a.getName(), val, a.getSchema(), a.getSerializer().orElse(partSerializer), a.isSkipIfEmpty());
      });

      var ba = rom.getContentArg();
      if (nn(ba)) {
         var val = args[ba.getIndex()];
         if (val == null) {
            var def = ba.getSchema().getDefault();
            if (def == null)
               def = rom.getContentDefault();
            if (nn(def))
               val = def;
         }
         rc.content(val, ba.getSchema());
      } else {
         var contentDef = rom.getContentDefault();
         if (nn(contentDef))
            rc.content(contentDef);
      }

      rom.forEachRequestArg(rmba -> {
         var rbm = rmba.getMeta();
         var bean = args[rmba.getIndex()];
         if (nn(bean)) {
            for (var p : rbm.getProperties()) {
               var val = safeSupplier(() -> p.getGetter().invoke(bean));
               if (val instanceof Optional<?> val2)
                  val = val2.orElse(null);
               var pt = p.getPartType();
               var pn = p.getPartName();
               var schema = p.getSchema();
               if (pt == PATH)
                  rc.pathArg(pn, val, schema, p.getSerializer().orElse(partSerializer));
               else if (nn(val)) {
                  if (pt == QUERY)
                     rc.queryArg(pn, val, schema, p.getSerializer().orElse(partSerializer), schema.isSkipIfEmpty());
                  else if (pt == FORMDATA)
                     rc.formDataArg(pn, val, schema, p.getSerializer().orElse(partSerializer), schema.isSkipIfEmpty());
                  else if (pt == HEADER)
                     rc.headerArg(pn, val, schema, p.getSerializer().orElse(partSerializer), schema.isSkipIfEmpty());
                  else /* (pt == HttpPartType.BODY) */
                     rc.content(val, schema);
               }
            }
         }
      });

      // Set the Accept header from the dedicated attribute unless a caller-supplied @Header param already provided one.
      if (ine(effAccept) && ! rc.containsHeader(HEADER_ACCEPT))
         rc.accept(effAccept);

      // Per-call response/read timeout (method-level overrides interface-level) via a per-call RequestConfig.
      var effTimeout = firstNonEmpty(rom.getTimeout(), rm.getTimeout());
      if (ine(effTimeout)) {
         var ms = getDuration(effTimeout);
         if (ms > 0) {
            var base = rc.getConfig();
            var cb = base != null ? RequestConfig.copy(base) : RequestConfig.custom();
            rc.config(cb.setSocketTimeout((int)ms).build());
         }
      }

      return rc;
   }

   /**
    * Executes a remote-proxy call and processes the return value, applying safe automatic retries when the method
    * opts in and all safety gates pass (idempotent verb or {@code retryNonIdempotent}, buffered return mode, and a
    * repeatable body).  Mirrors the next-generation engine's {@code RemoteInvocationHandler.processReturn(...)}.
    */
   @SuppressWarnings({
      "java:S135" // Two continue statements are the two retry triggers (transport failure, retryable status); merging them would obscure the loop
   })
   Object executeRemoteWithRetry(String uri, Serializer serializer, Parser parser, Method method, RemoteOperationMeta rom, RemoteMeta rm, Object[] args) throws Exception {
      var throwOnError = rm.isThrowOnError() || rom.isThrowOnError();
      var ror = rom.getReturns();
      var maxRetries = (isRetryableMode(ror, method.getReturnType()) && isRetryableVerb(rom, rm)) ? effectiveRetries(rom, rm) : 0;

      // Every getRemote() call is policy-covered; the SSRF guard is active unless allowPrivateUrls opts out.
      var allowPrivate = isAllowPrivateUrls() || rm.isAllowPrivateUrls();
      var guardActive = ! allowPrivate;
      if (guardActive && ! ssrfPolicySupported)
         throw new RestCallException(null, null, "%s", ssrfRefusal);

      var attempt = 0;
      while (true) {
         var rc = buildRemoteRequest(uri, serializer, parser, rom, rm, args);
         rc.rethrow(RuntimeException.class);
         rom.forEachException(rc::rethrow);
         // The classic run() throws by default on >=400; the proxy replicates NG's throwIfError() instead, so it
         // always suppresses that generic throw and applies the typed/conditional mapping itself.
         rc.ignoreErrors();
         if (guardActive) {
            var refusal = requestRefusal(rc);
            if (nn(refusal))
               throw new RestCallException(null, null, "%s", refusal);
            // Carried on the request's context, so the guard holds on whichever thread the request is sent.
            rc.ssrfGuard();
         }

         // Non-repeatable body: never retry (resending a consumed stream would corrupt the call).
         var canRetry = maxRetries > 0 && (attempt > 0 || rc.isBodyRepeatable());

         RestResponse res;
         if (guardActive)
            RemoteUrlPolicyState.activate();
         try {
            res = rc.run();
         } catch (SsrfGuardConnectionManager.GuardRefusedException e) {
            // Reported like the other guard refusals (and other transport failures), not as a raw runtime exception.
            throw new RestCallException(null, e, "%s", e.getMessage());
         } catch (RestCallException e) {
            // A transport failure (IOException cause) is retryable; a reconstructed server exception is not
            // caught here (it is not a RestCallException).
            if (canRetry && attempt < maxRetries && e.getCause() instanceof IOException) {
               attempt++;
               backoff(attempt);
               continue;
            }
            Throwable t = e.getCause();
            if (t instanceof RuntimeException t2)
               throw t2;
            if (t instanceof Exception t2) {
               for (var t3 : method.getExceptionTypes())
                  if (t3.isInstance(t2))
                     throw t2;
            }
            throw toRex(e);
         } finally {
            if (guardActive)
               RemoteUrlPolicyState.deactivate();
         }

         if (canRetry && attempt < maxRetries && isRetryableStatus(res.getStatusCode())) {
            res.close();
            attempt++;
            backoff(attempt);
            continue;
         }

         return materializeRemote(res, method, rom, throwOnError);
      }
   }

   /**
    * Materializes the terminal return value from an already-run response, applying the typed-exception /
    * conditional-throw error mapping (mirrors the next-generation engine's {@code throwIfError} +
    * {@code materializeResponse}).
    */
   Object materializeRemote(RestResponse res, Method method, RemoteOperationMeta rom, boolean throwOnError) throws Exception {
      var ror = rom.getReturns();
      var rv = ror.getReturnValue();

      if (rv == RemoteReturn.NONE) {
         res.close();
         return null;
      }
      if (rv == RemoteReturn.STATUS) {
         var sc = res.getStatusCode();
         var rt = method.getReturnType();
         res.close();
         if (rt == Integer.class || rt == int.class)
            return sc;
         if (rt == Boolean.class || rt == boolean.class)
            return sc < 400;
         throw new RestCallException(res, null, "Invalid return type on method annotated with @RemoteOp(returns=RemoteReturn.STATUS).  Only integer and booleans types are valid.");
      }
      if (rv == RemoteReturn.RESPONSE)
         return res;
      if (rv == RemoteReturn.BEAN) {
         throwRemoteError(res, method, throwOnError);
         return res.as(ror.getResponseBeanMeta());
      }
      // BODY (default)
      throwRemoteError(res, method, throwOnError);
      var rt = method.getReturnType();
      Object v = res.getContent().as(ror.getReturnType());
      if (v == null && rt.isPrimitive())
         v = ClassInfo.of(rt).getPrimitiveDefault();
      return v;
   }

   /**
    * Maps an error HTTP status (&ge;400) to a typed exception declared in the method's {@code throws} clause (a
    * {@link org.apache.juneau.http.response.BasicHttpException} subtype whose {@code STATUS_CODE} matches), else
    * conditionally throws a generic exception when {@code throwOnError} is set, else lets the error body flow through
    * as the return value.  Mirrors the next-generation engine's {@code throwIfError(...)}.
    */
   void throwRemoteError(RestResponse res, Method method, boolean throwOnError) throws Exception {
      var sc = res.getStatusCode();
      if (sc < 400)
         return;
      for (var et : method.getExceptionTypes()) {
         if (org.apache.juneau.http.response.BasicHttpException.class.isAssignableFrom(et) && httpStatusCode(et) == sc) {
            var body = res.getContent().asString();
            res.close();
            throw (org.apache.juneau.http.response.BasicHttpException) instantiateHttpType(et, body);
         }
      }
      if (throwOnError) {
         var body = res.getContent().asString();
         res.close();
         throw new org.apache.juneau.http.response.BasicHttpException(sc, body);
      }
      // else: let the error body flow through as the return value (parity with NG throwOnError=false).
   }

   /** Returns the static {@code STATUS_CODE} field of an HTTP response/exception type, or {@code -1} if absent. */
   private static int httpStatusCode(Class<?> c) {
      try {
         return c.getField("STATUS_CODE").getInt(null);
      } catch (ReflectiveOperationException e) {
         return -1;
      }
   }

   /** Instantiates an HTTP response/exception bean, preferring a {@code (String body)} constructor. */
   private static Object instantiateHttpType(Class<?> c, String body) {
      try {
         return newHttpTypeInstance(c, body);
      } catch (ReflectiveOperationException e) {
         throw rex(e, "Could not instantiate HTTP response/exception type %s", c.getName());
      }
   }

   private static Object newHttpTypeInstance(Class<?> c, String body) throws ReflectiveOperationException {
      try {
         return c.getConstructor(String.class).newInstance(body);
      } catch (NoSuchMethodException e) {
         return c.getConstructor().newInstance();
      }
   }

   /** Returns <jk>true</jk> if the return mode/type is a buffered (retryable) shape, not a streaming/wrapper one. */
   private static boolean isRetryableMode(RemoteOperationReturn ror, Class<?> returnType) {
      if (ror.getReturnValue() == RemoteReturn.RESPONSE)
         return false;
      if (ror.isFuture() || ror.isCompletableFuture())
         return false;
      return ! (returnType == InputStream.class || returnType == Reader.class || returnType == Optional.class);
   }

   /** Returns <jk>true</jk> if the verb may auto-retry: idempotent verbs always, POST/PATCH only when opted in. */
   private static boolean isRetryableVerb(RemoteOperationMeta rom, RemoteMeta rm) {
      if (isOneOf(rom.getHttpMethod(), "GET", "PUT", "DELETE", "HEAD"))
         return true;
      return rom.isRetryNonIdempotent() || rm.isRetryNonIdempotent();
   }

   /** Returns the effective retry count: a positive method-level value overrides the interface-level default. */
   private static int effectiveRetries(RemoteOperationMeta rom, RemoteMeta rm) {
      return rom.getRetries() > 0 ? rom.getRetries() : rm.getRetries();
   }

   /** Retryable HTTP statuses: {@code 429} (Too Many Requests) and all {@code 5xx} server errors. */
   private static boolean isRetryableStatus(int statusCode) {
      return statusCode == 429 || statusCode >= 500;
   }

   /** Sleeps a short exponential backoff ({@code 50ms * 2^(attempt-1)}, capped at {@code 1s}) before a retry. */
   private static void backoff(int attempt) {
      try {
         Thread.sleep(Math.min(50L << (attempt - 1), 1000L));
      } catch (InterruptedException e) {
         Thread.currentThread().interrupt();
      }
   }

   ExecutorService getExecutorService() {
      ExecutorService result = executorService.get();
      if (nn(result))
         return result;
      synchronized (this) {
         result = executorService.get();
         if (nn(result))
            return result;
         result = new ThreadPoolExecutor(1, 1, 30, TimeUnit.SECONDS, new ArrayBlockingQueue<>(10));
         executorService.set(result);
         return result;
      }
   }

   <T extends Context> T getInstance(Class<T> c) {
      var o = requestContexts.computeIfAbsent(c, k -> {
         if (Serializer.class.isAssignableFrom(k)) {
            return Serializer.createSerializerBuilder((Class<? extends Serializer>)k).marshallingContext(getMarshallingContext()).build();
         } else if (Parser.class.isAssignableFrom(k)) {
            return Parser.createParserBuilder((Class<? extends Parser>)k).marshallingContext(getMarshallingContext()).build();
         }
         return null;
      });
      return (T)o;
   }

   /*
    * Returns the parser that best matches the specified content type.
    * If no match found or the content type is <jk>null</jk>, returns the parser in the list if it's a list of one.
    * Returns <jk>null</jk> if no parsers are defined.
    */
   Parser getMatchingParser(String mediaType) {
      if (parsers.isEmpty())
         return null;
      if (nn(mediaType)) {
         var p = parsers.getParser(mediaType).orElse(null);
         if (nn(p))
            return p;
      }
      var l = parsers.getParsers();
      return (l.size() == 1 ? l.get(0) : null);
   }

   /*
    * Returns the serializer that best matches the specified content type.
    * If no match found or the content type is <jk>null</jk>, returns the serializer in the list if it's a list of one.
    * Returns <jk>null</jk> if no serializers are defined.
    */
   Serializer getMatchingSerializer(String mediaType) {
      if (serializers.isEmpty())
         return null;
      if (nn(mediaType)) {
         var s = serializers.getSerializer(mediaType).orElse(null);
         if (nn(s))
            return s;
      }
      var l = serializers.getSerializers();
      return (l.size() == 1 ? l.get(0) : null);
   }

   boolean hasParsers() {
      return ! parsers.getParsers().isEmpty();
   }

   boolean hasSerializers() {
      return ! serializers.getSerializers().isEmpty();
   }

   URI toUri(Object x, String rootUrl) throws RestCallException {
      try {
         if (x instanceof URI x2)
            return x2;
         if (x instanceof URL x2)
            return x2.toURI();
         if (x instanceof URIBuilder x2)
            return x2.build();
         var s = x == null ? "" : x.toString();
         if (nn(rootUrl) && ! absUrlPattern.matcher(s).matches()) {
            if (s.isEmpty())
               s = rootUrl;
            else {
               var sb = new StringBuilder(rootUrl);
               if (! s.startsWith("/"))
                  sb.append('/');
               sb.append(s);
               s = sb.toString();
            }
         }
         s = fixUrl(s);
         return new URI(s);
      } catch (URISyntaxException e) {
         throw new RestCallException(null, e, "Invalid URI encountered:  %s", x);  // Shouldn't happen.
      }
   }
}