org.apache.commons.beanutils

## Class LazyDynaList

- java.lang.Object
- - java.util.AbstractCollection<E>
  - - java.util.AbstractList<E>
    - - java.util.ArrayList<Object>
      - - org.apache.commons.beanutils.LazyDynaList

- All Implemented Interfaces:
    Serializable, Cloneable, Iterable<Object>, Collection<Object>, List<Object>, RandomAccess

      public class LazyDynaList
      extends ArrayList<Object>

  ## Lazy DynaBean List.

  There are two main purposes for this class:

  - To provide Lazy List behaviour - automatically growing and populating the `List` with either `DynaBean`, `java.util.Map` or POJO Beans.
  - To provide a straight forward way of putting a Collection or Array into the lazy list and a straight forward way to get it out again at the end.

  All elements added to the List are stored as `DynaBean`'s:

  - `java.util.Map` elements are "wrapped" in a `LazyDynaMap`.
  - POJO Bean elements are "wrapped" in a `WrapDynaBean.`
  - `DynaBean`'s are stored un-changed.

  #### `toArray()`

  The `toArray()` method returns an array of the elements of the appropriate type. If the `LazyDynaList` is populated with `java.util.Map` objects a `Map[]` array is returned. If the list is populated with POJO Beans an appropriate array of the POJO Beans is returned. Otherwise a `DynaBean[]` array is returned.

  #### `toDynaBeanArray()`

  The `toDynaBeanArray()` method returns a `DynaBean[]` array of the elements in the List.

  N.B.All the elements in the List must be the same type. If the `DynaClass` or `Class` of the `LazyDynaList`'s elements is not specified, then it will be automatically set to the type of the first element populated.

  ### Example 1

  If you have an array of `java.util.Map[]` - you can put that into a `LazyDynaList`.

          TreeMap[] myArray = .... // your Map[]
          List lazyList = new LazyDynaList(myArray);

  New elements of the appropriate Map type are automatically populated:

          // get(index) automatically grows the list
          DynaBean newElement = (DynaBean)lazyList.get(lazyList.size());
          newElement.put("someProperty", "someValue");

  Once you've finished you can get back an Array of the elements of the appropriate type:

          // Retrieve the array from the list
          TreeMap[] myArray = (TreeMap[])lazyList.toArray());

  ### Example 2

  Alternatively you can create an empty List and specify the Class for List's elements. The LazyDynaList uses the Class to automatically populate elements:

          // e.g. For Maps
          List lazyList = new LazyDynaList(TreeMap.class);

          // e.g. For POJO Beans
          List lazyList = new LazyDynaList(MyPojo.class);

          // e.g. For DynaBeans
          List lazyList = new LazyDynaList(MyDynaBean.class);

  ### Example 3

  Alternatively you can create an empty List and specify the DynaClass for List's elements. The LazyDynaList uses the DynaClass to automatically populate elements:

          // e.g. For Maps
          DynaClass dynaClass = new LazyDynaMap(new HashMap());
          List lazyList = new LazyDynaList(dynaClass);

          // e.g. For POJO Beans
          DynaClass dynaClass = (new WrapDynaBean(myPojo)).getDynaClass();
          List lazyList = new LazyDynaList(dynaClass);

          // e.g. For DynaBeans
          DynaClass dynaClass = new BasicDynaClass(properties);
          List lazyList = new LazyDynaList(dynaClass);

  N.B. You may wonder why control the type using a `DynaClass` rather than the `Class` as in the previous example - the reason is that some `DynaBean` implementations don't have a default empty constructor and therefore need to be instantiated using the `DynaClass.newInstance()` method.

  ### Example 4

  A slight variation - set the element type using either the `setElementType(Class)` method or the `setElementDynaClass(DynaClass)` method - then populate with the normal `java.util.List` methods(i.e. `add()`, `addAll()` or `set()`).

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

  Since:
    1.8.0
  Version:
    $Id$
  See Also:
    Serialized Form

