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)