JavaAPI之CopyOnWriteArrayList

结构

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

描述

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

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

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

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

此类是 Java Collections Framework 的成员。

从以下版本开始：

1.5

另请参见：

序列化表格

构造方法

1、public CopyOnWriteArrayList()  创建一个空列表。 

2、public CopyOnWriteArrayList(Collection<? extendsE> c)

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

参数：c - 最初保存元素的 collection

抛出：NullPointerException - 如果指定 collection 为 null

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

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

抛出：NullPointerException - 如果指定数组为 null

方法详细

1、public int size()  返回此列表中的元素数。

指定者：接口 Collection<E> 中的 size

指定者：接口 List<E> 中的 size

返回：此列表中的元素数

2、public boolean isEmpty()    如果此列表不包含任何元素，则返回true。

指定者：接口 Collection<E> 中的 isEmpty

指定者：接口 List<E> 中的 isEmpty

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

3、public booleancontains(Object o)

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

指定者：接口Collection<E> 中的contains

指定者：接口List<E> 中的contains

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

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

4、public intindexOf(Object o)

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

指定者：接口List<E> 中的indexOf

参数：o - 要搜索的元素

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

5、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 - 如果指定索引为负

6、public int lastIndexOf(Object o)

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

指定者：接口 List<E> 中的 lastIndexOf

参数：o - 要搜索的元素

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

7、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 - 如果指定索引大于等于此列表的当前大小

8、public Objectclone()    返回此列表的浅表副本。（这些元素本身未被复制。）

覆盖：类 Object 中的 clone

返回：此列表的一个副本

另请参见：Cloneable

9、public Object[]toArray()

返回一个按恰当顺序（从第一个元素到最后一个元素）包含此列表中所有元素的数组。由于此列表并不维护对返回数组的任何引用，因而它将是“安全的”。（换句话说，此方法必须分配一个新数组）。因此，调用者可以随意修改返回的数组。此方法充当基于数组的 API 与基于 collection 的 API 之间的桥梁。

指定者：接口 Collection<E> 中的 toArray

指定者：接口 List<E> 中的 toArray

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

另请参见：Arrays.asList(Object[])

10、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

11、public Eget(int index)    返回列表中指定位置的元素。

指定者：接口 List<E> 中的 get

参数：index - 要返回的元素的索引

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

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

12、public Eset(int index,  E element)    用指定的元素替代此列表指定位置上的元素。

指定者：接口 List<E> 中的 set

参数：index - 要替换的元素的索引   element - 要在指定位置存储的元素

返回：以前在指定位置的元素

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

13、public boolean add(E e)    将指定元素添加到此列表的尾部。

指定者：接口 Collection<E> 中的 add

指定者：接口 List<E> 中的 add

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

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

14、public void add(int index, E element)

在此列表的指定位置上插入指定元素。将当前在该位置上的元素（如果有）以及所有后续元素向右移（其索引加 1）。指定者：接口List<E> 中的 add

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

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

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

指定者：接口 List<E> 中的 remove

参数：index - 要移除的元素的索引

返回：以前在指定位置的元素

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

16、public boolean remove(Object o)

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

指定者：接口 Collection<E> 中的 remove

指定者：接口 List<E> 中的 remove

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

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

17、public booleanaddIfAbsent(E e)   添加元素（如果不存在）。

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

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

18、public booleancontainsAll(Collection<?> c)  如果此列表包含指定 collection 的所有元素，则返回true。

指定者：接口Collection<E> 中的containsAll

指定者：接口List<E> 中的containsAll

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

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

抛出：NullPointerException - 如果指定 collection 为 null

另请参见：contains(Object)

19、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)

20、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)

21、public int addAllAbsent(Collection<? extendsE> c)

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

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

返回：添加的元素数量

抛出：NullPointerException - 如果指定 collection 为 null

另请参见：addIfAbsent(Object)

22、public void clear()    从此列表移除所有元素。此调用返回之后，该列表将为空。

指定者：接口 Collection<E> 中的 clear

指定者：接口 List<E> 中的 clear

23、public boolean addAll(Collection<? extendsE> c)   按照指定 collection 的迭代器返回元素的顺序，将指定 collection 中的所有元素添加此列表的尾部。

指定者：接口 Collection<E> 中的 addAll

指定者：接口 List<E> 中的 addAll

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

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

抛出：NullPointerException - 如果指定 collection 为 null

另请参见：add(Object)

24、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)

25、public StringtoString()

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

覆盖：类 Object 中的 toString

返回：此列表的字符串表示形式

26、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

27、public int hashCode()   返回此列表的哈希码值。 此实现使用了List.hashCode() 中的定义。

指定者：接口 Collection<E> 中的 hashCode

指定者：接口 List<E> 中的 hashCode

覆盖：类 Object 中的 hashCode

返回：此列表的哈希码值

另请参见：Object.equals(java.lang.Object),Hashtable

28、public Iterator<E>iterator()

返回以恰当顺序在此列表元素上进行迭代的迭代器。构造该迭代器时，所返回的迭代器提供了列表状态的一个快照。遍历该迭代器时不需要执行任何同步。该迭代器不 支持remove 方法。

指定者：接口 Iterable<E> 中的 iterator

指定者：接口 Collection<E> 中的 iterator

指定者：接口 List<E> 中的 iterator

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

29、public ListIterator<E>listIterator()   返回此列表元素的列表迭代器（按适当顺序）。在构造该迭代器时，返回的迭代器提供了列表状态的一个快照。遍历该迭代器时不需要执行任何同步。该迭代器不 支持remove、set 或者 add 方法。

指定者：接口 List<E> 中的 listIterator

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

30、public ListIterator<E>listIterator(int index)

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

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

指定者：接口 List<E> 中的 listIterator

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

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

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

31、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)