/*
 * 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;

import static org.apache.juneau.commons.function.Suppliers.*;
import static org.apache.juneau.commons.reflect.ReflectionUtils.*;
import static org.apache.juneau.commons.utils.CollectionUtils.*;
import static org.apache.juneau.commons.utils.Shorts.*;
import static org.apache.juneau.marshall.ClassMeta.Category.*;

import java.io.*;
import java.lang.annotation.*;
import java.lang.reflect.*;
import java.lang.reflect.Proxy;
import java.net.*;
import java.time.*;
import java.time.temporal.*;
import java.util.*;
import java.util.function.*;
import java.util.stream.*;

import org.apache.juneau.commons.bean.*;
import org.apache.juneau.commons.collections.*;
import org.apache.juneau.commons.conversion.*;
import org.apache.juneau.commons.function.*;
import org.apache.juneau.commons.http.*;
import org.apache.juneau.commons.inject.*;
import org.apache.juneau.commons.reflect.*;
import org.apache.juneau.commons.utils.*;
import org.apache.juneau.marshall.json.*;
import org.apache.juneau.marshall.swap.spi.*;

/**
 * A wrapper class around the {@link Class} object that provides cached information about that class.
 *
 * <p>
 * Instances of this class can be created through the {@link MarshallingContext#getClassMeta(Class)} method.
 *
 * <p>
 * The {@link MarshallingContext} class will cache and reuse instances of this class except for the following class types:
 * <ul>
 *    <li>Arrays
 *    <li>Maps with non-Object key/values.
 *    <li>Collections with non-Object key/values.
 * </ul>
 *
 * <p>
 * This class is tied to the {@link MarshallingContext} class because it's that class that makes the determination of what is
 * a bean.
 *
 *
 * @param <T> The class type of the wrapped class.
 */
@BeanType(properties = "innerClass,elementType,keyType,valueType,notABeanReason,initException,beanMeta")
@SuppressWarnings({
   "java:S1200", // Class has 23 dependencies, acceptable for this core reflection metadata class
   "java:S1452", // Wildcard required - ClassMeta<?>, ObjectSwap<T,?>, etc. for element/component types
   "java:S3776", // The ClassMeta constructor's type-category chain, findNameProperty()/findParentProperty() annotation scans and getExample() each branch over many type/annotation cases
   "java:S6539", // Monster Class: ClassMeta is a focused reflection-metadata cache; splitting would increase coupling
   "unchecked" // Casts to T, ObjectSwap<T,?>, BuilderSwap<T,?> and Collection/Map<Object,Object> in example creation, newInstance and swap discovery are guaranteed by inner()
})
public final class ClassMeta<T> extends BeanInfo<T> {

   private static class Categories {
      int bits;

      /**
       * Checks whether this instance represents the same set of categories as another.
       *
       * @param cat The other instance to compare against.
       * @return <jk>true</jk> if both instances have identical category bits set.
       */
      public boolean same(Categories cat) {
         return cat.bits == bits;
      }

      boolean is(Category c) {
         return (bits & c.mask) != 0;
      }

      boolean isUnknown() {
         return bits == 0;
      }

      Categories set(Category c) {
         bits |= c.mask;
         return this;
      }
   }

   enum Category {
      MAP(0),
      COLLECTION(1),
      NUMBER(2),
      DECIMAL(3),
      DATE(4),
      ARRAY(5),
      ENUM(6),
      CHARSEQ(8),
      STR(9),
      URI(10),
      BEANMAP(11),
      READER(12),
      INPUTSTREAM(13),
      ARGS(14),
      CALENDAR(15),
      TEMPORAL(16),
      LIST(17),
      SET(18),
      DELEGATE(19),
      ITERATOR(21),
      ITERABLE(22),
      STREAM(23),
      DURATION(24),
      PERIOD(25);

      private final int mask;

      Category(int bitPosition) {
         this.mask = 1 << bitPosition;
      }
   }

   /**
    * Generated classes shouldn't be cacheable to prevent needlessly filling up the cache.
    */
   private static boolean isCacheable(Class<?> c) {
      var n = cn(c);
      var x = n.charAt(n.length() - 1);  // All generated classes appear to end with digits.
      return !(x >= '0' && x <= '9' && (n.indexOf("$$") != -1 || n.startsWith("sun") || n.startsWith("com.sun") || n.indexOf("$Proxy") != -1));
   }

   private final List<ClassMeta<?>> args;                                     // Arg types if this is an array of args.
   private final MarshallingContext marshallingContext;                                     // The bean context that created this object.
   private final Supplier<BuilderSwap<T,?>> builderSwap;                      // The builder swap associated with this bean (if it has one).
   private final Categories cat;                                              // The class category.
   private final Cache<Class<?>,ObjectSwap<?,?>> childSwapMap;                // Maps normal subclasses to ObjectSwaps.
   private final Supplier<List<ObjectSwap<?,?>>> childSwaps;                  // Any ObjectSwaps where the normal type is a subclass of this class.
   private final Cache<Class<?>,ObjectSwap<?,?>> childUnswapMap;              // Maps swap subclasses to ObjectSwaps.
   private final Supplier<String> beanDictionaryName;                             // The dictionary name of this class if it has one.
   private final Supplier<ClassMeta<?>> elementType;                          // If ARRAY or COLLECTION, the element class type.
   private final NullableSupplier<String> example;                            // Example JSON.
   private final NullableSupplier<FieldInfo> exampleField;                    // The @Example-annotated field (if it has one).
   private final NullableSupplier<MethodInfo> exampleMethod;                  // The example() or @Example-annotated method (if it has one).
   private final NullableSupplier<MethodInfo> fromStringMethod;               // Static fromString(String) or equivalent method
   private final NullableSupplier<ClassInfoTyped<? extends T>> implClass;     // The implementation class to use if this is an interface.
   private final Supplier<KeyValueTypes> keyValueTypes;                        // Key and value types for MAP types.
   private final Supplier<Type[]> parameters;                                  // Type parameters for converter dispatch.
   private final NullableSupplier<MarshalledFilter> marshalledFilter;
   private final Supplier<Property<T,Object>> nameProperty;                   // The method to set the name on an object (if it has one).
   private final NullableSupplier<ConstructorInfo> noArgConstructor;          // The no-arg constructor for this class (if it has one).
   private final Supplier<Property<T,Object>> parentProperty;                 // The method to set the parent on an object (if it has one).
   private final Cache<String,Optional<?>> properties;
   private final NullableSupplier<ConstructorInfo> stringConstructor;         // The X(String) constructor (if it has one).
   private final Supplier<List<ObjectSwap<T,?>>> swaps;                       // The object POJO swaps associated with this bean (if it has any).
   private final NullableSupplier<BeanMeta.BeanMetaValue<T>> beanMeta;
   private final boolean nonStaticMemberClass;                                // Class.isMemberClass() is a native call, so it is evaluated once here.

   private record KeyValueTypes(ClassMeta<?> keyType, ClassMeta<?> valueType) {
      Optional<ClassMeta<?>> optKeyType() { return o(keyType()); }
      Optional<ClassMeta<?>> optValueType() { return o(valueType()); }
   }

   /**
    * Construct a new {@code ClassMeta} based on the specified {@link Class}.
    *
    * @param innerClass The class being wrapped.
    * @param marshallingContext The bean context that created this object.
    */
   ClassMeta(Class<T> innerClass, MarshallingContext marshallingContext) {
      super(innerClass);
      this.marshallingContext = marshallingContext;
      this.nonStaticMemberClass = isMemberClass() && isNotStatic();
      this.cat = new Categories();

      var ap = marshallingContext.getAnnotationProvider();

      if (isAssignableTo(Delegate.class)) {
         cat.set(DELEGATE);
      }
      if (isEnum()) {
         cat.set(ENUM);
      } else if (isAssignableTo(CharSequence.class)) {
         cat.set(CHARSEQ);
         if (is(String.class)) {
            cat.set(STR);
         }
      } else if (isAssignableTo(Number.class) || isAny(byte.class, short.class, int.class, long.class, float.class, double.class)) {
         cat.set(NUMBER);
         if (isAssignableToAny(Float.class, Double.class) || isAny(float.class, double.class)) {
            cat.set(DECIMAL);
         }
      } else if (isAssignableTo(Collection.class)) {
         cat.set(COLLECTION);
         if (isAssignableTo(Set.class)) {
            cat.set(SET);
         } else if (isAssignableTo(List.class)) {
            cat.set(LIST);
         }
      } else if (isAssignableTo(Iterable.class)) {
         cat.set(ITERABLE);
      } else if (isAssignableTo(Iterator.class) || isAssignableTo(Enumeration.class)) {
         cat.set(ITERATOR);
      } else if (isAssignableTo(BaseStream.class)) {
         cat.set(STREAM);
      } else if (isAssignableTo(Map.class)) {
         cat.set(MAP);
         if (isAssignableTo(BeanMap.class)) {
            cat.set(BEANMAP);
         }
      } else if (isAssignableToAny(Date.class, Calendar.class)) {
         if (isAssignableTo(Date.class)) {
            cat.set(DATE);
         } else if (isAssignableTo(Calendar.class)) {
            cat.set(CALENDAR);
         }
      } else if (is(Duration.class)) {
         cat.set(DURATION);
      } else if (is(Period.class)) {
         cat.set(PERIOD);
      } else if (isAssignableTo(Temporal.class)) {
         cat.set(TEMPORAL);
      } else if (isAssignableTo(javax.xml.datatype.XMLGregorianCalendar.class)) {
         cat.set(CALENDAR);
      } else if (inner().isArray()) {
         cat.set(ARRAY);
      } else if (isAssignableToAny(URL.class, URI.class) || ap.has(Uri.class, this)) {
         cat.set(URI);
      } else if (isAssignableTo(Reader.class)) {
         cat.set(READER);
      } else if (isAssignableTo(InputStream.class)) {
         cat.set(INPUTSTREAM);
      }

      beanMeta = memoize(this::findBeanMeta);
      builderSwap = memoize(this::findBuilderSwap);
      childSwapMap = Cache.<Class<?>,ObjectSwap<?,?>>create().supplier(this::findSwap).build();
      childSwaps = memoize(this::findChildSwaps);
      childUnswapMap = Cache.<Class<?>,ObjectSwap<?,?>>create().supplier(this::findUnswap).build();
      beanDictionaryName = memoize(this::findBeanDictionaryName);
      elementType = memoize(this::findElementType);
      example = memoize(this::findExample);
      exampleField = memoize(this::findExampleField);
      exampleMethod = memoize(this::findExampleMethod);
      fromStringMethod = memoize(this::findFromStringMethod);
      implClass = memoize(this::findImplClass);
      keyValueTypes = memoize(this::findKeyValueTypes);
      parameters = memoize(this::findParameters);
      marshalledFilter = memoize(this::findMarshalledFilter);
      nameProperty = memoize(this::findNameProperty);
      noArgConstructor = memoize(this::findNoArgConstructor);
      parentProperty = memoize(this::findParentProperty);
      properties = Cache.<String,Optional<?>>create().build();
      stringConstructor = memoize(this::findStringConstructor);
      swaps = memoize(this::findSwaps);

      this.args = null;

      // Publish after fields are assigned so concurrent getClassMeta callers never observe
      // this instance with swaps == null.  Recursive bean-property lookups still resolve:
      // they run from the lazy suppliers after construction, once this entry is cached.
      if (nn(marshallingContext) && nn(marshallingContext.getCmCache()) && isCacheable(innerClass))
         marshallingContext.getCmCache().put(innerClass, this);
   }

