java.util
インタフェース Collection<E>

すべてのスーパーインタフェース:

Iterable<E>

既知のサブインタフェースの一覧:

BeanContext, BeanContextServices, BlockingQueue<E>, List<E>, Queue<E>, Set<E>, SortedSet<E>

既知の実装クラスの一覧:

AbstractCollection, AbstractList, AbstractQueue, AbstractSequentialList, AbstractSet, ArrayBlockingQueue, ArrayList, AttributeList, BeanContextServicesSupport, BeanContextSupport, ConcurrentLinkedQueue, CopyOnWriteArrayList, CopyOnWriteArraySet, DelayQueue, EnumSet, HashSet, JobStateReasons, LinkedBlockingQueue, LinkedHashSet, LinkedList, PriorityBlockingQueue, PriorityQueue, RoleList, RoleUnresolvedList, Stack, SynchronousQueue, TreeSet, Vector

public interface Collection<E>
extends Iterable<E>

「コレクション階層」のルートインタフェースです。コレクションは、その「要素」であるオブジェクトのグループを表します。コレクションによっては要素の重複を許可しますが、許可しないコレクションもあります。また、順序付けられているコレクションとそうでないコレクションがあります。JDK は、このインタフェースの「直接」の実装を一切提供しません。Set および List のような、より用途の特定されたサブインタフェースを提供します。このインタフェースは、通常は、最大限の普遍性が求められる場面でコレクションを渡したり、そのコレクションを操作するために使用されます。

「Bag」または「マルチセット」(重複要素を格納できる、順序付けのないコレクション) は、このインタフェースを直接実装する必要があります。

汎用 Collection 実装クラス (通常、サブインタフェースを介して間接的に Collection を実装する) は、2 つの「標準」コンストラクタを提供しなければいけません。空のコレクションを作成する void (引数なし) コンストラクタと、Collection 型の引数を 1 つ持ち、その引数と同じ要素で新しいコレクションを作成するコンストラクタです。したがって、後者のコンストラクタでは、ユーザはどのコレクションでもコピーでき、希望の実装型のコレクションと完全に同じコレクションを生成できます。この規約は義務づけられているわけではありませんが (インタフェースはコンストラクタを格納できないため)、Java プラットフォームライブラリにおけるすべての汎用 Collection の実装はこの規約に準拠しています。

このコレクションがオペレーションをサポートしていない場合、このインタフェース (処理されるコレクションを修正するメソッド) に含まれている「破壊的な」メソッドは、UnsupportedOperationException をスローするように指定されています。この時、呼び出しがコレクションに影響しない場合、こうしたメソッドは、UnsupportedOperationException をスローすることができますが、必須ではありません。たとえば、追加されたコレクションが空である場合、変更不可能なコレクションで addAll(Collection) を呼び出すと、例外をスローすることができますが、必須ではありません。

コレクションの実装には、格納できる要素に制限があるものもあります。たとえば、null 要素を禁止する実装や、null 要素の型に制限がある実装もあります。不適格な要素を追加しようとすると、通常 NullPointerException または ClassCastException のようなチェックされない例外をスローします。不適格な要素があるかどうかを照会しようとすると、例外をスローする場合や、ただ false を返す場合もあります。前の動作を表示する実装もあれば、後の動作を表示する実装もあります。多くの場合は、コレクションへの挿入がされない不適格な要素を処理しようとすると、実装により例外がスローされたり、処理が有効になります。このインタフェースに関するそうした例外は、「任意」の仕様としてマークされます。

このインタフェースは、Java Collections Framework のメンバです。

Collections Framework インタフェース内の多数のメソッドは、equals メソッドとの関連で定義されます。たとえば、contains(Object o) メソッドの仕様は、「このコレクションに (o==null ? e==null : o.equals(e)) を満たす要素 e が 1 つ以上含まれる場合にのみ、true を返す」というものです。この仕様は、「null 以外の引数 o を使用して Collection.contains を呼び出すと、要素 e で o.equals(e) が呼び出される」と理解すべきではありません。最適化の実装方法は自由であるため、2 つの要素のハッシュコードを比較するなどの方法で equals の呼び出しは避けられます (Object.hashCode() 仕様では、等価ではないハッシュコードを保持する 2 つのオブジェクトは等価ではないことが保証される)。通常、Collections Framework インタフェースのさまざまな実装で、実装者が適切と判断するなら、基盤となる Object メソッドの指定された動作を自由に利用できます。

