/*
 * 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.marshall.parser;

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.time.*;
import java.time.Duration;
import java.time.temporal.*;
import java.util.*;
import java.util.function.*;

import javax.xml.datatype.*;

import org.apache.juneau.commons.bean.*;
import org.apache.juneau.commons.collections.*;
import org.apache.juneau.commons.function.*;
import org.apache.juneau.commons.inject.*;
import org.apache.juneau.commons.reflect.*;
import org.apache.juneau.marshall.*;
import org.apache.juneau.marshall.collections.*;
import org.apache.juneau.marshall.httppart.*;
import org.apache.juneau.marshall.objecttools.*;
import org.apache.juneau.marshall.swap.spi.*;
import org.apache.juneau.marshall.utils.*;

/**
 * Session object that lives for the duration of a single use of {@link Parser}.
 *
 * <h5 class='section'>Notes:</h5><ul>
 *    <li class='warn'>This class is not thread safe and is typically discarded after one use.
 * </ul>
 *
 * <h5 class='section'>See Also:</h5><ul>
 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/SerializersAndParsers">Serializers and Parsers</a>

 * </ul>
 */
@SuppressWarnings({
   "java:S112", // throws Exception intentional - callback/lifecycle method
   "java:S1192", // Duplicated literals (argument/property names) read more clearly inline than as constants
   "java:S1452", // create(), getClassMeta() and getListenerClass() expose wildcard Builder<?>/ClassMeta<?>/Class<? extends ParserListener> because the concrete type is not known statically
   "rawtypes", // Raw types necessary for generic type handling throughout parser session
   "resource", // pipe field holds the per-parse ParserPipe whose lifecycle is managed by the session, not owned as a standalone field.
   "unchecked" // Type erasure requires unchecked casts throughout parser session
})
public class ParserSession extends MarshallingSession {

   /**
    * Default value for {@link Builder#maxParseDepth(int)}.
    */
   protected static final int DEFAULT_MAX_PARSE_DEPTH = 1000;

   /**
    * 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 MarshallingSession.Builder<SELF> {

      private HttpPartSchema schema;
      private Method javaMethod;
      private Object outer;
      private boolean trimStrings;
      private Nulls nulls;
      private int maxParseDepth = DEFAULT_MAX_PARSE_DEPTH;
      private final Parser ctx;

      /**
       * Constructor
       *
       * @param ctx The context creating this session.
       *    <br>Cannot be <jk>null</jk>.
       */
      protected Builder(Parser ctx) {
         super(reqnn("ctx", ctx).getMarshallingContext());
         this.ctx = ctx;
         mediaTypeDefault(ctx.getPrimaryMediaType());
         trimStrings = ctx.isTrimStrings();
         nulls = ctx.getNulls();
      }

      @Override
      public ParserSession build() {
         return new ParserSession(this);
      }

      /**
       * The java method that called this serializer, usually the method in a REST servlet.
       *
       * @param value
       *    The new property value.
       *    <br>Can be <jk>null</jk> to leave (or clear) the associated java method unset.
       * @return This object.
       */
      public SELF javaMethod(Method value) {
         javaMethod = value;
         return self();
      }


      /**
       * The outer object for instantiating top-level non-static inner classes.
       *
       * @param value
       *    The new property value.
       *    <br>Can be <jk>null</jk> (no outer object will be used, suitable for static or top-level classes).
       * @return This object.
       */
      public SELF outer(Object value) {
         outer = value;
         return self();
      }

      /**
       * The shared recursive-parse-depth budget honored by binary codec sessions (CBOR, Protobuf, MsgPack)
       * at their recursive databind entry points.
       *
       * @param value
       *    The new property value.
       *    <br>Defaults to {@value ParserSession#DEFAULT_MAX_PARSE_DEPTH}.
       * @return This object.
       * @see ParserSession#enterParseDepth()
       */
      public SELF maxParseDepth(int value) {
         maxParseDepth = value;
         return self();
      }

      @Override /* Overridden from Builder */
      public SELF property(String key, Object value) {
         if (key == null) {
            super.property(key, value);
            return self();
         }
         switch (key) {
            case "javaMethod", "ParserSession.javaMethod":
               return javaMethod(cvt(value, Method.class));
            case "outer", "ParserSession.outer":
               return outer(value);
            case "schema", "ParserSession.schema":
               return schema(cvt(value, HttpPartSchema.class));
            case "trimStrings", "ParserSession.trimStrings":
               return trimStrings(cvt(value, Boolean.class));
            case "nulls", "ParserSession.nulls":
               return nulls(cvt(value, Nulls.class));
            case "maxParseDepth", "ParserSession.maxParseDepth":
               return maxParseDepth(cvt(value, Integer.class));
            default:
               super.property(key, value);
               return self();
         }
      }

      /**
       * Trim parsed strings.
       *
       * @param value The new value for this setting.
       * @return This object.
       */
      public SELF trimStrings(boolean value) {
         trimStrings = value;
         return self();
      }

      /**
       * Per-session override for the parser's null-coercion policy.
       *
       * @param value The new value for this setting.  {@code null} is treated as {@link Nulls#NOT_SET}.
       * @return This object.
       * @see Parser.Builder#nulls(Nulls)
       * @since 10.0.0
       */
      public SELF nulls(Nulls value) {
         nulls = value == null ? Nulls.NOT_SET : value;
         return self();
      }

      /**
       * HTTP-part schema.
       *
       * <p>
       * Used for schema-based serializers and parsers to define additional formatting.
       *
       * @param value
       *    The new value for this property.
       *    <br>Can be <jk>null</jk> (will not set the value, keeps existing schema or remains <jk>null</jk>).
       * @return This object.
       */
      public SELF schema(HttpPartSchema value) {
         if (nn(value))
            schema = value;
         return self();
      }

