public class

FastArrayList

extends ArrayList<E>
java.lang.Object
   ↳ java.util.AbstractCollection<E>
     ↳ java.util.AbstractList<E>
       ↳ java.util.ArrayList<E>
         ↳ org.apache.commons.collections.FastArrayList

Class Overview

A customized implementation of java.util.ArrayList designed to operate in a multithreaded environment where the large majority of method calls are read-only, instead of structural changes. When operating in "fast" mode, read calls are non-synchronized and write calls perform the following steps:

  • Clone the existing collection
  • Perform the modification on the clone
  • Replace the existing collection with the (modified) clone

When first created, objects of this class default to "slow" mode, where all accesses of any type are synchronized but no cloning takes place. This is appropriate for initially populating the collection, followed by a switch to "fast" mode (by calling setFast(true)) after initialization is complete.

NOTE: If you are creating and accessing an ArrayList only within a single thread, you should use java.util.ArrayList directly (with no synchronization), for maximum performance.

NOTE: This class is not cross-platform. Using it may cause unexpected failures on some architectures. It suffers from the same problems as the double-checked locking idiom. In particular, the instruction that clones the internal collection and the instruction that sets the internal reference to the clone can be executed or perceived out-of-order. This means that any read operation might fail unexpectedly, as it may be reading the state of the internal collection before the internal collection is fully formed. For more information on the double-checked locking idiom, see the Double-Checked Locking Idiom Is Broken Declaration.

Summary

Fields
protected boolean fast Are we operating in "fast" mode?
protected ArrayList list The underlying list we are managing.
[Expand]
Inherited Fields
From class java.util.AbstractList
Public Constructors
FastArrayList()
Construct a an empty list.
FastArrayList(int capacity)
Construct an empty list with the specified capacity.
FastArrayList(Collection collection)
Construct a list containing the elements of the specified collection, in the order they are returned by the collection's iterator.
Public Methods
boolean add(Object element)
Appends the specified element to the end of this list.
void add(int index, Object element)
Insert the specified element at the specified position in this list, and shift all remaining elements up one position.
boolean addAll(Collection collection)
Append all of the elements in the specified Collection to the end of this list, in the order that they are returned by the specified Collection's Iterator.
boolean addAll(int index, Collection collection)
Insert all of the elements in the specified Collection at the specified position in this list, and shift any previous elements upwards as needed.
void clear()
Remove all of the elements from this list.
Object clone()
Return a shallow copy of this FastArrayList instance.
boolean contains(Object element)
Return true if this list contains the specified element.
boolean containsAll(Collection collection)
Return true if this list contains all of the elements in the specified Collection.
void ensureCapacity(int capacity)
Increase the capacity of this ArrayList instance, if necessary, to ensure that it can hold at least the number of elements specified by the minimum capacity argument.
boolean equals(Object o)
Compare the specified object with this list for equality.
Object get(int index)
Return the element at the specified position in the list.
boolean getFast()
Returns true if this list is operating in fast mode.
int hashCode()
Return the hash code value for this list.
int indexOf(Object element)
Search for the first occurrence of the given argument, testing for equality using the equals() method, and return the corresponding index, or -1 if the object is not found.
boolean isEmpty()
Test if this list has no elements.
Iterator iterator()
Return an iterator over the elements in this list in proper sequence.
int lastIndexOf(Object element)
Search for the last occurrence of the given argument, testing for equality using the equals() method, and return the corresponding index, or -1 if the object is not found.
ListIterator listIterator(int index)
Return an iterator of the elements of this list, in proper sequence, starting at the specified position.
ListIterator listIterator()
Return an iterator of the elements of this list, in proper sequence.
Object remove(int index)
Remove the element at the specified position in the list, and shift any subsequent elements down one position.
boolean remove(Object element)
Remove the first occurrence of the specified element from the list, and shift any subsequent elements down one position.
boolean removeAll(Collection collection)
Remove from this collection all of its elements that are contained in the specified collection.
boolean retainAll(Collection collection)
Remove from this collection all of its elements except those that are contained in the specified collection.
Object set(int index, Object element)
Replace the element at the specified position in this list with the specified element.
void setFast(boolean fast)
Sets whether this list will operate in fast mode.
int size()
Return the number of elements in this list.
List subList(int fromIndex, int toIndex)
Return a view of the portion of this list between fromIndex (inclusive) and toIndex (exclusive).
Object[] toArray(Object[] array)
Return an array containing all of the elements in this list in the correct order.
Object[] toArray()
Return an array containing all of the elements in this list in the correct order.
String toString()
Return a String representation of this object.
void trimToSize()
Trim the capacity of this ArrayList instance to be the list's current size.
[Expand]
Inherited Methods
From class java.util.ArrayList
From class java.util.AbstractList
From class java.util.AbstractCollection
From class java.lang.Object
From interface java.lang.Iterable
From interface java.util.Collection
From interface java.util.List

