LazyDynaList.java

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