/*
    * 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.parser;
  
  import static org.apache.juneau.commons.utils.AssertionUtils.*;
  import static org.apache.juneau.commons.utils.StringUtils.*;
  import static org.apache.juneau.commons.utils.ThrowableUtils.*;
  import static org.apache.juneau.commons.utils.Utils.*;
  
  import java.io.*;
  import java.lang.reflect.*;
  import java.nio.charset.*;
  import java.util.*;
  import java.util.function.*;
  
  import org.apache.juneau.*;
  import org.apache.juneau.annotation.*;
  import org.apache.juneau.collections.*;
  import org.apache.juneau.commons.collections.FluentMap;
  import org.apache.juneau.commons.reflect.*;
  import org.apache.juneau.cp.*;
  import org.apache.juneau.httppart.*;
  import org.apache.juneau.objecttools.*;
  import org.apache.juneau.swap.*;
  
  /**
   * 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>
   */
  public class ParserSession extends BeanSession {
  	/**
  	 * Builder class.
  	 */
  	public static class Builder extends BeanSession.Builder {
  
  		private HttpPartSchema schema;
  		private Method javaMethod;
  		private Object outer;
  		private Parser ctx;
  
  		/**
  		 * Constructor
  		 *
  		 * @param ctx The context creating this session.
  		 * 	<br>Cannot be <jk>null</jk>.
  		 */
  		protected Builder(Parser ctx) {
  			super(assertArgNotNull("ctx", ctx).getBeanContext());
  			this.ctx = ctx;
  			mediaTypeDefault(ctx.getPrimaryMediaType());
  		}
  
  		@Override /* Overridden from Builder */
  		public <T> Builder apply(Class<T> type, Consumer<T> apply) {
  			super.apply(type, apply);
  			return this;
  		}
  
  		@Override
  		public ParserSession build() {
  			return new ParserSession(this);
  		}
  
  		@Override /* Overridden from Builder */
  		public Builder debug(Boolean value) {
  			super.debug(value);
  			return 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>.
  		 * @return This object.
  		 */
 		public Builder javaMethod(Method value) {
 			javaMethod = value;
 			return this;
 		}
 
 		@Override /* Overridden from Builder */
 		public Builder locale(Locale value) {
 			super.locale(value);
 			return this;
 		}
 
 
 		@Override /* Overridden from Builder */
 		public Builder mediaType(MediaType value) {
 			super.mediaType(value);
 			return this;
 		}
 
 		@Override /* Overridden from Builder */
 		public Builder mediaTypeDefault(MediaType value) {
 			super.mediaTypeDefault(value);
 			return this;
 		}
 
 		/**
 		 * 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 Builder outer(Object value) {
 			outer = value;
 			return this;
 		}
 
 		@Override /* Overridden from Builder */
 		public Builder properties(Map<String,Object> value) {
 			super.properties(value);
 			return this;
 		}
 
 		@Override /* Overridden from Builder */
 		public Builder property(String key, Object value) {
 			super.property(key, value);
 			return this;
 		}
 
 		/**
 		 * 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 Builder schema(HttpPartSchema value) {
 			if (nn(value))
 				schema = value;
 			return this;
 		}
 
 		/**
 		 * 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 Builder schemaDefault(HttpPartSchema value) {
 			if (nn(value) && schema == null)
 				schema = value;
 			return this;
 		}
 
 		@Override /* Overridden from Builder */
 		public Builder timeZone(TimeZone value) {
 			super.timeZone(value);
 			return this;
 		}
 
 		@Override /* Overridden from Builder */
 		public Builder timeZoneDefault(TimeZone value) {
 			super.timeZoneDefault(value);
 			return this;
 		}
 
 		@Override /* Overridden from Builder */
 		public Builder unmodifiable() {
 			super.unmodifiable();
 			return this;
 		}
 	}
 
 	/**
 	 * 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 Builder(assertArgNotNull("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.
 	 * @param o The object.
 	 * @param name The name to set.
 	 * @throws ExecutableException Exception occurred on invoked constructor/method/field.
 	 */
 	@SuppressWarnings({ "rawtypes", "unchecked" })
 	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.
 	 * @param o The object.
 	 * @param parent The parent to set.
 	 * @throws ExecutableException Exception occurred on invoked constructor/method/field.
 	 */
 	@SuppressWarnings({ "unchecked", "rawtypes" })
 	protected static final void setParent(ClassMeta<?> cm, Object o, Object parent) throws ExecutableException {
 		Property m = cm.getParentProperty();
 		if (nn(m) && m.canWrite())
 			m.set(o, parent);
 	}
 
 	private final HttpPartSchema schema;
 	private final Method javaMethod;
 	private final Object outer;
 	private final Parser ctx;
 	private final ParserListener listener;
 	private final Stack<StringBuilder> sbStack;
 	private BeanPropertyMeta currentProperty;
 	private ClassMeta<?> currentClass;
 	private Position mark = new Position(-1);
 	private ParserPipe pipe;
 
 	/**
 	 * Constructor.
 	 *
 	 * @param builder The builder for this object.
 	 */
 	protected ParserSession(Builder builder) {
 		super(builder);
 		ctx = builder.ctx;
 		javaMethod = builder.javaMethod;
 		outer = builder.outer;
 		schema = builder.schema;
 		listener = BeanCreator.of(ParserListener.class).type(ctx.getListener()).orElse(null);
 		sbStack = new Stack<>();
 	}
 
 	/**
 	 * 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.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.
 	 */
 	@SuppressWarnings("unchecked")
 	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 #parse(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>.parse(<jv>json</jv>, String.<jk>class</jk>);
 	 *
 	 * 	<jc>// Parse into a bean.</jc>
 	 * 	MyBean <jv>bean</jv> = <jv>parser</jv>.parse(<jv>json</jv>, MyBean.<jk>class</jk>);
 	 *
 	 * 	<jc>// Parse into a bean array.</jc>
 	 * 	MyBean[] <jv>beanArray</jv> = <jv>parser</jv>.parse(<jv>json</jv>, MyBean[].<jk>class</jk>);
 	 *
 	 * 	<jc>// Parse into a linked-list of objects.</jc>
 	 * 	List <jv>list</jv> = <jv>parser</jv>.parse(<jv>json</jv>, LinkedList.<jk>class</jk>);
 	 *
 	 * 	<jc>// Parse into a map of object keys/values.</jc>
 	 * 	Map <jv>map</jv> = <jv>parser</jv>.parse(<jv>json</jv>, TreeMap.<jk>class</jk>);
 	 * </p>
 	 *
 	 * @param <T> The class type of the object being created.
 	 * @param input
 	 * 	The input.
 	 * 	See {@link #parse(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 parse(Object input, Class<T> type) throws ParseException, IOException {
 		try (var pipe = createPipe(input)) {
 			return parseInner(pipe, getClassMeta(type));
 		}
 	}
 
 	/**
 	 * Same as {@link #parse(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 #parse(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 parse(Object input, ClassMeta<T> type) throws ParseException, IOException {
 		try (var pipe = createPipe(input)) {
 			return parseInner(pipe, 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>.parse(<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>.parse(<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>.parse(<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>.parse(<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>.parse(<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 #parse(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).
 	 * 		<li>{@link File} containing system encoded text (or charset defined by
 	 * 			{@link ReaderParser.Builder#fileCharset(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>
 	 * 		<li>{@link File}
 	 * 	</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 BeanSession#getClassMeta(Type,Type...) for argument syntax for maps and collections.
 	 * @throws IOException Thrown by the underlying stream.
 	 */
 	@SuppressWarnings("unchecked")
 	public final <T> T parse(Object input, Type type, Type...args) throws ParseException, IOException {
 		try (var pipe = createPipe(input)) {
 			return (T)parseInner(pipe, getClassMeta(type, args));
 		}
 	}
 
 	/**
 	 * Same as {@link #parse(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>.parse(<jv>json</jv>, String.<jk>class</jk>);
 	 *
 	 * 	<jc>// Parse into a bean.</jc>
 	 * 	MyBean <jv>bean</jv> = <jv>parser</jv>.parse(<jv>json</jv>, MyBean.<jk>class</jk>);
 	 *
 	 * 	<jc>// Parse into a bean array.</jc>
 	 * 	MyBean[] <jv>beanArray</jv> = <jv>parser</jv>.parse(<jv>json</jv>, MyBean[].<jk>class</jk>);
 	 *
 	 * 	<jc>// Parse into a linked-list of objects.</jc>
 	 * 	List <jv>list</jv> = <jv>parser</jv>.parse(<jv>json</jv>, LinkedList.<jk>class</jk>);
 	 *
 	 * 	<jc>// Parse into a map of object keys/values.</jc>
 	 * 	Map <jv>map</jv> = <jv>parser</jv>.parse(<jv>json</jv>, TreeMap.<jk>class</jk>);
 	 * </p>
 	 *
 	 * @param <T> The class type of the object being created.
 	 * @param input
 	 * 	The input.
 	 * 	See {@link #parse(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 parse(String input, Class<T> type) throws ParseException {
 		try (var pipe = createPipe(input)) {
 			return parseInner(pipe, getClassMeta(type));
 		} catch (IOException e) {
 			throw new ParseException(e); // Shouldn't happen.
 		}
 	}
 
 	/**
 	 * Same as {@link #parse(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 #parse(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 parse(String input, ClassMeta<T> type) throws ParseException {
 		try (var pipe = createPipe(input)) {
 			return parseInner(pipe, type);
 		} catch (IOException e) {
 			throw new ParseException(e); // Shouldn't happen.
 		}
 	}
 
 	/**
 	 * Same as {@link #parse(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).
 	 * 		<li>{@link File} containing system encoded text (or charset defined by
 	 * 			{@link ReaderParser.Builder#fileCharset(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>
 	 * 		<li>{@link File}
 	 * 	</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 BeanSession#getClassMeta(Type,Type...) for argument syntax for maps and collections.
 	 */
 	@SuppressWarnings("unchecked")
 	public final <T> T parse(String input, Type type, Type...args) throws ParseException {
 		try (var pipe = createPipe(input)) {
 			return (T)parseInner(pipe, 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[] parseArgs(Object input, Type[] argTypes) throws ParseException {
 		try (var pipe = createPipe(input)) {
 			return doParse(pipe, 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={0}, message={1}.", cns(e), lm(e));
 		} catch (Exception e) {
 			throw new ParseException(this, e, "Exception occurred.  exception={0}, message={1}.", cns(e), lm(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 #parse(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> parseIntoCollection(Object input, Collection<E> c, Type elementType) throws ParseException {
 		try (var pipe = createPipe(input)) {
 			return doParseIntoCollection(pipe, 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={0}, message={1}.", cns(e), lm(e));
 		} catch (Exception e) {
 			throw new ParseException(this, e, "Exception occurred.  exception={0}, message={1}.", cns(e), lm(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 #parse(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> parseIntoMap(Object input, Map<K,V> m, Type keyType, Type valueType) throws ParseException {
 		try (var pipe = createPipe(input)) {
 			return doParseIntoMap(pipe, 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 #doParse(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 parseInner(ParserPipe pipe, ClassMeta<T> type) throws ParseException, IOException {
 		if (type.isVoid())
 			return null;
 		try {
 			return doParse(pipe, type);
 		} 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={0}, message={1}.", cns(e), lm(e));
 		} finally {
 			checkForWarnings();
 		}
 	}
 
 	/**
 	 * Converts the specified <c>JsonMap</c> into a bean identified by the <js>"_type"</js> property in the map.
 	 *
 	 * @param m The map to convert to a bean.
 	 * @param pMeta The current bean property being parsed.
 	 * @param eType The current expected type being parsed.
 	 * @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(JsonMap 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.getBeanSession().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 JsonMap v2)
 						v = cast(v2, pMeta, eType);
 					bm.put(k, v);
 				}
 			});
 			return 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.
 	 * @param s The string to convert.
 	 * @param type The class type to convert the string to.
 	 * @return The string converted as an object of the specified type.
 	 * @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("unchecked")
 	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.isCharSequence() || sType.isObject())) {
 			if (sType.canCreateNewInstanceFromString(outer))
 				o = sType.newInstanceFromString(outer, s);
 			else
 				throw new ParseException(this, "Invalid conversion from string to class ''{0}''", 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)}).
 	 * 		<li>{@link File} containing system encoded text (or whatever the encoding specified by
 	 * 			{@link ReaderParser.Builder#fileCharset(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 File}
 	 * 		<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#doParse(ParserSession,ParserPipe,ClassMeta)}.
 	 *
 	 * <p>
 	 * The default implementation of this method simply calls {@link Parser#doParse(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 doParse(ParserPipe pipe, ClassMeta<T> type) throws IOException, ParseException, ExecutableException {
 		return ctx.doParse(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> doParseIntoCollection(ParserPipe pipe, Collection<E> c, Type elementType) throws Exception {
 		throw unsupportedOp("Parser ''{0}'' 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> doParseIntoMap(ParserPipe pipe, Map<K,V> m, Type keyType, Type valueType) throws Exception {
 		throw unsupportedOp("Parser ''{0}'' 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.
 	 * @param eType The expected type we're currently parsing.
 	 * @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) {
 		var br = (BeanRegistry)null;
 
 		// Resolve via @Beanp(dictionary={})
 		if (nn(pMeta)) {
 			br = pMeta.getBeanRegistry();
 			if (nn(br) && br.hasName(typeName))
 				return br.getClassMeta(typeName);
 		}
 
 		// Resolve via @Bean(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.
 	*/
 	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.
 	 */
 	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.
 	*/
 	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(); }
 
 	/**
 	 * Strict mode.
 	 *
 	 * @see Parser.Builder#strict()
 	 * @return
 	 * 	<jk>true</jk> if strict mode for the parser is enabled.
 	 */
 	protected final boolean isStrict() { return ctx.isStrict(); }
 
 	/**
 	 * 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 ctx.isTrimStrings(); }
 
 	/**
 	 * 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(); }
 
 	/**
 	 * 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.
 	 * @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("{0}Could not call setValue() on property ''{1}'' of class ''{2}'', exception = {3}", prefix, p.getName(), p.getBeanMeta().getClassMeta(), lm(t));
 	}
 
 	/**
 	 * Method that gets called when an unknown bean property name is encountered.
 	 *
 	 * @param propertyName The unknown bean property name.
 	 * @param beanMap The bean that doesn't have the expected property.
 	 * @param value The parsed value.
 	 * @throws ParseException
 	 * 	Automatically thrown if {@link org.apache.juneau.BeanContext.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 {
 		if (propertyName.equals(getBeanTypePropertyName(beanMap.getClassMeta())))
 			return;
 		if (! isIgnoreUnknownBeanProperties())
 			if (nn(value) || ! isIgnoreUnknownNullBeanProperties())
 				throw new ParseException(this, "Unknown property ''{0}'' encountered while trying to parse into class ''{1}''", propertyName, beanMap.getClassMeta());
 		if (nn(listener))
 			listener.onUnknownBeanProperty(this, propertyName, beanMap.getClassMeta().inner(), beanMap.getBean());
 	}
 
 	@Override /* Overridden from BeanSession */
 	protected FluentMap<String,Object> properties() {
 		return super.properties()
 			.a("javaMethod", javaMethod)
 			.a("listener", listener)
 			.a("outer", outer);
 	}
 
 	/**
 	 * 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.
 	 */
 	@SuppressWarnings("unchecked")
 	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.
 	 * @param o The input object.
 	 * @param eType The expected type.
 	 * @return The swapped object.
 	 * @throws ParseException If swap method threw an exception.
 	 */
 	@SuppressWarnings({ "rawtypes", "unchecked" })
 	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);
 		}
 	}
 }