java.util.concurrent

Class CopyOnWriteArrayList<E>

java.lang.Object
- java.util.AbstractCollection<E>
- - java.util.AbstractList<E>
  - - java.util.concurrent.CopyOnWriteArrayList<E>

Implemented Interfaces:: Cloneable, Collection<E>, Iterable<E>, List<E>, RandomAccess, Serializable

public class CopyOnWriteArrayList<E>

extends AbstractList<E>

implements List<E>, RandomAccess, Cloneable, Serializable

A thread-safe implementation of an ArrayList. A CopyOnWriteArrayList is as special ArrayList which performs copies of the underlying storage each time a write (remove, add etc..) operation is performed.

The update operation in this class run usually in O(n) or worse, but traversal operations are fast and efficient, especially when running in a multi-thread environment without the need to design complex synchronize mechanisms.

Iterators in this class work on a snapshot of the backing store at the moment the iterator itself was created, hence the iterator will not reflect changes in the underlying storage. Thus, update operation on the Iterators are not supported, but as interferences from other threads are impossible, no ConcurrentModificationException will be ever thrown from within the Iterator.

This class is especially useful when used with event handling, like the following code demonstrates:

 
 CopyOnWriteArrayList listeners =
   new CopyOnWriteArrayList();
 
 [...]
 
 for (final EventListener listener : listeners)
   {
     Runnable dispatcher = new Runnable() {
       public void run()
       {
         listener.preferenceChange(event);
       }
     };
         
     Executor executor = Executors.newSingleThreadExecutor();
     executor.execute(dispatcher);
   }

Since:: 1.5

See Also:: Serialized Form

Fields inherited from class java.util.AbstractList<E>
`modCount`

Constructor Summary
`CopyOnWriteArrayList()` Construct a new ArrayList with the default capacity (16).
`CopyOnWriteArrayList(E> c)` Construct a new ArrayList, and initialize it with the elements in the supplied Collection.
`CopyOnWriteArrayList(E[] array)` Construct a new ArrayList, and initialize it with the elements in the supplied array.

Method Summary
	`T[] toArray(T[] a)` Returns an Array whose component type is the runtime component type of the passed-in Array.
`boolean`	`add(E e)` Appends the supplied element to the end of this list.
`void`	`add(int index, E e)` Adds the supplied element at the specified index, shifting all elements currently at that index or higher one to the right.
`boolean`	`addAll(E> c)` Add each element in the supplied Collection to this List.
`boolean`	`addAll(int index, E> c)` Add all elements in the supplied collection, inserting them beginning at the specified index. c can contain objects of any type, as well as null values.
`int`	`addAllAbsent(E> c)` Adds all the element from the given collection that are not already in this list.
`boolean`	`addIfAbsent(E val)` Adds an element if the list does not contains it already.
`void`	`clear()` Removes all elements from this List
`Object`	`clone()` Creates a shallow copy of this ArrayList (elements are not cloned).
`boolean`	`contains(Object e)` Returns true if element is in this ArrayList.
`E`	`get(int index)` Retrieves the element at the user-supplied index.
`int`	`indexOf(E e, int index)` Return the lowest index greater equal `index` at which `e` appears in this List, or -1 if it does not appear.
`int`	`indexOf(Object e)` Returns the lowest index at which element appears in this List, or -1 if it does not appear.
`boolean`	`isEmpty()` Checks if the list is empty.
`Iterator`	`iterator()` Return an Iterator containing the elements of this list.
`int`	`lastIndexOf(E e, int index)` Returns the highest index lesser equal `index` at which `e` appears in this List, or -1 if it does not appear.
`int`	`lastIndexOf(Object e)` Returns the highest index at which element appears in this List, or -1 if it does not appear.
`ListIterator`	`listIterator(int index)` Return a ListIterator containing the elements of this list.
`E`	`remove(int index)` Removes the element at the user-supplied index.
`boolean`	`remove(Object element)` Remove the first occurrence, if any, of the given object from this list, returning `true` if the object was removed, `false` otherwise.
`boolean`	`removeAll(Collection c)` Removes all the elements contained in the given collection.
`boolean`	`retainAll(Collection c)` Removes all the elements that are not in the passed collection.
`E`	`set(int index, E e)` Sets the element at the specified index.
`int`	`size()` Returns the number of elements in this list.
`Object[]`	`toArray()` Returns an Object array containing all of the elements in this ArrayList.

Methods inherited from class java.util.AbstractList<E>
`add`, `add`, `addAll`, `clear`, `equals`, `get`, `hashCode`, `indexOf`, `iterator`, `lastIndexOf`, `listIterator`, `listIterator`, `remove`, `removeRange`, `set`, `subList`

Methods inherited from class java.util.AbstractCollection<E>
`T[] toArray`, `add`, `addAll`, `clear`, `contains`, `containsAll`, `isEmpty`, `iterator`, `remove`, `removeAll`, `retainAll`, `size`, `toArray`, `toString`

Methods inherited from class java.lang.Object
`clone`, `equals`, `extends Object> getClass`, `finalize`, `hashCode`, `notify`, `notifyAll`, `toString`, `wait`, `wait`, `wait`