Fields

protected boolean fast

Are we operating in "fast" mode?

protected ArrayList list

The underlying list we are managing.

Public Constructors

public FastArrayList ()

Construct a an empty list.

public FastArrayList (int capacity)

Construct an empty list with the specified capacity.

Parameters
capacity The initial capacity of the empty list

public FastArrayList (Collection collection)

Construct a list containing the elements of the specified collection, in the order they are returned by the collection's iterator.

Parameters
collection The collection whose elements initialize the contents of this list

Public Methods

public boolean add (Object element)

Appends the specified element to the end of this list.

Parameters
element The element to be appended

public void add (int index, Object element)

Insert the specified element at the specified position in this list, and shift all remaining elements up one position.

Parameters
index Index at which to insert this element
element The element to be inserted
Throws
IndexOutOfBoundsException if the index is out of range

public boolean addAll (Collection collection)

Append all of the elements in the specified Collection to the end of this list, in the order that they are returned by the specified Collection's Iterator.

Parameters
collection The collection to be appended

public boolean addAll (int index, Collection collection)

Insert all of the elements in the specified Collection at the specified position in this list, and shift any previous elements upwards as needed.

Parameters
index Index at which insertion takes place
collection The collection to be added
Throws
IndexOutOfBoundsException if the index is out of range

public void clear ()

Remove all of the elements from this list. The list will be empty after this call returns.

Throws
UnsupportedOperationException if clear() is not supported by this list

public Object clone ()

Return a shallow copy of this FastArrayList instance. The elements themselves are not copied.

public boolean contains (Object element)

Return true if this list contains the specified element.

Parameters
element The element to test for

public boolean containsAll (Collection collection)

Return true if this list contains all of the elements in the specified Collection.

Parameters
collection Collection whose elements are to be checked

public void ensureCapacity (int capacity)

Increase the capacity of this ArrayList instance, if necessary, to ensure that it can hold at least the number of elements specified by the minimum capacity argument.

Parameters
capacity The new minimum capacity

public boolean equals (Object o)

Compare the specified object with this list for equality. This implementation uses exactly the code that is used to define the list equals function in the documentation for the List.equals method.

Parameters
o Object to be compared to this list

public Object get (int index)

Return the element at the specified position in the list.

Parameters
index The index of the element to return
Throws
IndexOutOfBoundsException if the index is out of range

public boolean getFast ()

Returns true if this list is operating in fast mode.

Returns
  • true if this list is operating in fast mode

public int hashCode ()

Return the hash code value for this list. This implementation uses exactly the code that is used to define the list hash function in the documentation for the List.hashCode method.

public int indexOf (Object element)

Search for the first occurrence of the given argument, testing for equality using the equals() method, and return the corresponding index, or -1 if the object is not found.

Parameters
element The element to search for

public boolean isEmpty ()

Test if this list has no elements.

public Iterator iterator ()

Return an iterator over the elements in this list in proper sequence.

Thread safety
The iterator returned is thread-safe ONLY in FAST mode. In slow mode there is no way to synchronize, or make the iterator thread-safe.

In fast mode iteration and modification may occur in parallel on different threads, however there is a restriction. Modification must be EITHER via the Iterator interface methods OR the List interface. If a mixture of modification methods is used a ConcurrentModificationException is thrown from the iterator modification method. If the List modification methods are used the changes are NOT visible in the iterator (it shows the list contents at the time the iterator was created).

