java.lang.Object | ||||
↳ | java.util.AbstractCollection<E> | |||
↳ | java.util.AbstractList<E> | |||
↳ | java.util.ArrayList<E> | |||
↳ | org.apache.commons.collections.FastArrayList |
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:
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.
Fields | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
fast | Are we operating in "fast" mode? | ||||||||||
list | The underlying list we are managing. |
[Expand]
Inherited Fields | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.util.AbstractList
|
Public Constructors | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Construct a an empty list.
| |||||||||||
Construct an empty list with the specified capacity.
| |||||||||||
Construct a list containing the elements of the specified collection,
in the order they are returned by the collection's iterator.
|
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Appends the specified element to the end of this list.
| |||||||||||
Insert the specified element at the specified position in this list,
and shift all remaining elements up one position.
| |||||||||||
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.
| |||||||||||
Insert all of the elements in the specified Collection at the specified
position in this list, and shift any previous elements upwards as
needed.
| |||||||||||
Remove all of the elements from this list.
| |||||||||||
Return a shallow copy of this
FastArrayList instance. | |||||||||||
Return
true if this list contains the specified element. | |||||||||||
Return
true if this list contains all of the elements
in the specified Collection. | |||||||||||
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. | |||||||||||
Compare the specified object with this list for equality.
| |||||||||||
Return the element at the specified position in the list.
| |||||||||||
Returns true if this list is operating in fast mode.
| |||||||||||
Return the hash code value for this list.
| |||||||||||
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. | |||||||||||
Test if this list has no elements.
| |||||||||||
Return an iterator over the elements in this list in proper sequence.
| |||||||||||
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. | |||||||||||
Return an iterator of the elements of this list, in proper sequence,
starting at the specified position.
| |||||||||||
Return an iterator of the elements of this list, in proper sequence.
| |||||||||||
Remove the element at the specified position in the list, and shift
any subsequent elements down one position.
| |||||||||||
Remove the first occurrence of the specified element from the list,
and shift any subsequent elements down one position.
| |||||||||||
Remove from this collection all of its elements that are contained
in the specified collection.
| |||||||||||
Remove from this collection all of its elements except those that are
contained in the specified collection.
| |||||||||||
Replace the element at the specified position in this list with
the specified element.
| |||||||||||
Sets whether this list will operate in fast mode.
| |||||||||||
Return the number of elements in this list.
| |||||||||||
Return a view of the portion of this list between fromIndex
(inclusive) and toIndex (exclusive).
| |||||||||||
Return an array containing all of the elements in this list in the
correct order.
| |||||||||||
Return an array containing all of the elements in this list in the
correct order.
| |||||||||||
Return a String representation of this object.
| |||||||||||
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
|
Are we operating in "fast" mode?
Construct a an empty list.
Construct an empty list with the specified capacity.
capacity | The initial capacity of the empty list |
---|
Construct a list containing the elements of the specified collection, in the order they are returned by the collection's iterator.
collection | The collection whose elements initialize the contents of this list |
---|
Appends the specified element to the end of this list.
element | The element to be appended |
---|
Insert the specified element at the specified position in this list, and shift all remaining elements up one position.
index | Index at which to insert this element |
---|---|
element | The element to be inserted |
IndexOutOfBoundsException | if the index is out of range |
---|
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.
collection | The collection to be appended |
---|
Insert all of the elements in the specified Collection at the specified position in this list, and shift any previous elements upwards as needed.
index | Index at which insertion takes place |
---|---|
collection | The collection to be added |
IndexOutOfBoundsException | if the index is out of range |
---|
Remove all of the elements from this list. The list will be empty after this call returns.
UnsupportedOperationException | if clear()
is not supported by this list
|
---|
Return a shallow copy of this FastArrayList
instance.
The elements themselves are not copied.
Return true
if this list contains the specified element.
element | The element to test for |
---|
Return true
if this list contains all of the elements
in the specified Collection.
collection | Collection whose elements are to be checked |
---|
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.
capacity | The new minimum capacity |
---|
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.
o | Object to be compared to this list |
---|
Return the element at the specified position in the list.
index | The index of the element to return |
---|
IndexOutOfBoundsException | if the index is out of range |
---|
Returns true if this list is operating in fast mode.
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.
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.
element | The element to search for |
---|
Test if this list has no elements.
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).
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.
element | The element to search for |
---|
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).
index | The starting position of the iterator to return |
---|
IndexOutOfBoundsException | if the index is out of range |
---|
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).
Remove the element at the specified position in the list, and shift any subsequent elements down one position.
index | Index of the element to be removed |
---|
IndexOutOfBoundsException | if the index is out of range |
---|
Remove the first occurrence of the specified element from the list, and shift any subsequent elements down one position.
element | Element to be removed |
---|
Remove from this collection all of its elements that are contained in the specified collection.
collection | Collection containing elements to be removed |
---|
UnsupportedOperationException | if this optional operation is not supported by this list |
---|
Remove from this collection all of its elements except those that are contained in the specified collection.
collection | Collection containing elements to be retained |
---|
UnsupportedOperationException | if this optional operation is not supported by this list |
---|
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.
index | Index of the element to replace |
---|---|
element | The new element to be stored |
IndexOutOfBoundsException | if the index is out of range |
---|
Sets whether this list will operate in fast mode.
fast | true if the list should operate in fast mode |
---|
Return the number of elements in this list.
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.
fromIndex | The starting index of the sublist view |
---|---|
toIndex | The index after the end of the sublist view |
IndexOutOfBoundsException | if an index is out of range |
---|
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.
array | Array defining the element type of the returned list |
---|
ArrayStoreException | if the runtime type of array
is not a supertype of the runtime type of every element in this list
|
---|
Return an array containing all of the elements in this list in the correct order.
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.