   protected ObjectSwap<?,?> findSwap(Class<?> c) {
      return childSwaps.get().stream().filter(x -> x.getNormalClass().isAssignableFrom(c)).findFirst().orElse(null);
   }

   protected ObjectSwap<?,?> findUnswap(Class<?> c) {
      return childSwaps.get().stream().filter(x -> x.getSwapClass().isAssignableFrom(c)).findFirst().orElse(null);
   }


   /**
    * Constructor for args-arrays.
    */
   ClassMeta(List<ClassMeta<?>> args) {
      super((Class<T>)Object[].class);
      this.args = args;
      this.nonStaticMemberClass = false;
      this.childSwaps = memoize(this::findChildSwaps);
      this.childSwapMap = null;
      this.childUnswapMap = null;
      this.cat = new Categories().set(ARGS);
      this.marshallingContext = null;
      this.elementType = memoize(this::findElementType);
      this.keyValueTypes = memoize(this::findKeyValueTypes);
      this.beanMeta = memoize(this::findBeanMeta);
      this.swaps = memoize(this::findSwaps);
      this.fromStringMethod = memoize(this::findFromStringMethod);
      this.exampleMethod = memoize(this::findExampleMethod);
      this.parentProperty = memoize(this::findParentProperty);
      this.nameProperty = memoize(this::findNameProperty);
      this.exampleField = memoize(this::findExampleField);
      this.noArgConstructor = memoize(this::findNoArgConstructor);
      this.properties = Cache.<String,Optional<?>>create().build();
      this.stringConstructor = memoize(this::findStringConstructor);
      this.marshalledFilter = memoize(this::findMarshalledFilter);
      this.builderSwap = memoize(this::findBuilderSwap);
      this.example = memoize(this::findExample);
      this.implClass = memoize(this::findImplClass);
      this.beanDictionaryName = memoize(this::findBeanDictionaryName);
      this.parameters = memoize(this::findParameters);
   }

   /**
    * Copy constructor.
    *
    * <p>
    * Used for creating Map and Collection class metas that shouldn't be cached.
    */
   ClassMeta(ClassMeta<T> mainType, ClassMeta<?> keyType, ClassMeta<?> valueType, ClassMeta<?> elementType) {
      super(mainType.inner());
      this.nonStaticMemberClass = mainType.nonStaticMemberClass;
      this.childSwaps = mainType.childSwaps;
      this.childSwapMap = mainType.childSwapMap;
      this.childUnswapMap = mainType.childUnswapMap;
      this.cat = mainType.cat;
      this.fromStringMethod = mainType.fromStringMethod;
      this.marshallingContext = mainType.marshallingContext;
      this.elementType = elementType != null ? memoize(()->elementType) : mainType.elementType;
      this.keyValueTypes = (keyType != null || valueType != null) ? memoize(()->new KeyValueTypes(keyType, valueType)) : mainType.keyValueTypes;
      this.beanMeta = mainType.beanMeta;
      this.swaps = mainType.swaps;
      this.exampleMethod = mainType.exampleMethod;
      this.args = null;
      this.parentProperty = mainType.parentProperty;
      this.nameProperty = mainType.nameProperty;
      this.exampleField = mainType.exampleField;
      this.noArgConstructor = mainType.noArgConstructor;
      this.properties = mainType.properties;
      this.stringConstructor = mainType.stringConstructor;
      this.marshalledFilter = mainType.marshalledFilter;
      this.builderSwap = mainType.builderSwap;
      this.example = mainType.example;
      this.implClass = mainType.implClass;
      this.beanDictionaryName = mainType.beanDictionaryName;
      this.parameters = memoize(this::findParameters);
   }

   /**
    * Returns <jk>true</jk> if this class can be instantiated as a bean.
    * Returns <jk>false</jk> if this is a non-static member class and the outer object does not match the class type of
    * the defining class.
    *
    * @param outer
    *    The outer class object for non-static member classes.  Can be <jk>null</jk> for non-member or static classes.
    * @return
    *    <jk>true</jk> if a new instance of this bean can be created within the context of the specified outer object.
    */
   public boolean canCreateNewBean(Object outer) {
      var bm = getBeanMeta();
      if (bm == null || ! bm.hasConstructor())
         return false;
      if (nonStaticMemberClass)
         return nn(outer) && bm.getConstructor().hasParameterTypes(outer.getClass());
      return true;
   }

   /**
    * Returns <jk>true</jk> if this class has a no-arg constructor or invocation handler.
    *
    * @return <jk>true</jk> if a new instance of this class can be constructed.
    */
   @Override
   public boolean canCreateNewInstance() {
      if (nonStaticMemberClass)
         return false;
      var bm = getBeanMeta();
      return noArgConstructor.isPresent() || (bm != null && bm.getBeanProxyInvocationHandler() != null) || (isArray() && elementType.get().canCreateNewInstance());
   }

   /**
    * Returns <jk>true</jk> if this class has a no-arg constructor or invocation handler.
    * Returns <jk>false</jk> if this is a non-static member class and the outer object does not match the class type of
    * the defining class.
    *
    * @param outer
    *    The outer class object for non-static member classes.  Can be <jk>null</jk> for non-member or static classes.
    * @return
    *    <jk>true</jk> if a new instance of this class can be created within the context of the specified outer object.
    */
   @Override
   public boolean canCreateNewInstance(Object outer) {
      if (nonStaticMemberClass)
         return nn(outer) && noArgConstructor.map(x -> x.hasParameterTypes(outer.getClass())).orElse(false);
      return canCreateNewInstance();
   }

   /**
    * Returns <jk>true</jk> if this class can call the {@link #newInstanceFromString(Object, String)} method.
    *
    * @param outer
    *    The outer class object for non-static member classes.
    *    Can be <jk>null</jk> for non-member or static classes.
    * @return <jk>true</jk> if this class has a no-arg constructor or invocation handler.
    */
   public boolean canCreateNewInstanceFromString(Object outer) {
      if (fromStringMethod.isPresent())
         return true;
      if (stringConstructor.isPresent()) {
         if (nonStaticMemberClass)
            return nn(outer) && stringConstructor.map(x -> x.hasParameterTypes(outer.getClass(), String.class)).orElse(false);
         return true;
      }
      return false;
   }

   @Override /* Overridden from Object */
   public boolean equals(Object o) {
      return (o instanceof ClassMeta<?>) && super.equals(o);
   }

   @Override /* Overridden from Object */
   public int hashCode() {
      return super.hashCode();
   }

   /**
    * Performs an action on all matching annotations of the specified type defined on this class or parent classes/interfaces in parent-to-child order.
    *
    * @param <A> The annotation type to look for.
    * @param type The annotation to search for.
    * @param filter A predicate to apply to the entries to determine if action should be performed.  Can be <jk>null</jk> (if null, all entries are accepted).
    * @param action An action to perform on the entry.
    * @return This object.
    */
   public <A extends Annotation> ClassMeta<T> forEachAnnotation(Class<A> type, Predicate<A> filter, Consumer<A> action) {
      if (marshallingContext != null) {
         marshallingContext.getAnnotationProvider().find(type, this).stream().map(AnnotationInfo::inner).filter(x -> filter == null || filter.test(x)).forEach(action::accept);
      }
      return this;
   }

   /**
    * Returns the argument metadata at the specified index if this is an args metadata object.
    *
    * @param index The argument index.
    * @return The argument metadata.  Never <jk>null</jk>.
    * @throws BeanRuntimeException If this metadata object is not a list of arguments, or the index is out of range.
    */
   public ClassMeta<?> getArg(int index) {
      if (nn(args) && index >= 0 && index < args.size())
         return args.get(index);
      throw brex("Invalid argument index specified:  %s.  Only %s arguments are defined.", index, args == null ? 0 : args.size());
   }

