public class

CopyOnWriteArrayList

extends Object
implements Serializable Cloneable List<E> RandomAccess
java.lang.Object
   ↳ java.util.concurrent.CopyOnWriteArrayList<E>

Class Overview

Implements a ArrayList variant that is thread-safe. All write operation result in a new copy of the underlying data being created. Iterators reflect the state of the CopyOnWriteArrayList at the time they were created. They are not updated to reflect subsequent changes to the list. In addition, these iterators cannot be used for modifying the underlying CopyOnWriteArrayList.

Summary

Public Constructors
CopyOnWriteArrayList()
Creates a new, empty instance of CopyOnWriteArrayList.
CopyOnWriteArrayList(Collection<? extends E> c)
Creates a new instance of CopyOnWriteArrayList and fills it with the contents of a given Collection.
CopyOnWriteArrayList(E[] array)
Creates a new instance of CopyOnWriteArrayList and fills it with the contents of a given array.
Public Methods
boolean add(E e)
Adds the specified object at the end of this List.
void add(int index, E e)
Inserts the specified object into this List at the specified location.
boolean addAll(Collection<? extends E> c)
Adds the objects in the specified collection to the end of this List.
boolean addAll(int index, Collection<? extends E> c)
Inserts the objects in the specified collection at the specified location in this List.
int addAllAbsent(Collection<? extends E> c)
Adds to this CopyOnWriteArrayList all those elements from a given collection that are not yet part of the list.
boolean addIfAbsent(E e)
Adds to this CopyOnWriteArrayList another element, given that this element is not yet part of the list.
void clear()
Removes all elements from this List, leaving it empty.
Object clone()
Creates and returns a copy of this Object.
boolean contains(Object o)
Tests whether this List contains the specified object.
boolean containsAll(Collection<?> c)
Tests whether this List contains all objects contained in the specified collection.
boolean equals(Object o)
Compares this instance with the specified object and indicates if they are equal.
E get(int index)
Returns the element at the specified location in this List.
int hashCode()
Returns an integer hash code for this object.
int indexOf(Object o)
Searches this List for the specified object and returns the index of the first occurrence.
int indexOf(E e, int index)
Returns the index of a given element, starting the search from a given position in the list.
boolean isEmpty()
Returns whether this List contains no elements.
Iterator<E> iterator()
Returns an iterator on the elements of this List.
int lastIndexOf(E e, int index)
Returns the last index of a given element, starting the search from a given position in the list and going backwards.
int lastIndexOf(Object o)
Searches this List for the specified object and returns the index of the last occurrence.
ListIterator<E> listIterator(int index)
Returns a list iterator on the elements of this List.
ListIterator<E> listIterator()
Returns a List iterator on the elements of this List.
E remove(int index)
Removes the object at the specified location from this List.
boolean remove(Object o)
Removes the first occurrence of the specified object from this List.
boolean removeAll(Collection<?> c)
Removes all occurrences in this List of each object in the specified collection.
boolean retainAll(Collection<?> c)
Removes all objects from this List that are not contained in the specified collection.
E set(int index, E e)
Replaces the element at the specified location in this List with the specified object.
int size()
Returns the number of elements in this List.
List<E> subList(int fromIndex, int toIndex)
Returns a List of the specified portion of this List from the given start index to the end index minus one.
<T> T[] toArray(T[] a)
Returns an array containing all elements contained in this List.
Object[] toArray()
Returns an array containing all elements contained in this List.
String toString()
Returns a string containing a concise, human-readable description of this object.
[Expand]
Inherited Methods
From class java.lang.Object
From interface java.lang.Iterable
From interface java.util.Collection
From interface java.util.List

Public Constructors

public CopyOnWriteArrayList ()

Since: API Level 1

Creates a new, empty instance of CopyOnWriteArrayList.

public CopyOnWriteArrayList (Collection<? extends E> c)

Since: API Level 1

Creates a new instance of CopyOnWriteArrayList and fills it with the contents of a given Collection.

Parameters
c the collection the elements of which are to be copied into the new instance.

public CopyOnWriteArrayList (E[] array)

