java.util.concurrent
类 CopyOnWriteArrayList

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

类型参数：

E - 此 collection 中所保存元素的类型

所有已实现的接口：

Serializable, Cloneable, Iterable<E>, Collection<E>, List<E>, RandomAccess

public class CopyOnWriteArrayList<E>
     

      extends 
      Object
     
     

      implements 
      List<E>, 
      RandomAccess, 
      Cloneable, 
      Serializable
     

ArrayList 的一个线程安全的变体，其中所有可变操作（add、set 等等）都是通过对底层数组进行一次新的复制来实现的。

这一般需要很大的开销，但是当遍历操作的数量大大超过可变操作的数量时，这种方法可能比其他替代方法更 有效。在不能或不想进行同步遍历，但又需要从并发线程中排除冲突时，它也很有用。“快照”风格的迭代器方法在创建迭代器时使用了对数组状态的引用。此数组在迭代器的生存期内不会更改，因此不可能发生冲突，并且迭代器保证不会抛出 ConcurrentModificationException。创建迭代器以后，迭代器就不会反映列表的添加、移除或者更改。在迭代器上进行的元素更改操作（remove、set 和 add）不受支持。这些方法将抛出 UnsupportedOperationException。

允许使用所有元素，包括 null。

内存一致性效果：当存在其他并发 collection 时，将对象放入 CopyOnWriteArrayList 之前的线程中的操作 happen-before 随后通过另一线程从 CopyOnWriteArrayList 中访问或移除该元素的操作。

此类是 Java Collections Framework 的成员。

从以下版本开始：

1.5

另请参见：

序列化表格

CopyOnWriteArrayList

public CopyOnWriteArrayList()

创建一个空列表。

CopyOnWriteArrayList

public CopyOnWriteArrayList(Collection<? extends E> c)

创建一个按 collection 的迭代器返回元素的顺序包含指定 collection 元素的列表。

参数：

c - 最初保存元素的 collection

抛出：

NullPointerException - 如果指定 collection 为 null

CopyOnWriteArrayList

public CopyOnWriteArrayList(E[] toCopyIn)

创建一个保存给定数组的副本的列表。

参数：

toCopyIn - 数组（将此数组的副本用作内部数组）

抛出：

NullPointerException - 如果指定数组为 null

size

public int size()

返回此列表中的元素数。

指定者：

接口 Collection<E> 中的 size

指定者：

接口 List<E> 中的 size

返回：

此列表中的元素数

isEmpty

public boolean isEmpty()

如果此列表不包含任何元素，则返回 true。

指定者：

接口 Collection<E> 中的 isEmpty

指定者：

接口 List<E> 中的 isEmpty

返回：

如果此列表不包含任何元素，则返回 true

contains

public boolean contains(Object o)

如果此列表包含指定的元素，则返回 true。更确切地讲，当且仅当此列表包含至少一个满足 (o==null ? e==null : o.equals(e)) 的元素 e 时，返回 true。

指定者：

接口 Collection<E> 中的 contains

指定者：

接口 List<E> 中的 contains

参数：

o - 测试是否存在于此列表中的元素。

返回：

如果此列表包含指定元素，则返回 true

indexOf

public int indexOf(Object o)

返回此列表中第一次出现的指定元素的索引；如果此列表不包含该元素，则返回 -1。更确切地讲，返回满足 (o==null ? get(i)==null : o.equals(get(i))) 的最低索引 i；如果没有这样的索引，则返回 -1。

指定者：

接口 List<E> 中的 indexOf

参数：

o - 要搜索的元素

返回：

此列表中第一次出现的指定元素的索引，如果列表不包含该元素，则返回 -1

indexOf

public int indexOf(E e,
                   int index)

返回第一次出现的指定元素在此列表中的索引，从 index 开始向前搜索，如果没有找到该元素，则返回 -1。更确切地讲，返回满足 (i >= index && (e==null ? get(i)==null : e.equals(get(i)))) 的最低索引 i，如果不存在这样的索引，则返回 -1。

参数：

e - 要搜索的元素

index - 搜索开始处的索引

返回：

此列表中 index 或其后的位置上第一次出现该元素的位置索引；如果未找到该元素，则返回 -1。

抛出：

IndexOutOfBoundsException - 如果指定索引为负

lastIndexOf

public int lastIndexOf(Object o)

返回此列表中最后出现的指定元素的索引；如果列表不包含此元素，则返回 -1。更确切地讲，返回满足 (o==null ? get(i)==null : o.equals(get(i))) 的最高索引 i；如果没有这样的索引，则返回 -1。

