/*
 * 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.commons.bean;

import static java.util.Collections.*;
import static org.apache.juneau.commons.function.Suppliers.*;
import static org.apache.juneau.commons.reflect.AnnotationTraversal.*;
import static org.apache.juneau.commons.reflect.ReflectionUtils.*;
import static org.apache.juneau.commons.utils.ClassUtils.*;
import static org.apache.juneau.commons.utils.CollectionUtils.*;
import static org.apache.juneau.commons.utils.ObjectUtils.*;
import static org.apache.juneau.commons.utils.Shorts.*;
import static org.apache.juneau.commons.utils.Shorts.eq;
import static org.apache.juneau.commons.utils.ThrowableUtils.*;

import java.lang.annotation.*;
import java.lang.reflect.*;
import java.net.*;
import java.util.*;
import java.util.concurrent.atomic.*;
import java.util.function.*;
import java.util.stream.*;

import org.apache.juneau.commons.collections.*;
import org.apache.juneau.commons.inject.*;
import org.apache.juneau.commons.lang.*;
import org.apache.juneau.commons.reflect.*;

/**
 * Contains metadata about a bean property.
 *
 * <p>
 * Contains information such as type of property (e.g. field/getter/setter), class type of property value, and whether
 * any transforms are associated with this property.
 *
 * <p>
 * Developers will typically not need access to this class.  The information provided by it is already exposed through
 * several methods on the {@link BeanMap} API.
 *
 * <h5 class='topic'>Thread safety</h5>
 *
 * Instances are immutable after construction and are safe for concurrent read access.
 *
 */
@SuppressWarnings({
   "java:S115", // Constants use UPPER_snakeCase convention (e.g., MSG_getterOrFieldNotDefined)
   "java:S1192", // Duplicated literals (argument/property names) read more clearly inline than as constants
   "java:S1452", // Wildcard required - BeanMap<?>, ClassMeta<?> for property metadata
   "java:S3776", // setPropertyValue(), add() and set() branch over every property kind (array, collection, map, bean, swap) and are kept as single flows
   "java:S6541", // setPropertyValue() (about 150 lines) is the single dispatch point for assigning a value of any property kind
   "rawtypes", // Raw types necessary for generic type handling
   "unchecked" // Type erasure requires unchecked casts
})
public class BeanPropertyMeta implements Comparable<BeanPropertyMeta> {

   /**
    * Sentinel value that, when returned from {@link BeanPropertyMeta.Builder#writeTransform} during
    * {@link #set(BeanMap, String, Object)}, causes the set to be skipped entirely — neither the configured setter
    * is invoked nor the property cache updated.
    *
    * <p>
    * Provided as a generic SPI hook so the marshalling layer (or any other transform-installing extension) can
    * implement "leave the bean's pre-existing value in place" semantics — used by the per-property null-coercion
    * {@code SKIP} mode added to the marshalling layer in 10.0.0.
    *
    * @since 10.0.0
    */
   public static final Object SKIP_VALUE = new Object();

   // Error message constants
   private static final String MSG_getterOrFieldNotDefined = "Getter or public field not defined on property '%s'";

   /**
    * BeanPropertyMeta builder class.
    */
   @SuppressWarnings({
      "java:S1104" // Public mutable fields are an intentional cross-module SPI seam: the marshalling-side post-processor (different package) reads/writes them after validate(), so they cannot be final or package-private.
   })
   public static class Builder {
      BeanMeta<?> beanMeta;  // Package-private for BeanMeta access
      BeanTypeResolver bc;  // The bean-modeling SPI seam to the marshalling-side type resolver.  Null when the owning BeanMeta was built via the commons-side path.
      BeanConfigContext config;  // Package-private for BeanMeta access.  Always non-null — sourced from the owning BeanMeta.
      public String name;  // Public so marshalling-side post-processors can use it when constructing diagnostic messages (e.g. MarshalledPropertyPostProcessor's schema-validation transform).
      FieldInfo field;  // Package-private for BeanMeta access
      public FieldInfo innerField;  // Package-private for BeanMeta access
      public MethodInfo getter;  // Package-private for BeanMeta access
      public MethodInfo setter;  // Package-private for BeanMeta access
      MethodInfo extraKeys;  // Package-private for BeanMeta access
      public BeanInfo<?> rawTypeMeta;  // Package-private for BeanMeta access (used to install swap-aware transforms).  Null on commons-side path (no type resolution).  Concrete instances are always {@code ClassMeta} since it's the only in-tree implementation; the field is typed against the bean-modeling SPI seam so the field can live in commons.bean.
      public Object swap;  // Object-typed so the field can live in commons.bean; cast to ObjectSwap by marshalling-side consumers.  Set only via MarshalledPropertyPostProcessor (marshalling-side post-processor).
      public BiFunction<BeanSession,Object,Object> readTransform;  // Package-private; defaults to identity if null.  Typed against the commons.bean SPI seam; marshalling-side installers cast the session argument back to {@code MarshallingSession} where needed (see {@code MarshalledPropertyPostProcessor#installSwapAwareTransforms}).
      public BiFunction<BeanSession,Object,Object> writeTransform; // Package-private; defaults to identity if null.  Typed against the commons.bean SPI seam (see readTransform note).
      public List<ClassInfo> dictionaryClasses;  // Package-private for BeanMeta access; @MarshalledProp(dictionary={}) classes scanned during validate().
      public Set<String> views;  // Named views this property belongs to; null = untagged (in all views when defaultViewInclusion is enabled). Set via MarshalledPropertyPostProcessor.
      private boolean isConstructorArg;
      public boolean isUri;  // Package-private so MarshalledPropertyPostProcessor can set @Uri-derived flag.  Mirrors rawTypeMeta.isUri() plus @Uri annotation reads on field/getter/setter.
      boolean isDyna;
      boolean isDynaGetterMap;
      public BeanInfo<?> typeMeta;  // Package-private so the marshalling-side post-processor can override after @Swap/@MarshalledProp detection.  Concrete instances are always {@code ClassMeta}; typed against the bean-modeling SPI seam.
      private Object overrideValue;
      private BeanPropertyMeta delegateFor;
      private boolean canRead;
      private boolean canWrite;
      private boolean readOnly;
      private boolean writeOnly;
      boolean required;  // @BeanProp(required=true) on the field, getter or setter (OR-merged).

      Builder(BeanMeta<?> beanMeta, String name) {
         this.beanMeta = beanMeta;
         this.bc = beanMeta.getBeanTypeResolver();  // Returns null on commons-side path.
         this.config = beanMeta.getConfig();
         this.name = name;
      }

      /**
       * @return A new BeanPropertyMeta object using this builder.
       */
      public BeanPropertyMeta build() {
         return new BeanPropertyMeta(this);
      }

      /**
       * Sets the original bean property that this one is overriding.
       *
       * @param value The original bean property that this one is overriding.  Must not be <jk>null</jk>.
       * @return This object.
       */
      public Builder delegateFor(BeanPropertyMeta value) {
         delegateFor = reqnn("value", value);
         return this;
      }

      /**
       * Installs the read-side value transform for this property.
       *
       * <p>
       * Applied to the raw getter result by {@link BeanPropertyMeta#get(BeanMap,String)} before it is returned to the
       * caller.  Defaults to identity (raw value passes through unchanged).
       *
       * <p>
       * Used by the marshalling layer to install {@code ObjectSwap}-aware behavior at bean-meta construction time;
       * the bean-modeling layer itself only invokes the function and does not directly reference
       * {@code ObjectSwap}.
       *
       * @param value The transform function.  Must not be <jk>null</jk>.
       * @return This object.
       */
      public Builder readTransform(BiFunction<BeanSession,Object,Object> value) {
         readTransform = reqnn("value", value);
         return this;
      }