Since: API Level 1

Creates a new instance of CopyOnWriteArrayList and fills it with the contents of a given array.

Parameters
array the array the elements of which are to be copied into the new instance.

Public Methods

public boolean add (E e)

Since: API Level 1

Adds the specified object at the end of this List.

Parameters
e the object to add.
Returns
  • always true.

public void add (int index, E e)

Since: API Level 1

Inserts the specified object into this List at the specified location. The object is inserted before the current element at the specified location. If the location is equal to the size of this List, the object is added at the end. If the location is smaller than the size of this List, then all elements beyond the specified location are moved by one position towards the end of the List.

Parameters
index the index at which to insert.
e the object to add.

public boolean addAll (Collection<? extends E> c)

Since: API Level 1

Adds the objects in the specified collection to the end of this List. The objects are added in the order in which they are returned from the collection's iterator.

Parameters
c the collection of objects.
Returns
  • true if this List is modified, false otherwise (i.e. if the passed collection was empty).

public boolean addAll (int index, Collection<? extends E> c)

Since: API Level 1

Inserts the objects in the specified collection at the specified location in this List. The objects are added in the order they are returned from the collection's iterator.

Parameters
index the index at which to insert.
c the collection of objects to be inserted.
Returns
  • true if this List has been modified through the insertion, false otherwise (i.e. if the passed collection was empty).

public int addAllAbsent (Collection<? extends E> c)

Since: API Level 1

Adds to this CopyOnWriteArrayList all those elements from a given collection that are not yet part of the list.

Parameters
c the collection from which the potential new elements are taken.
Returns
  • the number of elements actually added to this list.

public boolean addIfAbsent (E e)

Since: API Level 1

Adds to this CopyOnWriteArrayList another element, given that this element is not yet part of the list.

Parameters
e the potential new element.
Returns
  • true if the element was added, or false otherwise.

public void clear ()

Since: API Level 1

Removes all elements from this List, leaving it empty.

public Object clone ()

Since: API Level 1

Creates and returns a copy of this Object. The default implementation returns a so-called "shallow" copy: It creates a new instance of the same class and then copies the field values (including object references) from this instance to the new instance. A "deep" copy, in contrast, would also recursively clone nested objects. A subclass that needs to implement this kind of cloning should call super.clone() to create the new instance and then create deep copies of the nested, mutable objects.

Returns
  • a copy of this object.

public boolean contains (Object o)

Since: API Level 1

Tests whether this List contains the specified object.

Parameters
o the object to search for.
Returns
  • true if object is an element of this List, false otherwise

public boolean containsAll (Collection<?> c)

Since: API Level 1

Tests whether this List contains all objects contained in the specified collection.

Parameters
c the collection of objects
Returns
  • true if all objects in the specified collection are elements of this List, false otherwise.

public boolean equals (Object o)

Since: API Level 1

Compares this instance with the specified object and indicates if they are equal. In order to be equal, o must represent the same object as this instance using a class-specific comparison. The general contract is that this comparison should be reflexive, symmetric, and transitive. Also, no object reference other than null is equal to null.

The default implementation returns true only if this == o. See Writing a correct equals method if you intend implementing your own equals method.

The general contract for the equals and hashCode() methods is that if equals returns true for any two objects, then hashCode() must return the same value for these objects. This means that subclasses of Object usually override either both methods or neither of them.

Parameters
o the object to compare this instance with.
Returns
  • true if the specified object is equal to this Object; false otherwise.

public E get (int index)

Since: API Level 1

Returns the element at the specified location in this List.

Parameters
index the index of the element to return.
Returns
  • the element at the specified location.

public int hashCode ()

Since: API Level 1

Returns an integer hash code for this object. By contract, any two objects for which equals(Object) returns true must return the same hash code value. This means that subclasses of Object usually override both methods or neither method.

Note that hash values must not change over time unless information used in equals comparisons also changes.

See Writing a correct hashCode method if you intend implementing your own hashCode method.

Returns
  • this object's hash code.

public int indexOf (Object o)

Since: API Level 1

