/*
    * 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.commons.beanutils2;
  
  import java.lang.reflect.Array;
  import java.util.ArrayList;
  import java.util.Arrays;
  import java.util.Collection;
  import java.util.Map;
  import java.util.Objects;
  
  /**
   * <h2><em>Lazy</em> DynaBean List.</h2>
   *
   * <p>
   * There are two main purposes for this class:
   * </p>
   * <ul>
   * <li>To provide <em>Lazy List</em> behavior - automatically <em>growing</em> and <em>populating</em> the {@code List} with either
   * {@code DynaBean</code>, <code>java.util.Map}
   *            or POJO Beans.</li>
   *        <li>To provide a straight forward way of putting a Collection
   *            or Array into the lazy list <em>and</em> a straight forward
   *            way to get it out again at the end.</li>
   *    </ul>
   *
   * <p>All elements added to the List are stored as {@code DynaBean}'s:</p>
   * <ul>
   *    <li>{@code java.util.Map</code> elements are "wrapped" in a <code>LazyDynaMap}.</li>
   *    <li>POJO Bean elements are "wrapped" in a {@code WrapDynaBean}.</li>
   *    <li>{@code DynaBean}'s are stored un-changed.</li>
   * </ul>
   *
   * <h2>{@code toArray()}</h2>
   * <p>The {@code toArray()} method returns an array of the
   *    elements of the appropriate type. If the {@code LazyDynaList}
   *    is populated with {@link java.util.Map} objects a
   *    {@code Map[]} array is returned.
   *    If the list is populated with POJO Beans an appropriate
   *    array of the POJO Beans is returned. Otherwise a {@code DynaBean[]}
   *    array is returned.
   * </p>
   *
   * <h2>{@code toDynaBeanArray()}</h2>
   * <p>The {@code toDynaBeanArray()} method returns a
   *    {@code DynaBean[]} array of the elements in the List.
   * </p>
   *
   * <p><strong>N.B.</strong>All the elements in the List must be the
   *    same type. If the {@code DynaClass</code> or <code>Class}
   *    of the {@code LazyDynaList}'s elements is
   *    not specified, then it will be automatically set to the type
   *    of the first element populated.
   * </p>
   *
   * <h2>Example 1</h2>
   * <p>If you have an array of {@code java.util.Map[]} - you can put that into
   *    a {@code LazyDynaList}.</p>
   *
   * <pre>{@code
   *    TreeMap[] myArray = .... // your Map[]
   *    List lazyList = new LazyDynaList(myArray);
   * }</pre>
   *
   * <p>New elements of the appropriate Map type are
   *    automatically populated:</p>
   *
   * <pre>{@code
   *    // get(index) automatically grows the list
   *    DynaBean newElement = (DynaBean)lazyList.get(lazyList.size());
   *    newElement.put("someProperty", "someValue");
   * }</pre>
   *
   * <p>Once you've finished you can get back an Array of the
   *    elements of the appropriate type:</p>
   *
   * <pre>{@code
   *    // Retrieve the array from the list
   *    TreeMap[] myArray = (TreeMap[])lazyList.toArray());
   * }</pre>
   *
   *
   * <h2>Example 2</h2>
   * <p>Alternatively you can create an <em>empty</em> List and
   *    specify the Class for List's elements. The LazyDynaList
  *    uses the Class to automatically populate elements:</p>
  *
  * <pre>{@code
  *    // for example For Maps
  *    List lazyList = new LazyDynaList(TreeMap.class);
  *
  *    // for example For POJO Beans
  *    List lazyList = new LazyDynaList(MyPojo.class);
  *
  *    // for example For DynaBeans
  *    List lazyList = new LazyDynaList(MyDynaBean.class);
  * }</pre>
  *
  * <h2>Example 3</h2>
  * <p>Alternatively you can create an <em>empty</em> List and specify the
  *    DynaClass for List's elements. The LazyDynaList uses
  *    the DynaClass to automatically populate elements:</p>
  *
  * <pre>{@code
  *    // for example For Maps
  *    DynaClass dynaClass = new LazyDynaMap(new HashMap());
  *    List lazyList = new LazyDynaList(dynaClass);
  *
  *    // for example For POJO Beans
  *    DynaClass dynaClass = (new WrapDynaBean(myPojo)).getDynaClass();
  *    List lazyList = new LazyDynaList(dynaClass);
  *
  *    // for example For DynaBeans
  *    DynaClass dynaClass = new BasicDynaClass(properties);
  *    List lazyList = new LazyDynaList(dynaClass);
  * }</pre>
  *
  * <p><strong>N.B.</strong> You may wonder why control the type
  *    using a {@code DynaClass</code> rather than the <code>Class} as in the previous example - the reason is that some {@code DynaBean} implementations don't
  * have a <em>default</em> empty constructor and therefore need to be instantiated using the {@code DynaClass.newInstance()} method.
  * </p>
  *
  * <h2>Example 4</h2>
  * <p>
  * A slight variation - set the element type using either the {@code setElementType(Class)} method or the {@code setElementDynaClass(DynaClass)} method - then
  * populate with the normal {@link java.util.List} methods (i.e. {@code add()}, {@code addAll()} or {@code set()}).
  * </p>
  *
  * <pre>{@code
  * // Create a new LazyDynaList (100 element capacity)
  * LazyDynaList lazyList = new LazyDynaList(100);
  *
  * // Either Set the element type...
  * lazyList.setElementType(TreeMap.class);
  *
  * // ...or the element DynaClass...
  * lazyList.setElementDynaClass(new MyCustomDynaClass());
  *
  * // Populate from a collection
  * lazyList.addAll(myCollection);
  *
  * }</pre>
  *
  * @since 1.8.0
  */
 public class LazyDynaList extends ArrayList<Object> {
 
     private static final long serialVersionUID = 1L;
 
     /**
      * The DynaClass of the List's elements.
      */
     private DynaClass elementDynaClass;
 
     /**
      * The WrapDynaClass if the List's contains POJO Bean elements.
      *
      * N.B. WrapDynaClass isn't serializable, which is why its stored separately in a transient instance variable.
      */
     private transient WrapDynaClass wrapDynaClass;
 
     /**
      * The type of the List's elements.
      */
     private Class<?> elementType;
 
     /**
      * The DynaBean type of the List's elements.
      */
     private Class<?> elementDynaBeanType;
 
     /**
      * Constructs a new instance.
      */
     public LazyDynaList() {
     }
 
     /**
      * Constructs a LazyDynaList with a specified type for its elements.
      *
      * @param elementType The Type of the List's elements.
      */
     public LazyDynaList(final Class<?> elementType) {
         setElementType(elementType);
     }
 
     /**
      * Constructs a LazyDynaList populated with the elements of a Collection.
      *
      * @param collection The Collection to populate the List from.
      */
     public LazyDynaList(final Collection<?> collection) {
         super(collection.size());
         addAll(collection);
     }
 
     /**
      * Constructs a LazyDynaList with a specified DynaClass for its elements.
      *
      * @param elementDynaClass The DynaClass of the List's elements.
      */
     public LazyDynaList(final DynaClass elementDynaClass) {
         setElementDynaClass(elementDynaClass);
     }
 
     /**
      * Constructs a LazyDynaList with the specified capacity.
      *
      * @param capacity The initial capacity of the list.
      */
     public LazyDynaList(final int capacity) {
         super(capacity);
 
     }
 
     /**
      * Constructs a LazyDynaList populated with the elements of an Array.
      *
      * @param array The Array to populate the List from.
      */
     public LazyDynaList(final Object[] array) {
         super(array.length);
         this.addAll(Arrays.asList(array));
     }
 
     /**
      * <p>
      * Insert an element at the specified index position.
      * </p>
      *
      * <p>
      * If the index position is greater than the current size of the List, then the List is automatically <em>grown</em> to the appropriate size.
      * </p>
      *
      * @param index   The index position to insert the new element.
      * @param element The new element to add.
      */
     @Override
     public void add(final int index, final Object element) {
         final DynaBean dynaBean = transform(element);
 
         growList(index);
 
         super.add(index, dynaBean);
     }
 
     /**
      * <p>
      * Add an element to the List.
      * </p>
      *
      * @param element The new element to add.
      * @return true.
      */
     @Override
     public boolean add(final Object element) {
         final DynaBean dynaBean = transform(element);
 
         return super.add(dynaBean);
     }
 
     /**
      * <p>
      * Add all the elements from a Collection to the list.
      *
      * @param collection The Collection of new elements.
      * @return true if elements were added.
      */
     @Override
     public boolean addAll(final Collection<?> collection) {
         if (collection == null || collection.isEmpty()) {
             return false;
         }
 
         ensureCapacity(size() + collection.size());
 
         collection.forEach(this::add);
 
         return true;
     }
 
     /**
      * <p>
      * Insert all the elements from a Collection into the list at a specified position.
      *
      * <p>
      * If the index position is greater than the current size of the List, then the List is automatically <em>grown</em> to the appropriate size.
      * </p>
      *
      * @param collection The Collection of new elements.
      * @param index      The index position to insert the new elements at.
      * @return true if elements were added.
      */
     @Override
     public boolean addAll(final int index, final Collection<?> collection) {
         if (collection == null || collection.isEmpty()) {
             return false;
         }
 
         ensureCapacity(Math.max(index, size()) + collection.size());
 
         // Call "transform" with first element, before
         // List is "grown" to ensure the correct DynaClass
         // is set.
         if (isEmpty()) {
             transform(collection.iterator().next());
         }
 
         growList(index);
 
         int currentIndex = index;
         for (final Object e : collection) {
             add(currentIndex++, e);
         }
 
         return true;
     }
 
     /**
      * Creates a new {@code LazyDynaMap} object for the given property value.
      *
      * @param value the property value
      * @return the newly created {@code LazyDynaMap}
      */
     private LazyDynaMap createDynaBeanForMapProperty(final Object value) {
         @SuppressWarnings("unchecked")
         final
         // map properties are always stored as Map<String, Object>
         Map<String, Object> valueMap = (Map<String, Object>) value;
         return new LazyDynaMap(valueMap);
     }
 
     /**
      * <p>
      * Return the element at the specified position.
      * </p>
      *
      * <p>
      * If the position requested is greater than the current size of the List, then the List is automatically <em>grown</em> (and populated) to the appropriate
      * size.
      * </p>
      *
      * @param index The index position to insert the new elements at.
      * @return The element at the specified position.
      */
     @Override
     public Object get(final int index) {
         growList(index + 1);
 
         return super.get(index);
     }
 
     /**
      * Gets the DynaClass.
      */
     private DynaClass getDynaClass() {
         return elementDynaClass == null ? wrapDynaClass : elementDynaClass;
     }
 
     /**
      * <p>
      * Automatically <em>grown</em> the List to the appropriate size, populating with DynaBeans.
      * </p>
      *
      * @param requiredSize the required size of the List.
      */
     private void growList(final int requiredSize) {
         if (requiredSize < size()) {
             return;
         }
 
         ensureCapacity(requiredSize + 1);
 
         for (int i = size(); i < requiredSize; i++) {
             final DynaBean dynaBean = transform(null);
             super.add(dynaBean);
         }
     }
 
     /**
      * <p>
      * Set the element at the specified position.
      * </p>
      *
      * <p>
      * If the position requested is greater than the current size of the List, then the List is automatically <em>grown</em> (and populated) to the appropriate
      * size.
      * </p>
      *
      * @param index   The index position to insert the new element at.
      * @param element The new element.
      * @return The new element.
      */
     @Override
     public Object set(final int index, final Object element) {
         final DynaBean dynaBean = transform(element);
 
         growList(index + 1);
 
         return super.set(index, dynaBean);
     }
 
     /**
      * <p>
      * Set the element Type and DynaClass.
      * </p>
      *
      * @param elementDynaClass The DynaClass of the elements.
      * @throws IllegalArgumentException if the List already contains elements or the DynaClass is null.
      */
     public void setElementDynaClass(final DynaClass elementDynaClass) {
         Objects.requireNonNull(elementDynaClass, "elementDynaClass");
         if (!isEmpty()) {
             throw new IllegalStateException("Element DynaClass cannot be reset");
         }
 
         // Try to create a new instance of the DynaBean
         try {
             final DynaBean dynaBean = elementDynaClass.newInstance();
             this.elementDynaBeanType = dynaBean.getClass();
             if (WrapDynaBean.class.isAssignableFrom(elementDynaBeanType)) {
                 this.elementType = ((WrapDynaBean) dynaBean).getInstance().getClass();
                 this.wrapDynaClass = (WrapDynaClass) elementDynaClass;
             } else {
                 if (LazyDynaMap.class.isAssignableFrom(elementDynaBeanType)) {
                     this.elementType = ((LazyDynaMap) dynaBean).getMap().getClass();
                 } else {
                     this.elementType = dynaBean.getClass();
                 }
                 this.elementDynaClass = elementDynaClass;
             }
         } catch (final Exception e) {
             throw new IllegalArgumentException("Error creating DynaBean from " + elementDynaClass.getClass().getName() + " - " + e);
         }
     }
 
     /**
      * <p>
      * Set the element Type and DynaClass.
      * </p>
      *
      * @param elementType The type of the elements.
      * @throws IllegalArgumentException if the List already contains elements or the DynaClass is null.
      */
     public void setElementType(final Class<?> elementType) {
         Objects.requireNonNull(elementType, "elementType");
         final boolean changeType = this.elementType != null && !this.elementType.equals(elementType);
         if (changeType && !isEmpty()) {
             throw new IllegalStateException("Element Type cannot be reset");
         }
 
         this.elementType = elementType;
 
         // Create a new object of the specified type
         Object object = null;
         try {
             object = elementType.newInstance();
         } catch (final Exception e) {
             throw new IllegalArgumentException("Error creating type: " + elementType.getName() + " - " + e);
         }
 
         // Create a DynaBean
         DynaBean dynaBean = null;
         if (Map.class.isAssignableFrom(elementType)) {
             dynaBean = createDynaBeanForMapProperty(object);
             this.elementDynaClass = dynaBean.getDynaClass();
         } else if (DynaBean.class.isAssignableFrom(elementType)) {
             dynaBean = (DynaBean) object;
             this.elementDynaClass = dynaBean.getDynaClass();
         } else {
             dynaBean = new WrapDynaBean(object);
             this.wrapDynaClass = (WrapDynaClass) dynaBean.getDynaClass();
         }
 
         this.elementDynaBeanType = dynaBean.getClass();
 
         // Re-calculate the type
         if (WrapDynaBean.class.isAssignableFrom(elementDynaBeanType)) {
             this.elementType = ((WrapDynaBean) dynaBean).getInstance().getClass();
         } else if (LazyDynaMap.class.isAssignableFrom(elementDynaBeanType)) {
             this.elementType = ((LazyDynaMap) dynaBean).getMap().getClass();
         }
     }
 
     /**
      * <p>
      * Converts the List to an Array.
      * </p>
      *
      * <p>
      * The type of Array created depends on the contents of the List:
      * </p>
      * <ul>
      * <li>If the List contains only LazyDynaMap type elements then a java.util.Map[] array will be created.</li>
      * <li>If the List contains only elements which are "wrapped" DynaBeans then an Object[] of the most suitable type will be created.</li>
      * <li>...otherwise a DynaBean[] will be created.</li>
      * </ul>
      *
      * @return An Array of the elements in this List.
      */
     @Override
     public Object[] toArray() {
         if (isEmpty() && elementType == null) {
             return LazyDynaBean.EMPTY_ARRAY;
         }
 
         final Object[] array = (Object[]) Array.newInstance(elementType, size());
         for (int i = 0; i < size(); i++) {
             if (Map.class.isAssignableFrom(elementType)) {
                 array[i] = ((LazyDynaMap) get(i)).getMap();
             } else if (DynaBean.class.isAssignableFrom(elementType)) {
                 array[i] = get(i);
             } else {
                 array[i] = ((WrapDynaBean) get(i)).getInstance();
             }
         }
         return array;
     }
 
     /**
      * <p>
      * Converts the List to an Array of the specified type.
      * </p>
      *
      * @param <T>   The type of the array elements
      * @param model The model for the type of array to return
      * @return An Array of the elements in this List.
      */
     @Override
     public <T> T[] toArray(final T[] model) {
         final Class<?> arrayType = model.getClass().getComponentType();
         if (DynaBean.class.isAssignableFrom(arrayType) || isEmpty() && elementType == null) {
             return super.toArray(model);
         }
 
         if (arrayType.isAssignableFrom(elementType)) {
             T[] array;
             if (model.length >= size()) {
                 array = model;
             } else {
                 @SuppressWarnings("unchecked")
                 final
                 // This is safe because we know the element type
                 T[] tempArray = (T[]) Array.newInstance(arrayType, size());
                 array = tempArray;
             }
 
             for (int i = 0; i < size(); i++) {
                 Object elem;
                 if (Map.class.isAssignableFrom(elementType)) {
                     elem = ((LazyDynaMap) get(i)).getMap();
                 } else if (DynaBean.class.isAssignableFrom(elementType)) {
                     elem = get(i);
                 } else {
                     elem = ((WrapDynaBean) get(i)).getInstance();
                 }
                 Array.set(array, i, elem);
             }
             return array;
         }
 
         throw new IllegalArgumentException("Invalid array type: " + arrayType.getName() + " - not compatible with '" + elementType.getName());
     }
 
     /**
      * <p>
      * Converts the List to an DynaBean Array.
      * </p>
      *
      * @return A DynaBean[] of the elements in this List.
      */
     public DynaBean[] toDynaBeanArray() {
         if (isEmpty() && elementDynaBeanType == null) {
             return LazyDynaBean.EMPTY_ARRAY;
         }
 
         final DynaBean[] array = (DynaBean[]) Array.newInstance(elementDynaBeanType, size());
         for (int i = 0; i < size(); i++) {
             array[i] = (DynaBean) get(i);
         }
         return array;
     }
 
     /**
      * <p>
      * Transform the element into a DynaBean:
      * </p>
      *
      * <ul>
      * <li>Map elements are turned into LazyDynaMap's.</li>
      * <li>POJO Beans are "wrapped" in a WrapDynaBean.</li>
      * <li>DynaBeans are unchanged.</li></li>
      *
      * @param element The element to transformed.
      * @return The DynaBean to store in the List.
      */
     private DynaBean transform(final Object element) {
         DynaBean dynaBean = null;
         Class<?> newDynaBeanType = null;
         Class<?> newElementType;
 
         // Create a new element
         if (element == null) {
 
             // Default Types to LazyDynaBean
             // if not specified
             if (elementType == null) {
                 setElementDynaClass(new LazyDynaClass());
             }
 
             // Get DynaClass (restore WrapDynaClass lost in serialization)
             if (getDynaClass() == null) {
                 setElementType(elementType);
             }
 
             // Create a new DynaBean
             try {
                 dynaBean = getDynaClass().newInstance();
                 newDynaBeanType = dynaBean.getClass();
             } catch (final Exception e) {
                 throw new IllegalArgumentException("Error creating DynaBean: " + getDynaClass().getClass().getName() + " - " + e);
             }
 
         } else {
 
             // Transform Object to a DynaBean
             newElementType = element.getClass();
             if (Map.class.isAssignableFrom(element.getClass())) {
                 dynaBean = createDynaBeanForMapProperty(element);
             } else if (DynaBean.class.isAssignableFrom(element.getClass())) {
                 dynaBean = (DynaBean) element;
             } else {
                 dynaBean = new WrapDynaBean(element);
             }
 
             newDynaBeanType = dynaBean.getClass();
 
         }
 
         // Re-calculate the element type
         newElementType = dynaBean.getClass();
         if (WrapDynaBean.class.isAssignableFrom(newDynaBeanType)) {
             newElementType = ((WrapDynaBean) dynaBean).getInstance().getClass();
         } else if (LazyDynaMap.class.isAssignableFrom(newDynaBeanType)) {
             newElementType = ((LazyDynaMap) dynaBean).getMap().getClass();
         }
 
         // Check the new element type, matches all the
         // other elements in the List
         if (elementType != null && !newElementType.equals(elementType)) {
             throw new IllegalArgumentException("Element Type " + newElementType + " doesn't match other elements " + elementType);
         }
 
         return dynaBean;
     }
 }