   /**
    * Returns the argument types of this meta.
    *
    * @return The argument types of this meta, or <jk>null</jk> if this isn't an array of argument types.
    */
   public List<ClassMeta<?>> getArgs() { return args; }

   /**
    * Returns the {@link MarshallingContext} that created this object.
    *
    * <p>
    * Covariantly overrides {@link BeanInfo#getMarshallingContext()} to narrow the return type from
    * {@link Object} (commons SPI) back to {@link MarshallingContext} (marshalling-side concrete type).
    *
    * @return The bean context, or <jk>null</jk> if this is an arguments-array metadata object (see {@link #isArgs()}).
    */
   @Override
   public MarshallingContext getMarshallingContext() { return marshallingContext; }

   /**
    * Returns the {@link BeanConfigContext} snapshot carried by the {@link MarshallingContext} that built this
    * {@link ClassMeta}.
    *
    * <p>
    * Satisfies the {@link BeanInfo#getBeanConfigContext()} commons SPI contract.
    *
    * @return The bean-modeling configuration of the marshalling context.  Never <jk>null</jk>.
    */
   @Override
   public BeanConfigContext getBeanConfigContext() { return marshallingContext.getBeanConfigContext(); }

   /**
    * Returns the {@link BeanMeta} associated with this class.
    *
    * @return
    *    The {@link BeanMeta} associated with this class, or <jk>null</jk> if there is no bean meta associated with
    *    this class.
    */
   public BeanMeta<T> getBeanMeta() {
      return beanMeta.get().beanMeta();
   }

   /**
    * Same as {@link #getBeanMeta()} but derives property names using the supplied {@link PropertyNamer} instead of
    * the one configured on the owning context.
    *
    * <p>
    * Unlike {@link #getBeanMeta()}, the returned {@link BeanMeta} is built fresh on each call and is <b>not</b>
    * cached — the shared, {@code Class}-keyed default {@link BeanMeta} (which uses the context's default namer) is
    * left untouched.  This keeps the cache safe when callers request an alternate property-naming strategy (e.g.
    * {@code MarshallingSession#toBeanMap(Object, PropertyNamer)}).
    *
    * @param propertyNamer The property namer to use for deriving property names.  Must not be <jk>null</jk>.
    * @return
    *    A newly-built {@link BeanMeta} whose property names reflect the supplied namer, or <jk>null</jk> if there is
    *    no bean meta associated with this class.
    */
   public BeanMeta<T> getBeanMeta(PropertyNamer propertyNamer) {
      if (! cat.isUnknown())
         return null;
      return BeanMeta.create(this, implClass.get(), propertyNamer).beanMeta();
   }

   /**
    * Returns the bean registry for this class.
    *
    * <p>
    * This bean registry contains names specified in the {@link Marshalled#dictionary() @Marshalled(dictionary)} annotation
    * defined on the class, regardless of whether the class is an actual bean.
    * This allows interfaces to define subclasses with type names.
    *
    * <p>
    * This is a shortcut for calling getBeanMeta().getBeanRegistry().
    *
    * @return The bean registry for this class, or <jk>null</jk> if no bean registry is associated with it.
    */
   public BeanRegistry getBeanRegistry() {
      return beanMeta.get().optBeanMeta().map(x -> (BeanRegistry) x.getBeanRegistry()).orElse(null);
   }

   /**
    * Returns the builder swap associated with this class.
    *
    * @param session The current bean session (retained for API compatibility).
    * @return The builder swap associated with this class, or <jk>null</jk> if it doesn't exist.
    */
   @SuppressWarnings({
      "java:S1172" // 'session' retained for public-API/binary compatibility; the builder swap is session-independent.
   })
   public BuilderSwap<T,?> getBuilderSwap(MarshallingSession session) {
      return builderSwap.get();
   }

   /**
    * Returns the bean dictionary name associated with this class.
    *
    * <p>
    * The lexical name is defined by {@link Marshalled#typeName() @Marshalled(typeName)}.
    *
    * @return
    *    The type name associated with this bean class, or <jk>null</jk> if there is no type name defined or this
    *    isn't a bean.
    */
   public String getBeanDictionaryName() {
      return beanDictionaryName.get();
   }

   /**
    * For array and {@code Collection} types, returns the class type of the components of the array or
    * {@code Collection}.
    *
    * @return The element class type, or <jk>null</jk> if this class is not an array or Collection.
    */
   @Override
   public ClassMeta<?> getElementType() { return elementType.get(); }

   /**
    * Returns the example of this class.
    *
    * @param session
    *    The bean session.
    *    <br>Required because the example method may take it in as a parameter.
    * @param jpSession The JSON parser for parsing examples into POJOs.
    * @return An example instance of this class, or <jk>null</jk> if no example is defined or one could not be created.
    */
   public T getExample(MarshallingSession session, JsonParserSession jpSession) {
      try {
         if (example.isPresent())
            return jpSession.read(example.get(), this);
         if (exampleMethod.isPresent())
            return (T)exampleMethod.get().invokeLenient(null, session);
         if (exampleField.isPresent())
            return (T)exampleField.get().get(null);

         if (isCollection()) {
            var etExample = getElementType().getExample(session, jpSession);
            if (nn(etExample)) {
               if (canCreateNewInstance()) {
                  var c = (Collection<Object>)newInstance();
                  c.add(etExample);
                  return (T)c;
               }
               return (T)Collections.singleton(etExample);
            }
         } else if (super.isArray()) {
            var etExample = getElementType().getExample(session, jpSession);
            if (nn(etExample)) {
               var o = Array.newInstance(getElementType().inner(), 1);
               Array.set(o, 0, etExample);
               return (T)o;
            }
         } else if (isMap()) {
            var vtExample = getValueType().getExample(session, jpSession);
            var ktExample = getKeyType().getExample(session, jpSession);
            if (nn(ktExample) && nn(vtExample)) {
               if (canCreateNewInstance()) {
                  var m = (Map<Object,Object>)newInstance();
                  m.put(ktExample, vtExample);
                  return (T)m;
               }
               return (T)Collections.singletonMap(ktExample, vtExample);
            }
         }

         return null;
      } catch (Exception e) {
         throw new ClassMetaRuntimeException(e);
      }
   }

   /**
    * Returns <jk>true</jk> if this class can be instantiated from the specified input type.
    *
    * @param c The input class type.
    * @return <jk>true</jk> if a conversion exists.
    */
   public boolean canConvertFrom(Class<?> c) {
      return BasicConverter.INSTANCE.canConvert(c, inner());
   }

   /**
    * Returns the no-arg constructor for this class based on the {@link Marshalled#implClass()} value.
    *
    * @param conVis The constructor visibility.
    * @return The no-arg constructor for this class, or <jk>null</jk> if it does not exist.
    */
   public ConstructorInfo getImplClassConstructor(Visibility conVis) {
      return implClass.map(x -> x.getNoArgConstructor(conVis).orElse(null)).orElse(null);
   }


   /**
    * For {@code Map} types, returns the class type of the keys of the {@code Map}.
    *
    * @return The key class type, or <jk>null</jk> if this class is not a Map.
    */
   @Override
   public ClassMeta<?> getKeyType() {
      return keyValueTypes.get().keyType();
   }

   /**
    * Returns the method or field annotated with {@link NameProperty @NameProperty}.
    *
    * @return
    *    The method or field  annotated with {@link NameProperty @NameProperty} or <jk>null</jk> if method does not
    *    exist.
    */
   public Property<T,Object> getNameProperty() { return nameProperty.get(); }

   /**
    * Returns the reason why this class is not a bean, or <jk>null</jk> if it is a bean.
    *
    * @return The reason why this class is not a bean, or <jk>null</jk> if it is a bean.
    */
   public synchronized String getNotABeanReason() {
      return beanMeta.get().notABeanReason();
   }

   /**
    * If this is an {@link Optional}, returns an empty optional.
    *
    * <p>
    * Note that if this is a nested optional, will recursively create empty optionals.
    *
    * @return An empty optional, or <jk>null</jk> if this isn't an optional.
    */
   @SuppressWarnings({
      "java:S2789" // null intentionally signals "not an Optional type"; callers check for null
   })
   @Override
   public Optional<?> getOptionalDefault() {
      if (isPrimitiveOptional())
         return oe();
      if (isOptional())
         return o(getElementType().getOptionalDefault());
      return null;
   }

   /**
    * Returns <jk>true</jk> if this is one of the primitive {@link Optional} cousins
    * ({@link OptionalInt}, {@link OptionalLong}, or {@link OptionalDouble}).
    *
    * <p>
    * These types carry no generic element type but are treated as first-class optional types by the
    * marshallers (mirroring the {@link Optional} contract — empty ≡ null/absent, present unwraps to the
    * primitive number).  See {@link #getElementType()} which synthesizes the matching boxed element type.
    *
    * @return <jk>true</jk> if this is {@link OptionalInt}/{@link OptionalLong}/{@link OptionalDouble}.
    */
   public boolean isPrimitiveOptional() {
      return is(OptionalInt.class) || is(OptionalLong.class) || is(OptionalDouble.class);
   }

