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

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.

Методы

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 если эта очередь пуста