      /**
       * Installs the write-side value transform for this property.
       *
       * <p>
       * Applied to the incoming value by {@link BeanPropertyMeta#set(BeanMap,String,Object)} before the raw setter is
       * invoked.  Defaults to identity (raw value passes through unchanged).
       *
       * <p>
       * Used by the marshalling layer to install {@code ObjectSwap}-aware behavior at bean-meta construction time;
       * the bean-modeling layer itself only invokes the function and does not directly reference
       * {@code ObjectSwap}.
       *
       * @param value The transform function.  Must not be <jk>null</jk>.
       * @return This object.
       */
      public Builder writeTransform(BiFunction<BeanSession,Object,Object> value) {
         writeTransform = reqnn("value", value);
         return this;
      }

      /**
       * Sets the overridden value of this bean property.
       *
       * @param value The overridden value of this bean property.  Can be <jk>null</jk>, in which case no override is applied.
       * @return This object.
       */
      public Builder overrideValue(Object value) {
         overrideValue = value;
         return this;
      }

      /**
       * Sets the raw metadata type for this bean property.
       *
       * @param value The raw metadata type for this bean property.  Must not be <jk>null</jk>.
       * @return This object.
       */
      public Builder rawMetaType(BeanInfo<?> value) {
         rawTypeMeta = reqnn("value", value);
         typeMeta = rawTypeMeta;
         return this;
      }

      /**
       * Sets the raw metadata type for this bean property from a {@link Class}.
       *
       * <p>
       * Convenience overload that resolves the supplied class via the property's
       * {@link BeanTypeResolver}, allowing callers from the bean-modeling layer to seed the type without
       * holding a {@link BeanInfo} reference.
       *
       * <p>
       * When the owning {@link BeanMeta} was built via the commons-side path
       * ({@link BeanMeta#of(Class, BeanConfigContext)}), no resolver is available, so
       * {@code rawTypeMeta}/{@code typeMeta} are left <jk>null</jk> and the property runs in raw-reflection mode.
       *
       * @param value The raw metadata type for this bean property.  Must not be <jk>null</jk>.
       * @return This object.
       */
      public Builder rawMetaType(Class<?> value) {
         reqnn("value", value);
         if (bc == null)
            return this;
         rawTypeMeta = bc.resolveType(null, info(value), null);
         typeMeta = rawTypeMeta;
         return this;
      }

      /**
       * Marks this property as readable.
       *
       * @return This object.
       */
      public Builder canRead() {
         canRead = true;
         return this;
      }

      /**
       * Marks this property as writable.
       *
       * @return This object.
       */
      public Builder canWrite() {
         canWrite = true;
         return this;
      }

      /**
       * Marks this property as a constructor argument.
       *
       * @return This object.
       */
      public Builder setAsConstructorArg() {
         isConstructorArg = true;
         return this;
      }

      /**
       * Sets the extra keys method for this bean property.
       *
       * @param value The method info that returns extra keys for this property.  Must not be <jk>null</jk>.
       * @return This object.
       */
      public Builder setExtraKeys(MethodInfo value) {
         reqnn("value", value);
         extraKeys = value.accessible();
         return this;
      }

      /**
       * Sets the field for this bean property.
       *
       * @param value The field info for this bean property.  Must not be <jk>null</jk>.
       * @return This object.
       */
      public Builder setField(FieldInfo value) {
         reqnn("value", value);
         field = value.accessible();
         innerField = field;
         return this;
      }

      /**
       * Sets the getter method for this bean property.
       *
       * @param value The getter method info for this bean property.  Must not be <jk>null</jk>.
       * @return This object.
       */
      public Builder setGetter(MethodInfo value) {
         reqnn("value", value);
         getter = value.accessible();
         return this;
      }

      /**
       * Sets the inner field for this bean property from a {@link FieldInfo}.
       *
       * @param value The field info containing the inner field.  Must not be <jk>null</jk>.
       * @return This object.
       */
      public Builder setInnerField(FieldInfo value) {
         innerField = reqnn("innerField", value);
         return this;
      }

      /**
       * Sets the setter method for this bean property.
       *
       * @param value The setter method info for this bean property.  Must not be <jk>null</jk>.
       * @return This object.
       */
      public Builder setSetter(MethodInfo value) {
         reqnn("value", value);
         setter = value.accessible();
         return this;
      }

