| java.util.ArrayList
 org.apache.commons.collections.FastArrayList
| FastArrayList | | public class FastArrayList extends ArrayList (Code) | | 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.
since:
Commons Collections 1.0
version:
$Revision: 178303 $ $Date: 2005-05-24 23:39:51 +0100 (Tue, 24 May 2005) $
author:
Craig R. McClanahan
author:
Stephen Colebourne |
| Field Summary | |
| protected boolean | fast
| | protected ArrayList | list
The underlying list we are managing. |
| Constructor Summary | |
| public | FastArrayList()
Construct a an empty list. | | public | FastArrayList(int capacity)
Construct an empty list with the specified capacity. | | 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. |
| Method Summary | |
| public boolean | add(Object element)
Appends the specified element to the end of this list. | | 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. | | 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. | | 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. | | public void | clear()
Remove all of the elements from this list. | | public Object | clone()
Return a shallow copy of this FastArrayList instance. | | public boolean | contains(Object element)
Return true if this list contains the specified element. | | public boolean | containsAll(Collection collection)
Return true if this list contains all of the elements
in the specified Collection. | | 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. | | public boolean | equals(Object o)
Compare the specified object with this list for equality. | | public Object | get(int index)
Return the element at the specified position in the list. | | public boolean | getFast()
Returns true if this list is operating in fast mode. | | public int | hashCode()
Return the hash code value for this list. | | 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. | | 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. | | 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. | | 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. | | 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. | | public Object | remove(int index)
Remove the element at the specified position in the list, and shift
any subsequent elements down one position. | | public boolean | remove(Object element)
Remove the first occurrence of the specified element from the list,
and shift any subsequent elements down one position. | | public boolean | removeAll(Collection collection)
Remove from this collection all of its elements that are contained
in the specified collection. | | public boolean | retainAll(Collection collection)
Remove from this collection all of its elements except those that are
contained in the specified collection. | | public Object | set(int index, Object element)
Replace the element at the specified position in this list with
the specified element. | | public void | setFast(boolean fast)
Sets whether this list will 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). | | public Object[] | toArray()
Return an array containing all of the elements in this list in the
correct order. | | public Object[] | toArray(Object array)
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. |
| fast | | protected boolean fast(Code) | | Are we operating in "fast" mode?
|
| FastArrayList | | public FastArrayList()(Code) | | Construct a an empty list.
|
| FastArrayList | | public FastArrayList(int capacity)(Code) | | Construct an empty list with the specified capacity.
Parameters:
capacity - The initial capacity of the empty list |
| FastArrayList | | public FastArrayList(Collection collection)(Code) | | 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 contentsof this list |
| add | | public boolean add(Object element)(Code) | | Appends the specified element to the end of this list.
Parameters:
element - The element to be appended |
| add | | public void add(int index, Object element)(Code) | | 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
Parameters:
element - The element to be inserted
exception:
IndexOutOfBoundsException - if the index is out of range |
| addAll | | public boolean addAll(Collection collection)(Code) | | 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 |
| addAll | | public boolean addAll(int index, Collection collection)(Code) | | 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
Parameters:
collection - The collection to be added
exception:
IndexOutOfBoundsException - if the index is out of range |
| clear | | public void clear()(Code) | | Remove all of the elements from this list. The list will be empty
after this call returns.
exception:
UnsupportedOperationException - if clear()is not supported by this list |
| clone | | public Object clone()(Code) | | Return a shallow copy of this FastArrayList instance.
The elements themselves are not copied.
|
| contains | | public boolean contains(Object element)(Code) | | Return true if this list contains the specified element.
Parameters:
element - The element to test for |
| containsAll | | public boolean containsAll(Collection collection)(Code) | | Return true if this list contains all of the elements
in the specified Collection.
Parameters:
collection - Collection whose elements are to be checked |
| ensureCapacity | | public void ensureCapacity(int capacity)(Code) | | 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 |
| equals | | public boolean equals(Object o)(Code) | | 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 |
| get | | public Object get(int index)(Code) | | Return the element at the specified position in the list.
Parameters:
index - The index of the element to return
exception:
IndexOutOfBoundsException - if the index is out of range |
| getFast | | public boolean getFast()(Code) | | Returns true if this list is operating in fast mode.
true if this list is operating in fast mode |
| hashCode | | public int hashCode()(Code) | | 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.
|
| indexOf | | public int indexOf(Object element)(Code) | | 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 |
| isEmpty | | public boolean isEmpty()(Code) | | Test if this list has no elements.
|
| iterator | | public Iterator iterator()(Code) | | 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).
the iterator |
| lastIndexOf | | public int lastIndexOf(Object element)(Code) | | 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 |
| listIterator | | public ListIterator listIterator()(Code) | | 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).
the list iterator |
| listIterator | | public ListIterator listIterator(int index)(Code) | | 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 the list iterator
exception:
IndexOutOfBoundsException - if the index is out of range |
| remove | | public Object remove(int index)(Code) | | 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
exception:
IndexOutOfBoundsException - if the index is out of range |
| remove | | public boolean remove(Object element)(Code) | | 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 |
| removeAll | | public boolean removeAll(Collection collection)(Code) | | Remove from this collection all of its elements that are contained
in the specified collection.
Parameters:
collection - Collection containing elements to be removed
exception:
UnsupportedOperationException - if this optional operationis not supported by this list |
| retainAll | | public boolean retainAll(Collection collection)(Code) | | 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
exception:
UnsupportedOperationException - if this optional operationis not supported by this list |
| set | | public Object set(int index, Object element)(Code) | | 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
Parameters:
element - The new element to be stored
exception:
IndexOutOfBoundsException - if the index is out of range |
| setFast | | public void setFast(boolean fast)(Code) | | Sets whether this list will operate in fast mode.
Parameters:
fast - true if the list should operate in fast mode |
| size | | public int size()(Code) | | Return the number of elements in this list.
|
| subList | | public List subList(int fromIndex, int toIndex)(Code) | | 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
Parameters:
toIndex - The index after the end of the sublist view
exception:
IndexOutOfBoundsException - if an index is out of range |
| toArray | | public Object[] toArray()(Code) | | Return an array containing all of the elements in this list in the
correct order.
|
| toArray | | public Object[] toArray(Object array)(Code) | | 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
exception:
ArrayStoreException - if the runtime type of arrayis not a supertype of the runtime type of every element in this list |
| toString | | public String toString()(Code) | | Return a String representation of this object.
|
| trimToSize | | public void trimToSize()(Code) | | 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.
|
|
|