java.util.concurrent
クラス PriorityBlockingQueue<E>

java.lang.Object
  java.util.AbstractCollection<E>
      java.util.AbstractQueue<E>
          java.util.concurrent.PriorityBlockingQueue<E>

型パラメータ:

E - コレクション内に存在する要素の型

すべての実装されたインタフェース:

Serializable, Iterable<E>, Collection<E>, BlockingQueue<E>, Queue<E>

public class PriorityBlockingQueue<E>
extends AbstractQueue<E>
implements BlockingQueue<E>, Serializable

PriorityQueue クラスと同じ順序付けルールを使用し、ブロックする取得オペレーションを提供する、アンバウンド形式のブロッキングキューです。このキューは論理的にはアンバウンド形式ですが、追加を試みてもリソース不足により OutOfMemoryError が発生して失敗することがあります。このクラスは、null 要素を許容しません。Comparable の自然順序付けに基づく優先度キューでは、比較不可能なオブジェクトの挿入も許可されません (実行すると ClassCastException がスローされる)。

このクラスとその反復子は、Collection および Iterator インタフェースの「オプション」メソッドすべてを実装します。iterator() メソッド内で提供される Iterator では、特定の順序で PriorityBlockingQueue の要素をトラバースすることは保証されません。要素をトラバースする順序を指定する必要がある場合は、Arrays.sort(pq.toArray()) の使用を考慮してください。また、drainTo メソッドを使用して、優先順位順に一部またはすべての要素を削除して、それらを別のコレクションに配置することもできます。

このクラスのオペレーションでは、優先順位が同じ要素の順序付けについて保証がありません。順序付けを適用する必要がある場合は、カスタムのクラスまたはコンパレータを定義して、第 1 の優先順位値が同じ場合に順序付けするために第 2 のキーを使用することができます。たとえば次のクラスでは、比較可能な要素に対して要素の優先順位が同じ場合は、先入れ先出し方式の順序付けを適用します。このクラスを使用するには、通常のエントリオブジェクトの代わりに new FIFOEntry(anEntry) を挿入します。

 class FIFOEntry<E extends Comparable<? super E>>
     implements Comparable<FIFOEntry<E>> {
   final static AtomicLong seq = new AtomicLong();
   final long seqNum;
   final E entry;
   public FIFOEntry(E entry) {
     seqNum = seq.getAndIncrement();
     this.entry = entry;
   }
   public E getEntry() { return entry; }
   public int compareTo(FIFOEntry<E> other) {
     int res = entry.compareTo(other.entry);
     if (res == 0 && other.entry != this.entry)
       res = (seqNum < other.seqNum ? -1 : 1);
     return res;
   }
 }

このクラスは、Java Collections Framework のメンバーです。

導入されたバージョン:

1.5

関連項目:

直列化された形式

コンストラクタの概要

PriorityBlockingQueue()
Comparable の自然順序付けに従って要素を順序付けするデフォルトの初期容量 (11) を使用して、PriorityBlockingQueue を作成します。

PriorityBlockingQueue(Collection<? extends E> c)
指定されたコレクション内の要素を含む PriorityBlockingQueue を作成します。

PriorityBlockingQueue(int initialCapacity)
Comparable の自然順序付けに従って要素を順序付けする、指定された初期容量を持つ PriorityBlockingQueue を作成します。

PriorityBlockingQueue(int initialCapacity, Comparator<? super E> comparator)
指定されたコンパレータに従って要素を順序付けする、指定された初期容量を持つ PriorityBlockingQueue を作成します。

メソッドの概要

boolean	add(E e) 指定された要素をこの優先度キューに挿入します。
void	clear() すべての要素をこのキューから原子的に削除します。
Comparator<? super E>	comparator() このキュー内の要素を順序付けするのに使うコンパレータを返します。
boolean	contains(Object o) このキューに指定された要素が含まれている場合に true を返します。
int	drainTo(Collection<? super E> c) このキューから利用可能なすべての要素を削除し、それらを指定されたコレクションに追加します。
int	drainTo(Collection<? super E> c, int maxElements) 指定された数以内の利用可能な要素をこのキューから削除し、指定されたコレクションに追加します。
Iterator<E>	iterator() このキュー内の要素の反復子を返します。
boolean	offer(E e) 指定された要素をこの優先度キューに挿入します。
boolean	offer(E e, long timeout, TimeUnit unit) 指定された要素をこの優先度キューに挿入します。
E	peek() キューの先頭を取得しますが、削除しません。
E	poll() キューの先頭を取得および削除します。
E	poll(long timeout, TimeUnit unit) このキューの先頭を取得して削除します。
void	put(E e) 指定された要素をこの優先度キューに挿入します。
int	remainingCapacity() PriorityBlockingQueue は容量制約を受けないため、常に Integer.MAX_VALUE を返します。
boolean	remove(Object o) 指定された要素の単一のインスタンスがこのキューに存在する場合は、キューから削除します。
int	size() このコレクション中の要素の数を返します。
E	take() このキューの先頭を取得して削除します。
Object[]	toArray() このキューの要素がすべて含まれている配列を返します。
<T> T[]	toArray(T[] a) このキュー内のすべての要素を含む配列を返します。
String	toString() このコレクションの文字列表現を返します。