      /**
       * Validates this bean property configuration.
       *
       * <p>
       * After validation succeeds, marshalling-side callers (currently {@link BeanMeta}) read the
       * {@link #dictionaryClasses} field to construct the property-level registry lookup and store it in a
       * side-map keyed by the built {@link BeanPropertyMeta}.  The bean-modeling layer itself no longer carries a
       * concrete registry reference.
       *
       * <p>
       * When {@code bc} is <jk>null</jk> (commons-side path), this method runs in raw-reflection mode:
       * annotation reads are routed through {@link BeanConfigContext#getAnnotationProvider()} but no
       * {@code ClassMeta} resolution or {@code ObjectSwap} discovery is performed; the property's
       * {@code rawTypeMeta}/{@code typeMeta} stay <jk>null</jk> and the resulting {@link BeanPropertyMeta}
       * exposes raw getter/setter invocation only.
       *
       * @param bc The bean context.  May be <jk>null</jk> for the commons-side path.
       * @param typeVarImpls Type variable implementations.  Ignored when {@code bc} is <jk>null</jk>.
       * @param bpro Bean properties read-only set.  Must not be <jk>null</jk> (pass an empty set for none).
       * @param bpwo Bean properties write-only set.  Must not be <jk>null</jk> (pass an empty set for none).
       * @return <jk>true</jk> if this property is valid, <jk>false</jk> otherwise.
       * @throws Exception If validation fails.
       */
      @SuppressWarnings({
         "java:S112" // Generic exception thrown; acceptable for framework/lifecycle methods
      })
      public boolean validate(BeanTypeResolver bc, TypeVariables typeVarImpls, Set<String> bpro, Set<String> bpwo) throws Exception {

         var ap = nn(bc) ? bc.getAnnotationProvider() : config.getAnnotationProvider();

         if (field == null && getter == null && setter == null)
            return false;

         // Settings reads route through BeanConfigContext so the commons-side path works without a MarshallingContext.
         if (field == null && setter == null && config.isBeansRequireSettersForGetters() && ! isConstructorArg)
            return false;

         canRead |= (nn(field) || nn(getter));
         canWrite |= (nn(field) || nn(setter) || isConstructorArg);

         var ifi = innerField;
         var gi = getter;
         var si = setter;

         // @MarshalledProp / @Swap annotation reads have been lifted out to the marshalling-side post-processor
         // (see {@link org.apache.juneau.MarshalledPropertyPostProcessor#process}).  They are processed by {@link BeanMeta}
         // after this method returns.  The post-processor mutates {@link #swap}, {@link #properties},
         // {@link #dictionaryClasses}, and {@link #typeMeta} (when a swap is detected) on this builder.
         dictionaryClasses = emptyList();

         if (nn(innerField)) {
            var lbp = ap.find(BeanProp.class, ifi);
            if (nn(bc) && (nn(field) || ine(lbp))) {
               // Only use field type if it's a bean property or has @BeanProp annotation.
               // Otherwise, we want to infer the type from the getter or setter.
               rawTypeMeta = bc.resolveType(o(last(lbp)).orElse(null), innerField.getFieldType(), typeVarImpls);
               isUri |= (rawTypeMeta.isUri());
            }
            lbp.forEach(x -> {
               var beanp = x.inner();
               if (ine(beanp.ro()))
                  readOnly = b(beanp.ro());
               if (ine(beanp.wo()))
                  writeOnly = b(beanp.wo());
               required |= beanp.required();
            });
         }

         if (nn(getter)) {
            var lbp = ap.find(BeanProp.class, gi);
            if (nn(bc) && rawTypeMeta == null)
               rawTypeMeta = bc.resolveType(o(last(lbp)).orElse(null), getter.getReturnType(), typeVarImpls);
            if (nn(rawTypeMeta))
               isUri |= rawTypeMeta.isUri();
            lbp.forEach(x -> {
               var beanp = x.inner();
               if (ine(beanp.ro()))
                  readOnly = b(beanp.ro());
               if (ine(beanp.wo()))
                  writeOnly = b(beanp.wo());
               required |= beanp.required();
            });
         }

         if (nn(setter)) {
            var lbp = ap.find(BeanProp.class, si);
            if (nn(bc) && rawTypeMeta == null)
               rawTypeMeta = bc.resolveType(o(last(lbp)).orElse(null), setter.getParameterTypes().get(0), typeVarImpls);
            if (nn(rawTypeMeta))
               isUri |= rawTypeMeta.isUri();
            lbp.forEach(x -> {
               var beanp = x.inner();
               if (ine(beanp.ro()))
                  readOnly = b(beanp.ro());
               if (ine(beanp.wo()))
                  writeOnly = b(beanp.wo());
               required |= beanp.required();
            });
         }

         // On the commons-side path (bc == null), rawTypeMeta stays null and validate() accepts the property
         // in raw-reflection mode.  The marshalling-side path still requires a resolvable type.
         if (nn(bc) && rawTypeMeta == null)
            return false;

         isDyna = eq(name, "*");

         // Do some annotation validation.  Type-aware validation requires rawTypeMeta — on the commons-side
         // path we skip it entirely.
         if (nn(rawTypeMeta)) {
            var ci = rawTypeMeta;
            if (nn(getter)) {
               var pt = getter.getParameterTypes();
               if (isDyna) {
                  if (ci.isAssignableTo(Map.class) && ie(pt)) {
                     isDynaGetterMap = true;
                  } else if (pt.size() == 1 && pt.get(0).is(String.class)) {
                     // OK.
                  } else {
                     return false;
                  }
               } else {
                  if (! ci.isAssignableTo(getter.getReturnType()))
                     return false;
               }
            }
            if (nn(setter)) {
               var pt = setter.getParameterTypes();
               if (isDyna) {
                  if (pt.size() == 2 && pt.get(0).is(String.class)) {
                     // OK.
                  } else {
                     return false;
                  }
               } else {
                  if (pt.size() != 1 || ! ci.isAssignableTo(pt.get(0).inner()))
                     return false;
               }
            }
            if (nn(field)) {
               if (isDyna) {
                  if (! field.getFieldType().isAssignableTo(Map.class))
                     return false;
               } else {
                  if (! ci.isAssignableTo(field.getFieldType()))
                     return false;
               }
            }

            if (isDyna) {
               rawTypeMeta = rawTypeMeta.getValueType();
               if (rawTypeMeta == null && nn(bc))
                  rawTypeMeta = bc.objectType();
            }

            if (typeMeta == null) {
               if (rawTypeMeta == null && nn(bc))
                  typeMeta = bc.objectType();
               else
                  typeMeta = rawTypeMeta;
            }
            if (typeMeta == null)
               typeMeta = rawTypeMeta;
         }

         if (bpro.contains(name) || bpro.contains("*"))
            readOnly = true;
         if (bpwo.contains(name) || bpwo.contains("*"))
            writeOnly = true;

         return true;
      }

      /**
       * Returns whether this property is marked {@code @BeanProp(required=true)}.
       *
       * @return <jk>true</jk> if required.
       */
      boolean isRequired() { return required; }

      /**
       * Returns whether input can ever set this property, which a required property must allow.
       *
       * <p>
       * Call only after {@link #validate} and after constructor-argument marking.
       *
       * @return <jk>true</jk> if the property has a field, a setter, or is a constructor argument, and is not read-only or dynamic.
       */
      boolean canSatisfyRequired() {
         return ! isDyna && ! readOnly && (nn(field) || nn(setter) || isConstructorArg);
      }

   }

   /**
    * Creates a builder for {@link #BeanPropertyMeta} objects.
    *
    * @param beanMeta The metadata on the bean.  Must not be <jk>null</jk>.
    * @param name The bean property name.
    * @return A new builder.
    */
   public static Builder builder(BeanMeta<?> beanMeta, String name) {
      return new Builder(beanMeta, name);
   }

   private final AnnotationProvider ap;                             // Annotation provider for finding annotations on this property.  Sourced from bc (marshalling-side) or beanMeta.getConfig() (commons-side).
   private final Supplier<List<AnnotationInfo<?>>> annotations;     // Memoized list of all annotations on this property.
   private final BeanTypeResolver bc;                               // The bean-modeling SPI seam to the marshalling-side type resolver.  Null when the owning BeanMeta was built via the commons-side path.
   private final BeanConfigContext config;                          // Bean-modeling settings facade — always non-null.  Mirrors the BeanMeta's config.
   private final BeanMeta<?> beanMeta;                              // The bean that this property belongs to.
   private final boolean canRead;                                   // True if this property can be read.
   private final boolean canWrite;                                  // True if this property can be written.
   private final BeanPropertyMeta delegateFor;                      // The bean property that this meta is a delegate for.
   private final MethodInfo extraKeys;                              // The bean property extraKeys method.
   private final FieldInfo field;                                   // The bean property field (if it has one).
   private final MethodInfo getter;                                 // The bean property getter.
   private final int hashCode;                                      // Cached hash code for this property meta.
   private final FieldInfo innerField;                              // The bean property field even if private (if it has one).
   private final boolean isDyna;                                    // True if this is a dyna property (i.e. name="*").
   private final boolean isDynaGetterMap;                           // True if this is a dyna property where the getter returns a Map directly.
   private final boolean isUri;                                     // True if this is a URL/URI or annotated with @URI.
   private final String name;                                       // The name of the property.
   private final Object overrideValue;                              // The bean property value (if it's an overridden delegate).
   private final BeanInfo<?> rawTypeMeta;                           // The real class type of the bean property.  Concrete instances are always {@code ClassMeta}; typed against the bean-modeling SPI seam for the eventual move to commons.bean.
   private final BiFunction<BeanSession,Object,Object> readTransform;  // Applied to raw getter result; identity by default.  Typed against the commons.bean SPI seam.
   private final boolean required;                                  // True if this property is marked @BeanProp(required=true).
   private final boolean readOnly;                                  // True if this property is read-only.
   private final MethodInfo setter;                                 // The bean property setter.
   private final BeanInfo<?> typeMeta;                              // The transformed class type of the bean property.  Concrete instances are always {@code ClassMeta}; typed against the bean-modeling SPI seam.
   private final BiFunction<BeanSession,Object,Object> writeTransform; // Applied to incoming value before raw setter; identity by default.  Typed against the commons.bean SPI seam.
   private final AtomicReference<Supplier<Collection<?>>> abstractCollectionFactory = new AtomicReference<>();  // Memoized factory for abstract/interface collection property types.
   private final AtomicReference<Supplier<Collection<?>>> concreteCollectionFactory = new AtomicReference<>();  // Memoized factory for concrete collection property types.
   private final AtomicReference<Supplier<Map<?,?>>> mapFactory = new AtomicReference<>();  // Memoized factory for concrete map property types.
   private final boolean writeOnly;                                 // True if this property is write-only.
   private final Set<String> views;                                 // Named views this property belongs to; null = untagged (included in all views when defaultViewInclusion is enabled).