      /**
       * Same as {@link #schema(HttpPartSchema)} but doesn't overwrite the value if it is already set.
       *
       * @param value
       *    The new value for this property.
       *    <br>If <jk>null</jk>, the value will not be set (keeps existing schema or remains <jk>null</jk>).
       * @return This object.
       */
      public SELF schemaDefault(HttpPartSchema value) {
         if (nn(value) && schema == null)
            schema = value;
         return self();
      }

   }

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

      DefaultBuilder(Parser ctx) {
         super(ctx);
      }
   }

   /**
    * Creates a new builder for this object.
    *
    * @param ctx The context creating this session.
    *    <br>Cannot be <jk>null</jk>.
    * @return A new builder.
    */
   public static Builder<?> create(Parser ctx) {
      return new DefaultBuilder(reqnn("ctx", ctx));
   }

   /**
    * Convenience method for calling the {@link NameProperty @NameProperty} method on the specified object if it exists.
    *
    * @param cm The class type of the object.
    *    <br>Can be <jk>null</jk> (no-op).
    * @param o The object.
    * @param name The name to set.
    * @throws ExecutableException Exception occurred on invoked constructor/method/field.
    */
   protected static final void setName(ClassMeta<?> cm, Object o, Object name) throws ExecutableException {
      if (nn(cm)) {
         Property m = cm.getNameProperty();
         if (nn(m) && m.canWrite())
            m.set(o, name);
      }
   }

   /**
    * Convenience method for calling the {@link ParentProperty @ParentProperty} method on the specified object if it
    * exists.
    *
    * @param cm The class type of the object.
    *    <br>Can be <jk>null</jk> (no-op).
    * @param o The object.
    * @param parent The parent to set.
    * @throws ExecutableException Exception occurred on invoked constructor/method/field.
    */
   protected static final void setParent(ClassMeta<?> cm, Object o, Object parent) throws ExecutableException {
      if (cm == null)
         return;
      Property m = cm.getParentProperty();
      if (nn(m) && m.canWrite())
         m.set(o, parent);
   }

   /**
    * Returns the nearest enclosing bean used as the parent for {@link ParentProperty @ParentProperty} injection.
    *
    * <p>
    * Unlike {@link #getOuter()} (which also serves as the instantiation context for non-static member/inner classes),
    * this value tracks only the nearest enclosing <i>bean</i> as the object graph is parsed, deliberately skipping any
    * intermediate collections/maps/arrays.  It is {@code null} at the document root (no enclosing bean), which means a
    * bean parsed at the root or directly inside a top-level collection has no parent injected.
    *
    * @return The nearest enclosing bean, or {@code null} if there is none.
    */
   protected final Object parentBean() {
      return parentBean;
   }

   /**
    * Sets the nearest-enclosing-bean tracker used for {@link ParentProperty @ParentProperty} injection.
    *
    * <p>
    * Callers should invoke this when they begin populating a bean's properties (passing that bean), then pass the
    * returned previous value back to this method once done, restoring the tracker stack-style.
    *
    * @param value The new nearest enclosing bean (typically the bean currently being populated).
    * @return The previous value, to be passed back to this method to restore the tracker.
    */
   protected final Object swapParentBean(Object value) {
      var old = parentBean;
      parentBean = value;
      return old;
   }

   private final HttpPartSchema schema;
   private final Method javaMethod;
   private final Object outer;
   private final boolean trimStrings;
   private final Nulls nulls;
   private final int maxParseDepth;
   private final Parser ctx;
   private final ParserListener listener;
   private final Deque<StringBuilder> sbStack;
   private BeanPropertyMeta currentProperty;
   private ClassMeta<?> currentClass;
   private Object parentBean;
   private final Position mark = new Position(-1);
   private ParserPipe pipe;
   private int parseDepth;

   /**
    * Constructor.
    *
    * @param builder The builder for this object.
    *    <br>Cannot be <jk>null</jk>.
    */
   protected ParserSession(Builder<?> builder) {
      super(builder);
      ctx = builder.ctx;
      javaMethod = builder.javaMethod;
      outer = builder.outer;
      parentBean = builder.outer;
      schema = builder.schema;
      trimStrings = builder.trimStrings;
      nulls = builder.nulls == null ? Nulls.NOT_SET : builder.nulls;
      maxParseDepth = builder.maxParseDepth;
      listener = BeanInstantiator.createOrNull(ctx.getListener());
      sbStack = new ArrayDeque<>();
   }

   /**
    * Returns the input as a string.
    *
    * <p>
    * This always returns a value for input of type {@link CharSequence}.
    * <br>For other input types, use {@link org.apache.juneau.marshall.Context.Builder#debug() Context.Builder#debug()} setting to enable caching to a string
    * before parsing so that this method returns the input.
    *
    * @return The input as a string, or <jk>null</jk> if no pipe has been created or we're reading from an uncached reader or input stream source.
    */
   public String getInputAsString() { return pipe == null ? null : pipe.getInputAsString(); }

   /**
    * Returns information used to determine at what location in the parse a failure occurred.
    *
    * @return A map, typically containing something like <c>{line:123,column:456,currentProperty:"foobar"}</c>
    */
   public final JsonMap getLastLocation() {
      var m = new JsonMap();
      if (nn(currentClass))
         m.put("currentClass", currentClass.toString(true));
      if (nn(currentProperty))
         m.put("currentProperty", currentProperty);
      return m;
   }

   /**
    * Returns the listener associated with this session.
    *
    * @return The listener associated with this session, or <jk>null</jk> if there is no listener.
    */
   public ParserListener getListener() { return listener; }

   /**
    * Returns the listener associated with this session.
    *
    * @param <T> The listener type.
    * @param c The listener class to cast to.
    * @return The listener associated with this session, or <jk>null</jk> if there is no listener.
    */
   public <T extends ParserListener> T getListener(Class<T> c) {
      return (T)listener;
   }

   /**
    * Returns the current position into the reader or input stream.
    *
    * @return
    *    The current position into the reader or input stream.
    *    <br>Never <jk>null</jk>.
    */
   public Position getPosition() {
      if (mark.line != -1 || mark.column != -1 || mark.position != -1)
         return mark;
      if (pipe == null)
         return Position.UNKNOWN;
      return pipe.getPosition();
   }

   /**
    * HTTP part schema of object being parsed.
    *
    * @return HTTP part schema of object being parsed, or <jk>null</jk> if not specified.
    */
   public final HttpPartSchema getSchema() { return schema; }

   /**
    * Returns <jk>true</jk> if this parser subclasses from {@link ReaderParser}.
    *
    * @return <jk>true</jk> if this parser subclasses from {@link ReaderParser}.
    */
   public boolean isReaderParser() { return false; }

   /**
    * Same as {@link #read(Object, 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'>
    *    ReaderParser <jv>parser</jv> = JsonParser.<jsf>DEFAULT</jsf>;
    *
    *    <jc>// Parse into a string.</jc>
    *    String <jv>string</jv> = <jv>parser</jv>.read(<jv>json</jv>, String.<jk>class</jk>);
    *
    *    <jc>// Parse into a bean.</jc>
    *    MyBean <jv>bean</jv> = <jv>parser</jv>.read(<jv>json</jv>, MyBean.<jk>class</jk>);
    *
    *    <jc>// Parse into a bean array.</jc>
    *    MyBean[] <jv>beanArray</jv> = <jv>parser</jv>.read(<jv>json</jv>, MyBean[].<jk>class</jk>);
    *
    *    <jc>// Parse into a linked-list of objects.</jc>
    *    List <jv>list</jv> = <jv>parser</jv>.read(<jv>json</jv>, LinkedList.<jk>class</jk>);
    *
    *    <jc>// Parse into a map of object keys/values.</jc>
    *    Map <jv>map</jv> = <jv>parser</jv>.read(<jv>json</jv>, TreeMap.<jk>class</jk>);
    * </p>
    *
    * @param <T> The class type of the object being created.
    * @param input
    *    The input.
    *    See {@link #read(Object, Type, Type...)} for details.
    * @param type The object type to create.
    * @return The parsed object.
    * @throws ParseException Malformed input encountered.
    * @throws IOException Thrown by the underlying stream.
    */
   public final <T> T read(Object input, Class<T> type) throws ParseException, IOException {
      try (var p = createPipe(input)) {
         return readInner(p, getClassMeta(type));
      }
   }

   /**
    * Same as {@link #read(Object, Type, Type...)} except the type has already been converted into a {@link ClassMeta}
    * object.
    *
    * <p>
    * This is mostly an internal method used by the framework.
    *
    * @param <T> The class type of the object being created.
    * @param input
    *    The input.
    *    See {@link #read(Object, Type, Type...)} for details.
    * @param type The object type to create.
    * @return The parsed object.
    * @throws ParseException Malformed input encountered.
    * @throws IOException Thrown by the underlying stream.
    */
   public final <T> T read(Object input, ClassMeta<T> type) throws ParseException, IOException {
      try (var p = createPipe(input)) {
         return readInner(p, type);
      }
   }

   /**
    * Parses input 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'>
    *    ReaderParser <jv>parser</jv> = JsonParser.<jsf>DEFAULT</jsf>;
    *
    *    <jc>// Parse into a linked-list of strings.</jc>
    *    List <jv>list1</jv> = <jv>parser</jv>.read(<jv>json</jv>, LinkedList.<jk>class</jk>, String.<jk>class</jk>);
    *
    *    <jc>// Parse into a linked-list of beans.</jc>
    *    List <jv>list2</jv> = <jv>parser</jv>.read(<jv>json</jv>, LinkedList.<jk>class</jk>, MyBean.<jk>class</jk>);
    *
    *    <jc>// Parse into a linked-list of linked-lists of strings.</jc>
    *    List <jv>list3</jv> = <jv>parser</jv>.read(<jv>json</jv>, LinkedList.<jk>class</jk>, LinkedList.<jk>class</jk>, String.<jk>class</jk>);
    *
    *    <jc>// Parse into a map of string keys/values.</jc>
    *    Map <jv>map1</jv> = <jv>parser</jv>.read(<jv>json</jv>, 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 <jv>map2</jv> = <jv>parser</jv>.read(<jv>json</jv>, 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 #read(Object, Class)} method instead if you don't need a parameterized map/collection.
    * </ul>
    *
    * @param <T> The class type of the object to create.
    * @param input
    *    The input.
    *    <br>Character-based parsers can handle the following input class types:
    *    <ul>
    *       <li><jk>null</jk>
    *       <li>{@link Reader}
    *       <li>{@link CharSequence}
    *       <li>{@link InputStream} containing UTF-8 encoded text (or charset defined by
    *          {@link ReaderParser.Builder#streamCharset(Charset)} property value).
    *       <li><code><jk>byte</jk>[]</code> containing UTF-8 encoded text (or charset defined by
    *          {@link ReaderParser.Builder#streamCharset(Charset)} property value).
    *    </ul>
    *    <br>Stream-based parsers can handle the following input class types:
    *    <ul>
    *       <li><jk>null</jk>
    *       <li>{@link InputStream}
    *       <li><code><jk>byte</jk>[]</code>
    *    </ul>
    * @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 ParseException Malformed input encountered.
    * @see MarshallingSession#getClassMeta(Type,Type...) for argument syntax for maps and collections.
    * @throws IOException Thrown by the underlying stream.
    */
   public final <T> T read(Object input, Type type, Type...args) throws ParseException, IOException {
      try (var p = createPipe(input)) {
         return (T)readInner(p, getClassMeta(type, args));
      }
   }

   /**
    * Same as {@link #read(Object, Class)} but parses from a string and doesn't throw an {@link IOException}.
    *
    * <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'>
    *    ReaderParser <jv>parser</jv> = JsonParser.<jsf>DEFAULT</jsf>;
    *
    *    <jc>// Parse into a string.</jc>
    *    String <jv>string</jv> = <jv>parser</jv>.read(<jv>json</jv>, String.<jk>class</jk>);
    *
    *    <jc>// Parse into a bean.</jc>
    *    MyBean <jv>bean</jv> = <jv>parser</jv>.read(<jv>json</jv>, MyBean.<jk>class</jk>);
    *
    *    <jc>// Parse into a bean array.</jc>
    *    MyBean[] <jv>beanArray</jv> = <jv>parser</jv>.read(<jv>json</jv>, MyBean[].<jk>class</jk>);
    *
    *    <jc>// Parse into a linked-list of objects.</jc>
    *    List <jv>list</jv> = <jv>parser</jv>.read(<jv>json</jv>, LinkedList.<jk>class</jk>);
    *
    *    <jc>// Parse into a map of object keys/values.</jc>
    *    Map <jv>map</jv> = <jv>parser</jv>.read(<jv>json</jv>, TreeMap.<jk>class</jk>);
    * </p>
    *
    * @param <T> The class type of the object being created.
    * @param input
    *    The input.
    *    See {@link #read(Object, Type, Type...)} for details.
    * @param type The object type to create.
    * @return The parsed object.
    * @throws ParseException Malformed input encountered.
    */
   public final <T> T read(String input, Class<T> type) throws ParseException {
      try (var p = createPipe(input)) {
         return readInner(p, getClassMeta(type));
      } catch (IOException e) {
         throw new ParseException(e); // Shouldn't happen.
      }
   }

   /**
    * Same as {@link #read(Object, ClassMeta)} except parses from a string and doesn't throw an {@link IOException}.
    *
    * <p>
    * This is mostly an internal method used by the framework.
    *
    * @param <T> The class type of the object being created.
    * @param input
    *    The input.
    *    See {@link #read(Object, Type, Type...)} for details.
    * @param type The object type to create.
    * @return The parsed object.
    * @throws ParseException Malformed input encountered.
    */
   public final <T> T read(String input, ClassMeta<T> type) throws ParseException {
      try (var p = createPipe(input)) {
         return readInner(p, type);
      } catch (IOException e) {
         throw new ParseException(e); // Shouldn't happen.
      }
   }

   /**
    * Same as {@link #read(Object,Type,Type...)} but parses from a string and doesn't throw an {@link IOException}.
    *
    * @param <T> The class type of the object to create.
    * @param input
    *    The input.
    *    <br>Character-based parsers can handle the following input class types:
    *    <ul>
    *       <li><jk>null</jk>
    *       <li>{@link Reader}
    *       <li>{@link CharSequence}
    *       <li>{@link InputStream} containing UTF-8 encoded text (or charset defined by
    *          {@link ReaderParser.Builder#streamCharset(Charset)} property value).
    *       <li><code><jk>byte</jk>[]</code> containing UTF-8 encoded text (or charset defined by
    *          {@link ReaderParser.Builder#streamCharset(Charset)} property value).
    *    </ul>
    *    <br>Stream-based parsers can handle the following input class types:
    *    <ul>
    *       <li><jk>null</jk>
    *       <li>{@link InputStream}
    *       <li><code><jk>byte</jk>[]</code>
    *    </ul>
    * @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 ParseException Malformed input encountered.
    * @see MarshallingSession#getClassMeta(Type,Type...) for argument syntax for maps and collections.
    */
   public final <T> T read(String input, Type type, Type...args) throws ParseException {
      try (var p = createPipe(input)) {
         return (T)readInner(p, getClassMeta(type, args));
      } catch (IOException e) {
         throw new ParseException(e); // Shouldn't happen.
      }
   }

   /**
    * Parses the specified array input with each entry in the object defined by the {@code argTypes}
    * argument.
    *
    * <p>
    * Used for converting arrays (e.g. <js>"[arg1,arg2,...]"</js>) into an {@code Object[]} that can be passed
    * to the {@code Method.invoke(target, args)} method.
    *
    * <p>
    * Used in the following locations:
    * <ul class='spaced-list'>
    *    <li>
    *       Used to parse argument strings in the {@link ObjectIntrospector#invokeMethod(Method, Reader)} method.
    * </ul>
    *
    * @param input The input.  Subclasses can support different input types.
    * @param argTypes Specifies the type of objects to create for each entry in the array.
    * @return An array of parsed objects.
    * @throws ParseException Malformed input encountered.
    */
   public final Object[] readArgs(Object input, Type[] argTypes) throws ParseException {
      try (var p = createPipe(input)) {
         return doRead(p, getArgsClassMeta(argTypes));
      } catch (ParseException e) {
         throw e;
      } catch (@SuppressWarnings("unused") StackOverflowError e) {
         throw new ParseException(this, "Depth too deep.  Stack overflow occurred.");
      } catch (IOException e) {
         throw new ParseException(this, e, "I/O exception occurred.  exception=%s, message=%s.", cns(e), localizedMessage(e));
      } catch (Exception e) {
         throw new ParseException(this, e, "Exception occurred.  exception=%s, message=%s.", cns(e), localizedMessage(e));
      } finally {
         checkForWarnings();
      }
   }

   /**
    * Parses the contents of the specified reader and loads the results into the specified collection.
    *
    * <p>
    * Used in the following locations:
    * <ul class='spaced-list'>
    *    <li>
    *       The various character-based constructors in {@link JsonList} (e.g.
    *       {@link JsonList#JsonList(CharSequence,Parser)}.
    * </ul>
    *
    * @param <E> The element class type.
    * @param input The input.  See {@link #read(Object, ClassMeta)} for supported input types.
    * @param c The collection being loaded.
    * @param elementType The class type of the elements, or <jk>null</jk> to default to whatever is being parsed.
    * @return The same collection that was passed in to allow this method to be chained.
    * @throws ParseException Malformed input encountered.
    * @throws UnsupportedOperationException If not implemented.
    */
   public final <E> Collection<E> readIntoCollection(Object input, Collection<E> c, Type elementType) throws ParseException {
      try (var p = createPipe(input)) {
         return doReadIntoCollection(p, c, elementType);
      } catch (ParseException e) {
         throw e;
      } catch (@SuppressWarnings("unused") StackOverflowError e) {
         throw new ParseException(this, "Depth too deep.  Stack overflow occurred.");
      } catch (IOException e) {
         throw new ParseException(this, e, "I/O exception occurred.  exception=%s, message=%s.", cns(e), localizedMessage(e));
      } catch (Exception e) {
         throw new ParseException(this, e, "Exception occurred.  exception=%s, message=%s.", cns(e), localizedMessage(e));
      } finally {
         checkForWarnings();
      }
   }

   /**
    * Parses the contents of the specified reader and loads the results into the specified map.
    *
    * <p>
    * Reader must contain something that serializes to a map (such as text containing a JSON object).
    *
    * <p>
    * Used in the following locations:
    * <ul class='spaced-list'>
    *    <li>
    *       The various character-based constructors in {@link JsonMap} (e.g.
    *       {@link JsonMap#JsonMap(CharSequence,Parser)}).
    * </ul>
    *
    * @param <K> The key class type.
    * @param <V> The value class type.
    * @param input The input.  See {@link #read(Object, ClassMeta)} for supported input types.
    * @param m The map being loaded.
    * @param keyType The class type of the keys, or <jk>null</jk> to default to <code>String.<jk>class</jk></code>.
    * @param valueType The class type of the values, or <jk>null</jk> to default to whatever is being parsed.
    * @return The same map that was passed in to allow this method to be chained.
    * @throws ParseException Malformed input encountered.
    * @throws UnsupportedOperationException If not implemented.
    */
   public final <K,V> Map<K,V> readIntoMap(Object input, Map<K,V> m, Type keyType, Type valueType) throws ParseException {
      try (var p = createPipe(input)) {
         return doReadIntoMap(p, m, keyType, valueType);
      } catch (ParseException e) {
         throw e;
      } catch (Exception e) {
         throw new ParseException(this, e);
      } finally {
         checkForWarnings();
      }
   }

   /**
    * Entry point for all parsing calls.
    *
    * <p>
    * Calls the {@link #doRead(ParserPipe, ClassMeta)} implementation class and catches/re-wraps any exceptions
    * thrown.
    *
    * @param pipe The parser input.
    * @param type The class type of the object to create.
    * @param <T> The class type of the object to create.
    * @return The parsed object.
    * @throws ParseException Malformed input encountered.
    * @throws IOException Thrown by the underlying stream.
    */
   private <T> T readInner(ParserPipe pipe, ClassMeta<T> type) throws ParseException, IOException {
      if (type.isVoid())
         return null;
      if (BeanSupplier.class.isAssignableFrom(type.inner()) && !BeanChannel.class.isAssignableFrom(type.inner()))
         throw new ParseException(this, "BeanSupplier cannot be used as a parser target. Use BeanConsumer or BeanChannel for round-trip support.");
      try {
         var r = doRead(pipe, type);
         // Primitive optionals (OptionalInt/Long/Double) are parsed as first-class optionals — the format
         // parsers wrap the element in a generic Optional, so coerce the top-level result to the matching
         // primitive-optional type (mirrors the Optional<T> contract; absent/null already resolved to empty).
         if (type.isPrimitiveOptional() && ! type.inner().isInstance(r))
            return convertToType(r, type);
         return r;
      } catch (ParseException | IOException e) {
         throw e;
      } catch (@SuppressWarnings("unused") StackOverflowError e) {
         throw new ParseException(this, "Depth too deep.  Stack overflow occurred.");
      } catch (Exception e) {
         throw new ParseException(this, e, "Exception occurred.  exception=%s, message=%s.", cns(e), localizedMessage(e));
      } finally {
         checkForWarnings();
      }
   }

   /**
    * Parses the input and streams each parsed element into the given {@link BeanConsumer}.
    *
    * <p>
    * This is the primary API for large-dataset parsing where parsed beans should be consumed lazily
    * (e.g. inserted directly into a database) rather than collected into an in-memory collection.
    *
    * <p>
    * The parser drives the full consumer lifecycle:
    * <ol>
    *    <li>Calls {@link BeanConsumer#begin()} before parsing starts
    *    <li>Calls {@link BeanConsumer#acceptThrows(Object)} for each parsed element
    *    <li>If {@link BeanConsumer#acceptThrows(Object)} throws, calls {@link BeanConsumer#onError(Exception)};
    *        if {@code onError()} absorbs the exception, parsing continues to the next element
    *    <li>Always calls {@link BeanConsumer#complete()} at the end (like {@code finally})
    * </ol>
    *
    * <p>
    * The default implementation parses the input into a {@link List} first and then feeds each element
    * to the consumer. Format-specific subclasses may override {@link #doReadToBeanConsumer} for true
    * streaming behavior without loading all elements into memory.
    *
    * @param <T> The element type.
    * @param input The input to parse.
    * @param consumer The consumer to receive parsed elements.
    * @param elementType The type of each element.
    * @throws ParseException If a parse error occurs that causes {@code onError()} to rethrow.
    * @throws IOException If an I/O error occurs reading the input.
    */
   public final <T> void readToBeanConsumer(Object input, BeanConsumer<T> consumer, Class<T> elementType) throws ParseException, IOException {
      try (var p = createPipe(input)) {
         doReadToBeanConsumer(p, consumer, elementType);
      }
   }

   /**
    * Format-specific implementation for {@link #readToBeanConsumer}.
    *
    * <p>
    * The default implementation parses the input as a {@link List} and feeds each element to the consumer.
    * Override this method in format-specific parsers to support true streaming without collecting all
    * elements into memory.
    *
    * @param <T> The element type.
    * @param pipe The parser input pipe.
    * @param consumer The consumer to receive parsed elements.
    * @param elementType The type of each element.
    * @throws ParseException If a parse error occurs.
    * @throws IOException If an I/O error occurs.
    */
   protected <T> void doReadToBeanConsumer(ParserPipe pipe, BeanConsumer<T> consumer, Class<T> elementType) throws ParseException, IOException {
      List<T> list = (List<T>) doRead(pipe, getClassMeta(List.class, elementType));
      if (list == null)
         return;
      var bodyThrown = drainToConsumer(consumer, list);
      var completeThrown = completeQuietly(consumer);
      if (bodyThrown != null) {
         if (completeThrown != null)
            bodyThrown.addSuppressed(completeThrown);
         if (bodyThrown instanceof ParseException bodyThrown2)
            throw bodyThrown2;
         if (bodyThrown instanceof IOException bodyThrown2)
            throw bodyThrown2;
         throw new ParseException(this, bodyThrown, "Exception occurred.  exception=%s, message=%s.", cns(bodyThrown), localizedMessage(bodyThrown));
      }
      if (completeThrown != null)
         throw new ParseException(this, completeThrown, "Exception occurred in BeanConsumer.complete().  exception=%s, message=%s.", cns(completeThrown), localizedMessage(completeThrown));
   }

   private static <T> Exception drainToConsumer(BeanConsumer<T> consumer, List<T> list) {
      try {
         consumer.begin();
         for (var element : list)
            acceptOrError(consumer, element);
      } catch (Exception e) {
         return e;
      }
      return null;
   }

   private static <T> void acceptOrError(BeanConsumer<T> consumer, T element) throws Exception {
      try {
         consumer.acceptThrows(element);
      } catch (Exception e) {
         consumer.onError(e);
      }
   }

   private static Exception completeQuietly(BeanConsumer<?> consumer) {
      try {
         consumer.complete();
         return null;
      } catch (Exception e) {
         return e;
      }
   }

   /**
    * Throws {@link MissingRequiredPropertyException} if the bean map is missing {@code @BeanProp(required=true)} properties.
    *
    * <p>
    * Call once per bean, after all input properties have been put into the map and before {@link BeanMap#getBean()}
    * constructs it.  Do not call it for intermediate bean maps that are filled in later.
    *
    * @param <T> The bean type.
    * @param m The bean map.  Can be <jk>null</jk>.
    * @return The same bean map.
    */
   protected final <T> BeanMap<T> checkRequired(BeanMap<T> m) {
      return MissingRequiredPropertyException.check(this, m);
   }

   /**
    * Converts the specified {@link MarshalledMap} into a bean identified by the <js>"_type"</js> property in the map.
    *
    * @param m The map to convert to a bean.
    *    <br>Must not be <jk>null</jk>.
    * @param pMeta The current bean property being parsed.
    *    <br>Can be <jk>null</jk> (the <c>@MarshalledProp(dictionary={})</c> registry lookup is skipped).
    * @param eType The current expected type being parsed.
    *    <br>Can be <jk>null</jk> (the <c>@Marshalled(dictionary={})</c> registry lookup on the expected type is skipped).
    * @return
    *    The converted bean, or the same map if the <js>"_type"</js> entry wasn't found or didn't resolve to a bean.
    */
   protected final Object cast(MarshalledMap m, BeanPropertyMeta pMeta, ClassMeta<?> eType) {

      var btpn = getBeanTypePropertyName(eType);

      var o = m.get(btpn);
      if (o == null)
         return m;
      var typeName = o.toString();

      var cm = getClassMeta(typeName, pMeta, eType);

      if (nn(cm)) {
         var bm = m.getMarshallingSession().newBeanMap(cm.inner());

         // Iterate through all the entries in the map and set the individual field values.
         m.forEach((k, v) -> {
            if (! k.equals(btpn)) {
               // Attempt to recursively cast child maps.
               if (v instanceof MarshalledMap v2)
                  v = cast(v2, pMeta, eType);
               bm.put(k, v);
            }
         });
         return checkRequired(bm).getBean();
      }

      return m;
   }

   /**
    * Converts the specified string to the specified type.
    *
    * @param outer
    *    The outer object if we're converting to an inner object that needs to be created within the context
    *    of an outer object.
    *    <br>Can be <jk>null</jk> if the target is not a non-static inner class requiring an enclosing instance.
    * @param s The string to convert.
    *    <br>Can be <jk>null</jk> (returns <jk>null</jk>).
    * @param type The class type to convert the string to.
    *    <br>Can be <jk>null</jk> (defaults to <c>Object</c>).
    * @return The string converted as an object of the specified type, or <jk>null</jk> if the input string was <jk>null</jk>.
    * @param <T> The class type to convert the string to.
    * @throws ParseException Malformed input encountered.
    * @throws ExecutableException Exception occurred on invoked constructor/method/field.
    */
   @SuppressWarnings({
      "java:S3776" // Cognitive complexity acceptable for type-conversion dispatch across all supported target types
   })
   protected final <T> T convertAttrToType(Object outer, String s, ClassMeta<T> type) throws ParseException {
      if (s == null)
         return null;

      if (type == null)
         type = (ClassMeta<T>)object();
      var swap = type.getSwap(this);
      var sType = swap == null ? type : swap.getSwapClassMeta(this);

      var o = (Object)s;
      if (sType.isChar())
         o = parseCharacter(s);
      else if (sType.isNumber())
         o = parseNumber(s, (Class<? extends Number>)sType.inner());
      else if (sType.isBoolean())
         o = Boolean.parseBoolean(s);
      else if (sType.isDate())
         o = readDate(s, sType);
      else if (sType.isCalendar())
         o = readCalendar(s, sType);
      else if (sType.isTemporal())
         o = readTemporal(s, sType);
      else if (sType.isDuration())
         o = readDuration(s);
      else if (sType.isPeriod())
         o = readPeriod(s);
      else if (! (sType.isCharSequence() || sType.isObject())) {
         if (sType.canCreateNewInstanceFromString(outer))
            o = sType.newInstanceFromString(outer, s);
         else
            throw new ParseException(this, "Invalid conversion from string to class '%s'", type);
      }

      if (nn(swap))
         o = unswap(swap, o, type);

      return (T)o;
   }

   /**
    * Wraps the specified input object into a {@link ParserPipe} object so that it can be easily converted into
    * a stream or reader.
    *
    * @param input
    *    The input.
    *    <br>For character-based parsers, this can be any of the following types:
    *    <ul>
    *       <li><jk>null</jk>
    *       <li>{@link Reader}
    *       <li>{@link CharSequence}
    *       <li>{@link InputStream} containing UTF-8 encoded text (or whatever the encoding specified by
    *          {@link ReaderParser.Builder#streamCharset(Charset)}).
    *       <li><code><jk>byte</jk>[]</code> containing UTF-8 encoded text (or whatever the encoding specified by
    *          {@link ReaderParser.Builder#streamCharset(Charset)}).
    *    </ul>
    *    <br>For byte-based parsers, this can be any of the following types:
    *    <ul>
    *       <li><jk>null</jk>
    *       <li>{@link InputStream}
    *       <li><code><jk>byte</jk>[]</code>
    *       <li>{@link CharSequence} containing encoded bytes according to the {@link InputStreamParser.Builder#binaryFormat(BinaryFormat)} setting.
    *    </ul>
    * @return
    *    A new {@link ParserPipe} wrapper around the specified input object.
    */
   protected ParserPipe createPipe(Object input) {
      return null;
   }

   /**
    * Workhorse method.
    *
    * <p>
    * Subclasses are expected to implement this method or {@link Parser#doRead(ParserSession,ParserPipe,ClassMeta)}.
    *
    * <p>
    * The default implementation of this method simply calls {@link Parser#doRead(ParserSession,ParserPipe,ClassMeta)}.
    *
    * @param pipe Where to get the input from.
    * @param type
    *    The class type of the object to create.
    *    If <jk>null</jk> or <code>Object.<jk>class</jk></code>, object type is based on what's being parsed.
    *    For example, when parsing JSON text, it may return a <c>String</c>, <c>Number</c>,
    *    <c>JsonMap</c>, etc...
    * @param <T> The class type of the object to create.
    * @return The parsed object.
    * @throws IOException Thrown by underlying stream.
    * @throws ParseException Malformed input encountered.
    * @throws ExecutableException Exception occurred on invoked constructor/method/field.
    */
   protected <T> T doRead(ParserPipe pipe, ClassMeta<T> type) throws IOException, ParseException, ExecutableException {
      return ctx.doRead(this, pipe, type);
   }

   /**
    * Implementation method.
    *
    * <p>
    * Default implementation throws an {@link UnsupportedOperationException}.
    *
    * @param <E> The element type.
    * @param pipe The parser input.
    * @param c The collection being loaded.
    * @param elementType The class type of the elements, or <jk>null</jk> to default to whatever is being parsed.
    * @return The same collection that was passed in to allow this method to be chained.
    * @throws Exception If thrown from underlying stream, or if the input contains a syntax error or is malformed.
    */
   protected <E> Collection<E> doReadIntoCollection(ParserPipe pipe, Collection<E> c, Type elementType) throws Exception {
      throw uoex("Parser '%s' does not support this method.", cn(getClass()));
   }

   /**
    * Implementation method.
    *
    * <p>
    * Default implementation throws an {@link UnsupportedOperationException}.
    *
    * @param <K> The key type.
    * @param <V> The value type.
    * @param pipe The parser input.
    * @param m The map being loaded.
    * @param keyType The class type of the keys, or <jk>null</jk> to default to <code>String.<jk>class</jk></code>.
    * @param valueType The class type of the values, or <jk>null</jk> to default to whatever is being parsed.
    * @return The same map that was passed in to allow this method to be chained.
    * @throws Exception If thrown from underlying stream, or if the input contains a syntax error or is malformed.
    */
   protected <K,V> Map<K,V> doReadIntoMap(ParserPipe pipe, Map<K,V> m, Type keyType, Type valueType) throws Exception {
      throw uoex("Parser '%s' does not support this method.", cn(getClass()));
   }

   /**
    * Give the specified dictionary name, resolve it to a class.
    *
    * @param typeName The dictionary name to resolve.
    * @param pMeta The bean property we're currently parsing.
    *    <br>Can be <jk>null</jk> (the <c>@MarshalledProp(dictionary={})</c> registry lookup is skipped).
    * @param eType The expected type we're currently parsing.
    *    <br>Can be <jk>null</jk> (the <c>@Marshalled(dictionary={})</c> registry lookup on the expected type is skipped).
    * @return The resolved class, or <jk>null</jk> if the type name could not be resolved.
    */
   protected final ClassMeta<?> getClassMeta(String typeName, BeanPropertyMeta pMeta, ClassMeta<?> eType) {
      BeanRegistry br = null;

      // Resolve via @MarshalledProp(dictionary={})
      if (nn(pMeta)) {
         br = (BeanRegistry) pMeta.getBeanRegistry();
         if (nn(br) && br.hasName(typeName))
            return br.getClassMeta(typeName);
      }

      // Resolve via @Marshalled(dictionary={}) on the expected type where the
      // expected type is an interface with subclasses.
      if (nn(eType)) {
         br = eType.getBeanRegistry();
         if (nn(br) && br.hasName(typeName))
            return br.getClassMeta(typeName);
      }

      // Last resort, resolve using the session registry.
      return getBeanRegistry().getClassMeta(typeName);
   }

   /**
    * Debug output lines.
    *
    * @see Parser.Builder#debugOutputLines(int)
    * @return
    *    The number of lines of input before and after the error location to be printed as part of the exception message.
    */
   protected final int getDebugOutputLines() { return ctx.getDebugOutputLines(); }

   /**
    * Returns the Java method that invoked this parser.
    *
    * <p>
    * When using the REST API, this is the Java method invoked by the REST call.
    * Can be used to access annotations defined on the method or class.
    *
    * @return The Java method that invoked this parser, or <jk>null</jk> if not set.
   */
   protected final Method getJavaMethod() { return javaMethod; }

   /**
    * Parser listener.
    *
    * @see Parser.Builder#listener(Class)
    * @return
    *    Class used to listen for errors and warnings that occur during parsing, or <jk>null</jk> if none was configured.
    */
   protected final Class<? extends ParserListener> getListenerClass() { return ctx.getListener(); }

   /**
    * Returns the outer object used for instantiating top-level non-static member classes.
    *
    * <p>
    * When using the REST API, this is the servlet object.
    *
    * @return The outer object, or <jk>null</jk> if none was specified.
   */
   protected final Object getOuter() { return outer; }

   /**
    * Creates a reusable {@link StringBuilder} object from an internal pool.
    *
    * <p>
    * String builders are returned to the pool by calling {@link #returnStringBuilder(StringBuilder)}.
    *
    * @return A new or previously returned string builder.
    */
   protected final StringBuilder getStringBuilder() {
      if (sbStack.isEmpty())
         return new StringBuilder();
      return sbStack.pop();
   }

   /**
    * Auto-close streams.
    *
    * @see Parser.Builder#autoCloseStreams()
    * @return
    *    <jk>true</jk> if <l>InputStreams</l> and <l>Readers</l> passed into parsers will be closed
    *    after parsing is complete.
    */
   protected final boolean isAutoCloseStreams() { return ctx.isAutoCloseStreams(); }

   /**
    * Trim parsed strings.
    *
    * @see Parser.Builder#trimStrings()
    * @return
    *    <jk>true</jk> if string values will be trimmed of whitespace using {@link String#trim()} before being added to
    *    the POJO.
    */
   protected final boolean isTrimStrings() { return trimStrings; }

   /**
    * Returns the effective {@link Nulls} default for this session — the per-session override (set via
    * {@link ParserSession.Builder#nulls(Nulls)}) when present, otherwise the parser context's
    * {@link Parser#getNulls()} value.
    *
    * @return The current session-level value (never <jk>null</jk>; {@link Nulls#NOT_SET} when unconfigured).
    * @since 10.0.0
    */
   public final Nulls getNulls() { return nulls; }

   /**
    * Unbuffered.
    *
    * @see Parser.Builder#unbuffered()
    * @return
    *    <jk>true</jk> if parsers don't use internal buffering during parsing.
    */
   protected final boolean isUnbuffered() { return ctx.isUnbuffered(); }

   /**
    * Duration parse hint format.
    *
    * @return The configured duration parse hint format.
    */
   protected final DurationFormat getDurationFormat() { return ctx.getMarshallingContext().getDurationFormat(); }

   /**
    * Period parse hint format.
    *
    * @return The configured period parse hint format.
    */
   protected final PeriodFormat getPeriodFormat() { return ctx.getMarshallingContext().getPeriodFormat(); }

   /**
    * Calendar parse hint format.
    *
    * @return The configured calendar parse hint format.
    */
   protected final CalendarFormat getCalendarFormat() { return ctx.getMarshallingContext().getCalendarFormat(); }

   /**
    * Date parse hint format.
    *
    * @return The configured date parse hint format.
    */
   protected final DateFormat getDateFormat() { return ctx.getMarshallingContext().getDateFormat(); }

   /**
    * Temporal parse hint format.
    *
    * @return The configured temporal parse hint format.
    */
   protected final TemporalFormat getTemporalFormat() { return ctx.getMarshallingContext().getTemporalFormat(); }

   /**
    * Time-zone parse hint format.
    *
    * @return The configured time-zone parse hint format.
    */
   protected final TimeZoneFormat getTimeZoneFormat() { return ctx.getMarshallingContext().getTimeZoneFormat(); }

   /**
    * Locale parse hint format.
    *
    * @return The configured locale parse hint format.
    */
   protected final LocaleFormat getLocaleFormat() { return ctx.getMarshallingContext().getLocaleFormat(); }

   /**
    * Parses an ISO 8601 / numeric wire value into a {@link Duration} using this session's configured
    * {@linkplain #getDurationFormat() duration format} as the disambiguation hint.
    *
    * @param s The wire value to parse. <jk>null</jk> or empty returns <jk>null</jk>.
    * @return The parsed {@link Duration}, or <jk>null</jk> if {@code s} is <jk>null</jk> or empty.
    */
   protected final Duration readDuration(String s) {
      return Iso8601Utils.parseDuration(s, getDurationFormat());
   }

   /**
    * Parses an ISO 8601 / numeric wire value into a {@link Period} using this session's configured
    * {@linkplain #getPeriodFormat() period format} as the disambiguation hint.
    *
    * @param s The wire value to parse. <jk>null</jk> or empty returns <jk>null</jk>.
    * @return The parsed {@link Period}, or <jk>null</jk> if {@code s} is <jk>null</jk> or empty.
    */
   protected final Period readPeriod(String s) {
      return Iso8601Utils.parsePeriod(s, getPeriodFormat());
   }

   /**
    * Parses an ISO 8601 wire value into a {@link Date} target using this session's configured
    * {@linkplain #getDateFormat() date format} and {@linkplain #getTimeZone() time zone}.
    *
    * @param <T> The target type (unbounded to match {@link Iso8601Utils#parseDate}).
    * @param s The wire value to parse. <jk>null</jk> returns <jk>null</jk>.
    * @param cm The target class metadata.
    * @return The parsed value, or <jk>null</jk> if {@code s} is <jk>null</jk> or the target is not a
    *    recognized {@link Date} type.
    */
   protected final <T> T readDate(String s, ClassMeta<T> cm) {
      return Iso8601Utils.parseDate(s, cm, getDateFormat(), getTimeZone());
   }

   /**
    * Parses an ISO 8601 wire value into a {@link Calendar} or {@link XMLGregorianCalendar}
    * target using this session's configured {@linkplain #getCalendarFormat() calendar format} and
    * {@linkplain #getTimeZone() time zone}.
    *
    * @param <T> The target type (unbounded because {@link XMLGregorianCalendar} is not a
    *    {@link Calendar} subclass).
    * @param s The wire value to parse. <jk>null</jk> returns <jk>null</jk>.
    * @param cm The target class metadata.
    * @return The parsed value, or <jk>null</jk> if {@code s} is <jk>null</jk> or the target is not a
    *    recognized calendar type.
    */
   protected final <T> T readCalendar(String s, ClassMeta<T> cm) {
      return Iso8601Utils.parseCalendar(s, cm, getCalendarFormat(), getTimeZone());
   }

   /**
    * Parses an ISO 8601 wire value into the specified {@link Temporal} subtype using
    * this session's configured {@linkplain #getTemporalFormat() temporal format} and
    * {@linkplain #getTimeZone() time zone}.
    *
    * @param <T> The target type (unbounded to match {@link Iso8601Utils#parseTemporal}).
    * @param s The wire value to parse. <jk>null</jk> returns <jk>null</jk>.
    * @param cm The target class metadata.
    * @return The parsed value, or <jk>null</jk> if {@code s} is <jk>null</jk> or the target is not a
    *    {@link Temporal} subtype.
    */
   protected final <T> T readTemporal(String s, ClassMeta<T> cm) {
      return Iso8601Utils.parseTemporal(s, cm, getTemporalFormat(), getTimeZone());
   }

   /**
    * Enters one level of recursive databind parsing, enforcing the shared {@link Builder#maxParseDepth(int)}
    * budget (default {@value #DEFAULT_MAX_PARSE_DEPTH}).
    *
    * <p>
    * Binary codec sessions (CBOR, Protobuf, MsgPack) call this at their recursive databind entry point before
    * descending into a nested array/map/message element, and must call {@link #exitParseDepth()} in a matching
    * <jk>finally</jk> block regardless of outcome.  Exceeding the budget throws a {@link ParseException} so an
    * adversarial deeply-nested document fails cleanly instead of exhausting the call stack with a
    * {@link StackOverflowError}.
    *
    * <p>
    * Intentionally not applied to the JSON/XML/text parsers, whose recursive-descent parsers already rely on
    * {@link StackOverflowError} conversion at the outer parse boundary.
    *
    * @throws ParseException If the configured maximum parse depth was exceeded.
    */
   protected final void enterParseDepth() throws ParseException {
      if (++parseDepth > maxParseDepth) {
         parseDepth--;
         throw new ParseException(this, "Maximum parse depth exceeded (%s).", maxParseDepth);
      }
   }

   /**
    * Exits one level of recursive databind parsing previously entered via {@link #enterParseDepth()}.
    *
    * <p>
    * Must be called exactly once per successful {@link #enterParseDepth()} call, in a matching <jk>finally</jk>
    * block so the depth counter is restored even when the nested parse throws.
    */
   protected final void exitParseDepth() {
      parseDepth--;
   }

   /**
    * Runs a local, parser-controlled allocation (e.g. pre-sizing an array/collection/buffer from a
    * wire-declared count) and converts an {@link OutOfMemoryError} thrown specifically from it into a bounded
    * {@link ParseException}.
    *
    * <p>
    * Only an {@link OutOfMemoryError} thrown from {@code alloc}'s own execution is converted here.  Any other
    * {@link OutOfMemoryError} &mdash; one raised elsewhere in the call stack, signaling a JVM that is
    * genuinely running out of heap &mdash; is <b>not</b> this method's concern and is never observed by it; a
    * dying JVM is not a client input-validation failure and must not be reported as one.  Format-specific
    * parser sessions should route untrusted-length-driven local allocations through this helper instead of
    * relying on a blanket catch at an outer parse boundary.
    *
    * @param <T> The allocated object's type.
    * @param what A short human-readable description of what's being allocated, used in the exception message
    *    if the allocation fails.
    *    <br>Must not be <jk>null</jk>.
    * @param alloc The allocation to attempt.
    *    <br>Must not be <jk>null</jk>.
    * @return The allocated object.
    * @throws ParseException If {@code alloc} itself threw an {@link OutOfMemoryError}.
    */
   protected final <T> T allocateLocal(String what, Supplier<T> alloc) throws ParseException {
      try {
         return alloc.get();
      } catch (@SuppressWarnings("unused") OutOfMemoryError e) {
         throw new ParseException(this, "Out of memory occurred.  Input too large to parse.  Allocation: %s", what);
      }
   }

   /**
    * Marks the current position.
    */
   protected void mark() {
      if (nn(pipe)) {
         Position p = pipe.getPosition();
         mark.line = p.line;
         mark.column = p.column;
         mark.position = p.position;
      }
   }

   /**
    * Specialized warning when an exception is thrown while executing a bean setter.
    *
    * @param p The bean map entry representing the bean property.
    *    <br>Must not be <jk>null</jk>.
    * @param t The throwable that the bean setter threw.
    */
   protected final void onBeanSetterException(BeanPropertyMeta p, Throwable t) {
      if (nn(listener))
         listener.onBeanSetterException(this, t, p);
      var prefix = "";
      addWarning("%sCould not call setValue() on property '%s' of class '%s', exception = %s", prefix, p.getName(), p.getBeanMeta().getBeanInfo(), localizedMessage(t));
   }

   /**
    * Method that gets called when an unknown bean property name is encountered.
    *
    * @param propertyName The unknown bean property name.
    *    <br>Must not be <jk>null</jk>.
    * @param beanMap The bean that doesn't have the expected property.
    *    <br>Must not be <jk>null</jk>.
    * @param value The parsed value.
    *    <br>Can be <jk>null</jk>, in which case whether the property is ignored is governed by
    *    {@link MarshallingContext.Builder#disableIgnoreUnknownNullBeanProperties()} rather than
    *    {@link MarshallingContext.Builder#ignoreUnknownBeanProperties()}.
    * @throws ParseException
    *    Automatically thrown if {@link MarshallingContext.Builder#ignoreUnknownBeanProperties()} setting on this parser is
    *    <jk>false</jk>
    * @param <T> The class type of the bean map that doesn't have the expected property.
    */
   protected final <T> void onUnknownProperty(String propertyName, BeanMap<T> beanMap, Object value) throws ParseException {
      var bmcm = (ClassMeta<T>) beanMap.getBeanInfo();
      if (propertyName.equals(getBeanTypePropertyName(bmcm)))
         return;
      if (! isIgnoreUnknownBeanProperties() && (nn(value) || ! isIgnoreUnknownNullBeanProperties()))
         throw new ParseException(this, "Unknown property '%s' encountered while trying to parse into class '%s'", propertyName, bmcm);
      if (nn(listener))
         listener.onUnknownBeanProperty(this, propertyName, bmcm.inner(), beanMap.getBean());
   }

   @Override /* Overridden from MarshallingSession */
   protected FluentMap<String,Object> properties() {
      return super.properties()
         .a("javaMethod", javaMethod)
         .a("listener", listener)
         .a("outer", outer)
         .a("trimStrings", trimStrings)
         .a("nulls", nulls)
         .a("maxParseDepth", maxParseDepth);
   }

   /**
    * Returns a {@link StringBuilder} object back into the internal reuse pool.
    *
    * @param sb The string builder to return to the pool.  No-op if <jk>null</jk>.
    */
   protected final void returnStringBuilder(StringBuilder sb) {
      if (sb == null)
         return;
      sb.setLength(0);
      sbStack.push(sb);
   }

   /**
    * Sets the current class being parsed for proper error messages.
    *
    * @param currentClass The current class being parsed.
    */
   protected final void setCurrentClass(ClassMeta<?> currentClass) { this.currentClass = currentClass; }

   /**
    * Sets the current bean property being parsed for proper error messages.
    *
    * @param currentProperty The current property being parsed.
    */
   protected final void setCurrentProperty(BeanPropertyMeta currentProperty) { this.currentProperty = currentProperty; }

   /**
    * The {@link #createPipe(Object)} method should call this method to set the pipe for debugging purposes.
    *
    * @param pipe The pipe created for this session.
    * @return The same pipe.
    */
   protected ParserPipe setPipe(ParserPipe pipe) {
      this.pipe = pipe;
      return pipe;
   }

   /**
    * Trims the specified object if it's a <c>String</c> and {@link #isTrimStrings()} returns <jk>true</jk>.
    *
    * @param <K> The object type.
    * @param o The object to trim.
    * @return The trimmed string if it's a string.
    */
   protected final <K> K trim(K o) {
      if (isTrimStrings() && o instanceof String o2)
         return (K)o2.trim();
      return o;

   }

   /**
    * Trims the specified string if {@link ParserSession#isTrimStrings()} returns <jk>true</jk>.
    *
    * @param s The input string to trim.
    * @return The trimmed string, or <jk>null</jk> if the input was <jk>null</jk>.
    */
   protected final String trim(String s) {
      if (isTrimStrings() && nn(s))
         return s.trim();
      return s;
   }

   /**
    * Unmarks the current position.
    */
   protected void unmark() {
      mark.line = -1;
      mark.column = -1;
      mark.position = -1;
   }

   /**
    * Invokes the specified swap on the specified object.
    *
    * @param swap The swap to invoke.
    *    <br>Must not be <jk>null</jk>.
    * @param o The input object.
    * @param eType The expected type.
    * @return The swapped object.
    * @throws ParseException If swap method threw an exception.
    */
   protected Object unswap(ObjectSwap swap, Object o, ClassMeta<?> eType) throws ParseException {
      try {
         return swap.unswap(this, o, eType);
      } catch (Exception e) {
         throw new ParseException(e);
      }
   }
}