クラス java.util.AbstractQueue から継承されたメソッド

addAll, element, remove

クラス java.util.AbstractCollection から継承されたメソッド

containsAll, isEmpty, removeAll, retainAll

クラス java.lang.Object から継承されたメソッド

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

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

element, remove

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

addAll, containsAll, equals, hashCode, isEmpty, removeAll, retainAll

コンストラクタの詳細

PriorityBlockingQueue

public PriorityBlockingQueue()

Comparable の自然順序付けに従って要素を順序付けするデフォルトの初期容量 (11) を使用して、PriorityBlockingQueue を作成します。

PriorityBlockingQueue

public PriorityBlockingQueue(int initialCapacity)

Comparable の自然順序付けに従って要素を順序付けする、指定された初期容量を持つ PriorityBlockingQueue を作成します。

パラメータ:

initialCapacity - この優先度キューの初期容量

例外:

IllegalArgumentException - initialCapacity が 1 未満の場合

PriorityBlockingQueue

public PriorityBlockingQueue(int initialCapacity,
                             Comparator<? super E> comparator)

指定されたコンパレータに従って要素を順序付けする、指定された初期容量を持つ PriorityBlockingQueue を作成します。

パラメータ:

initialCapacity - この優先度キューの初期容量

comparator - この優先度キューを順序付けするために使用されるコンパレータ。 null の場合、要素のComparable の自然順序付けが使用される

例外:

IllegalArgumentException - initialCapacity が 1 未満の場合

PriorityBlockingQueue

public PriorityBlockingQueue(Collection<? extends E> c)

指定されたコレクション内の要素を含む PriorityBlockingQueue を作成します。指定されたコレクションが SortedSet または PriorityQueue である場合、この優先度キューの順序付けは、それと同じ順序付けに従って行われます。それ以外の場合、この優先度キューの順序付けは、その要素のComparable の自然順序付けに従って行われます。

パラメータ:

c - 要素が優先度キューに配置されるコレクション

例外:

ClassCastException - 指定されたコレクションの要素を優先度キューの順序付けに従って相互比較できない場合

NullPointerException - 指定されたコレクション、またはその要素のいずれかが null の場合

メソッドの詳細

add

public boolean add(E e)

指定された要素をこの優先度キューに挿入します。

定義:

インタフェース Collection<E> 内の add

定義:

インタフェース BlockingQueue<E> 内の add

定義:

インタフェース Queue<E> 内の add

オーバーライド:

クラス AbstractQueue<E> 内の add

パラメータ:

e - 追加する要素

戻り値:

true (Collection.add(E) で指定されているとおり)

例外:

ClassCastException - 指定された要素を、優先度キューに現在存在する要素と、優先度キューの順序付けに従って比較できない場合

NullPointerException - 指定された要素が null である場合

offer

public boolean offer(E e)

指定された要素をこの優先度キューに挿入します。

定義:

インタフェース BlockingQueue<E> 内の offer

定義:

インタフェース Queue<E> 内の offer

パラメータ:

e - 追加する要素

戻り値:

true (Queue.offer(E) で指定されているとおり)

例外:

ClassCastException - 指定された要素を、優先度キューに現在存在する要素と、優先度キューの順序付けに従って比較できない場合

NullPointerException - 指定された要素が null である場合

put

public void put(E e)

指定された要素をこの優先度キューに挿入します。キューがアンバウンド形式であるため、このメソッドはブロックを実行しません。

定義:

インタフェース BlockingQueue<E> 内の put

パラメータ:

e - 追加する要素

例外:

ClassCastException - 指定された要素を、優先度キューに現在存在する要素と、優先度キューの順序付けに従って比較できない場合

NullPointerException - 指定された要素が null である場合

offer

public boolean offer(E e,
                     long timeout,
                     TimeUnit unit)