   /**
    * Creates a new BeanPropertyMeta using the contents of the specified builder.
    *
    * @param b The builder to copy fields from.  Must not be <jk>null</jk>.
    */
   protected BeanPropertyMeta(Builder b) {
      annotations = memoize(this::findAnnotations);
      bc = b.bc;
      config = b.config;
      beanMeta = b.beanMeta;
      canRead = b.canRead;
      canWrite = b.canWrite;
      delegateFor = b.delegateFor;
      extraKeys = b.extraKeys;
      field = b.field;
      getter = b.getter;
      innerField = b.innerField;
      isDyna = b.isDyna;
      isDynaGetterMap = b.isDynaGetterMap;
      isUri = b.isUri;
      name = b.name;
      overrideValue = b.overrideValue;
      rawTypeMeta = b.rawTypeMeta;
      readOnly = b.readOnly;
      required = b.required;
      setter = b.setter;
      typeMeta = b.typeMeta;
      writeOnly = b.writeOnly;
      views = b.views != null ? u(b.views) : null;
      readTransform = b.readTransform != null ? b.readTransform : (session, o) -> o;
      writeTransform = b.writeTransform != null ? b.writeTransform : (session, o) -> o;

      ap = nn(bc) ? bc.getAnnotationProvider() : b.config.getAnnotationProvider();
      hashCode = h(beanMeta, name);
   }

   /**
    * Adds a value to a {@link Collection} or array property.
    *
    * <p>
    * Note that adding values to an array property is inefficient for large arrays since it must copy the array into a
    * larger array on each operation.
    *
    * <p>
    * <b>Marshalling-only path.</b>  Requires a property built via the marshalling-side construction path
    * (i.e. with a non-null {@link #getBeanInfo() rawTypeMeta} and a non-null backing
    * {@code MarshallingSession} on the supplied {@link BeanMap}).  When the owning {@link BeanMeta} was built via
    * {@link BeanMeta#of(Class, BeanConfigContext)}, this method throws
    * {@link UnsupportedOperationException} because adding into a Collection/array property requires
    * type-aware element conversion (the marshalling session's {@code convertToType}) that is not available in the
    * bean-modeling-only path.
    *
    * @param m The bean of the field being set.
    * @param pName
    *    The property name if this is a dyna property (i.e. <js>"*"</js>).
    *    <br>Otherwise can be <jk>null</jk>.
    * @param value The value to add to the field.  Can be <jk>null</jk>.
    * @throws BeanRuntimeException If field is not a collection or array.
    * @throws UnsupportedOperationException If this property was built via the bean-modeling-only path
    *    ({@link BeanMeta#of(Class, BeanConfigContext)}).
    */
   public void add(BeanMap<?> m, String pName, Object value) throws BeanRuntimeException {

      if (rawTypeMeta == null)
         throw uoex("Property '%s' was built via the bean-modeling-only path; Collection/array add operations require a marshalling context.", name);

      m.recordPresent(name);

      // Read-only beans get their properties stored in a cache.
      if (m.bean == null) {
         if (! m.propertyCache.containsKey(name))
            m.propertyCache.put(name, l());
         ((List)m.propertyCache.get(name)).add(value);
         return;
      }

      var session = m.getBeanSession();

      var isCollection = rawTypeMeta.isCollection();
      var isArray = rawTypeMeta.isArray();

      if (! (isCollection || isArray))
         throw brex(beanMeta.getBeanInfo(), "Attempt to add element to property '%s' which is not a collection or array", name);

      var bean = m.getBean(true);

      var elementType = rawTypeMeta.getElementType();

      try {
         var v = session.convertToType(value, elementType);

         if (isCollection) {
            Collection c = (Collection)invokeGetter(bean, pName);

            Collection c2 = null;
            if (nn(c)) {
               if (canAddTo(c)) {
                  c.add(v);
                  return;
               }
               c2 = c;
            }

            if (rawTypeMeta.canCreateNewInstance())
               c = (Collection)rawTypeMeta.newInstance();
            else
               c = l();

            if (c2 != null)
               c.addAll(c2);

            c.add(v);

            invokeSetter(bean, pName, c);

         } else /* isArray() */ {

            if (m.arrayPropertyCache == null)
               m.arrayPropertyCache = new TreeMap<>();

            List l = m.arrayPropertyCache.get(name);
            if (l == null) {
               l = new LinkedList();  // ArrayLists and LinkLists appear to perform equally.
               m.arrayPropertyCache.put(name, l);

               // Copy any existing array values into the temporary list.
               var oldArray = invokeGetter(bean, pName);
               copyArrayToList(oldArray, l);
            }

            // Add new entry to our array.
            l.add(v);
         }

      } catch (BeanRuntimeException e) {
         throw e;
      } catch (Exception e) {
         throw brex(e);
      }
   }

   /**
    * Adds a value to a {@link Map} or bean property.
    *
    * <p>
    * <b>Marshalling-only path.</b>  Requires a property built via the marshalling-side construction path
    * (i.e. with a non-null {@link #getBeanInfo() rawTypeMeta} and a non-null backing
    * {@code MarshallingSession} on the supplied {@link BeanMap}).  When the owning {@link BeanMeta} was built via
    * {@link BeanMeta#of(Class, BeanConfigContext)}, this method throws
    * {@link UnsupportedOperationException} because adding into a Map/bean property requires type-aware
    * value conversion (the marshalling session's {@code convertToType} / {@code toBeanMap}) that is not available
    * in the bean-modeling-only path.
    *
    * @param m The bean of the field being set.
    * @param pName
    *    The property name if this is a dyna property (i.e. <js>"*"</js>).
    *    <br>Otherwise can be <jk>null</jk>.
    * @param key The key to add to the field.
    * @param value The value to add to the field.  Can be <jk>null</jk>.
    * @throws BeanRuntimeException If field is not a map or array.
    * @throws UnsupportedOperationException If this property was built via the bean-modeling-only path
    *    ({@link BeanMeta#of(Class, BeanConfigContext)}).
    */
   public void add(BeanMap<?> m, String pName, String key, Object value) throws BeanRuntimeException {

      if (rawTypeMeta == null)
         throw uoex("Property '%s' was built via the bean-modeling-only path; Map/bean add operations require a marshalling context.", name);

      m.recordPresent(name);

      // Read-only beans get their properties stored in a cache.
      if (m.bean == null) {
         if (! m.propertyCache.containsKey(name))
            m.propertyCache.put(name, m());
         ((Map)m.propertyCache.get(name)).put(key, value);
         return;
      }

      var session = m.getBeanSession();

      var isMap = rawTypeMeta.isMap();
      var isBean = rawTypeMeta.isBean();

      if (! (isBean || isMap))
         throw brex(beanMeta.getBeanInfo(), "Attempt to add key/value to property '%s' which is not a map or bean", name);

      var bean = m.getBean(true);

      try {
         var v = session.convertToType(value, rawTypeMeta.getElementType());

         if (isMap) {
            var map = (Map)invokeGetter(bean, pName);

            if (nn(map)) {
               map.put(key, v);
               return;
            }

            if (rawTypeMeta.canCreateNewInstance())
               map = (Map)rawTypeMeta.newInstance();
            else
               map = m();

            map.put(key, v);

            invokeSetter(bean, pName, map);

         } else /* isBean() */ {

            var b = invokeGetter(bean, pName);

            if (nn(b)) {
               ((Map) session.toBeanMap(b)).put(key, v);
               return;
            }

            if (rawTypeMeta.canCreateNewInstance(m.getBean(false))) {
               b = rawTypeMeta.newInstance();
               ((Map) session.toBeanMap(b)).put(key, v);
            }

            invokeSetter(bean, pName, b);
         }

      } catch (BeanRuntimeException e) {
         throw e;
      } catch (Exception e) {
         throw brex(e);
      }
   }

