to top
Android APIs
public class

CopyOnWriteArrayList

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

Class Overview

A thread-safe random-access list.

Read operations (including get(int)) do not block and may overlap with update operations. Reads reflect the results of the most recently completed operations. Aggregate operations like addAll(int, Collection) and clear() are atomic; they never expose an intermediate state.

Iterators of this list never throw ConcurrentModificationException. When an iterator is created, it keeps a copy of the list's contents. It is always safe to iterate this list, but iterations may not reflect the latest state of the list.

Iterators returned by this list and its sub lists cannot modify the underlying list. In particular, remove(), add(E) and set(E) all throw UnsupportedOperationException.

This class offers extended API beyond the List interface. It includes additional overloads for indexed search (indexOf(E, int) and lastIndexOf(E, int)) and methods for conditional adds (addIfAbsent(E) and addAllAbsent(Collection)).

Summary

Public Constructors
CopyOnWriteArrayList()
Creates a new empty instance.
CopyOnWriteArrayList(Collection<? extends E> collection)
Creates a new instance containing the elements of collection.
CopyOnWriteArrayList(E[] array)
Creates a new instance containing the elements of array.
Public Methods
synchronized boolean add(E e)
Adds the specified object at the end of this List.
synchronized void add(int index, E e)
Inserts the specified object into this List at the specified location.
synchronized boolean addAll(Collection<? extends E> collection)
Adds the objects in the specified collection to the end of this List.
synchronized boolean addAll(int index, Collection<? extends E> collection)
Inserts the objects in the specified collection at the specified location in this List.
synchronized int addAllAbsent(Collection<? extends E> collection)
Adds the elements of collection that are not already present in this list.
synchronized boolean addIfAbsent(E object)
Adds object to the end of this list if it is not already present.
synchronized 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<?> collection)
Tests whether this List contains all objects contained in the specified collection.
boolean equals(Object other)
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 object)
Searches this List for the specified object and returns the index of the first occurrence.
int indexOf(E object, int from)
Searches this list for object and returns the index of the first occurrence that is at or after from.
boolean isEmpty()
Returns whether this List contains no elements.
Iterator<E> iterator()
Returns an Iterator that iterates over the elements of this list as they were at the time of this method call.
int lastIndexOf(Object object)
Searches this List for the specified object and returns the index of the last occurrence.
int lastIndexOf(E object, int to)
Searches this list for object and returns the index of the last occurrence that is before to.
ListIterator<E> listIterator(int index)
Returns a ListIterator that iterates over the elements of this list as they were at the time of this method call.
ListIterator<E> listIterator()
Equivalent to listIterator(0).
synchronized E remove(int index)
Removes the object at the specified location from this List.
synchronized boolean remove(Object o)
Removes the first occurrence of the specified object from this List.
synchronized boolean removeAll(Collection<?> collection)
Removes all occurrences in this List of each object in the specified collection.
synchronized boolean retainAll(Collection<?> collection)
Removes all objects from this List that are not contained in the specified collection.
synchronized 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 from, int to)
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[] contents)
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.

public CopyOnWriteArrayList (Collection<? extends E> collection)

Since: API Level 1

Creates a new instance containing the elements of collection.

public CopyOnWriteArrayList (E[] array)

Since: API Level 1

Creates a new instance containing the elements of array.

Public Methods

public synchronized 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 synchronized 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 synchronized boolean addAll (Collection<? extends E> collection)

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
collection the collection of objects.
Returns
  • true if this List is modified, false otherwise (i.e. if the passed collection was empty).

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

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.
collection 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 synchronized int addAllAbsent (Collection<? extends E> collection)

Since: API Level 1

Adds the elements of collection that are not already present in this list. If collection includes a repeated value, at most one occurrence of that value will be added to this list. Elements are added at the end of this list.

Callers of this method may prefer CopyOnWriteArraySet, whose API is more appropriate for set operations.

public synchronized boolean addIfAbsent (E object)

Since: API Level 1

Adds object to the end of this list if it is not already present.

Callers of this method may prefer CopyOnWriteArraySet, whose API is more appropriate for set operations.

public synchronized 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<?> collection)

Since: API Level 1

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

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

public boolean equals (Object other)

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
other 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 object)

Since: API Level 1

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

Parameters
object 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 object, int from)

Since: API Level 1

Searches this list for object and returns the index of the first occurrence that is at or after from.

Returns
  • the index or -1 if the object was not found.

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 that iterates over the elements of this list as they were at the time of this method call. Changes to the list made after this method call will not be reflected by the iterator, nor will they trigger a ConcurrentModificationException.

The returned iterator does not support remove().

Returns
  • an iterator on the elements of this List.

public int lastIndexOf (Object object)

Since: API Level 1

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

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

public int lastIndexOf (E object, int to)

Since: API Level 1

Searches this list for object and returns the index of the last occurrence that is before to.

Returns
  • the index or -1 if the object was not found.

public ListIterator<E> listIterator (int index)

Since: API Level 1

Returns a ListIterator that iterates over the elements of this list as they were at the time of this method call. Changes to the list made after this method call will not be reflected by the iterator, nor will they trigger a ConcurrentModificationException.

The returned iterator does not support add(E), set(E) or remove(),

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

Equivalent to listIterator(0).

Returns
  • a List iterator on the elements of this List

public synchronized 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 synchronized 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 synchronized boolean removeAll (Collection<?> collection)

Since: API Level 1

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

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

public synchronized boolean retainAll (Collection<?> collection)

Since: API Level 1

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

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

public synchronized 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 from, int to)

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
from the index at which to start the sublist.
to the index one past the end of the sublist.
Returns
  • a list of a portion of this List.

public T[] toArray (T[] contents)

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
contents 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.