E
- このコレクション内の要素の型public interface Collection<E> extends Iterable<E>
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
の実装に特定の同期プロトコルが含まれている場合は、デフォルトの実装をオーバーライドしてそのプロトコルを適用する必要があります。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)
このコレクション内のすべての要素を保持する配列を返します。返される配列の実行時の型は、指定された配列の型です。
|
int size()
boolean isEmpty()
boolean contains(Object o)
o
- このコレクション内にあるかどうかが判定される要素ClassCastException
- 指定された要素の型が、このコレクションと互換でない場合(オプション)NullPointerException
- 指定された要素がnullで、このコレクションがnull要素を許可しない場合(オプション)Iterator<E> iterator()
Object[] toArray()
返される配列への参照をコレクションが維持しないという点で、この配列は安全です。つまり、このメソッドは、コレクションが配列に連動している場合でも新しい配列を割り当てます。このため、呼出し側は、返された配列を自由に変更できます。
このメソッドは、配列ベースのAPIとコレクションベースのAPIの間の橋渡し役として機能します。
<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である場合boolean add(E e)
このオペレーションをサポートするコレクションでは、コレクションに追加できる要素について制限がある場合があります。たとえば、コレクションによっては、null要素の追加が許可されないことや、追加される要素の型を制限することがあります。追加される要素に関して制限がある場合は、そのCollectionクラスのドキュメントに明示すべきでしょう。
その要素がすでにあるという以外の理由で特定の要素の追加を拒否する場合、コレクションはfalseを返すのではなく例外をスローする必要があります。これにより、この呼出しが戻ったあとにコレクションが指定された要素を必ず格納するという不変性を保つことができます。
e
- このコレクションにあるかどうかを調べる要素UnsupportedOperationException
- addオペレーションがこのコレクションでサポートされない場合ClassCastException
- 指定された要素のクラスが原因で、このコレクションにその要素を追加できない場合NullPointerException
- 指定された要素がnullで、このコレクションがnull要素を許可しない場合IllegalArgumentException
- 要素のあるプロパティが原因で、このコレクションに要素を追加できない場合IllegalStateException
- 挿入制限のため、この時点で要素を追加できない場合boolean remove(Object o)
o
- このコレクションから削除される要素(その要素が存在する場合)ClassCastException
- 指定された要素の型が、このコレクションと互換でない場合(オプション)NullPointerException
- 指定された要素がnullで、このコレクションがnull要素を許可しない場合(オプション)UnsupportedOperationException
- removeオペレーションがこのコレクションでサポートされない場合boolean containsAll(Collection<?> c)
c
- このコレクションにあるかどうかを調べるコレクションClassCastException
- 指定されたコレクションの1つ以上の要素の型が、このコレクションと互換でない場合(オプション)NullPointerException
- 指定されたコレクションに1つ以上のnull要素が含まれており、このコレクションがnull要素を許可しない場合(オプション)、または指定されたコレクションがnullの場合。contains(Object)
boolean addAll(Collection<? extends E> c)
c
- このコレクションに追加される要素を含むコレクションUnsupportedOperationException
- addAllオペレーションがこのコレクションでサポートされない場合ClassCastException
- 指定されたコレクションの要素のクラスが原因で、このコレクションにその要素を追加できない場合NullPointerException
- 指定されたコレクション内にnull要素が含まれ、このコレクションがnull要素を許可しない場合。または指定されたコレクションがnullの場合IllegalArgumentException
- 指定されたコレクションの要素のあるプロパティが原因で、このコレクションにその要素を追加できない場合IllegalStateException
- 挿入制限のため、この時点で一部の要素を追加できない場合add(Object)
boolean removeAll(Collection<?> c)
c
- このコレクションから削除される要素を含むコレクションUnsupportedOperationException
- removeAllメソッドがこのコレクションでサポートされない場合ClassCastException
- このコレクション内の1つ以上の要素の型が、指定されたコレクションと互換でない場合(オプション)NullPointerException
- このコレクションに1つ以上のnull要素が含まれており、指定されたコレクションがnull要素をサポートしない場合(オプション)、または指定されたコレクションがnullの場合remove(Object)
, contains(Object)
default boolean removeIf(Predicate<? super E> filter)
iterator()
を使用してコレクションのすべての要素をトラバースします。一致する各要素は、Iterator.remove()
を使って削除されます。コレクションのイテレータが削除をサポートしていない場合は、最初に一致する要素に対してUnsupportedOperationException
がスローされます。filter
- 削除される要素に対してtrue
を返す述語true
NullPointerException
- 指定されたフィルタがnullである場合UnsupportedOperationException
- このコレクションから要素を削除できない場合。一致する要素を削除できない場合、または一般的に削除がサポートされていない場合、実装によってこの例外がスローされることがあります。boolean retainAll(Collection<?> c)
c
- このコレクションで保持される要素を含むコレクションUnsupportedOperationException
- retainAllオペレーションがこのコレクションでサポートされない場合ClassCastException
- このコレクション内の1つ以上の要素の型が、指定されたコレクションと互換でない場合(オプション)NullPointerException
- このコレクションに1つ以上のnull要素が含まれており、指定されたコレクションがnull要素を許可しない場合(オプション)、または指定されたコレクションがnullの場合remove(Object)
, contains(Object)
void clear()
UnsupportedOperationException
- clearオペレーションがこのコレクションでサポートされない場合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
- このコレクションと等しいかどうかが比較されるオブジェクトObject.equals(Object)
, Set.equals(Object)
, List.equals(Object)
int hashCode()
hashCode
、クラス: Object
Object.hashCode()
, Object.equals(Object)
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
default Stream<E> stream()
Stream
を返します。
このメソッドは、IMMUTABLE
、CONCURRENT
、または遅延バインディングであるスプリッテレータをspliterator()
メソッドが返せない場合にオーバーライドされるべきです。(詳細はspliterator()
を参照。)
Spliterator
から順次Stream
を作成します。Stream
default Stream<E> parallelStream()
Stream
を返します。このメソッドは順次ストリームを返すことができます。
このメソッドは、IMMUTABLE
、CONCURRENT
、または遅延バインディングであるスプリッテレータをspliterator()
メソッドが返せない場合にオーバーライドされるべきです。(詳細はspliterator()
を参照。)
Spliterator
から並列Stream
を作成します。Stream
バグまたは機能を送信
詳細なAPIリファレンスおよび開発者ドキュメントについては、Java SEのドキュメントを参照してください。そのドキュメントには、概念的な概要、用語の定義、回避方法、有効なコード例などの、開発者を対象にしたより詳細な説明が含まれています。
Copyright © 1993, 2020, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. Documentation Redistribution Policyも参照してください。