   /**
    * Returns <jk>true</jk> if this property can be read.
    *
    * <p>
    * Write-only properties (see {@link #isWriteOnly()}) are never readable, so serializers, tabular column sets and
    * schemas skip them.  They remain settable through {@link #canWrite()} and parsing.
    *
    * @return <jk>true</jk> if this property can be read.
    */
   public boolean canRead() {
      return canRead && ! writeOnly;
   }

   /**
    * Returns <jk>true</jk> if this property can be written.
    *
    * @return <jk>true</jk> if this property can be written.
    */
   public boolean canWrite() {
      return canWrite;
   }

   @Override /* Overridden from Comparable */
   public int compareTo(BeanPropertyMeta o) {
      return cmp(name, o.name);
   }

   @Override /* Overridden from Object */
   public boolean equals(Object o) {
      return (o instanceof BeanPropertyMeta o2) && eq(this, o2, (x, y) -> eq(x.name, y.name) && eq(x.beanMeta, y.beanMeta));
   }

   /**
    * Returns all annotations on this property (field, getter, and setter).
    *
    * <p>
    * The annotations are found on:
    * <ul>
    *    <li>The field (if present)
    *    <li>The getter method (if present) - including annotations on the method, its return type, and package
    *    <li>The setter method (if present) - including annotations on the method, its return type, and package
    * </ul>
    *
    * <p>
    * The result is memoized and computed only once.
    *
    * @return A list of all annotation infos on this property. Never <jk>null</jk>.
    */
   public List<AnnotationInfo> getAnnotations() {
      return (List)annotations.get();
   }

   /**
    * Returns a stream of annotations of the specified type on this property.
    *
    * <p>
    * The annotations are found on:
    * <ul>
    *    <li>The field (if present)
    *    <li>The getter method (if present) - including annotations on the method, its return type, and package
    *    <li>The setter method (if present) - including annotations on the method, its return type, and package
    * </ul>
    *
    * @param <A> The annotation type to find.
    * @param a The annotation class to find.  Can be <jk>null</jk>, in which case an empty stream is returned.
    * @return A stream of annotation infos of the specified type. Never <jk>null</jk>.
    */
   public <A extends Annotation> Stream<AnnotationInfo<A>> getAnnotations(Class<A> a) {
      if (a == null)
         return Stream.empty();
      return annotations.get().stream()
         .filter(x -> x.isType(a))
         .map(x -> (AnnotationInfo<A>)x);
   }

   /**
    * Helper method to find all annotations on this property.
    *
    * @return A list of all annotation infos found on the field, getter, and setter.
    */
   private List<AnnotationInfo<?>> findAnnotations() {
      var result = new ArrayList<AnnotationInfo<?>>();
      if (nn(field))
         result.addAll(ap.find(field));
      if (nn(getter))
         result.addAll(ap.find(getter, SELF, MATCHING_METHODS, RETURN_TYPE, PACKAGE));
      if (nn(setter))
         result.addAll(ap.find(setter, SELF, MATCHING_METHODS, RETURN_TYPE, PACKAGE));
      if (nn(extraKeys))
         result.addAll(ap.find(extraKeys, SELF, MATCHING_METHODS, RETURN_TYPE, PACKAGE));
      return u(result);
   }

   /**
    * Equivalent to calling {@link BeanMap#get(Object)}, but is faster since it avoids looking up the property meta.
    *
    * @param m The bean map to get the transformed value from.
    * @param pName
    *    The property name if this is a dyna property (i.e. <js>"*"</js>).
    *    <br>Otherwise can be <jk>null</jk>.
    * @return
    *    The property value.
    *    <br>Returns <jk>null</jk> if this is a write-only property.
    */
   public Object get(BeanMap<?> m, String pName) {
      return m.meta.onReadProperty(m.bean, pName, getInner(m, pName));
   }

   /**
    * Returns the bean meta that this property belongs to.
    *
    * @return The bean meta that this property belongs to.
    */
   public BeanMeta<?> getBeanMeta() { return beanMeta; }

   /**
    * Returns the bean dictionary in use for this bean property.
    *
    * <p>
    * The order of lookup for the dictionary is as follows:
    * <ol>
    *    <li>Dictionary defined via {@code @MarshalledProp(dictionary)}.
    *    <li>Dictionary defined via {@code MarshallingContext.Builder<?>#beanDictionary(Class...)}.
    * </ol>
    *
    * <p>
    * The per-property registry no longer lives on this object; it is stored in a marshalling-side
    * side-map on {@link BeanMeta} keyed by {@link BeanPropertyMeta}.  This method delegates to
    * {@link BeanMeta#getPropertyBeanRegistry(BeanPropertyMeta)} for backwards compatibility with existing call sites
    * in the marshalling layer (parser/serializer sessions, XML content-property handling, etc.).
    *
    * <p>
    * Returns the bean-modeling-side SPI type ({@link BeanRegistryLookup}).  Marshalling-side callers that need
    * implementation-specific behavior cast at the call site.
    *
    * @return The bean dictionary in use for this bean property, or <jk>null</jk> if no registry was registered.
    */
   public BeanRegistryLookup getBeanRegistry() { return beanMeta.getPropertyBeanRegistry(this); }

   /**
    * Returns the {@link BeanInfo} of the class of this property.
    *
    * <p>
    * If this property or the property type class has a {@code ObjectSwap} associated with it, this method returns the
    * transformed class meta.
    * This matches the class type that is used by the {@link #get(BeanMap,String)} and
    * {@link #set(BeanMap,String,Object)} methods.
    *
    * <p>
    * Returns the bean-modeling-side SPI type ({@link BeanInfo}).  Marshalling-side callers that need the
    * {@code ClassMeta} narrowing must cast — the concrete instance in-tree is always a {@code ClassMeta}.
    *
    * @return The {@link BeanInfo} of the class of this property, or <jk>null</jk> if this property was built via
    *    the bean-modeling-only path.
    */
   public BeanInfo<?> getBeanInfo() { return typeMeta; }

   /**
    * Returns the metadata on the property that this metadata is a delegate for.
    *
    * @return the metadata on the property that this metadata is a delegate for, or this object if it's not a delegate.
    */
   public BeanPropertyMeta getDelegateFor() { return coalesce(delegateFor, this); }

   /**
    * Returns the {@link Map} object returned by the DynaBean getter.
    *
    * <p>
    * The DynaBean property is the property whose name is <js>"*"</js> and returns a map of "extra" properties on the
    * bean.
    *
    * @param bean The bean.
    * @return
    *    The map returned by the getter, or an empty map if the getter returned <jk>null</jk> or this isn't a DynaBean
    *    property.
    * @throws IllegalArgumentException Thrown by method invocation.
    * @throws IllegalAccessException Thrown by method invocation.
    * @throws InvocationTargetException Thrown by method invocation.
    */
   public Map<String,Object> getDynaMap(Object bean) throws IllegalArgumentException, IllegalAccessException, InvocationTargetException {
      if (isDyna) {
         if (nn(extraKeys) && nn(getter) && ! isDynaGetterMap) {
            Map<String,Object> m = map();
            ((Collection<String>)extraKeys.invoke(bean)).forEach(x -> safe(() -> m.put(x, getter.invoke(bean, x))));
            return m;
         }
         if (nn(getter) && isDynaGetterMap)
            return (Map)getter.invoke(bean);
         if (nn(field))
            return (Map)field.get(bean);
         throw brex(beanMeta.getBeanInfo(), MSG_getterOrFieldNotDefined, name);
      }
      return emptyMap();
   }