Searches this List for the specified object and returns the index of the first occurrence.

Parameters
o the object to search for.
Returns
  • the index of the first occurrence of the object or -1 if the object was not found.

public int indexOf (E e, int index)

Since: API Level 1

Returns the index of a given element, starting the search from a given position in the list.

Parameters
e the element to search.
index the index at which to start the search.
Returns
  • the index of the element or null, if the element has not been found at or beyond the given start index.

public boolean isEmpty ()

Since: API Level 1

Returns whether this List contains no elements.

Returns
  • true if this List has no elements, false otherwise.

public Iterator<E> iterator ()

Since: API Level 1

Returns an iterator on the elements of this List. The elements are iterated in the same order as they occur in the List.

Returns
  • an iterator on the elements of this List.

public int lastIndexOf (E e, int index)

Since: API Level 1

Returns the last index of a given element, starting the search from a given position in the list and going backwards.

Parameters
e the element to search.
index the index at which to start the search.
Returns
  • the index of the element or null, if the element has not been found at or before the given start index.

public int lastIndexOf (Object o)

Since: API Level 1

Searches this List for the specified object and returns the index of the last occurrence.

Parameters
o the object to search for.
Returns
  • the index of the last occurrence of the object, or -1 if the object was not found.

public ListIterator<E> listIterator (int index)

Since: API Level 1

Returns a list iterator on the elements of this List. The elements are iterated in the same order as they occur in the List. The iteration starts at the specified location.

Parameters
index the index at which to start the iteration.
Returns
  • a list iterator on the elements of this List.

public ListIterator<E> listIterator ()

Since: API Level 1

Returns a List iterator on the elements of this List. The elements are iterated in the same order that they occur in the List.

Returns
  • a List iterator on the elements of this List

public E remove (int index)

Since: API Level 1

Removes the object at the specified location from this List.

Parameters
index the index of the object to remove.
Returns
  • the removed object.

public boolean remove (Object o)

Since: API Level 1

Removes the first occurrence of the specified object from this List.

Parameters
o the object to remove.
Returns
  • true if this List was modified by this operation, false otherwise.

public boolean removeAll (Collection<?> c)

Since: API Level 1

Removes all occurrences in this List of each object in the specified collection.

Parameters
c the collection of objects to remove.
Returns
  • true if this List is modified, false otherwise.

public boolean retainAll (Collection<?> c)

Since: API Level 1

Removes all objects from this List that are not contained in the specified collection.

Parameters
c the collection of objects to retain.
Returns
  • true if this List is modified, false otherwise.

public E set (int index, E e)

Since: API Level 1

Replaces the element at the specified location in this List with the specified object. This operation does not change the size of the List.

Parameters
index the index at which to put the specified object.
e the object to insert.
Returns
  • the previous element at the index.

public int size ()

Since: API Level 1

Returns the number of elements in this List.

Returns
  • the number of elements in this List.

public List<E> subList (int fromIndex, int toIndex)

Since: API Level 1

Returns a List of the specified portion of this List from the given start index to the end index minus one. The returned List is backed by this List so changes to it are reflected by the other.

Parameters
fromIndex the index at which to start the sublist.
toIndex the index one past the end of the sublist.
Returns
  • a list of a portion of this List.

public T[] toArray (T[] a)

Since: API Level 1

Returns an array containing all elements contained in this List. If the specified array is large enough to hold the elements, the specified array is used, otherwise an array of the same type is created. If the specified array is used and is larger than this List, the array element following the collection elements is set to null.

Parameters
a the array.
Returns
  • an array of the elements from this List.

public Object[] toArray ()

Since: API Level 1

Returns an array containing all elements contained in this List.

Returns
  • an array of the elements from this List.

public String toString ()

Since: API Level 1

Returns a string containing a concise, human-readable description of this object. Subclasses are encouraged to override this method and provide an implementation that takes into account the object's type and data. The default implementation is equivalent to the following expression: 

   getClass().getName() + '@' + Integer.toHexString(hashCode())

See Writing a useful toString method if you intend implementing your own toString method.

Returns
  • a printable representation of this object.