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

import static org.apache.juneau.commons.utils.IoUtils.*;
import static org.apache.juneau.commons.utils.ObjectUtils.*;
import static org.apache.juneau.commons.utils.Shorts.*;
import static org.apache.juneau.commons.utils.StringUtils.*;
import static org.apache.juneau.commons.utils.ThrowableUtils.*;

import java.io.*;
import java.lang.reflect.*;
import java.nio.charset.*;
import java.util.concurrent.*;
import java.util.regex.*;

import org.apache.http.*;
import org.apache.http.conn.*;
import org.apache.juneau.commons.conversion.*;
import org.apache.juneau.commons.http.*;
import org.apache.juneau.commons.reflect.ConstructorInfo;
import org.apache.juneau.commons.reflect.ExecutableException;
import org.apache.juneau.commons.utils.*;
import org.apache.juneau.http.classic.entity.*;
import org.apache.juneau.http.classic.resource.*;
import org.apache.juneau.marshall.*;
import org.apache.juneau.marshall.collections.*;
import org.apache.juneau.marshall.httppart.*;
import org.apache.juneau.marshall.oapi.*;
import org.apache.juneau.marshall.parser.*;
import org.apache.juneau.marshall.parser.ParseException;
import org.apache.juneau.marshall.stream.*;
import org.apache.juneau.rest.client.classic.assertion.*;
import org.apache.juneau.bct.assertions.*;

