Интерфейс BlockingDeque<E>

public interface BlockingDeque<E>
extends BlockingQueue<E>, Deque<E>

Двусторонняя очередь (Deque), дополнительно поддерживающая блокирующие операции, которые ожидают, пока очередь не станет непустой при получении элемента, и ожидают, пока место не освободится в очереди при сохранении элемента.

BlockingDeque методы представлены в четырёх формах с различными способами обработки операций, которые не могут быть удовлетворены немедленно, но могут быть удовлетворены в какой-то момент в будущем: один выбрасывает исключение, второй возвращает специальное значение (либо null или false, в зависимости от операции), третий блокирует текущий поток неопределённо долго, пока операция не сможет выполниться успешно, а четвёртый блокирует на заданный максимальный лимит времени, прежде чем отказаться. Эти методы обобщены в следующей таблице:

Первый элемент (голова)
	Выбрасывает исключение	Специальное значение	Блокирует	Таймаут
Вставка	addFirst(e)	offerFirst(e)	putFirst(e)	offerFirst(e, time, unit)
Удаление	removeFirst()	pollFirst()	takeFirst()	pollFirst(time, unit)
Просмотр	getFirst()	peekFirst()	не применяется	не применяется
Последний элемент (хвост)
	Выбрасывает исключение	Специальное значение	Блокирует	Таймаут
Вставка	addLast(e)	offerLast(e)	putLast(e)	offerLast(e, time, unit)
Удаление	removeLast()	pollLast()	takeLast()	pollLast(time, unit)
Просмотр	getLast()	peekLast()	не применяется	не применяется

Как и любая BlockingQueue, BlockingDeque потокобезопасна, не допускает нулевых элементов и может (или может не) иметь ограничение по емкости.

Реализация BlockingDeque может использоваться непосредственно как FIFO BlockingQueue. Методы, унаследованные от интерфейса BlockingQueue, точно эквивалентны BlockingDeque методам, как указано в следующей таблице:

BlockingQueue Метод	Эквивалентный BlockingDeque Метод
Вставка
add(e)	addLast(e)
offer(e)	offerLast(e)
put(e)	putLast(e)
offer(e, time, unit)	offerLast(e, time, unit)
Удаление
remove()	removeFirst()
poll()	pollFirst()
take()	takeFirst()
poll(time, unit)	pollFirst(time, unit)
Просмотр
element()	getFirst()
peek()	peekFirst()

Эффекты согласованности памяти: Как и в других конкурентных коллекциях, действия в потоке до размещения объекта в BlockingDeque происходят до действий, последующих за доступом или удалением этого элемента из BlockingDeque в другом потоке.

Этот интерфейс является частью Java Collections Framework.

Методы

addFirst

void addFirst(E e)

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

Указано в:

addFirst в интерфейсе Deque<E>

Параметры:

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

Исключения:

IllegalStateException - если элемент не может быть добавлен в данный момент из-за ограничений по емкости

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

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

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

addLast

void addLast(E e)

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

Указано в:

addLast в интерфейсе Deque<E>

Параметры:

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

Исключения:

IllegalStateException - если элемент не может быть добавлен в данный момент из-за ограничений по емкости

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

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

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

offerFirst

boolean offerFirst(E e)

Вставляет указанный элемент в начало очереди, если это возможно сделать немедленно без нарушения ограничений по емкости, возвращая true при успехе и false если места нет. При использовании очереди с ограниченной емкостью, этот метод обычно предпочтительнее метода addFirst, который может не вставить элемент, только выбросив исключение.

Указано в:

offerFirst в интерфейсе Deque<E>

Параметры:

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

Возвращает:

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

Исключения:

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

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

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

offerLast

boolean offerLast(E e)

Вставляет указанный элемент в конец очереди, если это возможно сделать немедленно без нарушения ограничений по емкости, возвращая true при успехе и false если места нет. При использовании очереди с ограниченной емкостью, этот метод обычно предпочтительнее метода addLast, который может не вставить элемент, только выбросив исключение.

Указано в:

offerLast в интерфейсе Deque<E>

Параметры:

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

Возвращает:

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

Исключения:

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

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

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

putFirst

void putFirst(E e)
       throws InterruptedException

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

Параметры:

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

Исключения:

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

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

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

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

putLast

void putLast(E e)
      throws InterruptedException

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

Параметры:

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

Исключения:

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

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

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

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

offerFirst

boolean offerFirst(E e,
                   long timeout,
                   TimeUnit unit)
            throws InterruptedException

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

Параметры:

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

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

unit - единица TimeUnit, определяющая интерпретацию параметра timeout

Возвращает:

true в случае успеха, или false если указанное время ожидания истекло до освобождения места

Исключения:

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

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

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

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

offerLast

boolean offerLast(E e,
                  long timeout,
                  TimeUnit unit)
           throws InterruptedException

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

Параметры:

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

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

unit - единица TimeUnit, определяющая интерпретацию параметра timeout

Возвращает:

true в случае успеха, или false если указанное время ожидания истекло до освобождения места

Исключения:

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

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

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

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

takeFirst

E takeFirst()
     throws InterruptedException

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

Возвращает:

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

Исключения:

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

takeLast

E takeLast()
    throws InterruptedException

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

Возвращает:

хвост этой очереди

Исключения:

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

pollFirst

E pollFirst(long timeout,
            TimeUnit unit)
     throws InterruptedException

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

Параметры:

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

unit - единица TimeUnit, определяющая интерпретацию параметра timeout

Возвращает:

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

Исключения:

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

pollLast

E pollLast(long timeout,
           TimeUnit unit)
    throws InterruptedException

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

Параметры:

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

unit - единица TimeUnit, определяющая интерпретацию параметра timeout

Возвращает:

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

Исключения:

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

removeFirstOccurrence

boolean removeFirstOccurrence(Object o)

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

Указано в:

removeFirstOccurrence в интерфейсе Deque<E>

Параметры:

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

Возвращает:

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

Исключения:

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

NullPointerException - если указанный элемент равен null (необязательно)

removeLastOccurrence

boolean removeLastOccurrence(Object o)

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

Указано в:

removeLastOccurrence в интерфейсе Deque<E>

Параметры:

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

Возвращает:

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

Исключения:

ClassCastException - если класс указанного элемента несовместим с этой декой (необязательно)

NullPointerException - если указанный элемент равен null (необязательно)

add

boolean add(E e)

Указано в:

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

Указано в:

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

Указано в:

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

Указано в:

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

Параметры:

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

Возвращает:

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

Исключения:

IllegalStateException - если элемент не может быть добавлен в данный момент из-за ограничений емкости

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

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

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

offer

boolean offer(E e)

Указано в:

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

Указано в:

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

Указано в:

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

Параметры:

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

Возвращает:

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

Исключения:

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

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

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

put

void put(E e)
  throws InterruptedException

Указано в:

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

Параметры:

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

Исключения:

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

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

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

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

offer

boolean offer(E e,
              long timeout,
              TimeUnit unit)
       throws InterruptedException

Указано в:

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

Параметры:

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

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

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

Возвращает:

true если элемент был добавлен в эту деку, иначе false

Исключения:

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

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

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

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

remove

E remove()

Указано в:

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

Указано в:

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

Возвращает:

головной элемент очереди, представленной этой декой

Исключения:

NoSuchElementException - если эта дека пуста

poll

E poll()

Указано в:

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

Указано в:

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

Возвращает:

головной элемент этой деки, или null, если эта дека пуста

take

E take()
throws InterruptedException

Указано в:

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

Возвращает:

головной элемент этой деки

Исключения:

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

poll

E poll(long timeout,
       TimeUnit unit)
throws InterruptedException

Указано в:

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

Параметры:

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

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

Возвращает:

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

Исключения:

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

element

E element()

Указано в:

element в интерфейсе Deque<E>

Указано в:

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

Возвращает:

головной элемент этой деки

Исключения:

NoSuchElementException - если эта дека пуста

peek

E peek()

Указано в:

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

Указано в:

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

Возвращает:

головной элемент этой деки, или null, если эта дека пуста

remove

boolean remove(Object o)

Определено в:

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

Определено в:

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

Определено в:

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

Параметры:

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

Возвращает:

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

Исключения:

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

NullPointerException - если указанный элемент равен null (необязательно)

contains

boolean contains(Object o)

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

Определено в:

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

Определено в:

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

Определено в:

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

Параметры:

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

Возвращает:

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

Исключения:

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

NullPointerException - если указанный элемент равен null (необязательно)

size

int size()

Возвращает количество элементов в этой очереди.

Определено в:

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

Определено в:

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

Возвращает:

количество элементов в этой очереди

iterator

Iterator<E> iterator()

Возвращает итератор по элементам в этой очереди в правильном порядке. Элементы будут возвращаться в порядке от первого (головы) до последнего (хвоста).

Определено в:

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

Определено в:

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

Определено в:

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

Возвращает:

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

push

void push(E e)

Определено в:

push в интерфейсе Deque<E>

Параметры:

e - элемент для помещения

Исключения:

IllegalStateException - если элемент не может быть добавлен в данный момент из-за ограничений по емкости

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

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

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