   /**
    * Returns the field for this property.
    *
    * @return The field info for this bean property, or <jk>null</jk> if there is no field associated with this bean property.
    */
   public FieldInfo getField() { return field; }

   /**
    * Returns the getter method for this property.
    *
    * @return The getter method info for this bean property, or <jk>null</jk> if there is no getter method.
    */
   public MethodInfo getGetter() { return getter; }

   /**
    * Returns the field for this property even if the field is private.
    *
    * @return The field info for this bean property, or <jk>null</jk> if there is no field associated with this bean property.
    */
   public FieldInfo getInnerField() { return innerField; }

   /**
    * Returns the name of this bean property.
    *
    * @return The name of the bean property.
    */
   public String getName() { return name; }

   /**
    * Equivalent to calling {@link BeanMap#getRaw(Object)}, but is faster since it avoids looking up the property meta.
    *
    * @param m The bean map to get the transformed value from.
    * @param pName
    *    The property name if this is a dyna property (i.e. <js>"*"</js>).
    *    <br>Otherwise can be <jk>null</jk>.
    * @return The raw property value.
    */
   public Object getRaw(BeanMap<?> m, String pName) {
      try {
         // Read-only beans have their properties stored in a cache until getBean() is called.
         var bean = m.bean;
         if (bean == null)
            return m.propertyCache.get(name);

      return invokeGetter(bean, pName);

   } catch (Exception e) {
      if (config.isIgnoreInvocationExceptionsOnGetters()) {
         if (nn(rawTypeMeta) && rawTypeMeta.isPrimitive())
            return rawTypeMeta.getPrimitiveDefault();
         return null;
      }
      throw brex(e, beanMeta.getClassInfo(), "Exception occurred while getting property '%s'", name);
   }
   }

   /**
    * Returns the setter method for this property.
    *
    * @return The setter method info for this bean property, or <jk>null</jk> if there is no setter method.
    */
   public MethodInfo getSetter() { return setter; }

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

   /**
    * Returns <jk>true</jk> if this bean property is named <js>"*"</js>.
    *
    * @return <jk>true</jk> if this bean property is named <js>"*"</js>.
    */
   public boolean isDyna() { return isDyna; }

   /**
    * Returns whether this property is marked {@code @BeanProp(required=true)}.
    *
    * <p>
    * Required properties must be present in parser input (or in the source map of a {@code Map}-to-bean conversion);
    * see {@link BeanProp#required()}.
    *
    * @return <jk>true</jk> if this property is required.
    */
   public boolean isRequired() { return required; }

   /**
    * Returns <jk>true</jk> if this property is read-only.
    *
    * <p>
    * This implies the property MIGHT be writable, but that parsers should not set a value for it.
    *
    * @return <jk>true</jk> if this property is read-only.
    */
   public boolean isReadOnly() { return readOnly; }

   /**
    * Returns <jk>true</jk> if this bean property is a URI.
    *
    * <p>
    * A bean property can be considered a URI if any of the following are true:
    * <ul>
    *    <li>Property class type is {@link URL} or {@link URI}.
    *    <li>Property class type is annotated with {@code @Uri}.
    *    <li>Property getter, setter, or field is annotated with {@code @Uri}.
    * </ul>
    *
    * @return <jk>true</jk> if this bean property is a URI.
    */
   public boolean isUri() { return isUri; }

   /**
    * Returns the set of named views this property belongs to, or <jk>null</jk> if the property is untagged.
    *
    * <p>
    * An untagged property (one with no {@code @MarshalledProp(view=...)} annotation) follows the
    * default-view-inclusion policy: it is included under every active view when the policy is enabled
    * (the default behavior), or excluded from all views when the policy is disabled.
    *
    * <p>
    * A tagged property is included only when the active view name is contained in this set.
    *
    * @return The set of named views, or <jk>null</jk> if no view membership was declared.
    */
   public Set<String> getViews() { return views; }

   /**
    * Equivalent to calling {@link BeanMap#put(String, Object)}, but is faster since it avoids looking up the property
    * meta.
    *
    * <p>
    * This is a no-op on a read-only property.
    *
    * @param m The bean map to set the property value on.
    * @param pName
    *    The property name if this is a dyna property (i.e. <js>"*"</js>).
    *    <br>Otherwise can be <jk>null</jk>.
    * @param value The value to set.  Can be <jk>null</jk> to set the property to <jk>null</jk>.
    * @return The previous property value.
    * @throws BeanRuntimeException If property could not be set.
    */
   public Object set(BeanMap<?> m, String pName, Object value) throws BeanRuntimeException {
      Object value1 = m.meta.onWriteProperty(m.bean, pName, value);
      if (! isDyna)
         m.recordPresent(name);
      try {

         if (readOnly)
            return null;

         var session = m.getBeanSession();

         // Apply the install-time write transform (identity by default; swap-aware in the marshalling layer).
         value1 = writeTransform.apply(session, value1);

         // Generic SPI hook: a transform that returns SKIP_VALUE causes the set to be skipped entirely so the
         // bean's pre-existing value (typically a field-initializer) is preserved.  Used by the marshalling
         // layer's per-property null-coercion SKIP mode.
         if (value1 == SKIP_VALUE)
            return null;

         if (m.bean == null) {

            // Read-only beans get their properties stored in a cache.
            if (nn(m.propertyCache))
               return m.propertyCache.put(name, value1);

            throw brex("Non-existent bean instance on bean.");
         }

         // Raw-reflection path: when the owning BeanMeta was built via the commons-side path, rawTypeMeta and
         // bc are null and there is no marshalling-aware type conversion to perform.  Just invoke the setter
         // (or write the field) directly.
         if (rawTypeMeta == null) {
            var bean = m.getBean(true);
            var old = (nn(getter) || nn(field)) ? get(m, pName) : null;
            invokeSetter(bean, pName, value1);
            return old;
         }

         var isMap = rawTypeMeta.isMap();
         var isCollection = rawTypeMeta.isCollection();

         if ((! isDyna) && field == null && setter == null && ! (isMap || isCollection)) {
            if ((value1 == null && config.isIgnoreUnknownNullBeanProperties()) || config.isIgnoreMissingSetters())
               return null;
            throw brex(beanMeta.getClassInfo(), "Setter or public field not defined on property '%s'", name);
         }

         var bean = m.getBean(true);  // Don't use getBean() because it triggers array creation!

         return setPropertyValue(m, pName, value1, bean, isMap, isCollection, session);
      } catch (org.apache.juneau.commons.BasicRuntimeException e2) {
         // Preserve previous behavior: marshalling-side BasicRuntimeException (notably ParseException raised by
         // session.parseToMap/parseToList or writeTransform) gets wrapped in BeanRuntimeException so callers can
         // uniformly catch BeanRuntimeException.  BeanRuntimeException itself does not extend BasicRuntimeException
         // so it propagates unchanged.
         throw brex(e2);
      }
   }

