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 的一个线程安全的变体，其中所有可变操作（添加、设置，等等）都是通过对基础数组进行一次新的复制来实现的。

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

此类是 Java Collections Framework 的成员。

从以下版本开始：

1.5

另请参见：

序列化表格

构造方法摘要

CopyOnWriteArrayList()
创建一个空列表。

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

CopyOnWriteArrayList(E[] toCopyIn)
创建一个新的 CopyOnWriteArrayList，它保持给定数组的副本。

方法摘要

boolean	add(E element) 将指定元素追加到此列表的尾部。
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 element) 追加元素（如果不存在）。
void	clear() 从此列表中移除所有元素。
Object	clone() 返回此列表的浅表复制。
boolean	contains(Object elem) 如果此列表包含指定的元素，则返回 true。
boolean	containsAll(Collection<?> c) 如果此 collection 包含指定 collection 的所有元素，则返回 ture。
boolean	equals(Object o) 比较指定对象与此列表是否相等。
E	get(int index) 返回此列表中指定位置上的元素。
int	hashCode() 返回此列表的哈希码值。
int	indexOf(E elem, int index) 从 index 处开始，搜索第一次出现的给定参数，用 equals 方法进行相等性测试。
int	indexOf(Object elem) 搜索第一次出现的给定参数，用 equals 方法进行相等性测试。
boolean	isEmpty() 测试此列表是否没有任何元素。
Iterator<E>	iterator() 返回此 collection 中包含的元素上的 Iterator。
int	lastIndexOf(E elem, int index) 从指定索引处开始向后搜索指定的对象，并返回其索引。
int	lastIndexOf(Object elem) 返回指定的对象在列表中最后一次出现的位置索引。
ListIterator<E>	listIterator() 返回此列表中元素的 Iterator（按适当顺序）。
ListIterator<E>	listIterator(int index) 从列表中指定位置开始，返回此列表中的元素的 ListIterator（按适当顺序）。
E	remove(int index) 移除此列表中指定位置上的元素。
boolean	remove(Object o) 从此列表中移除指定元素的一个实例，如果存在的话（可选操作）。
boolean	removeAll(Collection<?> c) 从此 Collection 中移除所有包含在指定 Collection 中的元素。
boolean	retainAll(Collection<?> c) 只保留此 Collection 中包含在指定 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() 返回此 Collection 的字符串表示形式，其中包含每个元素的字符串表示形式。

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

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

构造方法详细信息

CopyOnWriteArrayList

public CopyOnWriteArrayList()

创建一个空列表。

CopyOnWriteArrayList

public CopyOnWriteArrayList(Collection<? extends E> c)

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

参数：

c - 最初保持元素的 collection

CopyOnWriteArrayList

public CopyOnWriteArrayList(E[] toCopyIn)

创建一个新的 CopyOnWriteArrayList，它保持给定数组的副本。

参数：

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

方法详细信息

size

public int size()

返回此列表中的元素数。

指定者：

接口 Collection<E> 中的 size

指定者：

接口 List<E> 中的 size

返回：

此列表中的元素数。

isEmpty

public boolean isEmpty()

测试此列表是否没有任何元素。

指定者：

接口 Collection<E> 中的 isEmpty

指定者：

接口 List<E> 中的 isEmpty

返回：

如果此列表没有任何元素，则返回 true；否则返回 false。

contains

public boolean contains(Object elem)

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

指定者：

接口 Collection<E> 中的 contains

指定者：

接口 List<E> 中的 contains

参数：

elem - 测试该元素是否在此列表中存在。

返回：

如果指定的元素存在，则返回 true；否则返回 false。

indexOf

public int indexOf(Object elem)

搜索第一次出现的给定参数，用 equals 方法进行相等性测试。

指定者：

接口 List<E> 中的 indexOf

参数：

elem - 一个对象。

返回：

列表中第一次出现该参数的位置索引；如果未找到对象，则返回 -1。

另请参见：

Object.equals(Object)

indexOf

public int indexOf(E elem,
                   int index)

从 index 处开始，搜索第一次出现的给定参数，用 equals 方法进行相等性测试。

参数：

elem - 一个对象。

index - 搜索起始处的索引。

返回：

在列表中的 index 处或其后的位置上，第一次出现该对象参数的位置索引；如果未找到对象，则返回 -1。

另请参见：

Object.equals(Object)

lastIndexOf

public int lastIndexOf(Object elem)

返回指定的对象在列表中最后一次出现的位置索引。

指定者：

接口 List<E> 中的 lastIndexOf

参数：

elem - 所需的元素。

返回：

此列表中最后一次出现指定对象的位置索引；如果未找到对象，则返回 -1。

lastIndexOf

public int lastIndexOf(E elem,
                       int index)

从指定索引处开始向后搜索指定的对象，并返回其索引。

参数：

elem - 所需的元素。

index - 搜索起始处的索引。

返回：

在列表中小于 index 的位置上，最后一次出现指定对象的位置索引；如果未找到该对象，则返回 -1。

clone

public Object clone()

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

覆盖：

类 Object 中的 clone

返回：

此列表的一个克隆。

另请参见：

Cloneable

toArray

public Object[] toArray()

返回一个按照正确的顺序包含此列表中所有元素的数组。

指定者：

接口 Collection<E> 中的 toArray

指定者：

接口 List<E> 中的 toArray

返回：

返回一个按照正确的顺序包含此列表所有元素的数组。

另请参见：

Arrays.asList(Object[])

toArray

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

返回一个按照正确的顺序包含此列表所有元素的数组。返回数组的运行时类型就是指定数组的运行时类型。如果指定的数组能容纳该列表，则将它返回到该数组。否则，根据指定数组的运行时类型和此列表的大小分配一个新的数组。

