Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.commons.collections.list
Class GrowthList

    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

All Implemented Interfaces:
  java.io.Serializable, java.lang.Iterable, java.util.Collection, java.util.List

    public class GrowthList

extends AbstractSerializableListDecorator

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.

Since:
  Commons Collections 3.2
Version:
  $Revision: 155406 $ $Date: 2008-04-10 13:33:15 +0100 (Thu, 10 Apr 2008) $
Author:
  Stephen Colebourne, Paul Legato
See Also:
  `LazyList`, Serialized Form

Field Summary

Fields inherited from class org.apache.commons.collections.collection.AbstractCollectionDecorator
`collection`

Constructor Summary
`` | `GrowthList()` Constructor that uses an ArrayList internally.
`` | `GrowthList(int initialSize)` Constructor that uses an ArrayList internally.
`protected` | `GrowthList(java.util.List list)` Constructor that wraps (not copies).

Method Summary
`void` | `add(int index, java.lang.Object element)` Decorate the add method to perform the growth behaviour.
`boolean` | `addAll(int index, java.util.Collection coll)` Decorate the addAll method to perform the growth behaviour.
`static java.util.List` | `decorate(java.util.List list)` Factory method to create a growth list.
`java.lang.Object` | `set(int index, java.lang.Object element)` Decorate the set method to perform the growth behaviour.

Methods inherited from class org.apache.commons.collections.list.AbstractListDecorator
`get, getList, indexOf, lastIndexOf, listIterator, listIterator, remove, subList`

Methods inherited from class org.apache.commons.collections.collection.AbstractCollectionDecorator
`add, addAll, clear, contains, containsAll, equals, getCollection, hashCode, isEmpty, iterator, remove, removeAll, retainAll, size, toArray, toArray, toString`

Methods inherited from class java.lang.Object
`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

Methods inherited from interface java.util.List
`add, addAll, clear, contains, containsAll, equals, hashCode, isEmpty, iterator, remove, removeAll, retainAll, size, toArray, toArray`

Constructor Detail

### GrowthList

    public GrowthList()

  Constructor that uses an ArrayList internally.

### GrowthList

    public GrowthList(int initialSize)

  Constructor that uses an ArrayList internally.

  Parameters:
    `initialSize` - the initial size of the ArrayList
  Throws:
    `java.lang.IllegalArgumentException` - if initial size is invalid

### GrowthList

    protected GrowthList(java.util.List list)

  Constructor that wraps (not copies).

  Parameters:
    `list` - the list to decorate, must not be null
  Throws:
    `java.lang.IllegalArgumentException` - if list is null

Method Detail

### decorate

    public static java.util.List decorate(java.util.List list)

  Factory method to create a growth list.

  Parameters:
    `list` - the list to decorate, must not be null
  Throws:
    `java.lang.IllegalArgumentException` - if list is null

### add

    public void add(int index,
                    java.lang.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.

  Specified by:
    `add` in interface `java.util.List`
  Overrides:
    `add` in class `AbstractListDecorator`
  Parameters:
    `index` - the index to add at
    `element` - the object to add at the specified index
  Throws:
    `java.lang.UnsupportedOperationException` - if the underlying list doesn't implement set
    `java.lang.ClassCastException` - if the underlying list rejects the element
    `java.lang.IllegalArgumentException` - if the underlying list rejects the element

### addAll

    public boolean addAll(int index,
                          java.util.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.

  Specified by:
    `addAll` in interface `java.util.List`
  Overrides:
    `addAll` in class `AbstractListDecorator`
  Parameters:
    `index` - the index to add at
    `coll` - the collection to add at the specified index
  Returns:
    true if the list changed
  Throws:
    `java.lang.UnsupportedOperationException` - if the underlying list doesn't implement set
    `java.lang.ClassCastException` - if the underlying list rejects the element
    `java.lang.IllegalArgumentException` - if the underlying list rejects the element

### set

    public java.lang.Object set(int index,
                                java.lang.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.

  Specified by:
    `set` in interface `java.util.List`
  Overrides:
    `set` in class `AbstractListDecorator`
  Parameters:
    `index` - the index to set
    `element` - the object to set at the specified index
  Returns:
    the object previously at that index
  Throws:
    `java.lang.UnsupportedOperationException` - if the underlying list doesn't implement set
    `java.lang.ClassCastException` - if the underlying list rejects the element
    `java.lang.IllegalArgumentException` - if the underlying list rejects the element

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2001-2008 The Apache Software Foundation. All Rights Reserved.