   private Object setPropertyValue(BeanMap<?> m, String pName, Object value1, Object bean, boolean isMap, boolean isCollection, BeanSession session) {
      try {
         var r = (config.isBeanMapPutReturnsOldValue() || isMap || isCollection) && (nn(getter) || nn(field)) ? get(m, pName) : null;
         var propertyClass = rawTypeMeta.inner();
         var pcInfo = rawTypeMeta;

         if (value1 == null && (isMap || isCollection)) {
            invokeSetter(bean, pName, null);
            return r;
         }

         var vc = value1 == null ? null : value1.getClass();

         if (isMap && (setter == null || ! pcInfo.isAssignableFrom(vc))) {

            if (! (value1 instanceof Map)) {
               if (value1 instanceof CharSequence value12)
                  value1 = session.parseToMap(value12);
               else
                  throw brex(beanMeta.getBeanInfo(), "Cannot set property '%s' of type '%s' to object of type '%s'", name, propertyClass.getName(), cn(value1));
            }

            var valueMap = (Map)value1;
            var propMap = (Map)r;
            var keyType = rawTypeMeta.getKeyType();
            var valueType = rawTypeMeta.getValueType();

            // If the property type is abstract, then we either need to reuse the existing
            // map (if it's not null), or try to assign the value directly.
            if (! rawTypeMeta.canCreateNewInstance()) {
               if (propMap == null) {
                  if (setter == null && field == null)
                     throw brex(beanMeta.getBeanInfo(),
                        "Cannot set property '%s' of type '%s' to object of type '%s' because no setter or public field is defined, and the current value is null", name,
                        propertyClass.getName(), cn(value1));

                  if (propertyClass.isInstance(valueMap)) {
                     if (! (keyType.isObject() && valueType.isObject())) {
                        var needsConversion = Flag.create();
                        valueMap.forEach((k, v2) -> {
                           if (nn(k) && ! keyType.isObject() && ! keyType.isInstance(k))
                              needsConversion.set();
                           if (nn(v2) && ! valueType.isInstance(v2)) {
                              needsConversion.set();
                           }
                        });
                        if (needsConversion.isSet())
                           valueMap = (Map)session.convertToType(valueMap, rawTypeMeta);
                     }
                     invokeSetter(bean, pName, valueMap);
                     return r;
                  }
                  throw brex(beanMeta.getBeanInfo(),
                     "Cannot set property '%1$s' of type '%3$s' to object of type '%3$s' because the assigned map cannot be converted to the specified type because the property type is abstract, and the property value is currently null",
                     name, propertyClass.getName(), cn(value1));
               }
            } else {
               if (propMap == null) {
                  propMap = mapFactory().get();
               } else {
                  propMap.clear();
               }
            }

            // Set the values.
            for (var e : ((Set<Map.Entry>)valueMap.entrySet())) {
               var k1 = e.getKey();
               var v1 = e.getValue();
               if (! keyType.isObject())
                  k1 = session.convertToType(k1, keyType);
               if (! valueType.isObject())
                  v1 = session.convertToType(v1, valueType);
               propMap.put(k1, v1);
            }
            if (nn(setter) || nn(field))
               invokeSetter(bean, pName, propMap);

         } else if (isCollection && (setter == null || ! pcInfo.isAssignableFrom(vc))) {

            if (! (value1 instanceof Collection)) {
               if (value1 instanceof CharSequence value12)
                  value1 = session.parseToList(value12);
               else
                  throw brex(beanMeta.getBeanInfo(), "Cannot set property '%s' of type '%s' to object of type '%s'", name, propertyClass.getName(), cn(value1));
            }

            var valueList = (Collection)value1;
            var propList = (Collection)r;
            var elementType = rawTypeMeta.getElementType();

            // If the property type is abstract, then we either need to reuse the existing
            // collection (if it's not null), or try to assign the value directly.
            if (! rawTypeMeta.canCreateNewInstance()) {
               if (propList == null) {
                  if (setter == null && field == null)
                     throw brex(beanMeta.getBeanInfo(),
                        "Cannot set property '%s' of type '%s' to object of type '%s' because no setter or public field is defined, and the current value is null", name,
                        propertyClass.getName(), cn(value1));

                  if (propertyClass.isInstance(valueList) || (nn(setter) && setter.getParameterTypes().get(0).is(Collection.class))) {
                     if (! elementType.isObject()) {
                        // Element coercion is required.  Build the coerced elements into a concrete collection
                        // whose shape is assignable to the (abstract) property type — never a bare ArrayList —
                        // so Deque/Queue/SortedSet fields aren't handed an incompatible container.  (The source
                        // value can incidentally satisfy propertyClass.isInstance(...) — e.g. the parser's
                        // generic list is a LinkedList, which is-a Deque/Queue — yet still need coercion.)
                        Collection coerced = abstractCollectionFactory(propertyClass).get();
                        for (var v : valueList) {
                           var needsConversion = v == null ? elementType.isOptional() : ! elementType.isInstance(v);
                           coerced.add(needsConversion ? session.convertToType(v, elementType) : v);
                        }
                        valueList = coerced;
                     }
                     invokeSetter(bean, pName, valueList);
                     return r;
                  }

                  // Robust best-effort-then-fallback materialization — never returns null (see helper Javadoc).
                  propList = abstractCollectionFactory(propertyClass).get();
                  invokeSetter(bean, pName, propList);
               }
               propList.clear();
            } else {
               if (propList == null) {
                  propList = concreteCollectionFactory().get();
                  invokeSetter(bean, pName, propList);
               } else {
                  propList.clear();
               }
            }

            // Set the values.
            for (var x : valueList) {
               if (! elementType.isObject())
                  x = session.convertToType(x, elementType);
               propList.add(x);
            }

         } else {
            value1 = session.convertToMemberType(bean, value1, rawTypeMeta);
            invokeSetter(bean, pName, value1);
         }

         return r;

      } catch (BeanRuntimeException e) {
         throw e;
      } catch (Exception e1) {
         if (config.isIgnoreInvocationExceptionsOnSetters()) {
            if (rawTypeMeta.isPrimitive())
               return rawTypeMeta.getPrimitiveDefault();
            return null;
         }
         throw brex(e1, beanMeta.getBeanInfo(), "Error occurred trying to set property '%s'", name);
      }
   }

   protected FluentMap<String,Object> properties() {
      // @formatter:off
      return filteredBeanPropertyMap()
         .a("field", field)
         .a("getter", getter)
         .a("name", name)
         .a("setter", setter)
         .a("type", cn(rawTypeMeta));
      // @formatter:on
   }

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

   private Object getInner(BeanMap<?> m, String pName) {
      try {

         if (writeOnly)
            return null;

         if (nn(overrideValue))
            return overrideValue;

         // Read-only beans have their properties stored in a cache until getBean() is called.
         var bean = m.bean;
         if (bean == null)
            return m.propertyCache.get(name);

         var session = m.getBeanSession();
         var o = getRaw(m, pName);

         return readTransform.apply(session, o);

      } catch (Exception e) {
         if (config.isIgnoreInvocationExceptionsOnGetters()) {
            if (nn(rawTypeMeta) && rawTypeMeta.isPrimitive())
               return rawTypeMeta.getPrimitiveDefault();
            return null;
         }
         throw brex(e, beanMeta.getClassInfo(), "Exception occurred while getting property '%s'", name);
      }
   }

   private Object invokeGetter(Object bean, String pName) throws IllegalArgumentException {
      if (isDyna) {
         Map m = null;
         if (nn(getter)) {
            if (! isDynaGetterMap)
               return getter.invoke(bean, pName);
            m = (Map)getter.invoke(bean);
         } else if (nn(field))
            m = (Map)field.get(bean);
         else
            throw brex(beanMeta.getClassInfo(), MSG_getterOrFieldNotDefined, name);
         return (m == null ? null : m.get(pName));
      }
      if (nn(getter))
         return getter.invoke(bean);
      if (nn(field))
         return field.get(bean);
      throw brex(beanMeta.getClassInfo(), MSG_getterOrFieldNotDefined, name);
   }

