compact1, compact2, compact3

java.util

インタフェースCollection<E>

型パラメータ:

E - このコレクション内の要素の型

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

Iterable<E>

既知のすべてのサブインタフェース:

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

既知のすべての実装クラス:

AbstractCollection, AbstractList, AbstractQueue, AbstractSequentialList, AbstractSet, ArrayBlockingQueue, ArrayDeque, ArrayList, AttributeList, BeanContextServicesSupport, BeanContextSupport, ConcurrentHashMap.KeySetView, ConcurrentLinkedDeque, ConcurrentLinkedQueue, ConcurrentSkipListSet, CopyOnWriteArrayList, CopyOnWriteArraySet, DelayQueue, EnumSet, HashSet, JobStateReasons, LinkedBlockingDeque, LinkedBlockingQueue, LinkedHashSet, LinkedList, LinkedTransferQueue, 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メソッドの指定された動作を自由に利用できます。

コレクションの再帰的なトラバーサルを行うコレクション操作の中には、コレクションにそれ自身が直接または間接的に含まれる自己参照型インスタンスの例外によって失敗するものがあります。これには、clone()、equals()、hashCode()、およびtoString()メソッドが含まれます。実装ではオプションで自己参照シナリオを処理できますが、最新の実装では行われていません。

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

実装要件:

デフォルトのメソッド実装(継承または別の方法によるもの)は、同期プロトコルを適用しません。Collectionの実装に特定の同期プロトコルが含まれている場合は、デフォルトの実装をオーバーライドしてそのプロトコルを適用する必要があります。

導入されたバージョン:

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() コレクションの要素のイテレータを返します。
default Stream<E>	parallelStream() このコレクションをソースとして、潜在的に並列のStreamを返します。
boolean	remove(Object o) 指定された要素のインスタンスがこのコレクションにあれば、そのインスタンスをコレクションから1つ削除します(オプションの操作)。
boolean	removeAll(Collection<?> c) 指定されたコレクションにも格納されているこのコレクションのすべての要素を削除します(オプションの操作)。
default boolean	removeIf(Predicate<? super E> filter) 指定された述語を満たすこのコレクションの要素をすべて削除します。
boolean	retainAll(Collection<?> c) このコレクションにおいて、指定されたコレクションに格納されている要素だけを保持します(オプションの操作)。
int	size() このコレクション中の要素の数を返します。
default Spliterator<E>	spliterator() このコレクション内の要素に対するSpliteratorを作成します。
default Stream<E>	stream() このコレクションをソースとして使用して、逐次的なStreamを返します。
Object[]	toArray() このコレクションの要素がすべて格納されている配列を返します。
<T> T[]	toArray(T[] a) このコレクション内のすべての要素を保持する配列を返します。返される配列の実行時の型は、指定された配列の型です。

インタフェースjava.lang.Iterableから継承されたメソッド

forEach

メソッドの詳細

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

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

定義:

iterator、インタフェース: Iterable<E>

戻り値:

このコレクションの要素の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()と同一です。

型パラメータ:

T - コレクションを含む配列の実行時の型

パラメータ:

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)

removeIf

default boolean removeIf(Predicate<? super E> filter)

指定された述語を満たすこのコレクションの要素をすべて削除します。反復中に、または述語によってスローされたエラーまたは実行時例外は、呼出し側に中継されます。

実装要件:

デフォルトの実装では、そのiterator()を使用してコレクションのすべての要素をトラバースします。一致する各要素は、Iterator.remove()を使って削除されます。コレクションのイテレータが削除をサポートしていない場合は、最初に一致する要素に対してUnsupportedOperationExceptionがスローされます。

パラメータ:

filter - 削除される要素に対してtrueを返す述語

戻り値:

要素が削除された場合はtrue

例外:

NullPointerException - 指定されたフィルタがnullである場合