如果指定的数组能容纳该列表，而且还有剩余空间（即数组的元素比列表多），则将数组中紧随 collection 尾部的元素设置为 null。这在确定列表的长度时很有用，但仅 在调用方知道列表不包含任何 null 元素时才可行。

指定者：

接口 Collection<E> 中的 toArray

指定者：

接口 List<E> 中的 toArray

参数：

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

返回：

包含该列表元素的数组。

抛出：

ArrayStoreException - a 的运行时类型不是此列表中每个元素的运行时类型的超类型。

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

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

指定者：

接口 Collection<E> 中的 add

指定者：

接口 List<E> 中的 add

参数：

element - 要追加到此列表的元素。

返回：

true（按照 Collection.add 的常规协定）。

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 ? e==null : o.equals(e)) 的元素 e，则移除一个这样的元素。如果列表包含指定元素（或者列表随调用的结果发生改变），则返回 true。

指定者：

接口 Collection<E> 中的 remove

指定者：

接口 List<E> 中的 remove

参数：

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

返回：

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

addIfAbsent

public boolean addIfAbsent(E element)

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

参数：

element - 要添加到此 Collection 中的元素（如果不存在）。

返回：

如果已添加，则返回 ture

containsAll

public boolean containsAll(Collection<?> c)

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

此实现在指定 collection 上迭代，依次检查 Iterator 返回的每个元素，查看其是否包含在此 Collection 中。如果已经包含所有元素，则返回 ture，否则返回 false。

指定者：

接口 Collection<E> 中的 containsAll

指定者：

接口 List<E> 中的 containsAll

参数：

c - collection

返回：

如果包含所有元素，则返回 ture

另请参见：

Collection.contains(Object)

removeAll

public boolean removeAll(Collection<?> c)

从此 Collection 中移除所有包含在指定 Collection 中的元素。在此类中，这是一个特别昂贵的操作，因为它需要一个内部临时数组。

指定者：

接口 Collection<E> 中的 removeAll

指定者：

接口 List<E> 中的 removeAll

参数：

c - collection

返回：

如果此 Collection 随调用的结果而变化，则返回 true。

另请参见：

Collection.remove(Object), Collection.contains(Object)

retainAll

public boolean retainAll(Collection<?> c)

只保留此 Collection 中包含在指定 Collection 中的元素（可选操作）。换句话说，从此 Collection 中移除所有未包含在指定 Collection 中的元素。

指定者：

接口 Collection<E> 中的 retainAll

指定者：

接口 List<E> 中的 retainAll

参数：

c - collection

返回：

如果此 Collection 随调用的结果而变化，则返回 true。

另请参见：

Collection.remove(Object), Collection.contains(Object)

addAllAbsent

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

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

参数：

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

返回：

添加的元素数量

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 - 要插入此列表的元素。

返回：

如果添加了所有元素，则返回 ture

另请参见：

Collection.add(Object)

addAll

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

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

指定者：

接口 List<E> 中的 addAll

参数：

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

c - 要插入此列表的元素。

返回：

如果添加了所有元素，则返回 ture

抛出：

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

toString

public String toString()

返回此 Collection 的字符串表示形式，其中包含每个元素的字符串表示形式。

覆盖：

类 Object 中的 toString

返回：

该对象的字符串表示形式。

equals

public boolean equals(Object o)

比较指定对象与此列表是否相等。当且仅当指定对象也是一个列表，两个列表具有相同的大小，而且两个列表中所有相应的元素对都相等 时，才返回 true。（如果两个元素 e1 和 e2 满足 (e1==null ? e2==null : e1.equals(e2))，则它们是相等 的。）换句话说，如果两个列表包含相同的元素，且元素的顺序也相同，则将它们定义为相等的。

此实现首先检查指定的对象是否是此列表。如果是，则返回 true；否则，它将检查指定的对象是否是一个列表。如果不是，它将返回 false；如果是，它将迭代两个列表，比较相应的元素对。如果有任何比较结果返回 false，则此方法将返回 false。如果其中一个 Iterator 在另一个 Iterator 之前用完了元素，则返回 false（因为列表是不等长的）；否则，在迭代完成时返回 true。

指定者：

接口 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()

返回此 collection 中包含的元素上的 Iterator。构造该迭代器时，它提供了列表状态的一个快照。遍历该迭代器时不需要任何同步。该迭代器不 支持 remove 方法。

指定者：

接口 Iterable<E> 中的 iterator

指定者：

接口 Collection<E> 中的 iterator

指定者：

接口 List<E> 中的 iterator

返回：

迭代器

listIterator

public ListIterator<E> listIterator()

返回此列表中元素的 Iterator（按适当顺序）。构造该迭代器时，它提供了列表状态的一个快照。遍历该迭代器时不需要任何同步。该迭代器不 支持 remove、set 或者 add 方法。

指定者：

接口 List<E> 中的 listIterator

返回：

迭代器

listIterator

public ListIterator<E> listIterator(int index)

从列表中指定位置开始，返回此列表中的元素的 ListIterator（按适当顺序）。指定的索引指示将通过初始调用 nextElement 返回的第一个元素。对 previousElement 的初始调用将返回指定索引减 1 的元素。此实现返回的 ListIterator 将在其 remove、set 和 add 方法中抛出 UnsupportedOperationException。

指定者：

接口 List<E> 中的 listIterator

参数：

index - 将从 ListIterator 中返回的第一个元素的索引（通过调用 getNext）。

返回：

迭代器

抛出：

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