public class

GrowthList

extends AbstractSerializableListDecorator
java.lang.Object
   ↳ org.apache.commons.collections.collection.AbstractCollectionDecorator
     ↳ org.apache.commons.collections.list.AbstractListDecorator
       ↳ org.apache.commons.collections.list.AbstractSerializableListDecorator
         ↳ org.apache.commons.collections.list.GrowthList

Class Overview

Decorates another List to make it seamlessly grow when indices larger than the list size are used on add and set, avoiding most IndexOutOfBoundsExceptions.

This class avoids errors by growing when a set or add method would normally throw an IndexOutOfBoundsException. Note that IndexOutOfBoundsException IS returned for invalid negative indices.

Trying to set or add to an index larger than the size will cause the list to grow (using null elements). Clearly, care must be taken not to use excessively large indices, as the internal list will grow to match.

Trying to use any method other than add or set with an invalid index will call the underlying list and probably result in an IndexOutOfBoundsException.

Take care when using this list with null values, as null is the value added when growing the list.

All sub-lists will access the underlying list directly, and will throw IndexOutOfBoundsExceptions.

This class differs from LazyList because here growth occurs on set and add, where LazyList grows on get. However, they can be used together by decorating twice.

See Also

Summary

[Expand]
Inherited Fields
From class org.apache.commons.collections.collection.AbstractCollectionDecorator
Public Constructors
GrowthList()
Constructor that uses an ArrayList internally.
GrowthList(int initialSize)
Constructor that uses an ArrayList internally.
Protected Constructors
GrowthList(List list)
Constructor that wraps (not copies).
Public Methods
void add(int index, Object element)
Decorate the add method to perform the growth behaviour.
boolean addAll(int index, Collection coll)
Decorate the addAll method to perform the growth behaviour.
static List decorate(List list)
Factory method to create a growth list.
Object set(int index, Object element)
Decorate the set method to perform the growth behaviour.
[Expand]
Inherited Methods
From class org.apache.commons.collections.list.AbstractListDecorator
From class org.apache.commons.collections.collection.AbstractCollectionDecorator
From class java.lang.Object
From interface java.lang.Iterable
From interface java.util.Collection
From interface java.util.List

Public Constructors

public GrowthList ()

Constructor that uses an ArrayList internally.

public GrowthList (int initialSize)

Constructor that uses an ArrayList internally.

Parameters
initialSize the initial size of the ArrayList
Throws
IllegalArgumentException if initial size is invalid

Protected Constructors

protected GrowthList (List list)

Constructor that wraps (not copies).

Parameters
list the list to decorate, must not be null
Throws
IllegalArgumentException if list is null

Public Methods

public void add (int index, Object element)

Decorate the add method to perform the growth behaviour.

If the requested index is greater than the current size, the list will grow to the new size. Indices between the old size and the requested size will be filled with null.

If the index is less than the current size, the value will be added to the underlying list directly. If the index is less than zero, the underlying list is called, which will probably throw an IndexOutOfBoundsException.

Parameters
index the index to add at
element the object to add at the specified index
Throws
UnsupportedOperationException if the underlying list doesn't implement set
ClassCastException if the underlying list rejects the element
IllegalArgumentException if the underlying list rejects the element

public boolean addAll (int index, Collection coll)

Decorate the addAll method to perform the growth behaviour.

If the requested index is greater than the current size, the list will grow to the new size. Indices between the old size and the requested size will be filled with null.

If the index is less than the current size, the values will be added to the underlying list directly. If the index is less than zero, the underlying list is called, which will probably throw an IndexOutOfBoundsException.

Parameters
index the index to add at
coll the collection to add at the specified index
Returns
  • true if the list changed
Throws
UnsupportedOperationException if the underlying list doesn't implement set
ClassCastException if the underlying list rejects the element
IllegalArgumentException if the underlying list rejects the element

public static List decorate (List list)

Factory method to create a growth list.

Parameters
list the list to decorate, must not be null
Throws
IllegalArgumentException if list is null

public Object set (int index, Object element)

Decorate the set method to perform the growth behaviour.

If the requested index is greater than the current size, the list will grow to the new size. Indices between the old size and the requested size will be filled with null.

If the index is less than the current size, the value will be set onto the underlying list directly. If the index is less than zero, the underlying list is called, which will probably throw an IndexOutOfBoundsException.

Parameters
index the index to set
element the object to set at the specified index
Returns
  • the object previously at that index
Throws
UnsupportedOperationException if the underlying list doesn't implement set
ClassCastException if the underlying list rejects the element
IllegalArgumentException if the underlying list rejects the element