Класс PriorityBlockingQueue<E>

Неограниченная блокирующая очередь, которая использует те же правила упорядочивания, что и класс PriorityQueue и предоставляет блокирующие операции извлечения. Хотя эта очередь логически неограничена, попытки добавления могут завершиться неудачей из-за исчерпания ресурсов (приводя к OutOfMemoryError). Этот класс не допускает null элементов. Очередь с приоритетом, основанная на естественном порядке, также не допускает вставки несопоставимых объектов (что приводит к ClassCastException).

Этот класс и его итератор реализуют все необязательные методы интерфейсов Collection и Iterator. Итератор, предоставляемый методом iterator(), не гарантирует прохождение элементов PriorityBlockingQueue в каком-либо определённом порядке. Если вам нужен упорядоченный обход, рассмотрите использование Arrays.sort(pq.toArray()). Также метод drainTo может использоваться для удаления некоторых или всех элементов в порядке приоритета и размещения их в другой коллекции.

Операции над этим классом не гарантируют порядок элементов с одинаковым приоритетом. Если вам необходимо применить порядок, вы можете определить пользовательские классы или компараторы, которые используют вторичный ключ для разрыва ничьих в значениях первичного приоритета. Например, вот класс, который применяет порядок «первым пришёл, первым обслужен» для разрыва ничьих у сопоставимых элементов. Для его использования вы должны вставить new FIFOEntry(anEntry) вместо простого объекта записи.

