java.util.concurrent
类 CopyOnWriteArrayList<E>

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()
创建一个空列表。

CopyOnWriteArrayList(Collection<? extends E> c)
创建一个按 collection 的迭代器返回元素的顺序包含指定 collection 元素的列表。

CopyOnWriteArrayList(E[] toCopyIn)
创建一个保存给定数组的副本的列表。

方法摘要

boolean	add(E e) 将指定元素添加到此列表的尾部。
void	add(int index, E element) 在此列表的指定位置上插入指定元素。
boolean	addAll(Collection<? extends E> c) 按照指定 collection 的迭代器返回元素的顺序，将指定 collection 中的所有元素添加此列表的尾部。
boolean	addAll(int index, Collection<? extends E> c) 从指定位置开始，将指定 collection 的所有元素插入此列表。
int	addAllAbsent(Collection<? extends E> c) 按照指定 collection 的迭代器返回元素的顺序，将指定 collection 中尚未包含在此列表中的所有元素添加列表的尾部。
boolean	addIfAbsent(E e) 添加元素（如果不存在）。
void	clear() 从此列表移除所有元素。
Object	clone() 返回此列表的浅表副本。
boolean	contains(Object o) 如果此列表包含指定的元素，则返回 true。
boolean	containsAll(Collection<?> c) 如果此列表包含指定 collection 的所有元素，则返回 true。
boolean	equals(Object o) 比较指定对象与此列表的相等性。
E	get(int index) 返回列表中指定位置的元素。
int	hashCode() 返回此列表的哈希码值。
int	indexOf(E e, int index) 返回第一次出现的指定元素在此列表中的索引，从 index 开始向前搜索，如果没有找到该元素，则返回 -1。
int	indexOf(Object o) 返回此列表中第一次出现的指定元素的索引；如果此列表不包含该元素，则返回 -1。
boolean	isEmpty() 如果此列表不包含任何元素，则返回 true。
Iterator<E>	iterator() 返回以恰当顺序在此列表元素上进行迭代的迭代器。
int	lastIndexOf(E e, int index) 返回最后一次出现的指定元素在此列表中的索引，从 index 开始向后搜索，如果没有找到该元素，则返回 -1。
int	lastIndexOf(Object o) 返回此列表中最后出现的指定元素的索引；如果列表不包含此元素，则返回 -1。
ListIterator<E>	listIterator() 返回此列表元素的列表迭代器（按适当顺序）。
ListIterator<E>	listIterator(int index) 返回列表中元素的列表迭代器（按适当顺序），从列表的指定位置开始。
E	remove(int index) 移除此列表指定位置上的元素。
boolean	remove(Object o) 从此列表移除第一次出现的指定元素（如果存在）。
boolean	removeAll(Collection<?> c) 从此列表移除所有包含在指定 collection 中的元素。
boolean	retainAll(Collection<?> c) 只保留此列表中包含在指定 collection 中的元素。
E	set(int index, E element) 用指定的元素替代此列表指定位置上的元素。
int	size() 返回此列表中的元素数。
List<E>	subList(int fromIndex, int toIndex) 返回此列表中 fromIndex（包括）和 toIndex（不包括）之间部分的视图。
Object[]	toArray() 返回一个按恰当顺序（从第一个元素到最后一个元素）包含此列表中所有元素的数组。
<T> T[]	toArray(T[] a) 返回以恰当顺序（从第一个元素到最后一个元素）包含列表所有元素的数组；返回数组的运行时类型是指定数组的运行时类型。
String	toString() 返回此列表的字符串表示形式。

从类 java.lang.Object 继承的方法

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

构造方法详细信息

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 的迭代器返回的顺序出现在列表中。

指定者：

接口 List<E> 中的 addAll

参数：

index - 插入指定 collection 中第一个元素的索引

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

返回：

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

抛出：

NullPointerException - 如果指定的 collection 包含一个或多个 null 元素，并且该列表不允许 null 元素，或者指定的 collection 为 null

NullPointerException - 如果指定 collection 为 null

另请参见：

add(int,Object)

toString

public String toString()