CopyOnWriteArrayList

public CopyOnWriteArrayList()

Construct a new ArrayList with the default capacity (16).

CopyOnWriteArrayList

public CopyOnWriteArrayList(E> c)

Construct a new ArrayList, and initialize it with the elements in the supplied Collection. The initial capacity is 110% of the Collection's size.
Parameters:
c - the collection whose elements will initialize this list
Throws:
NullPointerException - if c is null

CopyOnWriteArrayList

public CopyOnWriteArrayList(E[] array)

Construct a new ArrayList, and initialize it with the elements in the supplied array.
Parameters:
array - the array used to initialize this list
Throws:
NullPointerException - if array is null

T[] toArray

public  T[] toArray(T[] a)

Returns an Array whose component type is the runtime component type of the passed-in Array. The returned Array is populated with all of the elements in this ArrayList. If the passed-in Array is not large enough to store all of the elements in this List, a new Array will be created and returned; if the passed-in Array is larger than the size of this List, then size() index will be set to null.
Specified by:
T[] toArray in interface List<E>
T[] toArray in interface Collection<E>
Overrides:
T[] toArray in interface AbstractCollection<E>
Parameters:
a - the passed-in Array
Returns:
an array representation of this list
Throws:
ArrayStoreException - if the runtime type of a does not allow an element in this list
NullPointerException - if a is null

add

public boolean add(E e)

Appends the supplied element to the end of this list. The element, e, can be an object of any type or null.
Specified by:
add in interface List<E>
add in interface Collection<E>
Overrides:
add in interface AbstractList<E>
Parameters:
e - the element to be appended to this list
Returns:
true, the add will always succeed

add

public void add(int index,
                E e)

Adds the supplied element at the specified index, shifting all elements currently at that index or higher one to the right. The element, e, can be an object of any type or null.
Specified by:
add in interface List<E>
Overrides:
add in interface AbstractList<E>
Parameters:
index - the index at which the element is being added
e - the item being added
Throws:
IndexOutOfBoundsException - if index < 0 || index > size()

addAll

public boolean addAll(E> c)

Add each element in the supplied Collection to this List. It is undefined what happens if you modify the list while this is taking place; for example, if the collection contains this list. c can contain objects of any type, as well as null values.
Specified by:
addAll in interface List<E>
addAll in interface Collection<E>
Overrides:
addAll in interface AbstractCollection<E>
Parameters:
c - a Collection containing elements to be added to this List
Returns:
true if the list was modified, in other words c is not empty
Throws:
NullPointerException - if c is null

addAll

public boolean addAll(int index,
                      E> c)

Add all elements in the supplied collection, inserting them beginning at the specified index. c can contain objects of any type, as well as null values.
Specified by:
addAll in interface List<E>
Overrides:
addAll in interface AbstractList<E>
Parameters:
index - the index at which the elements will be inserted
c - the Collection containing the elements to be inserted
Throws:
IndexOutOfBoundsException - if index < 0 || index > 0
NullPointerException - if c is null

addAllAbsent

public int addAllAbsent(E> c)

Adds all the element from the given collection that are not already in this list.
Parameters:
c - the Collection containing the elements to be inserted
Returns:
true the list internal storage changed as a result of this operation, false otherwise.

addIfAbsent

public boolean addIfAbsent(E val)

Adds an element if the list does not contains it already.
Parameters:
val - the element to add to the list.
Returns:
true if the element was added, false otherwise.

clear

public void clear()

Removes all elements from this List
Specified by:
clear in interface List<E>
clear in interface Collection<E>
Overrides:
clear in interface AbstractList<E>

clone

public Object clone()

Creates a shallow copy of this ArrayList (elements are not cloned).
Overrides:
clone in interface Object
Returns:
the cloned object

contains

public boolean contains(Object e)

Returns true if element is in this ArrayList.
Specified by:
contains in interface List<E>
contains in interface Collection<E>
Overrides:
contains in interface AbstractCollection<E>
Parameters:
e - the element whose inclusion in the List is being tested
Returns:
true if the list contains e

get

public E get(int index)

Retrieves the element at the user-supplied index.
Specified by:
get in interface List<E>
Overrides:
get in interface AbstractList<E>
Parameters:
index - the index of the element we are fetching
Throws:
IndexOutOfBoundsException - if index < 0 || index >= size()

indexOf

public int indexOf(E e,
                   int index)

Return the lowest index greater equal index at which e appears in this List, or -1 if it does not appear.
Parameters:
e - the element whose inclusion in the list is being tested
index - the index at which the search begins
Returns:
the index where e was found

indexOf

public int indexOf(Object e)

Returns the lowest index at which element appears in this List, or -1 if it does not appear.
Specified by:
indexOf in interface List<E>
Overrides:
indexOf in interface AbstractList<E>
Parameters:
e - the element whose inclusion in the List is being tested
Returns:
the index where e was found

isEmpty

public boolean isEmpty()

Checks if the list is empty.
Specified by:
isEmpty in interface List<E>
isEmpty in interface Collection<E>
Overrides:
isEmpty in interface AbstractCollection<E>
Returns:
true if there are no elements