   /**
    * Returns <jk>true</jk> if this class is {@link Optional} or one of its primitive cousins
    * ({@link OptionalInt}/{@link OptionalLong}/{@link OptionalDouble}).
    *
    * <p>
    * Overrides {@link ClassInfo#isOptional()} so the marshalling layer
    * treats the three primitive optional types as first-class optionals (synthetic boxed element type,
    * empty-as-null contract) without registering swaps for them.
    *
    * @return <jk>true</jk> if this is an optional-like type.
    */
   @Override
   public boolean isOptional() {
      return super.isOptional() || isPrimitiveOptional();
   }

   /**
    * Returns the method or field annotated with {@link ParentProperty @ParentProperty}.
    *
    * @return
    *    The method or field annotated with {@link ParentProperty @ParentProperty} or <jk>null</jk> if method does not
    *    exist.
    */
   public Property<T,Object> getParentProperty() { return parentProperty.get(); }

   /**
    * Returns a lazily-computed, cached property value for this {@link ClassMeta} instance.
    *
    * <p>
    * This method provides a memoization mechanism for expensive computations. The property value is computed
    * on the first call using the provided function, then cached for subsequent calls with the same property name.
    *
    * <p>
    * The function is only invoked once per property name per {@link ClassMeta} instance. Subsequent calls
    * with the same name will return the cached value without re-invoking the function.
    *
    * <h5 class='section'>Thread Safety:</h5>
    * <p>
    * This method is thread-safe. If multiple threads call this method simultaneously with the same property name,
    * the function may be invoked multiple times, but only one result will be cached and returned.
    *
    * <h5 class='section'>Usage:</h5>
    * <p class='bjava'>
    *    <jc>// Compute and cache an expensive property</jc>
    *    Optional&lt;String&gt; <jv>computedValue</jv> = classMeta.<jsm>getProperty</jsm>(<js>"expensiveProperty"</js>, cm -&gt; {
    *       <jc>// Expensive computation that only runs once</jc>
    *       <jk>return</jk> performExpensiveComputation(cm);
    *    });
    *
    *    <jc>// Subsequent calls return cached value</jc>
    *    Optional&lt;String&gt; <jv>cached</jv> = classMeta.<jsm>getProperty</jsm>(<js>"expensiveProperty"</js>, cm -&gt; {
    *       <jc>// This function is NOT called again</jc>
    *       <jk>return</jk> performExpensiveComputation(cm);
    *    });
    * </p>
    *
    * @param <T2> The type of the property value.
    * @param name The unique name identifying this property. Used as the cache key.
    * @param function The function that computes the property value. Receives this {@link ClassMeta} instance as input.
    *    Only invoked if the property hasn't been computed yet. Can return <jk>null</jk>.
    * @return An {@link Optional} containing the property value if the function returned a non-null value,
    *    otherwise an empty {@link Optional}. Never <jk>null</jk>.
    */
   public <T2> Optional<T2> getProperty(String name, Function<ClassMeta<?>,T2> function) {
      return (Optional<T2>)properties.get(name, () -> o(function.apply(this)));
   }

   /**
    * Returns the interface proxy invocation handler for this class.
    *
    * @return The interface proxy invocation handler, or <jk>null</jk> if it does not exist.
    */
   public InvocationHandler getProxyInvocationHandler() {
      return beanMeta.get().optBeanMeta().map(x -> x.getBeanProxyInvocationHandler()).orElse(null);
   }


   /**
    * Returns the serialized (swapped) form of this class if there is an {@link ObjectSwap} associated with it.
    *
    * @param session
    *    The bean session.
    *    <br>Required because the swap used may depend on the media type being serialized or parsed.
    * @return The serialized class type, or this object if no swap is associated with the class.
    */
   public ClassMeta<?> getSerializedClassMeta(MarshallingSession session) {
      var ps = getSwap(session);
      return (ps == null ? this : ps.getSwapClassMeta(session));
   }


   /**
    * Returns the {@link ObjectSwap} associated with this class that's the best match for the specified session.
    *
    * @param session
    *    The current bean session.
    *    <br>If multiple swaps are associated with a class, only the first one with a matching media type will
    *    be returned.
    * @return
    *    The {@link ObjectSwap} associated with this class, or <jk>null</jk> if there are no POJO swaps associated with
    *    this class.
    */
   public ObjectSwap<T,?> getSwap(MarshallingSession session) {
      var swapsList = swaps.get();
      if (! swapsList.isEmpty()) {
         var matchQuant = 0;
         ObjectSwap<T,?> matchSwap = null;

         for (var swap : swapsList) {
            var q = swap.match(session);
            if (q > matchQuant) {
               matchQuant = q;
               matchSwap = swap;
            }
         }

         if (matchSwap != null)
            return matchSwap;
      }
      return null;
   }

   /**
    * Returns <jk>true</jk> if this class can be converted to the specified output type.
    *
    * @param c The output class type.
    * @return <jk>true</jk> if a conversion exists.
    */
   public boolean canConvertTo(Class<?> c) {
      return BasicConverter.INSTANCE.canConvert(inner(), c);
   }

   /**
    * For {@code Map} types, returns the class type of the values of the {@code Map}.
    *
    * @return The value class type, or <jk>null</jk> if this class is not a Map.
    */
   @Override
   public ClassMeta<?> getValueType() {
      return keyValueTypes.get().valueType();
   }

   /**
    * Returns the type parameters for this class as a {@link Type} array suitable for passing to
    * {@link Converter#to(Object, Type, Type...)}.
    *
    * <p>
    * The returned array depends on the kind of type:
    * <ul>
    *    <li>{@link Map} types: {@code [keyType, valueType]}
    *    <li>{@link Collection} and {@link Optional} types: {@code [elementType, elementType.getParameters()...]}
    *       — the element raw class followed by the element's own parameters, recursively flattened by one level.
    *    <li>All other types: empty array.
    * </ul>
    *
    * <h5 class='section'>Examples:</h5>
    * <ul>
    *    <li><c>ClassMeta&lt;Optional&lt;Integer&gt;&gt;</c> → <c>[Integer]</c>
    *    <li><c>ClassMeta&lt;List&lt;Integer&gt;&gt;</c> → <c>[Integer]</c>
    *    <li><c>ClassMeta&lt;Map&lt;String,Integer&gt;&gt;</c> → <c>[String, Integer]</c>
    *    <li><c>ClassMeta&lt;List&lt;Map&lt;String,Integer&gt;&gt;&gt;</c> → <c>[Map, String, Integer]</c>
    * </ul>
    *
    * @return The type parameters as a {@link Type} array, never <jk>null</jk>.
    */
   public Type[] getParameters() { return parameters.get(); }

   private Type[] findParameters() {
      if (isMap()) {
         var kt = getKeyType();
         var vt = getValueType();
         if (kt == null || vt == null)
            return new Type[0];
         return new Type[]{kt.inner(), vt.inner()};
      }
      if (isCollection() || isOptional()) {
         var et = getElementType();
         var etParams = et.getParameters();
         var result = new Type[1 + etParams.length];
         result[0] = et.inner();
         System.arraycopy(etParams, 0, result, 1, etParams.length);
         return result;
      }
      return new Type[0];
   }

   /**
    * Returns <jk>true</jk> if this class has a transform associated with it that allows it to be created from an InputStream.
    *
    * <p>
    * Only returns <jk>true</jk> for types that can be explicitly constructed from an {@link InputStream} (e.g. via a
    * public constructor or static factory). Excludes assignable supertypes and the generic {@code toString()} fallback.
    *
    * @return <jk>true</jk> if this class has a transform associated with it that allows it to be created from an InputStream.
    */
   public boolean hasInputStreamMutater() {
      // Exclude String: BasicConverter maps InputStream→String via stream.toString() which doesn't read content.
      // Exclude supertypes of InputStream (e.g. Object, Closeable): assignability, not an explicit transform.
      if (inner() == String.class || inner().isAssignableFrom(InputStream.class))
         return false;
      return BasicConverter.INSTANCE.canConvert(InputStream.class, inner());
   }

   /**
    * Returns <jk>true</jk> if this class can be instantiated from the specified type via an explicit conversion.
    *
    * <p>
    * Same-type conversions (identity) always return <jk>true</jk>. Strict supertype relationships (where this
    * class is already a supertype of the source) return <jk>false</jk> — those are assignability, not explicit
    * transforms.
    *
    * @param c The class type to convert from.  Must not be <jk>null</jk>.
    * @return <jk>true</jk> if an explicit conversion from {@code c} to this type exists.
    */
   public boolean hasMutaterFrom(Class<?> c) {
      // Same type is always "convertible" (identity).
      if (inner() == c)
         return true;
      // Exclude strict supertype: if this type is already a strict supertype of c, it's assignability only.
      if (inner().isAssignableFrom(c))
         return false;
      // Exclude array→array: MarshallingSession handles those directly; BasicConverter infers
      // array conversions from element types, which can produce false positives here.
      if (inner().isArray() && c.isArray())
         return false;
      // Exclude Collections and Maps — MarshallingSession handles collection/map conversion directly.
      // BasicConverter's generic conversions produce false positives that Mutaters never did.
      if (Collection.class.isAssignableFrom(inner()) || Map.class.isAssignableFrom(inner()))
         return false;
      return BasicConverter.INSTANCE.canConvert(c, inner());
   }

   /**
    * Returns <jk>true</jk> if this class can be instantiated from the specified type via an explicit conversion.
    *
    * @param c The class type to convert from.  Must not be <jk>null</jk>.
    * @return <jk>true</jk> if an explicit conversion from {@code c} to this type exists.
    */
   public boolean hasMutaterFrom(ClassMeta<?> c) {
      return hasMutaterFrom(c.inner());
   }