導入されたバージョン:

1.2

関連項目:

Set, List, Map, SortedSet, SortedMap, HashSet, TreeSet, ArrayList, LinkedList, Vector, Collections, Arrays, AbstractCollection

メソッドの概要

boolean	add(E o) コレクションが指定された要素を格納するようにします (任意のオペレーション)。
boolean	addAll(Collection<? extends E> c) 指定されたコレクションのすべての要素をこのコレクションに追加します (任意のオペレーション)。
void	clear() コレクションからすべての要素を削除します (任意のオペレーション)。
boolean	contains(Object o) コレクションに指定された要素がある場合に true を返します。
boolean	containsAll(Collection<?> c) このコレクション内に、指定されたコレクションのすべての要素がある場合に true を返します。
boolean	equals(Object o) 指定されたオブジェクトとこのコレクションが等しいかどうかを比較します。
int	hashCode() コレクションのハッシュコード値を返します。
boolean	isEmpty() コレクションに要素がない場合に true を返します。
Iterator<E>	iterator() コレクションの要素の反復子を返します。
boolean	remove(Object o) 指定された要素の 1 つのインスタンスがこのコレクション内にある場合に、それをこのコレクションから削除します (任意のオペレーション)。
boolean	removeAll(Collection<?> c) 指定されたコレクションにも格納されているこのコレクションのすべての要素を削除します (任意のオペレーション)。
boolean	retainAll(Collection<?> c) このコレクションにおいて、指定されたコレクションに格納されている要素だけを保持します (任意のオペレーション)。
int	size() コレクションの要素数を返します。
Object[]	toArray() コレクションのすべての要素が格納されている配列を返します。
<T> T[]	toArray(T[] a) このコレクション内のすべての要素を保持する配列を返します。

メソッドの詳細

size

int size()

コレクションの要素数を返します。このコレクションに Integer.MAX_VALUE より多くの要素がある場合は、Integer.MAX_VALUE を返します。

戻り値:

コレクションの要素数

isEmpty

boolean isEmpty()

コレクションに要素がない場合に true を返します。

戻り値:

コレクションに要素がない場合は true

contains

boolean contains(Object o)

コレクションに指定された要素がある場合に true を返します。すなわち、このコレクションに (o==null ? e==null : o.equals(e)) である要素 e が 1 つ以上ある場合にだけ true を返します。

パラメータ:

o - コレクションにあるかどうかを調べる要素

戻り値:

コレクションに指定された要素がある場合は true

例外:

ClassCastException - 指定した要素の型が、このコレクションと互換でない場合 (任意のオプション)

NullPointerException - 指定された要素が null で、このコレクションが null 要素をサポートしない場合 (任意のオプション)

iterator

Iterator<E> iterator()

コレクションの要素の反復子を返します。要素が返される順序についての保証はありません。ただし、このコレクションが、保証を提供するクラスのインスタンスである場合は例外です。

定義:

インタフェース Iterable<E> 内の iterator

戻り値:

このコレクションの要素の Iterator

toArray

Object[] toArray()

コレクションのすべての要素が格納されている配列を返します。反復子によって返される要素の順序を保証しているコレクションの場合、このメソッドは同じ順序で要素を返さなければいけません。

返される配列への参照をコレクションが維持しないという点で、この配列は安全です。つまり、このメソッドは、コレクションが配列を基にしている場合でも新しい配列を割り当てます。このため、呼び出し側は、返された配列を自由に変更できます。

メソッドは、配列ベースの API とコレクションベースの API の間の橋渡し役として機能します。

戻り値:

コレクションのすべての要素が格納されている配列

toArray

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

このコレクション内のすべての要素を保持する配列を返します。返される配列の実行時の型は、指定された配列の型です。コレクションが指定された配列に収まる場合は、その中に返されます。そうでない場合は、指定された配列の実行時の型とコレクションのサイズを持つ新しい配列が割り当てられます。

コレクションが指定された配列に収まり、その配列にさらに余裕がある場合 (つまり、配列がコレクションより多くの要素を持つ場合)、その配列内でコレクションの終端よりあとの要素は null に設定されます。コレクションに null 要素がないことを呼び出し側が知っている場合にだけ、この特性を利用してコレクションの長さを判断できます。

反復子によって要素が返される順序をコレクションが保証する場合、このメソッドは同じ順序で要素を返さなければいけません。