/**
 * Represents the body of an HTTP response.
 *
 * <p>
 * An extension of an HttpClient {@link HttpEntity} that provides various support for converting the body to POJOs and
 * other convenience methods.
 *
 * <p>
 * To quickly retrieve a single value from inside a larger JSON document, parse the body into a {@link JsonMap} and use
 * its path-addressing methods &mdash; e.g. <c>getContent().as(JsonMap.<jk>class</jk>).getAt(<jv>path</jv>, <jv>type</jv>)</c>
 * or the RFC 6901 form <c>getContent().as(JsonMap.<jk>class</jk>).at(<jv>pointer</jv>)</c>.
 *
 * <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:S115", // Constants use UPPER_snakeCase convention (e.g., HEADER_ContentType)
   "java:S4144", // Identical methods intentional for different test scenarios
   "resource" // Resource management handled externally
})
public class ResponseContent implements HttpEntity {

   private static final String HEADER_ContentType = "Content-Type";
   private static final String CONTENT_TYPE_TEXT_PLAIN = "text/plain";

   private static final HttpEntity NULL_ENTITY = new HttpEntity() {

      @Override
      public void consumeContent() throws IOException {
         // No-op: Mock implementation - full functionality not required
      }

      @Override
      public InputStream getContent() throws IOException, UnsupportedOperationException { return new ByteArrayInputStream(new byte[0]); }

      @Override
      public Header getContentEncoding() { return ResponseHeader.NULL_HEADER; }

      @Override
      public long getContentLength() { return -1; }

      @Override
      public Header getContentType() { return ResponseHeader.NULL_HEADER; }

      @Override
      public boolean isChunked() { return false; }

      @Override
      public boolean isRepeatable() { return false; }

      @Override
      public boolean isStreaming() { return false; }

      @Override
      public void writeTo(OutputStream outstream) throws IOException {
         // Fail-fast: writeTo() is never legitimately invoked on this sentinel -- pipeTo() and asBytes()/
         // asInputStream() route through getContent()/getContentLength() instead, so a silent no-op here would
         // mask a caller bypassing those paths.
         throw new UnsupportedOperationException("NULL_ENTITY.writeTo() should never be called.");
      }
   };

   private final RestClient client;
   final RestRequest request;
   final RestResponse response;
   private final HttpEntity entity;
   private HttpPartSchema schema;
   private Parser parser;
   private byte[] body;
   private boolean cached;
   boolean isConsumed;

   /**
    * Constructor.
    *
    * @param client The client used to build this request.
    * @param request The request object.
    * @param response The response object.
    * @param parser The parser to use to consume the body.  Can be <jk>null</jk> to use the response's negotiated/default parser.
    */
   public ResponseContent(RestClient client, RestRequest request, RestResponse response, Parser parser) {
      this.client = client;
      this.request = request;
      this.response = response;
      this.parser = parser;
      this.entity = coalesce(response.asHttpResponse().getEntity(), NULL_ENTITY);
   }

   /**
    * Same as {@link #as(Type,Type...)} except optimized for a non-parameterized class.
    *
    * <p>
    * This is the preferred parse method for simple types since you don't need to cast the results.
    *
    * <h5 class='section'>Examples:</h5>
    * <p class='bjava'>
    *    <jc>// Parse into a string.</jc>
    *    String <jv>string</jv> = <jv>client</jv>.get(<jsf>URI</jsf>).run().getContent().as(String.<jk>class</jk>);
    *
    *    <jc>// Parse into a bean.</jc>
    *    MyBean <jv>bean</jv> = <jv>client</jv>.get(<jsf>URI</jsf>).run().getContent().as(MyBean.<jk>class</jk>);
    *
    *    <jc>// Parse into a bean array.</jc>
    *    MyBean[] <jv>beanArray</jv> = <jv>client</jv>.get(<jsf>URI</jsf>).run().getContent().as(MyBean[].<jk>class</jk>);
    *
    *    <jc>// Parse into a linked-list of objects.</jc>
    *    List <jv>list</jv> = <jv>client</jv>.get(<jsf>URI</jsf>).run().getContent().as(LinkedList.<jk>class</jk>);
    *
    *    <jc>// Parse into a map of object keys/values.</jc>
    *    Map <jv>map</jv> = <jv>client</jv>.get(<jsf>URI</jsf>).run().getContent().as(TreeMap.<jk>class</jk>);
    * </p>
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>
    *       You can also specify any of the following types:
    *       <ul class='compact'>
    *          <li>{@link ResponseContent}/{@link HttpEntity} - Returns access to this object.
    *          <li>{@link Reader} - Returns access to the raw reader of the response.
    *          <li>{@link InputStream} - Returns access to the raw input stream of the response.
    *          <li>{@link HttpResource} - Response will be converted to a {@link StreamResource}.
    *          <li>Any type that takes in an {@link HttpResponse} object.
    *       </ul>
    *    <li class='note'>
    *    If {@link #cache()} or {@link RestResponse#cacheContent()} has been called, this method can be can be called multiple times and/or combined with
    *    other methods that retrieve the content of the response.  Otherwise a {@link RestCallException}
    *    with an inner {@link IllegalStateException} will be thrown.
    *    <li class='note'>
    *       The input stream is automatically closed after this call.
    * </ul>
    *
    * @param <T>
    *    The class type of the object being created.
    *    See {@link #as(Type,Type...)} for details.
    * @param type The object type to create.
    * @return The parsed object.
    * @throws RestCallException
    *    If the input contains a syntax error or is malformed, or is not valid for the specified type, or if a connection
    *    error occurred.
    */
   public <T> T as(Class<T> type) throws RestCallException {
      return as(getClassMeta(type));
   }

   /**
    * Same as {@link #as(Class)} except allows you to predefine complex data types using the {@link ClassMeta} API.
    *
    * <h5 class='section'>Examples:</h5>
    * <p class='bjava'>
    *    MarshallingContext <jv>marshallingContext</jv> = MarshallingContext.<jsf>DEFAULT</jsf>;
    *
    *    <jc>// Parse into a linked-list of strings.</jc>
    * ClassMeta&lt;List&lt;String&gt;&gt; <jv>cm1</jv> = <jv>marshallingContext</jv>.getClassMeta(LinkedList.<jk>class</jk>, String.<jk>class</jk>);
    *    List&lt;String&gt; <jv>list1</jv> = <jv>client</jv>.get(<jsf>URI</jsf>).run().getContent().as(<jv>cm1</jv>);
    *
    *    <jc>// Parse into a linked-list of beans.</jc>
    * ClassMeta&lt;List&lt;String&gt;&gt; <jv>cm2</jv> = <jv>marshallingContext</jv>.getClassMeta(LinkedList.<jk>class</jk>, MyBean.<jk>class</jk>);
    *    List&lt;MyBean&gt; <jv>list2</jv> = <jv>client</jv>.get(<jsf>URI</jsf>).run().getContent().as(<jv>cm2</jv>);
    *
    *    <jc>// Parse into a linked-list of linked-lists of strings.</jc>
    * ClassMeta&lt;List&lt;String&gt;&gt; <jv>cm3</jv> = <jv>marshallingContext</jv>.getClassMeta(LinkedList.<jk>class</jk>, LinkedList.<jk>class</jk>, String.<jk>class</jk>);
    *    List&lt;List&lt;String&gt;&gt; <jv>list3</jv> = <jv>client</jv>.get(<jsf>URI</jsf>).run().getContent().as(<jv>cm3</jv>);
    *
    *    <jc>// Parse into a map of string keys/values.</jc>
    * ClassMeta&lt;List&lt;String&gt;&gt; <jv>cm4</jv> = <jv>marshallingContext</jv>.getClassMeta(TreeMap.<jk>class</jk>, String.<jk>class</jk>, String.<jk>class</jk>);
    *    Map&lt;String,String&gt; <jv>map4</jv> = <jv>client</jv>.get(<jsf>URI</jsf>).run().getContent().as(<jv>cm4</jv>);
    *
    *    <jc>// Parse into a map containing string keys and values of lists containing beans.</jc>
    * ClassMeta&lt;List&lt;String&gt;&gt; <jv>cm5</jv> = <jv>marshallingContext</jv>.getClassMeta(TreeMap.<jk>class</jk>, String.<jk>class</jk>, List.<jk>class</jk>, MyBean.<jk>class</jk>);
    *    Map&lt;String,List&lt;MyBean&gt;&gt; <jv>map5</jv> = <jv>client</jv>.get(<jsf>URI</jsf>).run().getContent().as(<jv>cm5</jv>);
    * </p>
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>
    *    If {@link #cache()} or {@link RestResponse#cacheContent()} has been called, this method can be can be called multiple times and/or combined with
    *    other methods that retrieve the content of the response.  Otherwise a {@link RestCallException}
    *    with an inner {@link IllegalStateException} will be thrown.
    *    <li class='note'>
    *       The input stream is automatically closed after this call.
    * </ul>
    *
    * @param <T> The class type of the object to create.
    * @param type The object type to create.
    * @return The parsed object.
    * @throws RestCallException
    *    <ul>
    *       <li>If the input contains a syntax error or is malformed, or is not valid for the specified type.
    *       <li>If a connection error occurred.
    *    </ul>
    * @see MarshallingSession#getClassMeta(Class) for argument syntax for maps and collections.
    */
   @SuppressWarnings({
      "java:S3776", // Cognitive complexity acceptable for this specific logic
      "unchecked" // Type erasure requires unchecked casts in content parsing
   })
   public <T> T as(ClassMeta<T> type) throws RestCallException {
      try {
         if (type.is(ResponseContent.class) || type.is(HttpEntity.class))
            return (T)this;

         if (type.is(Reader.class))
            return (T)asReader();

         if (type.is(InputStream.class))
            return (T)asInputStream();

         if (type.isChildOf(RecordReader.class) || type.is(RecordReader.class))
            return (T) asCursor(type);

         if (type.is(HttpResponse.class))
            return (T)response;

         if (type.is(HttpResource.class) || type.is(BasicResource.class))
            type = (ClassMeta<T>)getClassMeta(StreamResource.class);

         var responseCtor = type.getPublicConstructor(x -> x.hasParameterTypes(HttpResponse.class));
         if (responseCtor.isPresent())
            return construct(responseCtor.get(), type);

         var ct = firstNonEmpty(response.getHeader(HEADER_ContentType).orElse(CONTENT_TYPE_TEXT_PLAIN));

         if (parser == null)
            parser = client.getMatchingParser(ct);

         var mt = MediaType.of(ct);

         if ((parser == null || (mt.toString().contains(CONTENT_TYPE_TEXT_PLAIN) && ! parser.canHandle(ct))) && type.hasStringMutater())
            return BasicConverter.INSTANCE.to(asString(), type.inner());

         if (nn(parser))
            return parse(type, mt);

         if (type.hasReaderMutater())
            return BasicConverter.INSTANCE.to(asReader(), type.inner());

         if (type.hasInputStreamMutater())
            return BasicConverter.INSTANCE.to(asInputStream(), type.inner());

         ct = response.getStringHeader(HEADER_ContentType).orElse(null);

         if (ct == null && client.hasParsers())
            throw new ParseException("Content-Type not specified in response header.  Cannot find appropriate parser.");

         throw new ParseException("Unsupported media-type in request header 'Content-Type': '%s'", ct);

      } catch (ParseException | IOException e) {
         response.close();
         throw new RestCallException(response, e, "Could not parse response body.");
      }
   }

   /**
    * Constructs the target type from the response through its {@code (HttpResponse)} constructor.
    */
   private <T> T construct(ConstructorInfo ctor, ClassMeta<T> type) throws RestCallException {
      try {
         return ctor.newInstance(response);
      } catch (ExecutableException e) {
         // The (HttpResponse) constructor rejected the response (e.g. the status code does not match the class).
         response.close();
         throw new RestCallException(response, e.getCause() == null ? e : e.getCause(), "Could not construct %s from response.", type.inner().getName());
      }
   }

   /**
    * Parses the response body with the matched parser.
    */
   @SuppressWarnings({
      "unchecked" // Type erasure requires unchecked casts in content parsing
   })
   private <T> T parse(ClassMeta<T> type, MediaType mt) throws ParseException, IOException {
      try (Closeable in = parser.isReaderParser() ? asReader() : asInputStream()) {

         // @formatter:off
         T t = parser
            .createSession()
            .properties(JsonMap.create().inner(request.getSessionProperties()))
            .locale(response.getLocale())
            .mediaType(mt)
            .schema(schema)
            .build()
            .read(in, type);
         // @formatter:on

         // Some HTTP responses have no body, so try to create these beans if they've got no-arg constructors.
         if (t == null && ! type.is(String.class)) {
            var result2 = type.getPublicConstructor(cons -> cons.getParameterCount() == 0).map(c -> safe(() -> (T)c.newInstance()));
            if (result2.isPresent())
               return result2.get();
         }

         return t;
      }
   }

   /**
    * Resolves a cursor return type ({@link RecordReader} / {@link TokenReader} or any subtype)
    * by negotiating the response Content-Type to a parser and calling its
    * {@code readRecords(...)} / {@code readTokens(...)} factory.
    *
    * <p>
    * Implements two-layer resolution: the declared type filters eligible parsers (a concrete
    * subtype like {@code JsonlTokenReader} is only assignable from a parser that produces it);
    * the response's Content-Type negotiates within that filter.  Capability is detected via
    * {@code instanceof} against the {@link RecordReadable} / {@link TokenReadable} role interfaces.
    *
    * <p>
    * The caller owns the returned cursor's lifecycle — wrap it in try-with-resources.
    *
    * @param type The declared parameter / return type (must be {@link RecordReader} or a subtype).
    * @return A new cursor.
    * @throws RestCallException If no parser produces a cursor assignable to the declared type
    *    for the response's Content-Type, or if the matched parser does not implement the requested
    *    cursor role interface.
    */
   private Object asCursor(ClassMeta<?> type) throws RestCallException {
      try {
         var ct = firstNonEmpty(response.getHeader(HEADER_ContentType).orElse(CONTENT_TYPE_TEXT_PLAIN));
         var matchedParser = parser != null ? parser : client.getMatchingParser(ct);
         if (matchedParser == null)
            throw new RestCallException(response, null,
               "No registered parser matches Content-Type '%s' for cursor return type '%s'.",
               ct, type.inner().getName());

         var isToken = type.isChildOf(TokenReader.class) || type.is(TokenReader.class);
         var supported = isToken ? matchedParser instanceof TokenReadable : matchedParser instanceof RecordReadable;
         if (!supported)
            throw new RestCallException(response, null,
               "Parser '%s' does not support the %s surface.",
               matchedParser.getClass().getName(),
               isToken ? "token-reader" : "record-reader");

         Object input = matchedParser.isReaderParser() ? asReader() : asInputStream();
         Object cursor = isToken
            ? ((TokenReadable) matchedParser).readTokens(input)
            : ((RecordReadable) matchedParser).readRecords(input);

         if (!type.inner().isInstance(cursor))
            throw new RestCallException(response, null,
               "Parser '%s' produced cursor type '%s' which is not assignable to the declared type '%s'.",
               matchedParser.getClass().getName(),
               cursor == null ? "null" : cursor.getClass().getName(),
               type.inner().getName());

         return cursor;
      } catch (RestCallException e) {
         throw e;
      } catch (IOException e) {
         throw new RestCallException(response, e, "Could not open cursor over response body.");
      }
   }

   /**
    * Parses HTTP body into the specified object type.
    *
    * <p>
    * The type can be a simple type (e.g. beans, strings, numbers) or parameterized type (collections/maps).
    *
    * <h5 class='section'>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>
    * <c>Collection</c> classes are assumed to be followed by zero or one objects indicating the element type.
    *
    * <p>
    * <c>Map</c> classes are assumed to be followed by zero or two meta objects indicating the key and value types.
    *
    * <p>
    * The array can be arbitrarily long to indicate arbitrarily complex data structures.
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>
    *       Use the {@link #as(Class)} method instead if you don't need a parameterized map/collection.
    *    <li class='note'>
    *       You can also specify any of the following types:
    *       <ul class='compact'>
    *          <li>{@link ResponseContent}/{@link HttpEntity} - Returns access to this object.
    *          <li>{@link Reader} - Returns access to the raw reader of the response.
    *          <li>{@link InputStream} - Returns access to the raw input stream of the response.
    *          <li>{@link HttpResource} - Response will be converted to a {@link StreamResource}.
    *          <li>Any type that takes in an {@link HttpResponse} object.
    *       </ul>
    *    <li class='note'>
    *    If {@link #cache()} or {@link RestResponse#cacheContent()} has been called, this method can be can be called multiple times and/or combined with
    *    other methods that retrieve the content of the response.  Otherwise a {@link RestCallException}
    *    with an inner {@link IllegalStateException} will be thrown.
    *    <li class='note'>
    *       The input stream is automatically closed after this call.
    * </ul>
    *
    * @param <T> The class type of the object to create.
    * @param type
    *    The object type to create.
    *    <br>Can be any of the following: {@link ClassMeta}, {@link Class}, {@link ParameterizedType}, {@link GenericArrayType}
    * @param args
    *    The type arguments of the class if it's a collection or map.
    *    <br>Can be any of the following: {@link ClassMeta}, {@link Class}, {@link ParameterizedType}, {@link GenericArrayType}
    *    <br>Ignored if the main type is not a map or collection.
    * @return The parsed object.
    * @throws RestCallException
    *    <ul>
    *       <li>If the input contains a syntax error or is malformed, or is not valid for the specified type.
    *       <li>If a connection error occurred.
    *    </ul>
    * @see MarshallingSession#getClassMeta(Class) for argument syntax for maps and collections.
    */
   public <T> T as(Type type, Type...args) throws RestCallException {
      return as(getClassMeta(type, args));
   }

   /**
    * Same as {@link #asString()} but truncates the string to the specified length.
    *
    * <p>
    * If truncation occurs, the string will be suffixed with <js>"..."</js>.
    *
    * @param length The max length of the returned string.
    * @return The truncated string.
    * @throws RestCallException If a problem occurred trying to read from the reader.
    */
   public String asAbbreviatedString(int length) throws RestCallException {
      return StringUtils.abbreviate(asString(), length);
   }

   /**
    * Returns the HTTP response message body as a byte array.
    *
    *    The HTTP response message body as a byte array, never <jk>null</jk>.
    *    <br>For responses without a body(e.g. HTTP 204), returns an empty array.
    *
    * @return The HTTP response body as a byte array.
    * @throws RestCallException If an exception occurred.
    */
   public byte[] asBytes() throws RestCallException {
      if (body == null) {
         try {
            if (entity instanceof BasicHttpEntity<?> entity2) {
               body = entity2.asBytes();
            } else {
               body = readBytes(entity.getContent());
            }
         } catch (IOException e) {
            throw new RestCallException(response, e, "Could not read response body.");
         } finally {
            response.close();
         }
      }
      return body;
   }

   /**
    * Same as {@link #as(Class)} but allows you to run the call asynchronously.
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>
    *    If {@link #cache()} or {@link RestResponse#cacheContent()} has been called, this method can be can be called multiple times and/or combined with
    *    other methods that retrieve the content of the response.  Otherwise a {@link RestCallException}
    *    with an inner {@link IllegalStateException} will be thrown.
    *    <li class='note'>
    *       The input stream is automatically closed after the execution of the future.
    * </ul>
    *
    * @param <T> The class type of the object being created.
    * @param type The object type to create.
    * @return The future object.
    * @throws RestCallException If the executor service was not defined.
    * @see
    *    RestClient.Builder#executorService(ExecutorService, boolean) for defining the executor service for creating
    *    Future instances.
    */
   public <T> Future<T> asFuture(Class<T> type) throws RestCallException {
      return client.getExecutorService().submit(() -> as(type));
   }

   /**
    * Same as {@link #as(ClassMeta)} but allows you to run the call asynchronously.
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>
    *    If {@link #cache()} or {@link RestResponse#cacheContent()} has been called, this method can be can be called multiple times and/or combined with
    *    other methods that retrieve the content of the response.  Otherwise a {@link RestCallException}
    *    with an inner {@link IllegalStateException} will be thrown.
    *    <li class='note'>
    *       The input stream is automatically closed after the execution of the future.
    * </ul>
    *
    * @param <T>
    *    The class type of the object being created.
    *    See {@link #as(Type, Type...)} for details.
    * @param type The object type to create.
    * @return The future object.
    * @throws RestCallException If the executor service was not defined.
    * @see
    *    RestClient.Builder#executorService(ExecutorService, boolean) for defining the executor service for creating
    *    Future instances.
    */
   public <T> Future<T> asFuture(ClassMeta<T> type) throws RestCallException {
      return client.getExecutorService().submit(() -> as(type));
   }

   /**
    * Same as {@link #as(Type,Type...)} but allows you to run the call asynchronously.
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>
    *    If {@link #cache()} or {@link RestResponse#cacheContent()} has been called, this method can be can be called multiple times and/or combined with
    *    other methods that retrieve the content of the response.  Otherwise a {@link RestCallException}
    *    with an inner {@link IllegalStateException} will be thrown.
    *    <li class='note'>
    *       The input stream is automatically closed after the execution of the future.
    * </ul>
    *
    * @param <T>
    *    The class type of the object being created.
    *    See {@link #as(Type, Type...)} for details.
    * @param type
    *    The object type to create.
    *    <br>Can be any of the following: {@link ClassMeta}, {@link Class}, {@link ParameterizedType}, {@link GenericArrayType}
    * @param args
    *    The type arguments of the class if it's a collection or map.
    *    <br>Can be any of the following: {@link ClassMeta}, {@link Class}, {@link ParameterizedType}, {@link GenericArrayType}
    *    <br>Ignored if the main type is not a map or collection.
    * @return The future object.
    * @throws RestCallException If the executor service was not defined.
    * @see
    *    RestClient.Builder#executorService(ExecutorService, boolean) for defining the executor service for creating
    *    Future instances.
    */
   public <T> Future<T> asFuture(Type type, Type...args) throws RestCallException {
      return client.getExecutorService().submit(() -> as(type, args));
   }

   /**
    * Returns the HTTP body content as a simple hexadecimal character string.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bcode'>
    *    0123456789ABCDEF
    * </p>
    *
    * @return The incoming input from the connection as a plain string.
    * @throws RestCallException If a problem occurred trying to read from the reader.
    */
   public String asHex() throws RestCallException {
      return toHex(asBytes());
   }

   /**
    * Returns the HTTP response message body as an input stream.
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>
    *       Once this input stream is exhausted, it will automatically be closed.
    *  <li class='note'>
    *    This method can be called multiple times if {@link #cache()} has been called.
    *  <li class='note'>
    *    Calling this method multiple times without caching enabled will cause a {@link RestCallException}
    *    with an inner {@link IllegalStateException} to be thrown.
    * </ul>
    *
    * @return
    *    The HTTP response message body input stream, never <jk>null</jk>.
    *    <br>For responses without a body(e.g. HTTP 204), returns an empty stream.
    * @throws IOException If a stream or illegal state exception was thrown.
    */
   public InputStream asInputStream() throws IOException {
      try {
         if (nn(body))
            return new ByteArrayInputStream(body);

         if (cached) {
            body = readBytes(entity.getContent());
            response.close();
            return new ByteArrayInputStream(body);
         }

         if (isConsumed && ! entity.isRepeatable())
            throw new IllegalStateException("Method cannot be called.  Response has already been consumed.  Consider using the RestResponse.cacheBody() method.");

         HttpEntity e = response.asHttpResponse().getEntity();
         InputStream is = e == null ? new ByteArrayInputStream(new byte[0]) : e.getContent();

         is = new EofSensorInputStream(is, new EofSensorWatcher() {
            @Override
            public boolean eofDetected(InputStream wrapped) throws IOException {
               response.close();
               return true;
            }

            @Override
            public boolean streamAbort(InputStream wrapped) throws IOException {
               response.close();
               return true;
            }

            @Override
            public boolean streamClosed(InputStream wrapped) throws IOException {
               response.close();
               return true;
            }
         });

         isConsumed = true;

         return is;
      } catch (UnsupportedOperationException e) {
         throw ioex(e);
      }
   }

   /**
    * Converts the contents of the response body to a string and then matches the specified pattern against it.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    <jc>// Parse response using a regular expression.</jc>
    *    Matcher <jv>matcher</jv> = <jv>client</jv>
    *       .get(<jsf>URI</jsf>)
    *       .run()
    *       .getContent().asMatcher(Pattern.<jsm>compile</jsm>(<js>"foo=(.*)"</js>));
    *
    *    <jk>if</jk> (<jv>matcher</jv>.matches()) {
    *       String <jv>foo</jv> = <jv>matcher</jv>.group(1);
    *    }
    * </p>
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>
    *       If no charset was found on the <code>Content-Type</code> response header, <js>"UTF-8"</js> is assumed.
    *  <li class='note'>
    *    This method automatically calls {@link #cache()} so that the body can be retrieved multiple times.
    *    <li class='note'>
    *       The input stream is automatically closed after this call.
    * </ul>
    *
    * @param pattern The regular expression pattern to match.
    * @return The matcher.
    * @throws RestCallException If a connection error occurred.
    */
   public Matcher asMatcher(Pattern pattern) throws RestCallException {
      return pattern.matcher(asString());
   }

   /**
    * Converts the contents of the response body to a string and then matches the specified pattern against it.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    <jc>// Parse response using a regular expression.</jc>
    *    Matcher <jv>matcher</jv> = <jv>client</jv>
    *       .get(<jsf>URI</jsf>)
    *       .run()
    *       .getContent().asMatcher(<js>"foo=(.*)"</js>);
    *
    *    <jk>if</jk> (<jv>matcher</jv>.matches()) {
    *       String <jv>foo</jv> = <jv>matcher</jv>.group(1);
    *    }
    * </p>
    *
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>
    *       If no charset was found on the <code>Content-Type</code> response header, <js>"UTF-8"</js> is assumed.
    *  <li class='note'>
    *    If {@link #cache()} or {@link RestResponse#cacheContent()} has been called, this method can be can be called multiple times and/or combined with
    *    other methods that retrieve the content of the response.  Otherwise a {@link RestCallException}
    *    with an inner {@link IllegalStateException} will be thrown.
    *    <li class='note'>
    *       The input stream is automatically closed after this call.
    * </ul>
    *
    * @param regex The regular expression pattern to match.
    * @return The matcher.
    * @throws RestCallException If a connection error occurred.
    */
   public Matcher asMatcher(String regex) throws RestCallException {
      return asMatcher(regex, 0);
   }

   /**
    * Converts the contents of the response body to a string and then matches the specified pattern against it.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bjava'>
    *    <jc>// Parse response using a regular expression.</jc>
    *    Matcher <jv>matcher</jv> = <jv>client</jv>
    *       .get(<jsf>URI</jsf>)
    *       .run()
    *       .getContent().asMatcher(<js>"foo=(.*)"</js>, <jsf>MULTILINE</jsf> &amp; <jsf>CASE_INSENSITIVE</jsf>);
    *
    *    <jk>if</jk> (<jv>matcher</jv>.matches()) {
    *       String <jv>foo</jv> = <jv>matcher</jv>.group(1);
    *    }
    * </p>
    *
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>
    *       If no charset was found on the <code>Content-Type</code> response header, <js>"UTF-8"</js> is assumed.
    *  <li class='note'>
    *    If {@link #cache()} or {@link RestResponse#cacheContent()} has been called, this method can be can be called multiple times and/or combined with
    *    other methods that retrieve the content of the response.  Otherwise a {@link RestCallException}
    *    with an inner {@link IllegalStateException} will be thrown.
    *    <li class='note'>
    *       The input stream is automatically closed after this call.
    * </ul>
    *
    * @param regex The regular expression pattern to match.
    * @param flags Pattern match flags.  See {@link Pattern#compile(String, int)}.
    * @return The matcher.
    * @throws RestCallException If a connection error occurred.
    */
   public Matcher asMatcher(String regex, int flags) throws RestCallException {
      return asMatcher(Pattern.compile(regex, flags));
   }

   /**
    * Returns the HTTP response message body as a reader based on the charset on the <code>Content-Type</code> response header.
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>
    *       If no charset was found on the <code>Content-Type</code> response header, <js>"UTF-8"</js> is assumed.
    *    <li class='note'>
    *       Once this input stream is exhausted, it will automatically be closed.
    *  <li class='note'>
    *    This method can be called multiple times if {@link #cache()} has been called.
    *  <li class='note'>
    *    Calling this method multiple times without caching enabled will cause a {@link RestCallException}
    *    with an inner {@link IllegalStateException} to be thrown.
    * </ul>
    *
    * @return
    *    The HTTP response message body reader, never <jk>null</jk>.
    *    <br>For responses without a body(e.g. HTTP 204), returns an empty reader.
    * @throws IOException If an exception occurred.
    */
   public Reader asReader() throws IOException {

      // Figure out what the charset of the response is.
      String cs = null;
      var ct = getContentType().orElse(null);

      // First look for "charset=" in Content-Type header of response.
      if (nn(ct) && ct.contains("charset="))
         cs = ct.substring(ct.indexOf("charset=") + 8).trim();

      return asReader(cs == null ? UTF8 : Charset.forName(cs));
   }

   /**
    * Returns the HTTP response message body as a reader using the specified charset.
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>
    *       Once this input stream is exhausted, it will automatically be closed.
    *  <li class='note'>
    *    This method can be called multiple times if {@link #cache()} has been called.
    *  <li class='note'>
    *    Calling this method multiple times without caching enabled will cause a {@link RestCallException}
    *    with an inner {@link IllegalStateException} to be thrown.
    * </ul>
    *
    * @param charset
    *    The charset to use for the reader.
    *    <br>If <jk>null</jk>, <js>"UTF-8"</js> is used.
    * @return
    *    The HTTP response message body reader, never <jk>null</jk>.
    *    <br>For responses without a body(e.g. HTTP 204), returns an empty reader.
    * @throws IOException If an exception occurred.
    */
   public Reader asReader(Charset charset) throws IOException {
      return new InputStreamReader(asInputStream(), charset == null ? UTF8 : charset);
   }

   /**
    * Shortcut for calling <c>assertValue().asBytes()</c>.
    *
    * @return A new fluent assertion.
    */
   public FluentByteArrayAssertion<ResponseContent> assertBytes() {
      return new FluentResponseBodyAssertion<>(this, this).asBytes();
   }

   /**
    * Shortcut for calling <c>assertValue().as(<jv>type</jv>)</c>.
    *
    * @param <T> The object type to create.
    * @param type The object type to create.
    * @return A new fluent assertion.
    */
   public <T> FluentAnyAssertion<T,ResponseContent> assertObject(Class<T> type) {
      return new FluentResponseBodyAssertion<>(this, this).as(type);
   }

   /**
    * Shortcut for calling <c>assertValue().as(<jv>type</jv>, <jv>args</jv>)</c>.
    *
    * @param type The object type to create.
    * @param args Optional type arguments.
    * @return A new fluent assertion.
    */
   public FluentAnyAssertion<Object,ResponseContent> assertObject(Type type, Type...args) {
      return new FluentResponseBodyAssertion<>(this, this).as(type, args);
   }

   /**
    * Shortcut for calling <c>assertValue().asString()</c>.
    *
    * @return A new fluent assertion.
    */
   public FluentStringAssertion<ResponseContent> assertString() {
      return new FluentResponseBodyAssertion<>(this, this).asString();
   }

   /**
    * Provides the ability to perform fluent-style assertions on this response body.
    *
    * <p>
    * This method is called directly from the {@link RestResponse#assertContent()} method to instantiate a fluent assertions object.
    *
    * <h5 class='section'>Examples:</h5>
    * <p class='bjava'>
    *    <jc>// Validates the response body equals the text "OK".</jc>
    *    <jv>client</jv>
    *       .get(<jsf>URI</jsf>)
    *       .run()
    *       .getContent().assertValue().equals(<js>"OK"</js>);
    *
    *    <jc>// Validates the response body contains the text "OK".</jc>
    *    <jv>client</jv>
    *       .get(<jsf>URI</jsf>)
    *       .run()
    *       .getContent().assertValue().contains(<js>"OK"</js>);
    *
    *    <jc>// Validates the response body passes a predicate test.</jc>
    *    <jv>client</jv>
    *       .get(<jsf>URI</jsf>)
    *       .run()
    *       .getContent().assertValue().is(<jv>x</jv> -&gt; <jv>x</jv>.contains(<js>"OK"</js>));
    *
    *    <jc>// Validates the response body matches a regular expression.</jc>
    *    <jv>client</jv>
    *       .get(<jsf>URI</jsf>)
    *       .run()
    *       .getContent().assertValue().isPattern(<js>".*OK.*"</js>);
    *
    *    <jc>// Validates the response body matches a regular expression using regex flags.</jc>
    *    <jv>client</jv>
    *       .get(<jsf>URI</jsf>)
    *       .run()
    *       .getContent().assertValue().isPattern(<js>".*OK.*"</js>,  <jsf>MULTILINE</jsf> &amp; <jsf>CASE_INSENSITIVE</jsf>);
    *
    *    <jc>// Validates the response body matches a regular expression in the form of an existing Pattern.</jc>
    *    Pattern <jv>pattern</jv> = Pattern.<jsm>compile</jsm>(<js>".*OK.*"</js>);
    *    <jv>client</jv>
    *       .get(<jsf>URI</jsf>)
    *       .run()
    *       .getContent().assertValue().isPattern(<jv>pattern</jv>);
    * </p>
    *
    * <p>
    * The assertion test returns the original response object allowing you to chain multiple requests like so:
    * <p class='bjava'>
    *    <jc>// Validates the response body matches a regular expression.</jc>
    *    MyBean <jv>bean</jv> = <jv>client</jv>
    *       .get(<jsf>URI</jsf>)
    *       .run()
    *       .getContent().assertValue().isPattern(<js>".*OK.*"</js>);
    *       .getContent().assertValue().isNotPattern(<js>".*ERROR.*"</js>)
    *       .getContent().as(MyBean.<jk>class</jk>);
    * </p>
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>
    *       If no charset was found on the <code>Content-Type</code> response header, <js>"UTF-8"</js> is assumed.
    *  <li class='note'>
    *    This method automatically calls {@link #cache()} so that the body can be retrieved multiple times.
    *    <li class='note'>
    *       The input stream is automatically closed after this call.
    * </ul>
    *
    * @return A new fluent assertion object.
    */
   public FluentResponseBodyAssertion<ResponseContent> assertValue() {
      return new FluentResponseBodyAssertion<>(this, this);
   }

   /**
    * Returns the HTTP body content as a simple space-delimited hexadecimal character string.
    *
    * <h5 class='section'>Example:</h5>
    * <p class='bcode'>
    *    01 23 45 67 89 AB CD EF
    * </p>
    *
    * @return The incoming input from the connection as a plain string.
    * @throws RestCallException If a problem occurred trying to read from the reader.
    */
   public String asSpacedHex() throws RestCallException {
      return toSpacedHex(asBytes());
   }

   /**
    * Returns the contents of this body as a string.
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>
    *       If no charset was found on the <code>Content-Type</code> response header, <js>"UTF-8"</js> is assumed.
    *  <li class='note'>
    *    This method automatically calls {@link #cache()} so that the body can be retrieved multiple times.
    *    <li class='note'>
    *       The input stream is automatically closed after this call.
    * </ul>
    *
    * @return The response as a string.
    * @throws RestCallException
    *    <ul>
    *       <li>If the input contains a syntax error or is malformed, or is not valid for the specified type.
    *       <li>If a connection error occurred.
    *    </ul>
    */
   public String asString() throws RestCallException {
      cache();
      try (Reader r = asReader()) {
         return read(r);
      } catch (IOException e) {
         response.close();
         throw new RestCallException(response, e, "Could not read response body.");
      }
   }

   /**
    * Same as {@link #asString()} but allows you to run the call asynchronously.
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>
    *       If no charset was found on the <code>Content-Type</code> response header, <js>"UTF-8"</js> is assumed.
    *  <li class='note'>
    *    This method automatically calls {@link #cache()} so that the body can be retrieved multiple times.
    *    <li class='note'>
    *       The input stream is automatically closed after this call.
    * </ul>
    *
    * @return The future object.
    * @throws RestCallException If the executor service was not defined.
    * @see
    *    RestClient.Builder#executorService(ExecutorService, boolean) for defining the executor service for creating
    *    Future instances.
    */
   public Future<String> asStringFuture() throws RestCallException {
      return client.getExecutorService().submit(this::asString);
   }

   /**
    * Causes the contents of the response body to be stored so that it can be repeatedly read.
    *
    * <p>
    * Calling this method allows methods that read the response body to be called multiple times.
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>
    *       Multiple calls to this method are ignored.
    * </ul>
    *
    * @return This object.
    */
   public ResponseContent cache() {
      this.cached = true;
      return this;
   }

   /**
    * This method is called to indicate that the content of this entity is no longer required.
    *
    * <p>
    * This method is of particular importance for entities being received from a connection.
    * <br>The entity needs to be consumed completely in order to re-use the connection with keep-alive.
    *
    * @throws IOException If an I/O error occurs.
    * @deprecated Use standard java convention to ensure resource deallocation by calling {@link InputStream#close()} on
    * the input stream returned by {@link #getContent()}
    */
   @Override /* Overridden from HttpEntity */
   @Deprecated(since = "10.0", forRemoval = true)
   @SuppressWarnings({
      "java:S1133" // Intentional deprecation retained for backward compatibility until the documented removal; the reminder is not actionable now.
   })
   public void consumeContent() throws IOException {
      entity.consumeContent();
   }

   /**
    * Returns a content stream of the entity.
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>This method is equivalent to {@link #asInputStream()} which is the preferred method for fluent-style coding.
    *    <li class='note'>This input stream will auto-close once the end of stream has been reached.
    *    <li class='note'>It is up to the caller to properly close this stream if not fully consumed.
    *    <li class='note'>This method can be called multiple times if the entity is repeatable or the cache flag is set on this object.
    *    <li class='note'>Calling this method multiple times on a non-repeatable or cached body will throw a {@link IllegalStateException}.
    *       Note that this is different from the HttpClient specs for this method.
    * </ul>
    *
    * @return Content stream of the entity.
    */
   @Override /* Overridden from HttpEntity */
   public InputStream getContent() throws IOException, UnsupportedOperationException { return asInputStream(); }

   /**
    * Obtains the Content-Encoding header, if known.
    *
    * <p>
    * This is the header that should be used when sending the entity, or the one that was received with the entity.
    * <br>Wrapping entities that modify the content encoding should adjust this header accordingly.
    *
    * @return The <c>Content-Encoding</c> header for this entity.  Never <jk>null</jk>, but wraps a <jk>null</jk> value if the content encoding is unknown.
    */
   @Override /* Overridden from HttpEntity */
   public ResponseHeader getContentEncoding() { return new ResponseHeader("Content-Encoding", request, response, entity.getContentEncoding()); }

   /**
    * Tells the length of the content, if known.
    *
    * @return
    *    The number of bytes of the content, or a negative number if unknown.
    *    <br>If the content length is known but exceeds {@link Long#MAX_VALUE}, a negative number is returned.
    */
   @Override /* Overridden from HttpEntity */
   public long getContentLength() { return nn(body) ? body.length : entity.getContentLength(); }

   /**
    * Obtains the <c>Content-Type</c> header, if known.
    *
    * <p>
    * This is the header that should be used when sending the entity, or the one that was received with the entity.
    * It can include a charset attribute.
    *
    * @return The <c>Content-Type</c> header for this entity.  Never <jk>null</jk>, but wraps a <jk>null</jk> value if the content type is unknown.
    */
   @Override /* Overridden from HttpEntity */
   public ResponseHeader getContentType() { return new ResponseHeader(HEADER_ContentType, request, response, entity.getContentType()); }

   /**
    * Tells about chunked encoding for this entity.
    *
    * <p>
    * The primary purpose of this method is to indicate whether chunked encoding should be used when the entity is sent.
    * <br>For entities that are received, it can also indicate whether the entity was received with chunked encoding.
    *
    * <p>
    * The behavior of wrapping entities is implementation dependent, but should respect the primary purpose.
    *
    * @return <jk>true</jk> if chunked encoding is preferred for this entity, or <jk>false</jk> if it is not.
    */
   @Override /* Overridden from HttpEntity */
   public boolean isChunked() { return entity.isChunked(); }

   /**
    * Tells if the entity is capable of producing its data more than once.
    *
    * <p>
    * A repeatable entity's {@link #getContent()} and {@link #writeTo(OutputStream)} methods can be called more than
    * once whereas a non-repeatable entity's can not.
    *
    * <h5 class='section'>Notes:</h5><ul>
    * <li class='note'>This method always returns <jk>true</jk> if the response body is cached (see {@link #cache()}).
    * </ul>
    *
    * @return <jk>true</jk> if the entity is repeatable, <jk>false</jk> otherwise.
    */
   @Override /* Overridden from HttpEntity */
   public boolean isRepeatable() { return cached || entity.isRepeatable(); }

   /**
    * Tells whether this entity depends on an underlying stream.
    *
    * <h5 class='section'>Notes:</h5><ul>
    * <li class='note'>This method always returns <jk>false</jk> if the response body is cached (see {@link #cache()}.
    * </ul>
    *
    * @return <jk>true</jk> if the entity content is streamed, <jk>false</jk> otherwise.
    */
   @Override /* Overridden from HttpEntity */
   public boolean isStreaming() { return !cached && entity.isStreaming(); }

   /**
    * Specifies the parser to use for this body.
    *
    * <p>
    * If not specified, uses the parser defined on the client set via {@link RestClient.Builder#parser(Class)}.
    *
    * @param value
    *    The new parser to use for this body.
    * @return This object.
    */
   public ResponseContent parser(Parser value) {
      parser = value;
      return this;
   }

   /**
    * Pipes the contents of the response to the specified output stream.
    *
    * <h5 class='section'>Notes:</h5><ul>
    * <li class='note'>
    *    The output stream is not automatically closed.
    *    <li class='note'>
    *       Once the input stream is exhausted, it will automatically be closed.
    *  <li class='note'>
    *    This method can be called multiple times if {@link #cache()} has been called.
    *  <li class='note'>
    *    Calling this method multiple times without caching enabled will cause a {@link RestCallException}
    *    with an inner {@link IllegalStateException} to be thrown.
    * </ul>
    *
    * @param os The output stream to pipe the output to.
    * @return This object.
    * @throws IOException If an IO exception occurred.
    */
   public RestResponse pipeTo(OutputStream os) throws IOException {
      pipe(asInputStream(), os);
      return response;
   }

   /**
    * Pipes the contents of the response to the specified writer.
    *
    * <h5 class='section'>Notes:</h5><ul>
    * <li class='note'>
    *    The writer is not automatically closed.
    *    <li class='note'>
    *       Once the reader is exhausted, it will automatically be closed.
    *    <li class='note'>
    *       If no charset was found on the <code>Content-Type</code> response header, <js>"UTF-8"</js> is assumed.
    *  <li class='note'>
    *    This method can be called multiple times if {@link #cache()} has been called.
    *  <li class='note'>
    *    Calling this method multiple times without caching enabled will cause a {@link RestCallException}
    *    with an inner {@link IllegalStateException} to be thrown.
    * </ul>
    *
    * @param w The writer to pipe the output to.
    * @return This object.
    * @throws IOException If an IO exception occurred.
    */
   public RestResponse pipeTo(Writer w) throws IOException {
      return pipeTo(w, false);
   }

   /**
    * Pipes the contents of the response to the specified writer.
    *
    * <h5 class='section'>Notes:</h5><ul>
    * <li class='note'>
    *    The writer is not automatically closed.
    *    <li class='note'>
    *       Once the reader is exhausted, it will automatically be closed.
    *    <li class='note'>
    *       If no charset was found on the <code>Content-Type</code> response header, <js>"UTF-8"</js> is assumed.
    *  <li class='note'>
    *    This method can be called multiple times if {@link #cache()} has been called.
    *  <li class='note'>
    *    Calling this method multiple times without caching enabled will cause a {@link RestCallException}
    *    with an inner {@link IllegalStateException} to be thrown.
    * </ul>
    *
    * @param w The writer to write the output to.
    * @param byLines Flush the writers after every line of output.
    * @return This object.
    * @throws IOException If an IO exception occurred.
    */
   public RestResponse pipeTo(Writer w, boolean byLines) throws IOException {
      return pipeTo(w, null, byLines);
   }

   /**
    * Pipes the contents of the response to the specified writer.
    *
    * <h5 class='section'>Notes:</h5><ul>
    * <li class='note'>
    *    The writer is not automatically closed.
    *    <li class='note'>
    *       Once the reader is exhausted, it will automatically be closed.
    *  <li class='note'>
    *    This method can be called multiple times if {@link #cache()} has been called.
    *  <li class='note'>
    *    Calling this method multiple times without caching enabled will cause a {@link RestCallException}
    *    with an inner {@link IllegalStateException} to be thrown.
    * </ul>
    *
    * @param w The writer to pipe the output to.
    * @param charset
    *    The charset to use for the reader.
    *    <br>If <jk>null</jk>, <js>"UTF-8"</js> is used.
    * @return This object.
    * @throws IOException If an IO exception occurred.
    */
   public RestResponse pipeTo(Writer w, Charset charset) throws IOException {
      return pipeTo(w, charset, false);
   }

   /**
    * Pipes the contents of the response to the specified writer.
    *
    * <h5 class='section'>Notes:</h5><ul>
    * <li class='note'>
    *    The writer is not automatically closed.
    *    <li class='note'>
    *       Once the reader is exhausted, it will automatically be closed.
    *  <li class='note'>
    *    This method can be called multiple times if {@link #cache()} has been called.
    *  <li class='note'>
    *    Calling this method multiple times without caching enabled will cause a {@link RestCallException}
    *    with an inner {@link IllegalStateException} to be thrown.
    * </ul>
    *
    * @param w The writer to pipe the output to.
    * @param byLines Flush the writers after every line of output.
    * @param charset
    *    The charset to use for the reader.
    *    <br>If <jk>null</jk>, <js>"UTF-8"</js> is used.
    * @return This object.
    * @throws IOException If an IO exception occurred.
    */
   public RestResponse pipeTo(Writer w, Charset charset, boolean byLines) throws IOException {
      if (byLines)
         pipeLines(asReader(charset), w);
      else
         pipe(asReader(charset), w);
      return response;
   }

   /**
    * Returns the response that created this object.
    *
    * @return The response that created this object.
    */
   public RestResponse response() {
      return response;
   }

   /**
    * Specifies the schema for this body.
    *
    * <p>
    * Used by schema-based parsers such as {@link OpenApiParser}.
    *
    * @param value The schema.
    * @return This object.
    */
   public ResponseContent schema(HttpPartSchema value) {
      schema = value;
      return this;
   }

   @Override
   public String toString() {
      try {
         return asString();
      } catch (RestCallException e) {
         return localizedMessage(e);
      }
   }

   /**
    * Writes the entity content out to the output stream.
    *
    * <h5 class='section'>Notes:</h5><ul>
    *    <li class='note'>This method is equivalent to {@link #pipeTo(OutputStream)} which is the preferred method for fluent-style coding.
    * </ul>
    *
    * @param outstream The output stream to write entity content to.
    */
   @Override /* Overridden from HttpEntity */
   public void writeTo(OutputStream outstream) throws IOException {
      pipeTo(outstream);
   }

   private MarshallingContext getMarshallingContext() { return parser == null ? MarshallingContext.DEFAULT : parser.getMarshallingContext(); }

   private <T> ClassMeta<T> getClassMeta(Class<T> c) {
      return getMarshallingContext().getClassMeta(c);
   }

   private <T> ClassMeta<T> getClassMeta(Type type, Type...args) {
      return getMarshallingContext().getClassMeta(type, args);
   }
}