返回此列表的字符串表示形式。该字符串表示形式由列表元素的字符串表示形式组成，这些元素按其迭代器返回的顺序排序，并用方括号 ("[]") 括起来。相邻元素由字符 ", "（逗号加空格）分隔。通过 String.valueOf(Object) 可以将元素转换成字符串。

覆盖：

类 Object 中的 toString

返回：

此列表的字符串表示形式

equals

public boolean equals(Object o)

比较指定对象与此列表的相等性。如果指定对象与此对象是同一对象，或者它也是一个 List，并且在指定列表上迭代的迭代器所返回的元素的序列与在此列表上迭代的迭代器所返回的元素序列相同，则返回 true。如果两个序列具有相同的长度，并且对应元素在序列的同一位置上，则认为两个序列是相等的。满足 (e1==null ? e2==null : e1.equals(e2)) 的两个元素 e1 和 e2 视为相等。

指定者：

接口 Collection<E> 中的 equals

指定者：

接口 List<E> 中的 equals

覆盖：

类 Object 中的 equals

参数：

o - 将与此列表进行相等性比较的对象

返回：

如果指定的对象与此列表相等，则返回 true

另请参见：

Object.hashCode(), Hashtable

hashCode

public int hashCode()

返回此列表的哈希码值。

此实现使用了 List.hashCode() 中的定义。

指定者：

接口 Collection<E> 中的 hashCode

指定者：

接口 List<E> 中的 hashCode

覆盖：

类 Object 中的 hashCode

返回：

此列表的哈希码值

另请参见：

Object.equals(java.lang.Object), Hashtable

iterator

public Iterator<E> iterator()

返回以恰当顺序在此列表元素上进行迭代的迭代器。

构造该迭代器时，所返回的迭代器提供了列表状态的一个快照。遍历该迭代器时不需要执行任何同步。该迭代器不 支持 remove 方法。

指定者：

接口 Iterable<E> 中的 iterator

指定者：

接口 Collection<E> 中的 iterator

指定者：

接口 List<E> 中的 iterator

返回：

以恰当顺序在此列表元素上进行迭代的迭代器

listIterator

public ListIterator<E> listIterator()

返回此列表元素的列表迭代器（按适当顺序）。

在构造该迭代器时，返回的迭代器提供了列表状态的一个快照。遍历该迭代器时不需要执行任何同步。该迭代器不 支持 remove、set 或者 add 方法。

指定者：

接口 List<E> 中的 listIterator

返回：

此列表元素的列表迭代器（按适当顺序）

listIterator

public ListIterator<E> listIterator(int index)

返回列表中元素的列表迭代器（按适当顺序），从列表的指定位置开始。指定的索引表示 next 的初始调用所返回的第一个元素。previous 方法的初始调用将返回索引比指定索引少 1 的元素。

在构造该迭代器时，返回的迭代器提供了列表状态的一个快照。遍历该迭代器时不需要执行任何同步。该迭代器不 支持 remove、set 或者 add 方法。

指定者：

接口 List<E> 中的 listIterator

参数：

index - 从列表迭代器返回的第一个元素的索引（通过调用 next 方法）

返回：

此列表中元素的列表迭代器（按适当顺序），从列表中的指定位置开始

抛出：

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

subList

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

返回此列表中 fromIndex（包括）和 toIndex（不包括）之间部分的视图。返回的列表受此列表的支持，因此返回列表中的更改将反映在此列表中，反之亦然。当支持可变操作时，它们对于 CopyOnWriteArrayLists 可能不是很有用。

如果通过返回列表以外的其他任何方式从结构上修改 底层实现列表（即此列表），则此方法返回的列表语义将是不确定的。（从结构上修改是指更改列表的大小，或者以其他方式打乱列表，使正在进行的迭代生成错误的结果。）

指定者：

接口 List<E> 中的 subList

参数：

fromIndex - subList 的低端点（包括）

toIndex - subList 的高端点（不包括）

返回：

此列表中指定范围的视图

抛出：

IndexOutOfBoundsException - 非法的端点值 (fromIndex < 0 || toIndex > size || fromIndex > toIndex)