   /**
    * Returns <jk>true</jk> if this class can be transformed to the specified type via an explicit conversion.
    *
    * <p>
    * Same-type conversions (identity) always return <jk>true</jk>. Cases where the target is already a strict
    * supertype of this class return <jk>false</jk> — those are assignability, not explicit transforms.
    *
    * @param c The class type to convert to.  Must not be <jk>null</jk>.
    * @return <jk>true</jk> if an explicit conversion from this type to {@code c} exists.
    */
   public boolean hasMutaterTo(Class<?> c) {
      // Same type is always "convertible" (identity).
      if (inner() == c)
         return true;
      // Exclude strict supertype: if the target is already a strict supertype of this type, it's assignability only.
      if (c.isAssignableFrom(inner()))
         return false;
      // Exclude array→array: MarshallingSession handles those directly; BasicConverter infers
      // array conversions from element types, which can produce false positives here.
      if (inner().isArray() && c.isArray())
         return false;
      // Exclude Collection/Map targets — MarshallingSession handles collection/map conversion directly.
      // BasicConverter's generic conversions produce false positives that Mutaters never did.
      if (Collection.class.isAssignableFrom(c) || Map.class.isAssignableFrom(c))
         return false;
      return BasicConverter.INSTANCE.canConvert(inner(), c);
   }

   /**
    * Returns <jk>true</jk> if this class can be transformed to the specified type via an explicit conversion.
    *
    * @param c The class type to convert to.  Must not be <jk>null</jk>.
    * @return <jk>true</jk> if an explicit conversion from this type to {@code c} exists.
    */
   public boolean hasMutaterTo(ClassMeta<?> c) {
      return hasMutaterTo(c.inner());
   }

   /**
    * Returns <jk>true</jk> if this class has a transform associated with it that allows it to be created from a Reader.
    *
    * <p>
    * Only returns <jk>true</jk> for types that can be explicitly constructed from a {@link Reader} (e.g. via a
    * public constructor or static factory). Excludes assignable supertypes and the generic {@code toString()} fallback.
    *
    * @return <jk>true</jk> if this class has a transform associated with it that allows it to be created from a Reader.
    */
   public boolean hasReaderMutater() {
      // Exclude String: BasicConverter maps Reader→String via reader.toString() which doesn't read content.
      // Exclude supertypes of Reader (e.g. Object, Closeable): assignability, not an explicit transform.
      if (inner() == String.class || inner().isAssignableFrom(Reader.class))
         return false;
      return BasicConverter.INSTANCE.canConvert(Reader.class, inner());
   }

   /**
    * Returns <jk>true</jk> if this class has a transform associated with it that allows it to be created from a String.
    *
    * <p>
    * Delegates to {@link #hasMutaterFrom(Class)} with {@link String} as the source type, which applies the
    * same exclusions: supertypes of {@link String} (e.g. {@link Object}), arrays, and {@link Collection}/{@link Map}
    * targets are excluded because those are handled by parsers or {@code MarshallingSession}, not explicit string transforms.
    *
    * @return <jk>true</jk> if this class has a transform associated with it that allows it to be created from a String.
    */
   public boolean hasStringMutater() {
      return hasMutaterFrom(String.class);
   }

   /**
    * Returns <jk>true</jk> if this metadata represents an array of argument types.
    *
    * @return <jk>true</jk> if this metadata represents an array of argument types.
    */
   public boolean isArgs() { return cat.is(ARGS); }

   /**
    * Returns <jk>true</jk> if this class is a bean.
    *
    * @return <jk>true</jk> if this class is a bean.
    */
   @Override
   public boolean isBean() { return nn(getBeanMeta()); }

   /**
    * Returns <jk>true</jk> if this class is a subclass of {@link BeanMap}.
    *
    * @return <jk>true</jk> if this class is a subclass of {@link BeanMap}.
    */
   public boolean isBeanMap() { return cat.is(BEANMAP); }

   /**
    * Returns <jk>true</jk> if this class is a {@link Boolean}.
    *
    * @return <jk>true</jk> if this class is a {@link Boolean}.
    */
   @Override
   public boolean isBoolean() { return isAny(boolean.class, Boolean.class); }

   /**
    * Returns <jk>true</jk> if this class is <code><jk>byte</jk>[]</code>.
    *
    * @return <jk>true</jk> if this class is <code><jk>byte</jk>[]</code>.
    */
   public boolean isByteArray() { return is(byte[].class); }

   /**
    * Returns <jk>true</jk> if this class is a {@link Calendar}.
    *
    * @return <jk>true</jk> if this class is a {@link Calendar}.
    */
   public boolean isCalendar() { return cat.is(CALENDAR); }

   /**
    * Returns <jk>true</jk> if this class is a {@link Character}.
    *
    * @return <jk>true</jk> if this class is a {@link Character}.
    */
   public boolean isChar() { return isAny(char.class, Character.class); }

   /**
    * Returns <jk>true</jk> if this class is a subclass of {@link CharSequence}.
    *
    * @return <jk>true</jk> if this class is a subclass of {@link CharSequence}.
    */
   @Override
   public boolean isCharSequence() { return cat.is(CHARSEQ); }

   /**
    * Returns <jk>true</jk> if this class is a subclass of {@link Collection}.
    *
    * @return <jk>true</jk> if this class is a subclass of {@link Collection}.
    */
   @Override
   public boolean isCollection() { return cat.is(COLLECTION); }

   /**
    * Returns <jk>true</jk> if this class is a subclass of {@link Collection} or is an array or {@link Optional}.
    *
    * @return <jk>true</jk> if this class is a subclass of {@link Collection} or is an array or {@link Optional}.
    */
   public boolean isCollectionOrArrayOrOptional() { return cat.is(ARRAY) || is(Optional.class) || cat.is(COLLECTION); }

   /**
    * Returns <jk>true</jk> if this class is a {@link Date}.
    *
    * @return <jk>true</jk> if this class is a {@link Date}.
    */
   public boolean isDate() { return cat.is(DATE); }

   /**
    * Returns <jk>true</jk> if this class is a {@link Date} or {@link Calendar}.
    *
    * @return <jk>true</jk> if this class is a {@link Date} or {@link Calendar}.
    */
   @Override
   public boolean isDateOrCalendar() { return cat.is(DATE) || cat.is(CALENDAR); }

   /**
    * Returns <jk>true</jk> if this class is a {@link Date} or {@link Calendar} or {@link Temporal}.
    *
    * @return <jk>true</jk> if this class is a {@link Date} or {@link Calendar} or {@link Temporal}.
    */
   public boolean isDateOrCalendarOrTemporal() { return cat.is(DATE) || cat.is(CALENDAR) || cat.is(TEMPORAL) || cat.is(PERIOD); }

   /**
    * Returns <jk>true</jk> if this class is a subclass of {@link Float} or {@link Double}.
    *
    * @return <jk>true</jk> if this class is a subclass of {@link Float} or {@link Double}.
    */
   @Override
   public boolean isDecimal() { return cat.is(DECIMAL); }

   /**
    * Returns <jk>true</jk> if this class implements {@link Delegate}, meaning it's a representation of some other
    * object.
    *
    * @return <jk>true</jk> if this class implements {@link Delegate}.
    */
   public boolean isDelegate() { return cat.is(DELEGATE); }

   /**
    * Returns <jk>true</jk> if this class is either {@link Double} or <jk>double</jk>.
    *
    * @return <jk>true</jk> if this class is either {@link Double} or <jk>double</jk>.
    */
   @Override
   public boolean isDouble() { return isAny(Double.class, double.class); }

   /**
    * Returns <jk>true</jk> if this class is either {@link Float} or <jk>float</jk>.
    *
    * @return <jk>true</jk> if this class is either {@link Float} or <jk>float</jk>.
    */
   public boolean isFloat() { return isAny(Float.class, float.class); }

   /**
    * Returns <jk>true</jk> if this class is an {@link InputStream}.
    *
    * @return <jk>true</jk> if this class is an {@link InputStream}.
    */
   public boolean isInputStream() { return cat.is(INPUTSTREAM); }

   /**
    * Returns <jk>true</jk> if this class is either {@link Integer} or <jk>int</jk>.
    *
    * @return <jk>true</jk> if this class is either {@link Integer} or <jk>int</jk>.
    */
   public boolean isInteger() { return isAny(Integer.class, int.class); }

   /**
    * Returns <jk>true</jk> if this class implements {@link Iterable} but is not a {@link Collection}.
    *
    * @return <jk>true</jk> if this class implements {@link Iterable} but is not a {@link Collection}.
    * @since 9.2.1
    */
   public boolean isIterable() { return cat.is(ITERABLE); }

   /**
    * Returns <jk>true</jk> if this class implements {@link Iterator} or {@link Enumeration}.
    *
    * @return <jk>true</jk> if this class implements {@link Iterator} or {@link Enumeration}.
    * @since 9.2.1
    */
   public boolean isIterator() { return cat.is(ITERATOR); }

   /**
    * Returns <jk>true</jk> if this class is an {@link Iterator}, {@link Iterable} (non-Collection), or {@link BaseStream}.
    *
    * <p>
    * These types represent lazily-evaluated sequences that can be serialized as arrays.
    *
    * @return <jk>true</jk> if this class is a streamable type.
    * @since 9.2.1
    */
   public boolean isStreamable() { return cat.is(ITERATOR) || cat.is(ITERABLE) || cat.is(STREAM); }

   /**
    * Returns <jk>true</jk> if this class extends from {@link List}.
    *
    * @return <jk>true</jk> if this class extends from {@link List}.
    */
   public boolean isList() { return cat.is(LIST); }