toArray メソッドと同じように、このメソッドは、配列ベースの API とコレクションベースの API の間の橋渡し役として機能します。さらに、このメソッドでは、出力配列の実行時の型を正確に制御できるため、環境によっては割り当ての手間を抑えることができます。

l が、文字列だけからなる List であることがわかっていると仮定します。次のコードを使うと、新しく割り当てられた String の配列にリストのダンプを収集できます。

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

toArray(new Object[0]) は、機能の点で toArray() と同一です。

パラメータ:

a - コレクションの要素の格納先の配列。配列のサイズが十分でない場合は、同じ実行時の型で新しい配列が格納用として割り当てられる

戻り値:

コレクションの要素を含む配列

例外:

ArrayStoreException - 指定された配列の実行時の型が、このコレクションの各要素の実行時の型のスーパータイプではない場合

NullPointerException - 指定された配列が null である場合

add

boolean add(E o)

コレクションが指定された要素を格納するようにします (任意のオペレーション)。この呼び出しの結果、コレクションが変更された場合は true を返します。このコレクションが重複を許可せず、すでに指定された要素を格納している場合は false を返します。

このオペレーションをサポートするコレクションでは、コレクションに追加できる要素について制限がある場合があります。特に、コレクションによっては、null 要素の追加を拒否される場合や、追加できる要素の型が制限される場合があります。追加できる要素の制限については、該当するコレクションクラスのドキュメントに明記するようにしてください。

その要素がすでにあるという以外の理由で特定の要素の追加を拒否する場合、コレクションは false を返すのではなく例外をスローする必要があります。これにより、この呼び出しが戻ったあとにコレクションが指定された要素を必ず格納するという不変性を保つことができます。

パラメータ:

o - コレクションにあるかどうかを調べる要素

戻り値:

この呼び出しの結果、このコレクションが変更された場合は true

例外:

UnsupportedOperationException - このコレクションが add をサポートしない場合

ClassCastException - 指定された要素のクラスが原因で、このコレクションに追加できなかった場合

NullPointerException - 指定された要素が null で、このコレクションが null 要素をサポートしない場合

IllegalArgumentException - この要素の特性が原因で、このコレクションに追加できなかった場合

remove

boolean remove(Object o)

指定された要素の 1 つのインスタンスがこのコレクション内にある場合に、それをこのコレクションから削除します (任意のオペレーション)。すなわち、(o==null ? e==null : o.equals(e)) である要素 e がコレクション内に 1 つ以上格納されている場合に、これを削除します。指定された要素がコレクション内に格納されていた場合には true を返します。すなわち、この呼び出しの結果、コレクションが変更された場合に true を返します。

パラメータ:

o - コレクションから削除される要素 (その要素がある場合)

戻り値:

この呼び出しの結果、このコレクションが変更された場合は true

例外:

ClassCastException - 指定した要素の型が、このコレクションと互換でない場合 (任意のオプション)

NullPointerException - 指定された要素が null で、このコレクションが null 要素をサポートしない場合 (任意のオプション)

UnsupportedOperationException - このコレクションが remove をサポートしない場合

containsAll

boolean containsAll(Collection<?> c)

このコレクション内に、指定されたコレクションのすべての要素がある場合に true を返します。

パラメータ:

c - このコレクションにあるかどうかを調べるコレクション

戻り値:

指定されたコレクションのすべての要素がこのコレクション内にある場合は true

例外:

ClassCastException - 指定されたコレクションの 1 つまたは複数の要素の型が、このコレクションと互換でない場合 (任意のオプション)

NullPointerException - 指定されたコレクションが 1 つまたは複数の null 要素を含み、このコレクションが null 要素をサポートしない場合 (任意のオプション)

NullPointerException - 指定されたコレクションが null である場合

関連項目:

contains(Object)

addAll

boolean addAll(Collection<? extends E> c)

指定されたコレクションのすべての要素をこのコレクションに追加します (任意のオペレーション)。オペレーションの進行中に、指定されたコレクションが変更された場合の、このオペレーションの動作は定義されていません。したがって、指定されたコレクションがこのコレクション自身であり、このコレクションが空ではない場合、この呼び出しの動作は定義されていません。

パラメータ:

c - コレクションに挿入される要素

戻り値:

この呼び出しの結果、このコレクションが変更された場合は true

例外:

UnsupportedOperationException - このコレクションが addAll メソッドをサポートしない場合

ClassCastException - 指定されたコレクションの要素のクラスが原因で、このコレクションに追加できなかった場合