Returns
  • the iterator

public int lastIndexOf (Object element)

Search for the last occurrence of the given argument, testing for equality using the equals() method, and return the corresponding index, or -1 if the object is not found.

Parameters
element The element to search for

public ListIterator listIterator (int index)

Return an iterator of the elements of this list, in proper sequence, starting at the specified position.

Thread safety
The iterator returned is thread-safe ONLY in FAST mode. In slow mode there is no way to synchronize, or make the iterator thread-safe.

In fast mode iteration and modification may occur in parallel on different threads, however there is a restriction. Modification must be EITHER via the Iterator interface methods OR the List interface. If a mixture of modification methods is used a ConcurrentModificationException is thrown from the iterator modification method. If the List modification methods are used the changes are NOT visible in the iterator (it shows the list contents at the time the iterator was created).

Parameters
index The starting position of the iterator to return
Returns
  • the list iterator
Throws
IndexOutOfBoundsException if the index is out of range

public ListIterator listIterator ()

Return an iterator of the elements of this list, in proper sequence.

Thread safety
The iterator returned is thread-safe ONLY in FAST mode. In slow mode there is no way to synchronize, or make the iterator thread-safe.

In fast mode iteration and modification may occur in parallel on different threads, however there is a restriction. Modification must be EITHER via the Iterator interface methods OR the List interface. If a mixture of modification methods is used a ConcurrentModificationException is thrown from the iterator modification method. If the List modification methods are used the changes are NOT visible in the iterator (it shows the list contents at the time the iterator was created).

Returns
  • the list iterator

public Object remove (int index)

Remove the element at the specified position in the list, and shift any subsequent elements down one position.

Parameters
index Index of the element to be removed
Throws
IndexOutOfBoundsException if the index is out of range

public boolean remove (Object element)

Remove the first occurrence of the specified element from the list, and shift any subsequent elements down one position.

Parameters
element Element to be removed

public boolean removeAll (Collection collection)

Remove from this collection all of its elements that are contained in the specified collection.

Parameters
collection Collection containing elements to be removed
Throws
UnsupportedOperationException if this optional operation is not supported by this list

public boolean retainAll (Collection collection)

Remove from this collection all of its elements except those that are contained in the specified collection.

Parameters
collection Collection containing elements to be retained
Throws
UnsupportedOperationException if this optional operation is not supported by this list

public Object set (int index, Object element)

Replace the element at the specified position in this list with the specified element. Returns the previous object at that position.

IMPLEMENTATION NOTE - This operation is specifically documented to not be a structural change, so it is safe to be performed without cloning.

Parameters
index Index of the element to replace
element The new element to be stored
Throws
IndexOutOfBoundsException if the index is out of range

public void setFast (boolean fast)

Sets whether this list will operate in fast mode.

Parameters
fast true if the list should operate in fast mode

public int size ()

Return the number of elements in this list.

public List subList (int fromIndex, int toIndex)

Return a view of the portion of this list between fromIndex (inclusive) and toIndex (exclusive). The returned list is backed by this list, so non-structural changes in the returned list are reflected in this list. The returned list supports all of the optional list operations supported by this list.

Parameters
fromIndex The starting index of the sublist view
toIndex The index after the end of the sublist view
Throws
IndexOutOfBoundsException if an index is out of range

public Object[] toArray (Object[] array)

Return an array containing all of the elements in this list in the correct order. The runtime type of the returned array is that of the specified array. If the list fits in the specified array, it is returned therein. Otherwise, a new array is allocated with the runtime type of the specified array, and the size of this list.

Parameters
array Array defining the element type of the returned list
Throws
ArrayStoreException if the runtime type of array is not a supertype of the runtime type of every element in this list

public Object[] toArray ()

Return an array containing all of the elements in this list in the correct order.

public String toString ()

Return a String representation of this object.

public void trimToSize ()

Trim the capacity of this ArrayList instance to be the list's current size. An application can use this operation to minimize the storage of an ArrayList instance.