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

Параметры типа:: E - тип элементов, хранящихся в очереди

Все суперинтерфейсы:: Collection<E>, Iterable<E>

Все известные подинтерфейсы:: BlockingDeque<E>, BlockingQueue<E>, Deque<E>, TransferQueue<E>

Все известные реализующие классы:: AbstractQueue, ArrayBlockingQueue, ArrayDeque, ConcurrentLinkedDeque, ConcurrentLinkedQueue, DelayQueue, LinkedBlockingDeque, LinkedBlockingQueue, LinkedList, LinkedTransferQueue, PriorityBlockingQueue, PriorityQueue, SynchronousQueue

public interface Queue<E>
extends Collection<E>

Коллекция, предназначенная для хранения элементов до обработки. Помимо основных Collection операций, очереди предоставляют дополнительные операции вставки, извлечения и проверки. Каждая из этих операций существует в двух формах: одна выбрасывает исключение, если операция завершается неудачно, а другая возвращает специальное значение (либо null, либо false, в зависимости от операции). Последняя форма операции вставки специально разработана для использования с ограниченными по емкости Queue реализациями; в большинстве реализаций операции вставки не могут завершиться неудачно.

	Выбрасывает исключение	Возвращает специальное значение
Вставка	`add(e)`	`offer(e)`
Удаление	`remove()`	`poll()`
Просмотр	`element()`	`peek()`

Очереди обычно, но не обязательно, упорядочивают элементы в порядке FIFO (первым вошел — первым вышел). К исключениям относятся очереди с приоритетами, которые упорядочивают элементы в соответствии с предоставленным компаратором или естественным порядком элементов, и очереди LIFO (или стеки), которые упорядочивают элементы в порядке LIFO (последним вошел — первым вышел). Какой бы порядок ни использовался, голова очереди — это тот элемент, который будет удален при вызове remove() или poll(). В очереди FIFO все новые элементы вставляются в хвост очереди. Другие типы очередей могут использовать разные правила размещения. Каждая Queue реализация должна указывать свои свойства упорядочения.

Метод offer вставляет элемент, если это возможно, в противном случае возвращает false. Это отличается от метода Collection.add, который может не добавить элемент только путем выброса необработанного исключения. Метод offer предназначен для использования, когда ошибка является обычным, а не исключительным случаем, например, в очередях с фиксированной емкостью (или «ограниченной»).

Методы remove() и poll() удаляют и возвращают голову очереди. Точно какой элемент удаляется из очереди, является функцией политики упорядочения очереди, которая отличается от реализации к реализации. Методы remove() и poll() отличаются только своим поведением при пустой очереди: метод remove() выбрасывает исключение, а метод poll() возвращает null.

Методы element() и peek() возвращают, но не удаляют, голову очереди.

Интерфейс Queue не определяет блокирующие методы очереди, которые являются распространенными в параллельном программировании. Эти методы, которые ожидают появления элементов или освобождения места, определены в интерфейсе BlockingQueue, который расширяет этот интерфейс.

Queue реализации обычно не допускают вставки null элементов, хотя некоторые реализации, такие как LinkedList, не запрещают вставку null. Даже в тех реализациях, которые это допускают, null не следует вставлять в Queue, так как null также используется как специальное возвращаемое значение методом poll для обозначения того, что очередь не содержит элементов.

Queue реализации обычно не определяют версий методов, основанных на элементах, equals и hashCode, а вместо этого наследуют основанные на идентичности версии из класса Object, потому что основанная на элементах эквивалентность не всегда хорошо определена для очередей с одинаковыми элементами, но разными свойствами упорядочения.

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

С момента:: 1.5

Методы

Модификатор и тип	Метод	Описание
`boolean`	`add(E e)`	Вставляет указанный элемент в эту очередь, если это возможно сделать немедленно, не нарушая ограничений по емкости, возвращая `true` при успехе и выбрасывая `IllegalStateException` при отсутствии свободного места.
`E`	`element()`	Возвращает, но не удаляет, голову этой очереди.
`boolean`	`offer(E e)`	Вставляет указанный элемент в эту очередь, если это возможно сделать немедленно, не нарушая ограничений по емкости.
`E`	`peek()`	Возвращает, но не удаляет, голову этой очереди или возвращает `null` если эта очередь пуста.
`E`	`poll()`	Возвращает и удаляет голову этой очереди или возвращает `null` если эта очередь пуста.
`E`	`remove()`	Возвращает и удаляет голову этой очереди.

Методы, объявленные в интерфейсе java.util.Collection

addAll, clear, contains, containsAll, equals, hashCode, isEmpty, iterator, parallelStream, remove, removeAll, removeIf, retainAll, size, spliterator, stream, toArray, toArray, toArray

Методы, объявленные в интерфейсе java.lang.Iterable

forEach

Методы

add

boolean add(E e)

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

Определено в:: add в интерфейсе Collection<E>
Параметры:: e - добавляемый элемент
Возвращает:: true (как указано в Collection.add(E))
Исключения:: IllegalStateException - если элемент не может быть добавлен в данный момент из-за ограничений по емкости; ClassCastException - если класс указанного элемента препятствует его добавлению в эту очередь; NullPointerException - если указанный элемент имеет значение null, а эта очередь не допускает null элементов; IllegalArgumentException - если какие-либо свойства этого элемента препятствуют его добавлению в эту очередь

offer

boolean offer(E e)

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

Параметры:: e - добавляемый элемент
Возвращает:: true если элемент был добавлен в эту очередь, иначе false
Исключения:: ClassCastException - если класс указанного элемента препятствует его добавлению в эту очередь; NullPointerException - если указанный элемент имеет значение null, а эта очередь не допускает null элементов; IllegalArgumentException - если какие-либо свойства этого элемента препятствуют его добавлению в эту очередь

remove

E remove()

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

Возвращает:: голова этой очереди
Исключения:: NoSuchElementException - если эта очередь пуста

poll

E poll()

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

Возвращает:: голова этой очереди или null если эта очередь пуста

element

E element()

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

Возвращает:: голова этой очереди
Исключения:: NoSuchElementException - если эта очередь пуста

peek

E peek()

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

Возвращает:: голова этой очереди или null если эта очередь пуста