指定者：

接口 List<E> 中的 lastIndexOf

参数：

o - 要搜索的元素

返回：

列表中最后出现的指定元素的索引；如果列表不包含此元素，则返回 -1

lastIndexOf

public int lastIndexOf(E e,
                       int index)

返回最后一次出现的指定元素在此列表中的索引，从 index 开始向后搜索，如果没有找到该元素，则返回 -1。更确切地讲，返回满足 (i <= index && (e==null ? get(i)==null : e.equals(get(i)))) 的最高索引 i，如果不存在这样的索引，则返回 -1。

参数：

e - 要搜索的元素

index - 开始向后搜索处的索引

返回：

此列表中小于等于 index 的位置上最后一次出现该元素的位置索引；如果未找到该元素，则返回 -1。

抛出：

IndexOutOfBoundsException - 如果指定索引大于等于此列表的当前大小

clone

public Object clone()

返回此列表的浅表副本。（这些元素本身未被复制。）

覆盖：

类 Object 中的 clone

返回：

此列表的一个副本

另请参见：

Cloneable

toArray

public Object[] toArray()

返回一个按恰当顺序（从第一个元素到最后一个元素）包含此列表中所有元素的数组。

由于此列表并不维护对返回数组的任何引用，因而它将是“安全的”。（换句话说，此方法必须分配一个新数组）。因此，调用者可以随意修改返回的数组。

此方法充当基于数组的 API 与基于 collection 的 API 之间的桥梁。

指定者：

接口 Collection<E> 中的 toArray

指定者：

接口 List<E> 中的 toArray

返回：

返回包含此列表所有元素的数组

另请参见：

Arrays.asList(Object[])

toArray

public <T> T[] toArray(T[] a)

返回以恰当顺序（从第一个元素到最后一个元素）包含列表所有元素的数组；返回数组的运行时类型是指定数组的运行时类型。如果指定数组能容纳列表，则则将该队列返回此处。否则，将分配一个具有指定数组的运行时类型和此列表的大小的新数组。

如果指定的数组能容纳列表，并有剩余的空间（即数组的元素比列表多），那么会将紧接列表尾部的元素设置为 null。（仅 当调用者知道此列表不包含任何 null 元素时，才可使用此方法来确定此列表的长度。）

像 toArray() 方法一样，此方法充当基于数组的 API 与基于 collection 的 API 之间的桥梁。更进一步说，此方法允许对输出数组的运行时类型进行精确控制，在某些情况下，这可以用来节省分配开销。

假定 x 是只包含字符串的一个已知列表。以下代码用来将该列表转储到一个新分配的 String 数组：

     String[] y = x.toArray(new String[0]);

注意， toArray(new Object[0]) 和 toArray() 在功能上是相同的。

指定者：

接口 Collection<E> 中的 toArray

指定者：

接口 List<E> 中的 toArray

参数：

a - 要存储列表元素的数组（如果该数组足够大）；否则，将分配一个具有相同运行时类型的新数组。

返回：

包含此列表所有元素的数组

抛出：

ArrayStoreException - 如果指定数组的运行时类型不是此列表每个元素的运行时类型的超类型

NullPointerException - 如果指定数组为 null

get

public E get(int index)

返回列表中指定位置的元素。

指定者：

接口 List<E> 中的 get

参数：

index - 要返回的元素的索引

返回：

列表中指定位置的元素

抛出：

IndexOutOfBoundsException - 如果索引超出范围 ( index < 0 || index >= size())

set

public E set(int index,
             E element)

用指定的元素替代此列表指定位置上的元素。

指定者：

接口 List<E> 中的 set

参数：

index - 要替换的元素的索引

element - 要在指定位置存储的元素

返回：

以前在指定位置的元素

抛出：

IndexOutOfBoundsException - 如果索引超出范围 ( index < 0 || index >= size())

add

public boolean add(E e)

将指定元素添加到此列表的尾部。

指定者：

接口 Collection<E> 中的 add

指定者：

接口 List<E> 中的 add

参数：

e - 要添加到此列表的元素。

返回：

true（根据 Collection.add(E) 的规定）

add

public void add(int index,
                E element)

在此列表的指定位置上插入指定元素。将当前在该位置上的元素（如果有）以及所有后续元素向右移（其索引加 1）。

指定者：

接口 List<E> 中的 add

参数：

index - 要在其中插入指定元素处的索引

