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

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

Iterable<E>

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

BeanContext, BeanContextServices, BlockingDeque<E>, BlockingQueue<E>, Deque<E>, List<E>, NavigableSet<E>, Queue<E>, Set<E>, SortedSet<E>

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

AbstractCollection, AbstractList, AbstractQueue, AbstractSequentialList, AbstractSet, ArrayBlockingQueue, ArrayDeque, ArrayList, AttributeList, BeanContextServicesSupport, BeanContextSupport, ConcurrentLinkedQueue, ConcurrentSkipListSet, CopyOnWriteArrayList, CopyOnWriteArraySet, DelayQueue, EnumSet, HashSet, JobStateReasons, LinkedBlockingDeque, 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 を返す場合もあります。 前の動作を禁止する実装もあれば、後の動作を禁止する実装もあります。前の動作を表示する実装もあれば、あとの動作を表示する実装もあります。 多くの場合は、コレクションへの挿入がされない不適格な要素を処理しようとすると、実装により例外がスローされたり、処理が有効になります。このインタフェースに関するそうした例外は、「任意」の仕様としてマークされます。

独自の同期ポリシーを決定するかどうかは、それぞれのコレクションによって異なります。実装による強い保証がない場合、別のスレッドによって変更されるコレクションでメソッドを呼び出すと、定義されていない動作が発生する可能性があります。これには、直接の呼び出し、呼び出しを実行する可能性があるメソッドへのコレクションの引き渡し、および既存の反復子を使用したコレクションの検査が含まれます。

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 メソッドの指定された動作を自由に利用できます。

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

導入されたバージョン:

1.2

関連項目:

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

メソッドの概要

boolean	add(E e) 指定された要素がこのコレクションに格納されていることを保証します (任意のオペレーション)。
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 の間の橋渡し役として機能します。さらに、このメソッドでは、出力配列の実行時の型を正確に制御できるため、環境によっては割り当ての手間を抑えることができます。

x が、文字列だけからなるコレクションであることがわかっていると仮定します。次のコードを使うと、新しく割り当てられた String の配列にコレクションをダンプできます。

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

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

パラメータ:

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

戻り値:

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

例外:

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

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

add

boolean add(E e)

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

このオペレーションをサポートするコレクションでは、コレクションに追加できる要素について制限がある場合があります。たとえば、コレクションによっては、null 要素の追加が許可されないことや、追加される要素の型を制限することがあります。追加される要素に関して制限がある場合は、その Collection クラスのドキュメントに明示すべきでしょう。

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

パラメータ:

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

戻り値:

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

例外:

UnsupportedOperationException - add オペレーションがこのコレクションでサポートされない場合

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

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

IllegalArgumentException - 要素のある特性が原因で、このコレクションに要素を追加できない場合

IllegalStateException - 挿入制限のためにこの時点で要素を追加できない場合

remove

boolean remove(Object o)

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

パラメータ:

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

戻り値:

この呼び出しの結果、要素が削除された場合は true

例外:

ClassCastException - 指定した要素の型が、このコレクションと互換でない場合 (省略可能)

NullPointerException - 指定された要素が null で、このコレクションが null 要素を許容しない場合 (省略可能)

UnsupportedOperationException - remove オペレーションがこのコレクションでサポートされない場合

containsAll

boolean containsAll(Collection<?> c)

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

パラメータ:

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

戻り値:

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

例外:

ClassCastException - 指定されたコレクションの 1 つ以上の要素の型が、このコレクションと互換でない場合 (省略可能)

NullPointerException - 指定されたコレクションに 1 つ以上の null 要素が含まれており、このコレクションが null 要素を許可しない場合 (省略可能)。または指定されたコレクションが null の場合

関連項目:

contains(Object)

addAll

boolean addAll(Collection<? extends E> c)

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

パラメータ:

c - コレクションに追加される要素を含むコレクション

戻り値:

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

例外:

UnsupportedOperationException - addAll オペレーションがこのコレクションでサポートされない場合

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

NullPointerException - 指定されたコレクション内に null 要素が含まれ、このコレクションが null 要素を許可しない場合。または指定されたコレクションが null の場合

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

IllegalStateException - 挿入制限のため、この時点で一部の要素を追加できない場合

関連項目:

add(Object)

removeAll

boolean removeAll(Collection<?> c)

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

パラメータ:

c - このコレクションから削除される要素を含むコレクション

戻り値:

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

例外:

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

ClassCastException - このコレクションの 1 つ以上の要素の型が、指定されたコレクションと互換でない場合 (省略可能)

NullPointerException - このコレクション内に 1 つ以上の null 要素が含まれており、指定されたコレクションが null 要素をサポートしない場合 (省略可能)。または指定されたコレクションが null の場合

関連項目:

remove(Object), contains(Object)

retainAll

boolean retainAll(Collection<?> c)

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

パラメータ:

c - このコレクションで保持される要素を含むコレクション

戻り値:

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

例外:

UnsupportedOperationException - retainAll オペレーションがこのコレクションでサポートされない場合

ClassCastException - このコレクションの 1 つ以上の要素の型が、指定されたコレクションと互換でない場合 (省略可能)

NullPointerException - このコレクション内に 1 つ以上の null 要素が含まれており、指定されたコレクションが null 要素を許可しない場合 (省略可能)。または指定されたコレクションが 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 - このコレクションと等しいかどうかが比較されるオブジェクト

戻り値:

指定されたオブジェクトがこのコレクションに等しい場合は 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)