Skip to content

Most visited

Recently visited

navigation
Added in API level 1

CopyOnWriteArrayList

public class CopyOnWriteArrayList
extends Object implements List<E>, RandomAccess, Cloneable, Serializable

java.lang.Object
   ↳ java.util.concurrent.CopyOnWriteArrayList<E>


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

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> collection)

Adds the objects in the specified collection to the end of this List.

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

Inserts the objects in the specified collection at the specified location in this List.

int addAllAbsent(Collection<? extends E> collection)

Adds the elements of collection that are not already present in this list.

boolean addIfAbsent(E object)

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

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

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

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

boolean retainAll(Collection<?> collection)

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

Inherited methods

From class java.lang.Object
From interface java.util.List
From interface java.util.Collection
From interface java.lang.Iterable

Public constructors

CopyOnWriteArrayList

Added in API level 1
CopyOnWriteArrayList ()

Creates a new empty instance.

CopyOnWriteArrayList

Added in API level 1
CopyOnWriteArrayList (Collection<? extends E> collection)

Creates a new instance containing the elements of collection.

Parameters
collection Collection

CopyOnWriteArrayList

Added in API level 1
CopyOnWriteArrayList (E[] array)

Creates a new instance containing the elements of array.

Parameters
array E

Public methods

add

Added in API level 1
boolean add (E e)

Adds the specified object at the end of this List.

Parameters
e E: the object to add.
Returns
boolean always true.

add

Added in API level 1
void add (int index, 
                E e)

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 int: the index at which to insert.
e E: the object to add.

addAll

Added in API level 1
boolean addAll (Collection<? extends E> collection)

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

addAll

Added in API level 1
boolean addAll (int index, 
                Collection<? extends E> collection)

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 int: the index at which to insert.
collection Collection: the collection of objects to be inserted.
Returns
boolean true if this List has been modified through the insertion, false otherwise (i.e. if the passed collection was empty).

addAllAbsent

Added in API level 1
int addAllAbsent (Collection<? extends E> collection)

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.

Parameters
collection Collection
Returns
int

addIfAbsent

Added in API level 1
boolean addIfAbsent (E object)

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.

Parameters
object E
Returns
boolean

clear

Added in API level 1
void clear ()

Removes all elements from this List, leaving it empty.

clone

Added in API level 1
Object clone ()

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
Object a copy of this object.

contains

Added in API level 1
boolean contains (Object o)

Tests whether this List contains the specified object.

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

containsAll

Added in API level 1
boolean containsAll (Collection<?> collection)

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

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

equals

Added in API level 1
boolean equals (Object other)

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 Object: the object to compare this instance with.
Returns
boolean true if the specified object is equal to this Object; false otherwise.

get

Added in API level 1
E get (int index)

Returns the element at the specified location in this List.

Parameters
index int: the index of the element to return.
Returns
E the element at the specified location.

hashCode

Added in API level 1
int hashCode ()

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
int this object's hash code.

indexOf

Added in API level 1
int indexOf (Object object)

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

Parameters
object Object: the object to search for.
Returns
int the index of the first occurrence of the object or -1 if the object was not found.

indexOf

Added in API level 1
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.

Parameters
object E
from int
Returns
int the index or -1 if the object was not found.

isEmpty

Added in API level 1
boolean isEmpty ()

Returns whether this List contains no elements.

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

iterator

Added in API level 1
Iterator<E> iterator ()

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
Iterator<E> an iterator on the elements of this List.

lastIndexOf

Added in API level 1
int lastIndexOf (Object object)

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

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

lastIndexOf

Added in API level 1
int lastIndexOf (E object, 
                int to)

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

Parameters
object E
to int
Returns
int the index or -1 if the object was not found.

listIterator

Added in API level 1
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. 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 int: the index at which to start the iteration.
Returns
ListIterator<E> a list iterator on the elements of this List.

listIterator

Added in API level 1
ListIterator<E> listIterator ()

Equivalent to listIterator(0).

Returns
ListIterator<E> a List iterator on the elements of this List

remove

Added in API level 1
E remove (int index)

Removes the object at the specified location from this List.

Parameters
index int: the index of the object to remove.
Returns
E the removed object.

remove

Added in API level 1
boolean remove (Object o)

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

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

removeAll

Added in API level 1
boolean removeAll (Collection<?> collection)

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

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

retainAll

Added in API level 1
boolean retainAll (Collection<?> collection)

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

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

set

Added in API level 1
E set (int index, 
                E e)

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 int: the index at which to put the specified object.
e E: the object to insert.
Returns
E the previous element at the index.

size

Added in API level 1
int size ()

Returns the number of elements in this List.

Returns
int the number of elements in this List.

subList

Added in API level 1
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. The returned List is backed by this List so changes to it are reflected by the other.

Parameters
from int: the index at which to start the sublist.
to int: the index one past the end of the sublist.
Returns
List<E> a list of a portion of this List.

toArray

Added in API level 1
T[] toArray (T[] contents)

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 T: the array.
Returns
T[] an array of the elements from this List.

toArray

Added in API level 1
Object[] toArray ()

Returns an array containing all elements contained in this List.

Returns
Object[] an array of the elements from this List.

toString

Added in API level 1
String toString ()

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
String a printable representation of this object.
This site uses cookies to store your preferences for site-specific language and display options.

Hooray!

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.