NullPointerException - 指定されたコレクション内に 1 つまたは複数の null 要素が含まれず、このコレクションが null 要素をサポートしない場合。または指定されたコレクションが null の場合

IllegalArgumentException - 指定されたコレクションの要素の特性が原因で、このコレクションに追加できなかった場合

関連項目:

add(Object)

removeAll

boolean removeAll(Collection<?> c)

指定されたコレクションにも格納されているこのコレクションのすべての要素を削除します (任意のオペレーション)。この呼び出しの結果、このコレクションには指定されたコレクションと共通の要素はなくなります。

パラメータ:

c - コレクションから削除される要素

戻り値:

この呼び出しの結果、このコレクションが変更された場合は true

例外:

UnsupportedOperationException - このコレクションが removeAll メソッドをサポートしない場合

ClassCastException - このコレクションの 1 つまたは複数の要素の型が、指定されたコレクションと互換でない場合 (任意のオプション)

NullPointerException - このコレクションが 1 つまたは複数の null 要素を含み、指定されたコレクションが null 要素をサポートしない場合 (任意のオプション)

NullPointerException - 指定されたコレクションが null である場合

関連項目:

remove(Object), contains(Object)

retainAll

boolean retainAll(Collection<?> c)

このコレクションにおいて、指定されたコレクションに格納されている要素だけを保持します (任意のオペレーション)。つまり、指定されたコレクションに格納されていないすべての要素をこのコレクションから削除します。

パラメータ:

c - コレクションで保持される要素

戻り値:

この呼び出しの結果、このコレクションが変更された場合は true

例外:

UnsupportedOperationException - コレクションが retainAll メソッドをサポートしていない場合

ClassCastException - このコレクションの 1 つまたは複数の要素の型が、指定されたコレクションと互換でない場合 (任意のオプション)

NullPointerException - このコレクションが 1 つまたは複数の null 要素を含み、指定されたコレクションが null 要素をサポートしない場合 (任意のオプション)

NullPointerException - 指定されたコレクションが null である場合

関連項目:

remove(Object), contains(Object)

clear

void clear()

コレクションからすべての要素を削除します (任意のオペレーション)。この呼び出しの結果、例外をスローしないかぎり、コレクションは空になります。

例外:

UnsupportedOperationException - このコレクションが clear メソッドをサポートしない場合

equals

boolean equals(Object o)

指定されたオブジェクトとこのコレクションが等しいかどうかを比較します。

Collection インタフェースは Object.equals の汎用規約に条項を追加しませんが、Collection を「直接」に実装する (つまり、Collection であり、Set または List ではないクラスを作成する) ときには、Object.equals をオーバーライドする場合に配慮が必要です。Object.equals をオーバーライドする必要がない場合、もっとも単純な方法は Object の実装に依存することですが、実装によっては、デフォルトの「参照比較」の代わりに「値比較」を実装する必要があることがあります。List および Set では、このような値比較が必要です。

Object.equals メソッドの一般規約によると、equals は対称的でなければいけません (つまり、b.equals(a) の場合にだけ a.equals(b))。List.equals および Set.equals の規約によると、リストはほかのリストとだけ等しくなり、セットはほかのセットとだけ等しくなります。このため、List と Set のどちらのインタフェースも実装しないコレクションクラスのカスタム equals メソッドは、このコレクションがリストまたはセットと比較された場合に false を返します。同じ論理により、Set と List の両インタフェースを正しく実装するクラスを記述することはできません。

オーバーライド:

クラス Object 内の equals

パラメータ:

o - このコレクションと等しいかどうかが比較される Object

戻り値:

指定されたオブジェクトがこのコレクションに等しい場合は true

関連項目:

Object.equals(Object), Set.equals(Object), List.equals(Object)

hashCode

int hashCode()

コレクションのハッシュコード値を返します。Collection インタフェースは Object.hashCode メソッドの一般規約に条項を追加しませんが、プログラミングにおいて、Object.equals メソッドをオーバーライドするクラスは、Object.hashCode メソッドの一般規約を満たすために Object.hashCode メソッドもオーバーライドしなければならないことに注意してください。特に、c1.equals(c2) は c1.hashCode()==c2.hashCode() を意味します。

オーバーライド:

クラス Object 内の hashCode

戻り値:

このコレクションのハッシュコード値

関連項目:

Object.hashCode(), Object.equals(Object)