   /**
    * Returns <jk>true</jk> if this class is either {@link Long} or <jk>long</jk>.
    *
    * @return <jk>true</jk> if this class is either {@link Long} or <jk>long</jk>.
    */
   @Override
   public boolean isLong() { return isAny(Long.class, long.class); }

   /**
    * Returns <jk>true</jk> if this class is a subclass of {@link Map}.
    *
    * @return <jk>true</jk> if this class is a subclass of {@link Map}.
    */
   @Override
   public boolean isMap() { return cat.is(MAP); }

   /**
    * Returns <jk>true</jk> if this class is a subclass of {@link Map} or it's a bean.
    *
    * @return <jk>true</jk> if this class is a subclass of {@link Map} or it's a bean.
    */
   public boolean isMapOrBean() { return cat.is(MAP) || nn(getBeanMeta()); }

   /**
    * Returns <jk>true</jk> if this class is {@link Method}.
    *
    * @return <jk>true</jk> if this class is {@link Method}.
    */
   public boolean isMethod() { return is(Method.class); }

   /**
    * Returns <jk>true</jk> if instance of this object can be <jk>null</jk>.
    *
    * <p>
    * Objects can be <jk>null</jk>, but primitives cannot, except for chars which can be represented by
    * <code>(<jk>char</jk>)0</code>.
    *
    * @return <jk>true</jk> if instance of this class can be null.
    */
   public boolean isNullable() {
      if (isPrimitive())
         return is(char.class);
      return true;
   }

   /**
    * Returns <jk>true</jk> if this class is a subclass of {@link Number}.
    *
    * @return <jk>true</jk> if this class is a subclass of {@link Number}.
    */
   @Override
   public boolean isNumber() { return cat.is(NUMBER); }

   /**
    * Returns <jk>true</jk> if this class is a {@link Reader}.
    *
    * @return <jk>true</jk> if this class is a {@link Reader}.
    */
   public boolean isReader() { return cat.is(READER); }

   /**
    * Returns <jk>true</jk> if this class extends from {@link Set}.
    *
    * @return <jk>true</jk> if this class extends from {@link Set}.
    */
   public boolean isSet() { return cat.is(SET); }

   /**
    * Returns <jk>true</jk> if this class is either {@link Short} or <jk>short</jk>.
    *
    * @return <jk>true</jk> if this class is either {@link Short} or <jk>short</jk>.
    */
   public boolean isShort() { return isAny(Short.class, short.class); }

   /**
    * Returns <jk>true</jk> if this class is a subclass of {@link BaseStream} (includes {@link Stream}).
    *
    * @return <jk>true</jk> if this class is a subclass of {@link BaseStream}.
    * @since 9.2.1
    */
   public boolean isStream() { return cat.is(STREAM); }

   /**
    * Returns <jk>true</jk> if this class is a {@link String}.
    *
    * @return <jk>true</jk> if this class is a {@link String}.
    */
   public boolean isString() { return is(String.class); }

   /**
    * Returns <jk>true</jk> if this class is a {@link Temporal}.
    *
    * @return <jk>true</jk> if this class is a {@link Temporal}.
    */
   @Override
   public boolean isTemporal() { return cat.is(TEMPORAL); }

   /**
    * Returns <jk>true</jk> if this class is a {@link Duration}.
    *
    * @return <jk>true</jk> if this class is a {@link Duration}.
    */
   public boolean isDuration() { return cat.is(DURATION); }

   /**
    * Returns <jk>true</jk> if this class is a {@link Period}.
    *
    * @return <jk>true</jk> if this class is a {@link Period}.
    */
   public boolean isPeriod() { return cat.is(PERIOD); }

   /**
    * Returns <jk>true</jk> if this class is a {@link URI} or {@link URL}.
    *
    * @return <jk>true</jk> if this class is a {@link URI} or {@link URL}.
    */
   @Override
   public boolean isUri() { return cat.is(URI); }

   /**
    * Converts the specified object into an instance of this class.
    *
    * @param o The object to convert.
    * @return The converted object, or <jk>null</jk> if no conversion is available.
    */
   public T mutateFrom(Object o) {
      return BasicConverter.INSTANCE.to(o, inner());
   }

   /**
    * Converts the specified object to the specified output type.
    *
    * @param <O> The output class.
    * @param o The object to convert.
    * @param c The target class.
    * @return The converted object, or <jk>null</jk> if no conversion is available.
    */
   public static <O> O mutateTo(Object o, Class<O> c) {
      return BasicConverter.INSTANCE.to(o, c);
   }

   /**
    * Converts the specified object to the type represented by this class meta.
    *
    * @param <O> The output class.
    * @param o The object to convert.
    * @param c The target class meta.  Must not be <jk>null</jk>.
    * @return The converted object, or <jk>null</jk> if no conversion is available.
    */
   public static <O> O mutateTo(Object o, ClassMeta<O> c) {
      return mutateTo(o, c.inner());
   }

   /**
    * Create a new instance of the main class of this declared type.
    *
    * @return A new instance of the object, or <jk>null</jk> if there is no no-arg constructor on the object.
    * @throws ExecutableException Exception occurred on invoked constructor/method/field.
    */
   @Override
   public T newInstance() throws ExecutableException {
      if (super.isArray())
         return (T)Array.newInstance(inner().getComponentType(), 0);
      if (noArgConstructor.isPresent())
         return noArgConstructor.get().newInstance();
      var h = getProxyInvocationHandler();
      if (nn(h))
         return (T)Proxy.newProxyInstance(this.getClass().getClassLoader(), a(inner(), Serializable.class), h);
      return null;
   }

   /**
    * Same as {@link #newInstance()} except for instantiating non-static member classes.
    *
    * @param outer
    *    The instance of the owning object of the member class instance.
    *    Can be <jk>null</jk> if instantiating a non-member or static class.
    * @return A new instance of the object, or <jk>null</jk> if there is no no-arg constructor on the object.
    * @throws ExecutableException Exception occurred on invoked constructor/method/field.
    */
   public T newInstance(Object outer) throws ExecutableException {
      if (nonStaticMemberClass && noArgConstructor.isPresent())
         return noArgConstructor.get().<T>newInstance(outer);
      return newInstance();
   }

   /**
    * Create a new instance of the main class of this declared type from a <c>String</c> input.
    *
    * <p>
    * In order to use this method, the class must have one of the following methods:
    * <ul>
    *    <li><code><jk>public static</jk> T valueOf(String in);</code>
    *    <li><code><jk>public static</jk> T fromString(String in);</code>
    *    <li><code><jk>public</jk> T(String in);</code>
    * </ul>
    *
    * @param outer
    *    The outer class object for non-static member classes.  Can be <jk>null</jk> for non-member or static classes.
    * @param arg The input argument value.
    * @return A new instance of the object, or <jk>null</jk> if there is no string constructor on the object.
    * @throws ExecutableException Exception occurred on invoked constructor/method/field.
    */
   public T newInstanceFromString(Object outer, String arg) throws ExecutableException {

      if (isEnum()) {
         try {
            return (T) EnumFormat.parse(arg, asEnumClass(inner()));
         } catch (@SuppressWarnings("unused") IllegalArgumentException e) {
            if (marshallingContext.isIgnoreUnknownEnumValues())
               return null;
            throw new ExecutableException("Could not resolve enum value '%s' on class '%s'", arg, cn(inner()));
         }
      }

      if (fromStringMethod.isPresent())
         return (T)fromStringMethod.get().invoke(null, arg);

      if (stringConstructor.isPresent()) {
         if (nonStaticMemberClass)
            return stringConstructor.get().<T>newInstance(outer, arg);
         return stringConstructor.get().<T>newInstance(arg);
      }
      throw exex("No string constructor or valueOf(String) method found for class '%s'", cn(inner()));
   }

   /**
    * Similar to {@link #equals(Object)} except primitive and Object types that are similar are considered the same.
    * (e.g. <jk>boolean</jk> == <c>Boolean</c>).
    *
    * @param cm The class meta to compare to. Can be <jk>null</jk>, in which case this method returns <jk>false</jk>.
    * @return <jk>true</jk> if the specified class-meta is equivalent to this one.
    */
   public boolean same(ClassMeta<?> cm) {
      if (cm == null)
         return false;
      if (equals(cm))
         return true;
      return (isPrimitive() && cat.same(cm.cat));
   }

   @Override /* Overridden from Object */
   public String toString() {
      return toString(false);
   }

   /**
    * Same as {@link #toString()} except use simple class names.
    *
    * @param simple Print simple class names only (no package).
    * @return A new string.
    */
   public String toString(boolean simple) {
      return toString(new StringBuilder(), simple).toString();
   }

   /**
    * Converts the specified object to a string.
    *
    * @param t The object to convert.  Can be <jk>null</jk> (returns <jk>null</jk>).
    * @return The object converted to a string, or <jk>null</jk> if the object was null.
    */
   public String toString(Object t) {
      if (t == null)
         return null;
      if (isEnum())
         return marshallingContext.getEnumFormat().format((Enum<?>)t);
      return t.toString();
   }

   private ObjectSwap<T,?> createSwap(Swap s) {
      var c = s.value();
      if (ClassUtils.isVoid(c))
         c = s.impl();
      var ci = info(c);

      if (ci.isAssignableTo(ObjectSwap.class)) {
         var ps = BeanInstantiator.of(ObjectSwap.class).type(ci).run();
         if (s.mediaTypes().length > 0)
            ps.forMediaTypes(MediaType.ofAll(s.mediaTypes()));
         if (! s.template().isEmpty())
            ps.withTemplate(s.template());
         return ps;
      }

      if (ci.isAssignableTo(Surrogate.class)) {
         List<SurrogateSwap<?,?>> l = SurrogateSwap.findObjectSwaps(c, marshallingContext);
         return first(l).map(x -> (ObjectSwap<T,?>)x).orElse(null);
      }

      throw new ClassMetaRuntimeException(c, "Invalid swap class '%s' specified.  Must extend from ObjectSwap or Surrogate.", c);
   }