iterator

public Iterator iterator()

Return an Iterator containing the elements of this list. The Iterator uses a snapshot of the state of the internal storage at the moment this method is called and does not support update operations, so no synchronization is needed to traverse the iterator.
Specified by:
iterator in interface List<E>
iterator in interface Collection<E>
iterator in interface Iterable<E>
Overrides:
iterator in interface AbstractList<E>
Returns:
an Iterator containing the elements of this list in sequence.

lastIndexOf

public int lastIndexOf(E e,
                       int index)

Returns the highest index lesser equal index at which e appears in this List, or -1 if it does not appear.
Parameters:
e - the element whose inclusion in the list is being tested
index - the index at which the search begins
Returns:
the index where e was found

lastIndexOf

public int lastIndexOf(Object e)

Returns the highest index at which element appears in this List, or -1 if it does not appear.
Specified by:
lastIndexOf in interface List<E>
Overrides:
lastIndexOf in interface AbstractList<E>
Parameters:
e - the element whose inclusion in the List is being tested
Returns:
the index where e was found

listIterator

public ListIterator listIterator(int index)

Return a ListIterator containing the elements of this list. The Iterator uses a snapshot of the state of the internal storage at the moment this method is called and does not support update operations, so no synchronization is needed to traverse the iterator.
Specified by:
listIterator in interface List<E>
Overrides:
listIterator in interface AbstractList<E>
Returns:
a ListIterator containing the elements of this list in sequence.

remove

public E remove(int index)

Removes the element at the user-supplied index.
Specified by:
remove in interface List<E>
Overrides:
remove in interface AbstractList<E>
Parameters:
index - the index of the element to be removed
Returns:
the removed Object
Throws:
IndexOutOfBoundsException - if index < 0 || index >= size()

remove

public boolean remove(Object element)

Remove the first occurrence, if any, of the given object from this list, returning true if the object was removed, false otherwise.
Specified by:
remove in interface List<E>
remove in interface Collection<E>
Overrides:
remove in interface AbstractCollection<E>
Parameters:
element - the object to be removed.
Returns:
true if element was removed, false otherwise. false means also that the underlying storage was unchanged after this operation concluded.

removeAll

public boolean removeAll(Collection c)

Removes all the elements contained in the given collection. This method removes the elements that are contained in both this list and in the given collection.
Specified by:
removeAll in interface List<E>
removeAll in interface Collection<E>
Overrides:
removeAll in interface AbstractCollection<E>
Parameters:
c - the collection containing the elements to be removed from this list.
Returns:
true if at least one element was removed, indicating that the list internal storage changed as a result, false otherwise.

retainAll

public boolean retainAll(Collection c)

Removes all the elements that are not in the passed collection. If the collection is void, this method has the same effect of clear(). Please, note that this method is extremely slow (unless the argument has size == 0) and has bad performance is both space and time usage.
Specified by:
retainAll in interface List<E>
retainAll in interface Collection<E>
Overrides:
retainAll in interface AbstractCollection<E>
Parameters:
c - the collection containing the elements to be retained by this list.
Returns:
true the list internal storage changed as a result of this operation, false otherwise.

set

public E set(int index,
             E e)

Sets the element at the specified index. The new element, e, can be an object of any type or null.
Specified by:
set in interface List<E>
Overrides:
set in interface AbstractList<E>
Parameters:
index - the index at which the element is being set
e - the element to be set
Returns:
the element previously at the specified index
Throws:
IndexOutOfBoundsException - if index < 0 || index >= 0

size

public int size()

Returns the number of elements in this list.
Specified by:
size in interface List<E>
size in interface Collection<E>
Overrides:
size in interface AbstractCollection<E>
Returns:
the list size

toArray

public Object[] toArray()

Returns an Object array containing all of the elements in this ArrayList. The array is independent of this list.
Specified by:
toArray in interface List<E>
toArray in interface Collection<E>
Overrides:
toArray in interface AbstractCollection<E>
Returns:
an array representation of this list

CopyOnWriteArrayList.java Copyright (C) 2006 Free Software Foundation This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.

Overview Package Class Use Source Tree Index Deprecated About	GNU Classpath (0.97.1)
Prev Class \| Next Class	GNU Classpath (0.97.1)	Frames \| No Frames
Summary: Nested \| Field \| Method \| Constr	Detail: Nested \| Field \| Method \| Constr

java.util.concurrent

Class CopyOnWriteArrayList<E>

Field Summary

Fields inherited from class java.util.AbstractList<E>

Constructor Summary

Method Summary

Methods inherited from class java.util.AbstractList<E>

Methods inherited from class java.util.AbstractCollection<E>

Methods inherited from class java.lang.Object

Constructor Details

CopyOnWriteArrayList

CopyOnWriteArrayList

CopyOnWriteArrayList

Method Details

T[] toArray

add

add

addAll

addAll

addAllAbsent

addIfAbsent

clear

clone

contains

get

indexOf

indexOf

isEmpty

iterator

lastIndexOf

lastIndexOf

listIterator

remove

remove

removeAll

retainAll

set

size

toArray