class FIFOEntry<E extends Comparable<? super E>>
     implements Comparable<FIFOEntry<E>> {
   static final AtomicLong seq = new AtomicLong(0);
   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.

Конструкторы

PriorityBlockingQueue

public PriorityBlockingQueue()

Создаёт PriorityBlockingQueue с начальной ёмкостью по умолчанию (11), которая упорядочивает элементы в соответствии с их естественным порядком.

PriorityBlockingQueue

public PriorityBlockingQueue(int initialCapacity)

Создаёт PriorityBlockingQueue с заданной начальной ёмкостью, которая упорядочивает элементы в соответствии с их естественным порядком.

Параметры:

initialCapacity - начальная ёмкость этой очереди с приоритетами

Исключения:

IllegalArgumentException - если initialCapacity меньше 1

PriorityBlockingQueue

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

Создаёт PriorityBlockingQueue с заданной начальной ёмкостью, которая упорядочивает элементы в соответствии с указанным компаратором.

Параметры:

initialCapacity - начальная ёмкость этой очереди с приоритетами

comparator - компаратор, который будет использоваться для упорядочивания этой очереди с приоритетами. Если null, будет использован естественный порядок элементов.

Исключения:

IllegalArgumentException - если initialCapacity меньше 1

PriorityBlockingQueue

public PriorityBlockingQueue(Collection<? extends E> c)

Создаёт PriorityBlockingQueue, содержащую элементы из указанного набора. Если указанный набор является SortedSet или PriorityQueue, эта очередь с приоритетами будет упорядочена в соответствии с тем же порядком. В противном случае эта очередь с приоритетами будет упорядочена в соответствии с естественным порядком элементов.

Параметры:

c - набор, элементы которого должны быть помещены в эту очередь с приоритетами

Исключения:

ClassCastException - если элементы указанного набора нельзя сравнить друг с другом в соответствии с порядком очереди с приоритетами

NullPointerException - если указанный набор или любой из его элементов равен null

Методы

add

public boolean add(E e)

Вставляет указанный элемент в эту очередь с приоритетами.

Унаследованно от:

add в интерфейсе Collection<E>

Унаследованно от:

add в интерфейсе BlockingQueue<E>

Унаследованно от:

add в интерфейсе Queue<E>

Переопределяет:

add в классе AbstractQueue<E>

Параметры:

e - добавляемый элемент

Возвращает:

true (как указано в Collection.add(E))

Исключения:

ClassCastException - если указанный элемент нельзя сравнить с элементами, которые в данный момент находятся в очереди с приоритетами, в соответствии с порядком очереди

NullPointerException - если указанный элемент равен null

offer

public boolean offer(E e)

Вставляет указанный элемент в эту очередь с приоритетами. Так как очередь не имеет ограничений по размеру, этот метод никогда не вернёт false.

Унаследованно от:

offer в интерфейсе BlockingQueue<E>

Унаследованно от:

offer в интерфейсе Queue<E>

Параметры:

e - добавляемый элемент

Возвращает:

true (как указано в Queue.offer(E))

Исключения:

ClassCastException - если указанный элемент нельзя сравнить с элементами, которые в данный момент находятся в очереди с приоритетами, в соответствии с порядком очереди

NullPointerException - если указанный элемент равен null

put

public void put(E e)

Вставляет указанный элемент в эту очередь с приоритетами. Поскольку очередь не имеет ограничений по размеру, этот метод никогда не заблокируется.

Унаследованно от:

put в интерфейсе BlockingQueue<E>

Параметры:

e - добавляемый элемент

Исключения:

ClassCastException - если указанный элемент нельзя сравнить с элементами, которые в данный момент находятся в очереди с приоритетами, в соответствии с порядком очереди

NullPointerException - если указанный элемент равен null

offer

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

Вставляет указанный элемент в эту очередь с приоритетами. Так как очередь не имеет ограничений по размеру, этот метод никогда не заблокируется или не вернёт false.

Унаследованно от:

offer в интерфейсе BlockingQueue<E>

Параметры:

e - добавляемый элемент

timeout - Этот параметр игнорируется, так как метод никогда не блокируется

unit - Этот параметр игнорируется, так как метод никогда не блокируется

Возвращает:

true (как указано в BlockingQueue.offer)

Исключения:

ClassCastException - если указанный элемент нельзя сравнить с элементами, которые в данный момент находятся в очереди с приоритетами, в соответствии с порядком очереди

NullPointerException - если указанный элемент равен null

poll

public E poll()

Описание скопировано из интерфейса: Queue

Извлекает и удаляет голову этой очереди или возвращает null если эта очередь пустая.

Унаследованно от:

poll в интерфейсе Queue<E>

Возвращает:

голова этой очереди или null если эта очередь пустая

take

public E take()
       throws InterruptedException

Описание скопировано из интерфейса: BlockingQueue

Извлекает и удаляет голову этой очереди, ожидая, если необходимо, пока элемент станет доступным.

Унаследованно от:

take в интерфейсе BlockingQueue<E>

Возвращает:

голова этой очереди

Исключения:

InterruptedException - если прервано ожидание

poll

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

Описание скопировано из интерфейса: BlockingQueue

Извлекает и удаляет голову этой очереди, ожидая до указанного времени ожидания, если необходимо, чтобы элемент стал доступным.

Унаследованно от:

poll в интерфейсе BlockingQueue<E>

Параметры:

timeout - время ожидания, прежде чем отказаться, в единицах unit

unit - TimeUnit определяющий, как интерпретировать параметр timeout

Возвращает:

голова этой очереди или null если указанное время ожидания истекло, прежде чем элемент стал доступным

Исключения:

InterruptedException - если прервано ожидание

peek

public E peek()

Описание скопировано из интерфейса: Queue

Извлекает, но не удаляет, голову этой очереди или возвращает null если эта очередь пустая.

Унаследованно от:

peek в интерфейсе Queue<E>

Возвращает:

голова этой очереди или null если эта очередь пустая

comparator

public Comparator<? super E> comparator()

Возвращает компаратор, используемый для упорядочивания элементов в этой очереди, или null если эта очередь использует естественный порядок элементов.

Возвращает:

компаратор, используемый для упорядочивания элементов в этой очереди, или null если эта очередь использует естественный порядок элементов

size

public int size()

Описание скопировано из интерфейса: Collection

Возвращает количество элементов в этом наборе. Если этот набор содержит более Integer.MAX_VALUE элементов, возвращает Integer.MAX_VALUE.

Унаследованно от:

size в интерфейсе Collection<E>

Унаследованно от:

size в классе AbstractCollection<E>

Возвращает:

количество элементов в этом наборе

remainingCapacity

public int remainingCapacity()

Всегда возвращает Integer.MAX_VALUE потому что очередь с приоритетами не имеет ограничений по размеру.

Унаследованно от:

remainingCapacity в интерфейсе BlockingQueue<E>

Возвращает:

Integer.MAX_VALUE всегда

remove

public boolean remove(Object o)

Удаляет единственный экземпляр указанного элемента из этой очереди, если он присутствует. Более формально, удаляет элемент e такой, что o.equals(e), если эта очередь содержит один или несколько таких элементов. Возвращает true тогда и только тогда, когда эта очередь содержала указанный элемент (или, эквивалентно, если эта очередь изменилась в результате вызова).

Унаследованно от:

remove в интерфейсе Collection<E>

Унаследованно от:

remove в интерфейсе BlockingQueue<E>

Переопределяет:

remove в классе AbstractCollection<E>

Параметры:

o - элемент, который нужно удалить из этой очереди, если он присутствует

Возвращает:

true если эта очередь изменилась в результате вызова

contains

public boolean contains(Object o)

Возвращает true если эта очередь содержит указанный элемент. Более формально, возвращает true тогда и только тогда, когда эта очередь содержит по крайней мере один элемент e такой, что o.equals(e).

Унаследованно от:

contains в интерфейсе Collection<E>

Унаследованно от:

contains в интерфейсе BlockingQueue<E>

Переопределяет:

contains в классе AbstractCollection<E>

Параметры:

o - объект, который нужно проверить на наличие в этой очереди

Возвращает:

true если эта очередь содержит указанный элемент

toArray

public Object[] toArray()

Указано:

toArray в интерфейсе Collection<E>

Переопределяет:

toArray в классе AbstractCollection<E>

Возвращает:

массив, содержащий все элементы в этой очереди

toString

public String toString()

Описание скопировано из класса: AbstractCollection

Возвращает строковое представление этой коллекции. Строковое представление состоит из списка элементов коллекции в порядке, в котором они возвращаются её итератором, заключёнными в квадратные скобки ("[]"). Смежные элементы разделяются символами ", " (запятая и пробел). Элементы преобразуются в строки с помощью String.valueOf(Object).

Переопределяет:

toString в классе AbstractCollection<E>

Возвращает:

строковое представление этой коллекции

drainTo

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

Описание скопировано из интерфейса: BlockingQueue

Удаляет все доступные элементы из этой очереди и добавляет их в заданную коллекцию. Эта операция может быть более эффективной, чем многократное извлечение из этой очереди. Непредвиденная ошибка при попытке добавить элементы в коллекцию c может привести к тому, что элементы будут находиться ни в одной, ни в той, ни в другой, или в обеих коллекциях, когда будет брошено соответствующее исключение. Попытки слить очередь в саму себя приводят к IllegalArgumentException. Кроме того, поведение этой операции не определено, если заданная коллекция изменяется во время выполнения операции.

Указано:

drainTo в интерфейсе BlockingQueue<E>

Параметры:

c - коллекция для перемещения элементов

Возвращает:

количество перемещённых элементов

Исключения:

UnsupportedOperationException - если добавление элементов не поддерживается заданной коллекцией

ClassCastException - если класс элемента этой очереди препятствует его добавлению в заданную коллекцию

NullPointerException - если заданная коллекция равна null

IllegalArgumentException - если заданная коллекция является этой очередью, или какая-либо характеристика элемента этой очереди препятствует его добавлению в заданную коллекцию

drainTo

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

Описание скопировано из интерфейса: BlockingQueue

Удаляет не более заданного количества доступных элементов из этой очереди и добавляет их в заданную коллекцию. Непредвиденная ошибка при попытке добавить элементы в коллекцию c может привести к тому, что элементы будут находиться ни в одной, ни в той, ни в другой, или в обеих коллекциях, когда будет брошено соответствующее исключение. Попытки слить очередь в саму себя приводят к IllegalArgumentException. Кроме того, поведение этой операции не определено, если заданная коллекция изменяется во время выполнения операции.

Указано:

drainTo в интерфейсе BlockingQueue<E>

Параметры:

c - коллекция для перемещения элементов

maxElements - максимальное количество элементов для перемещения

Возвращает:

количество перемещённых элементов

Исключения:

UnsupportedOperationException - если добавление элементов не поддерживается заданной коллекцией

ClassCastException - если класс элемента этой очереди препятствует его добавлению в заданную коллекцию

NullPointerException - если заданная коллекция равна null

IllegalArgumentException - если заданная коллекция является этой очередью, или какая-либо характеристика элемента этой очереди препятствует его добавлению в заданную коллекцию

clear

public void clear()

Атомарно удаляет все элементы из этой очереди. Очередь будет пустой после возврата этого вызова.

Указано:

clear в интерфейсе Collection<E>

Переопределяет:

clear в классе AbstractQueue<E>

toArray

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

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

Указано:

toArray в интерфейсе Collection<E>

Переопределяет:

toArray в классе AbstractCollection<E>

Параметры типа:

T - тип выполнения массива для хранения коллекции

Параметры:

a - массив, в который должны быть помещены элементы очереди, если он достаточно велик; в противном случае для этой цели выделяется новый массив того же типа выполнения

Возвращает:

массив, содержащий все элементы в этой очереди

Исключения:

ArrayStoreException - если тип выполнения указанного массива не является супертипом типа выполнения каждого элемента в этой очереди

NullPointerException - если указанный массив равен null

iterator

public Iterator<E> iterator()

Указано:

iterator в интерфейсе Iterable<E>

Указано:

iterator в интерфейсе Collection<E>

Указано:

iterator в классе AbstractCollection<E>

Возвращает:

итератор по элементам в этой очереди

spliterator

public Spliterator<E> spliterator()

Указано:

spliterator в интерфейсе Iterable<E>

Указано:

spliterator в интерфейсе Collection<E>

Примечание реализации:

Spliterator дополнительно сообщает о Spliterator.SUBSIZED.

Возвращает:

Spliterator по элементам в этой очереди

С момента:

1.8