   private String findBeanDictionaryName() {
      if (marshallingContext == null)
         return null;

      var d = beanMeta.get().optBeanMeta().map(x -> x.getDictionaryName()).orElse(null);
      if (nn(d))
         return d;

      // Note that @Marshalled(typeName) can be defined on non-bean types, so
      // we have to check again.
      return marshallingContext.getAnnotationProvider().find(Marshalled.class, this)
         .stream()
         .map(AnnotationInfo::inner)
         .filter(x -> ! x.typeName().isEmpty())
         .map(Marshalled::typeName)
         .findFirst()
         .orElse(null);
   }

   private BeanMeta.BeanMetaValue<T> findBeanMeta() {
      if (! cat.isUnknown())
         return new BeanMeta.BeanMetaValue<>((BeanMeta<T>)null, "Known non-bean type");
      return BeanMeta.create(this, implClass.get());
   }

   private KeyValueTypes findKeyValueTypes() {
      if (cat.is(MAP) && ! cat.is(BEANMAP)) {
         // If this is a MAP, see if it's parameterized (e.g. AddressBook extends HashMap<String,Person>)
         var typeParams = marshallingContext.findParameters(inner(), inner());
         if (nn(typeParams) && typeParams.length == 2) {
            return new KeyValueTypes(typeParams[0], typeParams[1]);
         }
         return new KeyValueTypes(marshallingContext.getClassMeta(Object.class), marshallingContext.getClassMeta(Object.class));
      }
      return new KeyValueTypes(null, null);
   }

   private ClassMeta<?> findElementType() {
      if (marshallingContext == null)
         return null;
      // Primitive optional types carry no generic parameter — synthesize the matching boxed element type so
      // the first-class optional path (serialize unwrap / parse element-typed wrap) has a target type.
      if (is(OptionalInt.class))
         return marshallingContext.getClassMeta(Integer.class);
      if (is(OptionalLong.class))
         return marshallingContext.getClassMeta(Long.class);
      if (is(OptionalDouble.class))
         return marshallingContext.getClassMeta(Double.class);
      if (cat.is(ARRAY)) {
         return marshallingContext.getClassMeta(inner().getComponentType());
      } else if (cat.is(COLLECTION) || cat.is(ITERABLE) || cat.is(ITERATOR) || cat.is(STREAM) || is(Optional.class)) {
         var typeParams = marshallingContext.findParameters(inner(), inner());
         if (nn(typeParams) && typeParams.length == 1) {
            return typeParams[0];
         }
         return marshallingContext.getClassMeta(Object.class);
      }
      return null;
   }

   private BuilderSwap<T,?> findBuilderSwap() {
      var bc = marshallingContext;
      if (bc == null)
         return null;
      return (BuilderSwap<T,?>)BuilderSwap.findSwapFromObjectClass(bc, inner(), bc.getBeanConstructorVisibility(), bc.getBeanMethodVisibility());
   }

   private List<ObjectSwap<T,?>> findSwaps() {
      if (marshallingContext == null)
         return l();

      var list = new ArrayList<ObjectSwap<T,?>>();
      var swapArray = marshallingContext.getSwaps();
      if (! swapArray.isEmpty()) {
         var innerClass = inner();
         swapArray.stream().filter(f -> f.getNormalClass().isAssignableFrom(innerClass)).forEach(f -> list.add((ObjectSwap<T,?>)f));
      }

      var ap = marshallingContext.getAnnotationProvider();
      ap.find(Swap.class, this).stream().map(AnnotationInfo::inner).forEach(x -> list.add(createSwap(x)));

      // @Marshalled(as=STRING) installs an AutoStringSwap before any auto-detection.
      if (list.isEmpty()) {
         var marshalledList = ap.find(Marshalled.class, this);
         if (marshalledList.stream().anyMatch(x -> x.inner().as() == MarshalledAs.STRING))
            list.add(new AutoStringSwap<>(this));
      }

      // @MarshalledIgnore on TYPE — skip entirely: serialize as null, parse as null.
      // Use String.class (not Object.class) as swapClass so sType.isObject() stays false
      // and the serializer correctly emits "null" when swap() returns null.
      if (list.isEmpty() && ap.has(MarshalledIgnore.class, this))
         list.add(new ObjectSwap<T,String>(inner(), String.class) {
            @Override public String swap(MarshallingSession session, T o) { return null; }
            @Override public T unswap(MarshallingSession session, String s, ClassMeta<?> hint) { return null; }
         });

      var ds = DefaultSwaps.find(this);
      if (ds == null && !isStreamable()) {
         ds = AutoObjectSwap.find(marshallingContext, this);
      if (ds == null)
         ds = AutoNumberSwap.find(marshallingContext, this);
      if (ds == null)
         ds = AutoMapSwap.find(marshallingContext, this);
      if (ds == null)
         ds = AutoListSwap.find(marshallingContext, this);
      }

      if (nn(ds))
         list.add((ObjectSwap<T,?>)ds);

      return u(list);
   }

   private List<ObjectSwap<?,?>> findChildSwaps() {
      if (marshallingContext == null)
         return l();
      var swapArray = marshallingContext.getSwaps();
      if (swapArray.isEmpty())
         return l();
      var list = new ArrayList<ObjectSwap<?,?>>();
      var innerClass = inner();
      swapArray.stream().filter(f -> f.getNormalClass().isAssignableTo(innerClass)).forEach(list::add);
      return u(list);
   }

   private String findExample() {

      var ex = beanMeta.get().optBeanMeta().map(x -> (MarshalledFilter) x.getBeanFilter()).map(x -> x.getExample()).orElse(null);

      if (ex == null)
         ex = marshalledFilter.map(x -> x.getExample()).orElse(null);

      if (ex == null && nn(marshallingContext))
         ex = marshallingContext.getAnnotationProvider().find(Example.class, this).stream().map(x -> x.inner().value()).filter(Shorts::ine).findFirst().orElse(null);

      if (ex == null) {
         if (isAny(boolean.class, Boolean.class)) {
            ex = "true";
         } else if (isAny(char.class, Character.class)) {
            ex = "a";
         } else if (cat.is(CHARSEQ)) {
            ex = "foo";
         } else if (cat.is(ENUM)) {
            Optional<Enum<?>> e = first(EnumSet.allOf(asEnumClass(inner())));
            ex = e.map(x -> marshallingContext.getEnumFormat().format(x)).orElse(null);
         } else if (isAny(float.class, Float.class, double.class, Double.class)) {
            ex = "1.0";
         } else if (isAny(short.class, Short.class, int.class, Integer.class, long.class, Long.class)) {
            ex = "1";
         }
      }

      return ex;
   }

   private FieldInfo findExampleField() {
      var ap = marshallingContext.getAnnotationProvider();

      return getDeclaredFields()
         .stream()
         .filter(x -> x.isStatic() && isAssignableFrom(x.getFieldType()) && ap.has(Example.class, x))
         .map(x -> x.accessible())
         .findFirst()
         .orElse(null);
   }

   private MethodInfo findExampleMethod() {
      // @formatter:off
      var ap = marshallingContext.getAnnotationProvider();

      // Option 1:  Public example() or @Example method.
      var m = getPublicMethod(
         x -> x.isStatic() && x.isNotDeprecated() && (x.hasName("example") || ap.has(Example.class, x)) && x.hasParameterTypesLenient(MarshallingSession.class)
      );
      if (m.isPresent()) return m.get();

      // Option 2:  Non-public @Example method.
      return getDeclaredMethods()
         .stream()
         .flatMap(x -> x.getMatchingMethods().stream())
         .filter(x -> x.isStatic() && ap.has(Example.class, x))
         .map(x -> x.accessible())
         .findFirst()
         .orElse(null);
      // @formatter:on
   }

   private MethodInfo findFromStringMethod() {
      // @formatter:off

      // Option 1:  Explicit @StringCtor(name) short-circuits the name-based guessing below.
      // marshallingContext is null for context-less ClassMetas (e.g. the args-array ClassMeta), so there's
      // no annotation provider to consult in that case.
      if (marshallingContext != null) {
         var ap = marshallingContext.getAnnotationProvider();
         var stringCtor = ap.find(StringCtor.class, this).stream().findFirst();
         if (stringCtor.isPresent()) {
            var methodName = stringCtor.get().inner().value();
            return getPublicMethod(
               x -> x.isStatic() && x.hasReturnType(this) && x.hasParameterTypes(String.class) && x.hasName(methodName)
            ).orElse(null);
         }
      }

      // Option 2:  Find static fromString(String) or equivalent method by conventional name.
      // fromString() must be checked before valueOf() so that Enum classes can create their own
      //    specialized fromString() methods to override the behavior of Enum.valueOf(String).
      // valueOf() is used by enums.
      // parse() is used by the java logging Level class.
      // forName() is used by Class and Charset
      var names = a("fromString", "fromValue", "valueOf", "parse", "parseString", "forName", "forString");
      return getPublicMethod(
         x -> x.isStatic() && x.isNotDeprecated() && x.hasReturnType(this) && x.hasParameterTypes(String.class) && contains(x.getName(), names)
      ).orElse(null);
      // @formatter:on
   }