UnsupportedOperationException - このコレクションから要素を削除できない場合。一致する要素を削除できない場合、または一般的に削除がサポートされていない場合、実装によってこの例外がスローされることがあります。

導入されたバージョン:

1.8

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の実装に依存することですが、実装によっては、デフォルトの「参照比較」の代わりに「値比較」を実装する必要があることがあります。ListおよびSetインタフェースでは、このような値比較が必要です。

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

オーバーライド:

equals、クラス: Object

パラメータ:

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()を意味します。

オーバーライド:

hashCode、クラス: Object

戻り値:

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

関連項目:

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

spliterator

default Spliterator<E> spliterator()

このコレクション内の要素に対するSpliteratorを作成します。実装では、このスプリッテレータによって報告された特性値をドキュメント化する必要があります。スプリッテレータがSpliterator.SIZEDを報告し、このコレクションに要素が1つも含まれていない場合は、そのような特性値が報告される必要はありません。

デフォルトの実装は、より効率的なスプリッテレータを返すことができるサブクラスによってオーバーライドされるべきです。stream()およびparallelStream()}メソッドの期待される遅延動作を維持するため、スプリッテレータはIMMUTABLEまたはCONCURRENTの特性を持っているか、遅延バインディングであるべきです。これらのどれも実現できない場合、オーバーライドするクラスはバインディングおよび構造上の干渉に関するスプリッテレータのドキュメント化されたポリシーを記述し、次にあるようにstream()およびparallelStream()メソッドをオーバーライドして、スプリッテレータのSupplierでストリームを作成するべきです。

     Stream<E> s = StreamSupport.stream(() -> spliterator(), spliteratorCharacteristics)
 

これらの要件により、stream()およびparallelStream()メソッドによって作成されたストリームは、ストリーム終端操作の開始以降、コレクションの内容を反映するようになります。

定義:

spliterator、インタフェース: Iterable<E>

実装要件:

デフォルトの実装では、コレクションのIteratorから遅延バインディング・スプリッテレータを作成します。このスプリッテレータは、コレクションのイテレータのフェイルファスト特性を継承します。

作成されたSpliteratorはSpliterator.SIZEDを報告します。

実装上の注意:

作成されたSpliteratorはさらにSpliterator.SUBSIZEDも報告します。

スプリッテレータの適用される要素がない場合は、SIZEDおよびSUBSIZEDの他に追加の特性値を報告しても、クライアントによる計算の制御、特殊化、または簡素化には役立ちません。ただし、これによって、不変および空のスプリッテレータ・インスタンス(Spliterators.emptySpliterator()を参照)を空のコレクションに共同利用できるようになり、そのようなスプリッテレータが適用される要素がないかどうかをクライアントが判定できるようになります。

戻り値:

このコレクション内の要素に対するSpliterator

導入されたバージョン:

1.8

stream

default Stream<E> stream()

このコレクションをソースとして使用して、逐次的なStreamを返します。

このメソッドは、IMMUTABLE、CONCURRENT、または遅延バインディングであるスプリッテレータをspliterator()メソッドが返せない場合にオーバーライドされるべきです。(詳細はspliterator()を参照。)

実装要件:

デフォルトの実装では、コレクションのSpliteratorから順次Streamを作成します。

戻り値:

このコレクション内の要素に対する順次Stream

導入されたバージョン:

1.8

parallelStream

default Stream<E> parallelStream()

このコレクションをソースとして、潜在的に並列のStreamを返します。このメソッドは順次ストリームを返すことができます。

このメソッドは、IMMUTABLE、CONCURRENT、または遅延バインディングであるスプリッテレータをspliterator()メソッドが返せない場合にオーバーライドされるべきです。(詳細はspliterator()を参照。)

実装要件:

デフォルトの実装では、コレクションのSpliteratorから並列Streamを作成します。

戻り値:

このコレクション内の要素に対する、並列の可能性のあるStream

導入されたバージョン:

1.8