指定された要素をこの優先度キューに挿入します。キューがアンバウンド形式であるため、このメソッドはブロックを実行しません。

定義:

インタフェース BlockingQueue<E> 内の offer

パラメータ:

e - 追加する要素

timeout - メソッドがブロックを実行することはないため、このパラメータは無視される

unit - メソッドがブロックを実行することはないため、このパラメータは無視される

戻り値:

true

例外:

ClassCastException - 指定された要素を、優先度キューに現在存在する要素と、優先度キューの順序付けに従って比較できない場合

NullPointerException - 指定された要素が null である場合

poll

public E poll()

インタフェース Queue の記述:

キューの先頭を取得および削除します。キューが空の場合は null を返します。

定義:

インタフェース Queue<E> 内の poll

戻り値:

キューの先頭。キューが空の場合は null

take

public E take()
       throws InterruptedException

インタフェース BlockingQueue の記述:

このキューの先頭を取得して削除します。必要に応じて、要素が利用可能になるまで待機します。

定義:

インタフェース BlockingQueue<E> 内の take

戻り値:

キューの先頭

例外:

InterruptedException - 待機中に割り込みが発生した場合

poll

public E poll(long timeout,
              TimeUnit unit)
       throws InterruptedException

インタフェース BlockingQueue の記述:

このキューの先頭を取得して削除します。必要に応じて、指定された待機時間まで要素が利用可能になるのを待機します。

定義:

インタフェース BlockingQueue<E> 内の poll

パラメータ:

timeout - 処理を中止するまでの待機時間。単位は unit

unit - timeout パラメータの解釈方法を決定する TimeUnit

戻り値:

このキューの先頭。空きが生じる前に指定された待機時間が経過した場合は null

例外:

InterruptedException - 待機中に割り込みが発生した場合

peek

public E peek()

インタフェース Queue の記述:

キューの先頭を取得しますが、削除しません。キューが空の場合は null を返します。

定義:

インタフェース Queue<E> 内の peek

戻り値:

キューの先頭。キューが空の場合は null

comparator

public Comparator<? super E> comparator()

このキュー内の要素を順序付けするのに使うコンパレータを返します。ただし、このキューがその要素のComparable の自然順序付けを使う場合は null を返します。

戻り値:

このキュー内の要素を順序付けするのに使うコンパレータ。ただし、このキューが要素の自然順序付けを使う場合は null

size

public int size()

インタフェース Collection の記述:

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

定義:

インタフェース Collection<E> 内の size

定義:

クラス AbstractCollection<E> 内の size

戻り値:

コレクションの要素数

remainingCapacity

public int remainingCapacity()

PriorityBlockingQueue は容量制約を受けないため、常に Integer.MAX_VALUE を返します。

定義:

インタフェース BlockingQueue<E> 内の remainingCapacity

戻り値:

Integer.MAX_VALUE

remove

public boolean remove(Object o)

指定された要素の単一のインスタンスがこのキューに存在する場合は、キューから削除します。つまり、o.equals(e) となる要素 e がこのキュー内に 1 つ以上含まれている場合に、その 1 つを削除します。このキューに指定された要素が含まれていた場合 (つまり、呼び出しの結果としてこのキューが変更された場合) にだけ、true を返します。

定義:

インタフェース Collection<E> 内の remove

定義:

インタフェース BlockingQueue<E> 内の remove

オーバーライド:

クラス AbstractCollection<E> 内の remove

パラメータ:

o - キューから削除される要素 (その要素が存在する場合)

戻り値:

この呼び出しの結果、このキューが変更された場合は true

contains

public boolean contains(Object o)

このキューに指定された要素が含まれている場合に true を返します。つまり、キューに o.equals(e) となる要素 e が 1 つ以上含まれている場合にだけ true を返します。

定義:

インタフェース Collection<E> 内の contains

定義:

インタフェース BlockingQueue<E> 内の contains

オーバーライド:

クラス AbstractCollection<E> 内の contains

パラメータ:

o - このキューに含まれているかどうかを調べるオブジェクト

戻り値:

指定された要素がこのキューに含まれている場合は true

toArray

public Object[] toArray()

このキューの要素がすべて含まれている配列を返します。返される配列の要素に特定の順序はありません。

返される配列への参照をこのキューが維持しないという点で、この配列は安全です。(つまり、このメソッドは新しい配列を割り当てる必要があります)。このため、呼び出し側は、返された配列を自由に変更できます。

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

定義:

インタフェース Collection<E> 内の toArray

オーバーライド:

クラス AbstractCollection<E> 内の toArray