   private ClassInfoTyped<? extends T> findImplClass() {

      if (is(Object.class))
         return null;

      var mf = marshalledFilter.get();
      if (mf == null)
         return null;
      var implClassInfo = mf.getImplClass();
      if (implClassInfo == null)
         return null;
      return (ClassInfoTyped<? extends T>)implClassInfo;
   }

   private MarshalledFilter findMarshalledFilter() {
      var ap = marshallingContext.getAnnotationProvider();
      var l = ap.find(Marshalled.class, this);
      var bt = ap.find(BeanType.class, this);
      if (l.isEmpty() && bt.isEmpty())
         return null;
      return MarshalledFilter.create(this)
         .applyAnnotations(reverse(l.stream().map(AnnotationInfo::inner).toList()))
         .applyBeanTypeAnnotations(reverse(bt.stream().map(AnnotationInfo::inner).toList()))
         .build();
   }

   private Property<T,Object> findNameProperty() {
      var ap = marshallingContext.getAnnotationProvider();

      var s = getAllFields()
         .stream()
         .filter(x -> ap.has(NameProperty.class, x))
         .map(x -> x.accessible())
         .map(x -> Property.<T,Object>create().field(x).build())
         .findFirst();

      if (s.isPresent()) return s.get();

      var builder = Property.<T,Object>create();

      // Look for setter method (1 parameter) with @NameProperty
      var setterMethod = getAllMethods()
         .stream()
         .filter(x -> ap.has(NameProperty.class, x) && x.hasNumParameters(1))
         .findFirst();

      if (setterMethod.isPresent()) {
         builder.setter(setterMethod.get().accessible());

         // Try to find a corresponding getter method (even if not annotated)
         // If setter is "setName", look for "getName" or "isName"
         var setterName = setterMethod.get().getNameSimple();
         if (setterName.startsWith("set") && setterName.length() > 3) {
            var propertyName = setterName.substring(3);
            var getterName1 = "get" + propertyName;
            var getterName2 = "is" + propertyName;

            var getter = getAllMethods()
               .stream()
               .filter(x -> !x.isStatic() && x.hasNumParameters(0) &&
                  (x.hasName(getterName1) || x.hasName(getterName2)) &&
                  !x.getReturnType().is(Void.TYPE))
               .findFirst();

            if (getter.isPresent()) {
               builder.getter(getter.get().accessible());
            } else {
               // Try to find a field with the property name (lowercase first letter)
               var fieldName = Character.toLowerCase(propertyName.charAt(0)) + propertyName.substring(1);
               var field = getAllFields()
                  .stream()
                  .filter(x -> !x.isStatic() && x.hasName(fieldName))
                  .findFirst();

               if (field.isPresent()) {
                  var f = field.get().accessible();
                  builder.getter(f::get);
               }
            }
         }
      }

      // Look for getter method (0 parameters, non-void return) with @NameProperty
      var getterMethod = getAllMethods()
         .stream()
         .filter(x -> ap.has(NameProperty.class, x) && x.hasNumParameters(0) && !x.getReturnType().is(Void.TYPE))
         .findFirst();

      if (getterMethod.isPresent()) {
         builder.getter(getterMethod.get().accessible());
      }

      // Return null if neither setter nor getter was found
      if (setterMethod.isEmpty() && getterMethod.isEmpty())
         return null;

      return builder.build();
   }

   private ConstructorInfo findNoArgConstructor() {

      if (is(Object.class))
         return null;

      if (implClass.isPresent())
         return implClass.get().getPublicConstructor(x -> x.hasNumParameters(0)).orElse(null);

      if (isAbstract())
         return null;

      var numParams = nonStaticMemberClass ? 1 : 0;
      return getPublicConstructors()
         .stream()
         .filter(x -> x.isPublic() && x.isNotDeprecated() && x.hasNumParameters(numParams))
         .findFirst()
         .orElse(null);
   }

   private Property<T,Object> findParentProperty() {
      var ap = marshallingContext.getAnnotationProvider();

      var s = getAllFields()
         .stream()
         .filter(x -> ap.has(ParentProperty.class, x))
         .map(x -> x.accessible())
         .map(x -> Property.<T,Object>create().field(x).build())
         .findFirst();

      if (s.isPresent()) return s.get();

      var builder = Property.<T,Object>create();

      // Look for setter method (1 parameter) with @ParentProperty
      var setterMethod = getAllMethods()
         .stream()
         .filter(x -> ap.has(ParentProperty.class, x) && x.hasNumParameters(1))
         .findFirst();

      if (setterMethod.isPresent()) {
         builder.setter(setterMethod.get().accessible());

         // Try to find a corresponding getter method (even if not annotated)
         // If setter is "setParent", look for "getParent" or "isParent"
         var setterName = setterMethod.get().getNameSimple();
         if (setterName.startsWith("set") && setterName.length() > 3) {
            var propertyName = setterName.substring(3);
            var getterName1 = "get" + propertyName;
            var getterName2 = "is" + propertyName;

            var getter = getAllMethods()
               .stream()
               .filter(x -> !x.isStatic() && x.hasNumParameters(0) &&
                  (x.hasName(getterName1) || x.hasName(getterName2)) &&
                  !x.getReturnType().is(Void.TYPE))
               .findFirst();

            if (getter.isPresent()) {
               builder.getter(getter.get().accessible());
            } else {
               // Try to find a field with the property name (lowercase first letter)
               var fieldName = Character.toLowerCase(propertyName.charAt(0)) + propertyName.substring(1);
               var field = getAllFields()
                  .stream()
                  .filter(x -> !x.isStatic() && x.hasName(fieldName))
                  .findFirst();

               if (field.isPresent()) {
                  var f = field.get().accessible();
                  builder.getter(f::get);
               }
            }
         }
      }

      // Look for getter method (0 parameters, non-void return) with @ParentProperty
      var getterMethod = getAllMethods()
         .stream()
         .filter(x -> ap.has(ParentProperty.class, x) && x.hasNumParameters(0) && !x.getReturnType().is(Void.TYPE))
         .findFirst();

      if (getterMethod.isPresent()) {
         builder.getter(getterMethod.get().accessible());
      }

      // Return null if neither setter nor getter was found
      if (setterMethod.isEmpty() && getterMethod.isEmpty())
         return null;

      return builder.build();
   }

   private ConstructorInfo findStringConstructor() {

      if (is(Object.class) || isAbstract())
         return null;

      if (implClass.isPresent())
         return implClass.get().getPublicConstructor(x -> x.hasParameterTypes(String.class)).orElse(null);

      if (isAbstract())
         return null;

      var numParams = nonStaticMemberClass ? 2 : 1;
      return getPublicConstructors()
         .stream()
         .filter(x -> x.isPublic() && x.isNotDeprecated() && x.hasNumParameters(numParams))
         .filter(x -> x.getParameter(numParams == 2 ? 1 : 0).isType(String.class))
         .findFirst()
         .orElse(null);
   }

   /**
    * Returns the {@link ObjectSwap} where the specified class is the same/subclass of the normal class of one of the
    * child POJO swaps associated with this class.
    *
    * @param normalClass The normal class being resolved.
    * @return The resolved {@link ObjectSwap} or <jk>null</jk> if none were found.
    */
   protected ObjectSwap<?,?> getChildObjectSwapForSwap(Class<?> normalClass) {
      return childSwapMap.get(normalClass);
   }

   /**
    * Returns the {@link ObjectSwap} where the specified class is the same/subclass of the swap class of one of the child
    * POJO swaps associated with this class.
    *
    * @param swapClass The swap class being resolved.
    * @return The resolved {@link ObjectSwap} or <jk>null</jk> if none were found.
    */
   protected ObjectSwap<?,?> getChildObjectSwapForUnswap(Class<?> swapClass) {
      return childUnswapMap.get(swapClass);
   }

   /**
    * Returns <jk>true</jk> if this class or any child classes has a {@link ObjectSwap} associated with it.
    *
    * <p>
    * Used when transforming bean properties to prevent having to look up transforms if we know for certain that no
    * transforms are associated with a bean property.
    *
    * @return <jk>true</jk> if this class or any child classes has a {@link ObjectSwap} associated with it.
    */
   protected boolean hasChildSwaps() {
      return ! childSwaps.get().isEmpty();
   }

   /**
    * Appends this object as a readable string to the specified string builder.
    *
    * @param sb The string builder to append this object to.  Must not be <jk>null</jk>.
    * @param simple Print simple class names only (no package).
    * @return The passed-in string builder.
    */
   protected StringBuilder toString(StringBuilder sb, boolean simple) {
      var n = simple ? cnsq(inner()) : cn(inner());
      if (cat.is(ARRAY))
         return elementType.get().toString(sb, simple).append('[').append(']');
      if (cat.is(BEANMAP))
         return sb.append(cn(BeanMap.class)).append('<').append(n).append('>');
      if (cat.is(MAP)) {
         var kvTypes = keyValueTypes.get();
         var kt = kvTypes.optKeyType();
         var vt = kvTypes.optValueType();
         if (kt.isPresent() && vt.isPresent() && kt.get().isObject() && vt.get().isObject())
            return sb.append(n);
         return sb.append(n).append('<').append(kt.map(x -> x.toString(simple)).orElse("?")).append(',').append(vt.map(x -> x.toString(simple)).orElse("?")).append('>');
      }
      if (cat.is(COLLECTION) || is(Optional.class)) {
         var et = elementType.get();
         String typeString = et != null ? et.toString(simple) : "?";
         return sb.append(n).append(et != null && et.isObject() ? "" : "<" + typeString + ">");
      }
      return sb.append(n);
   }
}