- - ### Field Summary

    - ### Fields inherited from class java.util.AbstractList

      `modCount`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `LazyDynaList()` Default Constructor.
    `LazyDynaList(Class<?> elementType)` Construct a LazyDynaList with a specified type for its elements.
    `LazyDynaList(Collection<?> collection)` Construct a LazyDynaList populated with the elements of a Collection.
    `LazyDynaList(DynaClass elementDynaClass)` Construct a LazyDynaList with a specified DynaClass for its elements.
    `LazyDynaList(int capacity)` Construct a LazyDynaList with the specified capacity.
    `LazyDynaList(Object[] array)` Construct a LazyDynaList populated with the elements of an Array.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `add(int index, Object element)` Insert an element at the specified index position.
    `boolean` | `add(Object element)` Add an element to the List.
    `boolean` | `addAll(Collection<?> collection)` Add all the elements from a Collection to the list.
    `boolean` | `addAll(int index, Collection<?> collection)` Insert all the elements from a Collection into the list at a specified position.
    `Object` | `get(int index)` Return the element at the specified position.
    `Object` | `set(int index, Object element)` Set the element at the specified position.
    `void` | `setElementDynaClass(DynaClass elementDynaClass)` Set the element Type and DynaClass.
    `void` | `setElementType(Class<?> elementType)` Set the element Type and DynaClass.
    `Object[]` | `toArray()` Converts the List to an Array.
    `<T> T[]` | `toArray(T[] model)` Converts the List to an Array of the specified type.
    `DynaBean[]` | `toDynaBeanArray()` Converts the List to an DynaBean Array.

    - ### Methods inherited from class java.util.ArrayList

      `clear, clone, contains, ensureCapacity, forEach, indexOf, isEmpty, iterator, lastIndexOf, listIterator, listIterator, remove, remove, removeAll, removeIf, removeRange, replaceAll, retainAll, size, sort, spliterator, subList, trimToSize`

    - ### Methods inherited from class java.util.AbstractList

      `equals, hashCode`

    - ### Methods inherited from class java.util.AbstractCollection

      `containsAll, toString`

    - ### Methods inherited from class java.lang.Object

      `finalize, getClass, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface java.util.List

      `containsAll, equals, hashCode`

    - ### Methods inherited from interface java.util.Collection

      `parallelStream, stream`

- - ### Constructor Detail

    - #### LazyDynaList

          public LazyDynaList()

      Default Constructor.

    - #### LazyDynaList

          public LazyDynaList(int capacity)

      Construct a LazyDynaList with the specified capacity.
      Parameters:
        `capacity` - The initial capacity of the list.

    - #### LazyDynaList

          public LazyDynaList(DynaClass elementDynaClass)

      Construct a LazyDynaList with a specified DynaClass for its elements.
      Parameters:
        `elementDynaClass` - The DynaClass of the List's elements.

    - #### LazyDynaList

          public LazyDynaList(Class<?> elementType)

      Construct a LazyDynaList with a specified type for its elements.
      Parameters:
        `elementType` - The Type of the List's elements.

    - #### LazyDynaList

          public LazyDynaList(Collection<?> collection)

      Construct a LazyDynaList populated with the elements of a Collection.
      Parameters:
        `collection` - The Collection to populate the List from.

    - #### LazyDynaList

          public LazyDynaList(Object[] array)

      Construct a LazyDynaList populated with the elements of an Array.
      Parameters:
        `array` - The Array to populate the List from.

  - ### Method Detail

    - #### add

          public void add(int index,
                          Object element)

      Insert an element at the specified index position.

      If the index position is greater than the current size of the List, then the List is automatically grown to the appropriate size.

      Specified by:
        `add` in interface `List<Object>`
      Overrides:
        `add` in class `ArrayList<Object>`
      Parameters:
        `index` - The index position to insert the new element.
        `element` - The new element to add.

    - #### add

          public boolean add(Object element)

      Add an element to the List.

      Specified by:
        `add` in interface `Collection<Object>`
      Specified by:
        `add` in interface `List<Object>`
      Overrides:
        `add` in class `ArrayList<Object>`
      Parameters:
        `element` - The new element to add.
      Returns:
        true.

    - #### addAll

          public boolean addAll(Collection<?> collection)

      Add all the elements from a Collection to the list.

      Specified by:
        `addAll` in interface `Collection<Object>`
      Specified by:
        `addAll` in interface `List<Object>`
      Overrides:
        `addAll` in class `ArrayList<Object>`
      Parameters:
        `collection` - The Collection of new elements.
      Returns:
        true if elements were added.

    - #### addAll

          public boolean addAll(int index,
                                Collection<?> collection)

      Insert all the elements from a Collection into the list at a specified position.

      If the index position is greater than the current size of the List, then the List is automatically grown to the appropriate size.

      Specified by:
        `addAll` in interface `List<Object>`
      Overrides:
        `addAll` in class `ArrayList<Object>`
      Parameters:
        `collection` - The Collection of new elements.
        `index` - The index position to insert the new elements at.
      Returns:
        true if elements were added.

    - #### get

          public Object get(int index)

      Return the element at the specified position.

      If the position requested is greater than the current size of the List, then the List is automatically grown (and populated) to the appropriate size.

      Specified by:
        `get` in interface `List<Object>`
      Overrides:
        `get` in class `ArrayList<Object>`
      Parameters:
        `index` - The index position to insert the new elements at.
      Returns:
        The element at the specified position.

    - #### set

          public Object set(int index,
                            Object element)

      Set the element at the specified position.

      If the position requested is greater than the current size of the List, then the List is automatically grown (and populated) to the appropriate size.

      Specified by:
        `set` in interface `List<Object>`
      Overrides:
        `set` in class `ArrayList<Object>`
      Parameters:
        `index` - The index position to insert the new element at.
        `element` - The new element.
      Returns:
        The new element.

    - #### toArray

          public Object[] toArray()

      Converts the List to an Array.

      The type of Array created depends on the contents of the List:

      - If the List contains only LazyDynaMap type elements then a java.util.Map[] array will be created.
      - If the List contains only elements which are "wrapped" DynaBeans then an Object[] of the most suitable type will be created.
      - ...otherwise a DynaBean[] will be created.
      Specified by:
        `toArray` in interface `Collection<Object>`
      Specified by:
        `toArray` in interface `List<Object>`
      Overrides:
        `toArray` in class `ArrayList<Object>`
      Returns:
        An Array of the elements in this List.

    - #### toArray

          public <T> T[] toArray(T[] model)

      Converts the List to an Array of the specified type.

      Specified by:
        `toArray` in interface `Collection<Object>`
      Specified by:
        `toArray` in interface `List<Object>`
      Overrides:
        `toArray` in class `ArrayList<Object>`
      Type Parameters:
        `T` - The type of the array elements
      Parameters:
        `model` - The model for the type of array to return
      Returns:
        An Array of the elements in this List.

    - #### toDynaBeanArray

          public DynaBean[] toDynaBeanArray()

      Converts the List to an DynaBean Array.

      Returns:
        A DynaBean[] of the elements in this List.

    - #### setElementType

          public void setElementType(Class<?> elementType)

      Set the element Type and DynaClass.

      Parameters:
        `elementType` - The type of the elements.
      Throws:
        `IllegalArgumentException` - if the List already contains elements or the DynaClass is null.

    - #### setElementDynaClass

          public void setElementDynaClass(DynaClass elementDynaClass)

      Set the element Type and DynaClass.

      Parameters:
        `elementDynaClass` - The DynaClass of the elements.
      Throws:
        `IllegalArgumentException` - if the List already contains elements or the DynaClass is null.

Copyright © 2000–2019 The Apache Software Foundation. All rights reserved.