Package java.util.concurrent

Class CopyOnWriteArrayList<E>

java.lang.Object
java.util.concurrent.CopyOnWriteArrayList<E>
All Implemented Interfaces:
Serializable, Cloneable, Iterable<E>, Collection<E>, List<E>, RandomAccess
public class CopyOnWriteArrayList<E>
extends Object
implements List<E>, RandomAccess, Cloneable, Serializable
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(java.util.Collection<? extends E>) 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, Iterator.remove(), ListIterator.add(E) and ListIterator.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(java.util.Collection<? extends E>)).

See Also:
Serialized Form

  • Constructor Summary

    Constructors
    Constructor Description
    CopyOnWriteArrayList()
    Creates a new empty instance.
    CopyOnWriteArrayList​(E[] array)
    Creates a new instance containing the elements of array.
    CopyOnWriteArrayList​(Collection<? extends E> collection)
    Creates a new instance containing the elements of collection.

  • Method Summary

    Modifier and Type Method Description
    void add​(int index, E e)
    Inserts the specified object into this List at the specified location.
    boolean add​(E e)
    Adds the specified object at 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.
    boolean addAll​(Collection<? extends E> collection)
    Adds the objects in the specified collection to the end of 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​(E object, int from)
    Searches this list for object and returns the index of the first occurrence that is at or after from.
    int indexOf​(Object object)
    Searches this List for the specified object and returns the index of the first occurrence.
    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​(E object, int to)
    Searches this list for object and returns the index of the last occurrence that is before to.
    int lastIndexOf​(Object object)
    Searches this List for the specified object and returns the index of the last occurrence.
    ListIterator<E> listIterator()
    Equivalent to listIterator(0).
    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.
    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.
    Object[] toArray()
    Returns an array containing all elements contained in this List.
    <T> T[] toArray​(T[] contents)
    Returns an array containing all elements contained in this List.
    String toString()
    Returns a string containing a concise, human-readable description of this object.

    Methods inherited from class java.lang.Object

    finalize, getClass, notify, notifyAll, wait, wait, wait

  • Constructor Details

    • CopyOnWriteArrayList

      public CopyOnWriteArrayList()
      Creates a new empty instance.

    • CopyOnWriteArrayList

      public CopyOnWriteArrayList​(Collection<? extends E> collection)
      Creates a new instance containing the elements of collection.

    • CopyOnWriteArrayList

      public CopyOnWriteArrayList​(E[] array)
      Creates a new instance containing the elements of array.

  • Method Details

    • clone

      public Object clone()
      Description copied from class: Object
      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.
      Overrides:
      clone in class Object
      Returns:
      a copy of this object.

    • size

      public int size()
      Description copied from interface: List
      Returns the number of elements in this List.
      Specified by:
      size in interface Collection<E>
      Specified by:
      size in interface List<E>
      Returns:
      the number of elements in this List.

    • get

      public E get​(int index)
      Description copied from interface: List
      Returns the element at the specified location in this List.
      Specified by:
      get in interface List<E>
      Parameters:
      index - the index of the element to return.
      Returns:
      the element at the specified location.

    • contains

      public boolean contains​(Object o)
      Description copied from interface: List
      Tests whether this List contains the specified object.
      Specified by:
      contains in interface Collection<E>
      Specified by:
      contains in interface List<E>
      Parameters:
      o - the object to search for.
      Returns:
      true if object is an element of this List, false otherwise

    • containsAll

      public boolean containsAll​(Collection<?> collection)
      Description copied from interface: List
      Tests whether this List contains all objects contained in the specified collection.
      Specified by:
      containsAll in interface Collection<E>
      Specified by:
      containsAll in interface List<E>
      Parameters:
      collection - the collection of objects
      Returns:
      true if all objects in the specified collection are elements of this List, false otherwise.

    • indexOf

      public 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.
      Returns:
      the index or -1 if the object was not found.

    • indexOf

      public int indexOf​(Object object)
      Description copied from interface: List
      Searches this List for the specified object and returns the index of the first occurrence.
      Specified by:
      indexOf in interface List<E>
      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.

    • lastIndexOf

      public int lastIndexOf​(E object, int to)
      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.

    • lastIndexOf

      public int lastIndexOf​(Object object)
      Description copied from interface: List
      Searches this List for the specified object and returns the index of the last occurrence.
      Specified by:
      lastIndexOf in interface List<E>
      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.

    • isEmpty

      public boolean isEmpty()
      Description copied from interface: List
      Returns whether this List contains no elements.
      Specified by:
      isEmpty in interface Collection<E>
      Specified by:
      isEmpty in interface List<E>
      Returns:
      true if this List has no elements, false otherwise.
      See Also:
      List.size()

    • iterator

      public 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 Iterator.remove().

      Specified by:
      iterator in interface Collection<E>
      Specified by:
      iterator in interface Iterable<E>
      Specified by:
      iterator in interface List<E>
      Returns:
      an iterator on the elements of this List.
      See Also:
      Iterator

    • listIterator

      public 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 ListIterator.add(E), ListIterator.set(E) or Iterator.remove(),

      Specified by:
      listIterator in interface List<E>
      Parameters:
      index - the index at which to start the iteration.
      Returns:
      a list iterator on the elements of this List.
      See Also:
      ListIterator

    • listIterator

      public ListIterator<E> listIterator()
      Equivalent to listIterator(0).
      Specified by:
      listIterator in interface List<E>
      Returns:
      a List iterator on the elements of this List
      See Also:
      ListIterator

    • subList

      public List<E> subList​(int from, int to)
      Description copied from interface: List
      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.
      Specified by:
      subList in interface List<E>
      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.

    • toArray

      public Object[] toArray()
      Description copied from interface: List
      Returns an array containing all elements contained in this List.
      Specified by:
      toArray in interface Collection<E>
      Specified by:
      toArray in interface List<E>
      Returns:
      an array of the elements from this List.

    • toArray

      public <T> T[] toArray​(T[] contents)
      Description copied from interface: List
      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.
      Specified by:
      toArray in interface Collection<E>
      Specified by:
      toArray in interface List<E>
      Parameters:
      contents - the array.
      Returns:
      an array of the elements from this List.

    • equals

      public boolean equals​(Object other)
      Description copied from class: Object
      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 Object.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.

      Specified by:
      equals in interface Collection<E>
      Specified by:
      equals in interface List<E>
      Overrides:
      equals in class Object
      Parameters:
      other - the object to compare this instance with.
      Returns:
      true if the specified object is equal to this Object; false otherwise.
      See Also:
      Object.hashCode()

    • hashCode

      public int hashCode()
      Description copied from class: Object
      Returns an integer hash code for this object. By contract, any two objects for which Object.equals(java.lang.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.

      Specified by:
      hashCode in interface Collection<E>
      Specified by:
      hashCode in interface List<E>
      Overrides:
      hashCode in class Object
      Returns:
      this object's hash code.
      See Also:
      Object.equals(java.lang.Object)

    • toString

      public String toString()
      Description copied from class: Object
      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.

      Overrides:
      toString in class Object
      Returns:
      a printable representation of this object.

    • add

      public boolean add​(E e)
      Description copied from interface: List
      Adds the specified object at the end of this List.
      Specified by:
      add in interface Collection<E>
      Specified by:
      add in interface List<E>
      Parameters:
      e - the object to add.
      Returns:
      always true.

    • add

      public void add​(int index, E e)
      Description copied from interface: List
      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.
      Specified by:
      add in interface List<E>
      Parameters:
      index - the index at which to insert.
      e - the object to add.

    • addAll

      public boolean addAll​(Collection<? extends E> collection)
      Description copied from interface: List
      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.
      Specified by:
      addAll in interface Collection<E>
      Specified by:
      addAll in interface List<E>
      Parameters:
      collection - the collection of objects.
      Returns:
      true if this List is modified, false otherwise (i.e. if the passed collection was empty).

    • addAll

      public boolean addAll​(int index, Collection<? extends E> collection)
      Description copied from interface: List
      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.
      Specified by:
      addAll in interface List<E>
      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).

    • addAllAbsent

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

    • addIfAbsent

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

    • clear

      public void clear()
      Description copied from interface: List
      Removes all elements from this List, leaving it empty.
      Specified by:
      clear in interface Collection<E>
      Specified by:
      clear in interface List<E>
      See Also:
      List.isEmpty(), List.size()

    • remove

      public E remove​(int index)
      Description copied from interface: List
      Removes the object at the specified location from this List.
      Specified by:
      remove in interface List<E>
      Parameters:
      index - the index of the object to remove.
      Returns:
      the removed object.

    • remove

      public boolean remove​(Object o)
      Description copied from interface: List
      Removes the first occurrence of the specified object from this List.
      Specified by:
      remove in interface Collection<E>
      Specified by:
      remove in interface List<E>
      Parameters:
      o - the object to remove.
      Returns:
      true if this List was modified by this operation, false otherwise.

    • removeAll

      public boolean removeAll​(Collection<?> collection)
      Description copied from interface: List
      Removes all occurrences in this List of each object in the specified collection.
      Specified by:
      removeAll in interface Collection<E>
      Specified by:
      removeAll in interface List<E>
      Parameters:
      collection - the collection of objects to remove.
      Returns:
      true if this List is modified, false otherwise.

    • retainAll

      public boolean retainAll​(Collection<?> collection)
      Description copied from interface: List
      Removes all objects from this List that are not contained in the specified collection.
      Specified by:
      retainAll in interface Collection<E>
      Specified by:
      retainAll in interface List<E>
      Parameters:
      collection - the collection of objects to retain.
      Returns:
      true if this List is modified, false otherwise.

    • set

      public E set​(int index, E e)
      Description copied from interface: List
      Replaces the element at the specified location in this List with the specified object. This operation does not change the size of the List.
      Specified by:
      set in interface List<E>
      Parameters:
      index - the index at which to put the specified object.
      e - the object to insert.
      Returns:
      the previous element at the index.