   private Object invokeSetter(Object bean, String pName, Object val) throws IllegalArgumentException {
      if (isDyna) {
         if (nn(setter))
            return setter.invoke(bean, pName, val);
         Map m = null;
         if (nn(field))
            m = (Map<String,Object>)field.get(bean);
         else if (nn(getter))
            m = (Map<String,Object>)getter.invoke(bean);
         else
            throw brex(beanMeta.getClassInfo(), "Cannot set property '%s' of type '%s' to object of type '%s' because no setter is defined on this property, and the existing property value is null",
               name, classNameForError(), cn(val));
         return (m == null ? null : m.put(pName, val));
      }
      if (nn(setter))
         return setter.invoke(bean, val);
      if (nn(field)) {
         field.set(bean, val);
         return null;
      }
      throw brex(beanMeta.getClassInfo(), "Cannot set property '%s' of type '%s' to object of type '%s' because no setter is defined on this property, and the existing property value is null", name,
         classNameForError(), cn(val));
   }

   private String classNameForError() {
      var cm = getBeanInfo();
      if (nn(cm))
         return cm.getName();
      return beanMeta.getClassInfo().getName();
   }

   /**
    * Returns a concrete {@link Collection} instance suitable for populating an abstract collection-typed bean
    * property that has no setter and no {@code @BeanProp(type=...)} override.
    *
    * <p>
    * Resolution is <b>best-effort-then-fallback</b>:
    * <ol>
    *    <li><b>Best-effort materialization of the declared type.</b>  First attempts to instantiate
    *       {@code propertyClass} directly via {@link BeanInstantiator} (preferring a zero-arg constructor).  This
    *       succeeds when the declared type is itself instantiable — e.g. a concrete {@link AbstractSet} /
    *       {@link AbstractList} subclass with an accessible no-arg constructor, or any type
    *       {@code BeanInstantiator} can otherwise construct.  The attempt never throws; on any failure it silently
    *       degrades to the shape-based fallback below.
    *    <li><b>Shape-based fallback.</b>  When the declared type is genuinely not instantiable (a {@link Set} /
    *       {@link List} / {@link Queue} interface, a truly abstract class, or a class with no usable constructor),
    *       a default concrete type is chosen by collection shape:
    *       <ul>
    *          <li>{@link SortedSet} / {@link NavigableSet} &rarr; {@link TreeSet}
    *          <li>{@link Set} &rarr; {@link LinkedHashSet} (preserves insertion order)
    *          <li>{@link Deque} / {@link Queue} &rarr; {@link ArrayDeque}
    *          <li>{@link List} / raw {@link Collection} (and any other collection shape) &rarr; {@link ArrayList}
    *       </ul>
    * </ol>
    *
    * <p>
    * The choice between the two is made once per property and memoized; each call to the returned supplier
    * creates a new, empty, concrete {@link Collection} instance (never <jk>null</jk>).
    *
    * @param propertyClass The declared (abstract or interface) collection type of the property.
    * @return The memoized factory for new collections of this property.
    */
   private Supplier<Collection<?>> abstractCollectionFactory(Class<?> propertyClass) {
      var f = abstractCollectionFactory.get();
      if (f == null) {
         // Best-effort: try to materialize the declared type itself (handles concrete AbstractSet/AbstractList
         // subclasses, registered defaults, etc.).  Never throws — degrades to the shape-based fallback on failure.
         Supplier<Collection<?>> declared = () -> BeanInstantiator.of(Collection.class).type(info(propertyClass)).preferZeroArgConstructor().fallback(() -> null).run();
         if (nn(declared.get()))
            f = declared;
         else
            f = shapeDefaultCollectionFactory(propertyClass);
         abstractCollectionFactory.set(f);
      }
      return f;
   }

   private static Supplier<Collection<?>> shapeDefaultCollectionFactory(Class<?> propertyClass) {
      // Shape-based fallback for genuinely non-instantiable declared types.
      if (SortedSet.class.isAssignableFrom(propertyClass) || NavigableSet.class.isAssignableFrom(propertyClass))
         return TreeSet::new;
      if (Set.class.isAssignableFrom(propertyClass))
         return LinkedHashSet::new;
      if (Deque.class.isAssignableFrom(propertyClass) || Queue.class.isAssignableFrom(propertyClass))
         return ArrayDeque::new;
      return ArrayList::new;  // List or raw Collection (and any other collection shape).
   }

   /**
    * Returns the memoized factory used to create a new collection for a concrete (instantiable) property type.
    *
    * <p>
    * Resolved once per property: a public no-arg constructor is cached when the type has one, otherwise each
    * call goes through the full {@link BeanInstantiator} pipeline.
    */
   private Supplier<Collection<?>> concreteCollectionFactory() {
      var f = concreteCollectionFactory.get();
      if (f == null) {
         var ctor = publicNoArgConstructor(rawTypeMeta);
         if (nn(ctor))
            f = ctor::newInstance;
         else
            f = () -> BeanInstantiator.of(Collection.class).type(rawTypeMeta).preferZeroArgConstructor().run();
         concreteCollectionFactory.set(f);
      }
      return f;
   }

   /**
    * Same as {@link #concreteCollectionFactory()} but for map-typed properties.
    */
   private Supplier<Map<?,?>> mapFactory() {
      var f = mapFactory.get();
      if (f == null) {
         var ctor = publicNoArgConstructor(rawTypeMeta);
         if (nn(ctor))
            f = ctor::newInstance;
         else
            f = () -> BeanInstantiator.of(Map.class).type(rawTypeMeta).preferZeroArgConstructor().run();
         mapFactory.set(f);
      }
      return f;
   }

   private static ConstructorInfo publicNoArgConstructor(ClassInfo ci) {
      if (ci.isAbstract() || ci.isInterface())
         return null;
      return ci.getPublicConstructors().stream()
         .filter(x -> x.isAll(ElementFlag.NOT_DEPRECATED))
         .filter(x -> x.isDeclaringClass(ci))
         .filter(x -> x.getParameterCount() == 0)
         .findFirst()
         .map(ConstructorInfo::accessible)
         .orElse(null);
   }

   /**
    * Returns <jk>true</jk> if this property is write-only.
    *
    * <p>
    * This implies the property MIGHT be readable, but that serializers should not serialize it.
    *
    * @return <jk>true</jk> if this property is write-only.
    */
   public boolean isWriteOnly() { return writeOnly; }

   /**
    * Sets an array field on this bean.
    *
    * <p>
    * Works on both <c>Object</c> and primitive arrays.
    *
    * <p>
    * <b>Marshalling-only path.</b>  Requires a property built via the marshalling-side construction path
    * (i.e. with a non-null {@link #getBeanInfo() rawTypeMeta}).  When the owning {@link BeanMeta} was built via
    * {@link BeanMeta#of(Class, BeanConfigContext)}, this method throws
    * {@link UnsupportedOperationException} because the array element type is only known via {@code rawTypeMeta},
    * which is not populated in the bean-modeling-only path.
    *
    * @param bean The bean of the field.
    * @param l The collection to use to set the array field.
    * @throws IllegalArgumentException Thrown by method invocation.
    * @throws IllegalAccessException Thrown by method invocation.
    * @throws InvocationTargetException Thrown by method invocation.
    * @throws UnsupportedOperationException If this property was built via the bean-modeling-only path
    *    ({@link BeanMeta#of(Class, BeanConfigContext)}).
    */
   protected void setArray(Object bean, List l) throws IllegalArgumentException, IllegalAccessException, InvocationTargetException {
      if (rawTypeMeta == null)
         throw uoex("Property '%s' was built via the bean-modeling-only path; setArray requires a marshalling context.", name);
      var array = toArray(l, this.rawTypeMeta.getElementType().inner());
      invokeSetter(bean, name, array);
   }
}