element - 要插入的元素

抛出：

IndexOutOfBoundsException - 如果索引超出范围 ( index < 0 || index > size())

remove

public E remove(int index)

移除此列表指定位置上的元素。将所有后续元素都向左移（其索引减 1）。返回从此列表中移除的元素。

指定者：

接口 List<E> 中的 remove

参数：

index - 要移除的元素的索引

返回：

以前在指定位置的元素

抛出：

IndexOutOfBoundsException - 如果索引超出范围 ( index < 0 || index >= size())

remove

public boolean remove(Object o)

从此列表移除第一次出现的指定元素（如果存在）。 如果列表不包含这样的元素，则不更改列表。更确切地讲，移除具有满足 (o==null ? get(i)==null : o.equals(get(i))) 的最低索引 i 的元素（如果存在这样的元素）。如果此列表包含指定元素（或者此列表由于调用而发生更改），则返回 true。

指定者：

接口 Collection<E> 中的 remove

指定者：

接口 List<E> 中的 remove

参数：

o - 要从此列表移除的元素（如果存在）

返回：

如果此列表包含指定的元素，则返回 true

addIfAbsent

public boolean addIfAbsent(E e)

添加元素（如果不存在）。

参数：

e - 要添加到此列表中的元素（如果不存在）

返回：

如果已添加该元素，则返回 true

containsAll

public boolean containsAll(Collection<?> c)

如果此列表包含指定 collection 的所有元素，则返回 true。

指定者：

接口 Collection<E> 中的 containsAll

指定者：

接口 List<E> 中的 containsAll

参数：

c - 将被检查是否包含于此列表的 collection

返回：

如果此列表包含指定 collection 的所有元素，则返回 true

抛出：

NullPointerException - 如果指定 collection 为 null

另请参见：

contains(Object)

removeAll

public boolean removeAll(Collection<?> c)

从此列表移除所有包含在指定 collection 中的元素。在此类中，这是一个开销很大的操作，因为它需要一个内部临时数组。

指定者：

接口 Collection<E> 中的 removeAll

指定者：

接口 List<E> 中的 removeAll

参数：

c - 包含将从此列表中移除的元素的 collection

返回：

如果此列表由于调用而发生更改，则返回 true

抛出：

ClassCastException - 如果此列表的元素与指定 collection 不兼容（可选）

NullPointerException - 如果此列表包含一个 null 元素，并且指定 collection 不允许使用 null 元素（可选），或者指定 collection 为 null

另请参见：

remove(Object)

retainAll

public boolean retainAll(Collection<?> c)

只保留此列表中包含在指定 collection 中的元素。换句话说，从此列表中移除所有未包含在指定 collection 中的元素。

指定者：

接口 Collection<E> 中的 retainAll

指定者：

接口 List<E> 中的 retainAll

参数：

c - 包含保留在此列表中的元素的 collection

返回：

如果此列表由于调用而发生更改，则返回 true

抛出：

ClassCastException - 如果此列表的元素的类与指定 collection 不兼容（可选）

NullPointerException - 如果此列表包含一个 null 元素，并且指定 collection 不允许使用 null 元素（可选），或者指定 collection 为 null

另请参见：

remove(Object)

addAllAbsent

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

按照指定 collection 的迭代器返回元素的顺序，将指定 collection 中尚未包含在此列表中的所有元素添加列表的尾部。

参数：

c - 包含要添加到此列表中的元素的 collection

返回：

添加的元素数量

抛出：

NullPointerException - 如果指定 collection 为 null

另请参见：

addIfAbsent(Object)

clear

public void clear()

从此列表移除所有元素。此调用返回之后，该列表将为空。

指定者：

接口 Collection<E> 中的 clear

指定者：

接口 List<E> 中的 clear

addAll

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

按照指定 collection 的迭代器返回元素的顺序，将指定 collection 中的所有元素添加此列表的尾部。

指定者：

接口 Collection<E> 中的 addAll

指定者：

接口 List<E> 中的 addAll

参数：

c - 包含将插入此列表中的元素的 collection

返回：

如果此列表由于调用而发生更改，则返回 true

抛出：

NullPointerException - 如果指定 collection 为 null

另请参见：

add(Object)

addAll

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

从指定位置开始，将指定 collection 的所有元素插入此列表。将当前在该位置上的元素（如果有）以及所有后续元素都向右移（其索引加 1）。新元素将按指定 collection 的迭代器返回的顺序出现在列表中。

指定者：

接口