戻り値:

キューのすべての要素が格納されている配列

toString

public String toString()

クラス AbstractCollection の記述:

このコレクションの文字列表現を返します。文字列表現は、コレクションの要素をその反復子が返した順に角括弧 ("[]") で囲んで示すリストです。隣接する要素は、文字 ", " (カンマと空白文字) によって区切られます。各要素は、String.valueOf(Object) を実行したかのように文字列に変換されます。

オーバーライド:

クラス AbstractCollection<E> 内の toString

戻り値:

このコレクションの文字列表現

drainTo

public int drainTo(Collection<? super E> c)

インタフェース BlockingQueue の記述:

このキューから利用可能なすべての要素を削除し、それらを指定されたコレクションに追加します。このオペレーションは、このキューを繰り返しポーリングする場合よりも効率的な場合があります。コレクション c に要素を追加しようとしたときに障害が発生すると、関連する例外のスロー時に、要素がこのキューとコレクションのいずれにも存在しない場合と、一方または両方に存在する場合があります。キューをそれ自体に排出しようとすると、IllegalArgumentException がスローされます。また、オペレーションの進行中に指定されたコレクションが変更された場合の、このオペレーションの動作は定義されていません。

定義:

インタフェース BlockingQueue<E> 内の drainTo

パラメータ:

c - 要素の転送先のコレクション

戻り値:

転送された要素の数

例外:

UnsupportedOperationException - 指定されたコレクションで追加の要素がサポートされていない場合

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

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

IllegalArgumentException - 指定されたコレクションがこのキューである場合、またはこのキューの要素のあるプロパティーが原因で指定されたコレクションに追加できない場合

drainTo

public int drainTo(Collection<? super E> c,
                   int maxElements)

インタフェース BlockingQueue の記述:

指定された数以内の利用可能な要素をこのキューから削除し、指定されたコレクションに追加します。コレクション c に要素を追加しようとしたときに障害が発生すると、関連する例外のスロー時に、要素がこのキューとコレクションのいずれにも存在しない場合と、一方または両方に存在する場合があります。キューをそれ自体に排出しようとすると、IllegalArgumentException がスローされます。また、オペレーションの進行中に指定されたコレクションが変更された場合の、このオペレーションの動作は定義されていません。

定義:

インタフェース BlockingQueue<E> 内の drainTo

パラメータ:

c - 要素の転送先のコレクション

maxElements - 転送する要素の最大数

戻り値:

転送された要素の数

例外:

UnsupportedOperationException - 指定されたコレクションで追加の要素がサポートされていない場合

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

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

IllegalArgumentException - 指定されたコレクションがこのキューである場合、またはこのキューの要素のあるプロパティーが原因で指定されたコレクションに追加できない場合

clear

public void clear()

すべての要素をこのキューから原子的に削除します。この呼び出しが戻ると、キューは空になります。

定義:

インタフェース Collection<E> 内の clear

オーバーライド:

クラス AbstractQueue<E> 内の clear

toArray

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

このキュー内のすべての要素を含む配列を返します。返される配列の実行時の型は、指定された配列の型です。返される配列の要素に特定の順序はありません。キューが指定された配列に収まる場合は、その中に返されます。そうでない場合は、指定された配列の実行時の型とキューのサイズを持つ新しい配列が割り当てられます。

キューが指定された配列に収まり、その配列にさらに余裕がある場合 (つまり、配列がキューより多くの要素を持つ場合)、その配列内でキューの終端よりあとの要素は null に設定されます。

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

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

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

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

定義:

インタフェース Collection<E> 内の toArray

オーバーライド:

クラス AbstractCollection<E> 内の toArray

パラメータ:

a - 配列が十分な大きさを持つ場合は、キューの要素が格納される配列。そうでない場合は、要素を格納するために同じ実行時の型の新しい配列が割り当てられる

戻り値:

キューのすべての要素が格納されている配列

例外:

ArrayStoreException - 指定された配列の実行時の型が、このキュー内のすべての要素の実行時の型のスーパータイプでない場合

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

iterator

public Iterator<E> iterator()

このキュー内の要素の反復子を返します。反復子が要素を返す特定の順序はありません。返される Iterator は「弱一貫性」を持つ反復子であり、ConcurrentModificationException をスローすることはなく、反復子の構築時に存在した要素をトラバースすることを保証します。また、構築後のすべての変更を反映します (ただし保証されてはいない)。

定義:

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

定義:

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

定義:

クラス AbstractCollection<E> 内の iterator

戻り値:

キュー内の要素の反復子