Inserts the specified element into this queue if it is possible to do so immediately without violating capacity restrictions, returning {@code true} upon success and throwing an {@code IllegalStateException} if no space is currently available.
Retrieves, but does not remove, the head of this queue. This method differs from {@link #peek peek} only in that it throws an exception if this queue is empty.
Inserts the specified element into this queue if it is possible to do so immediately without violating capacity restrictions. When using a capacity-restricted queue, this method is generally preferable to {@link #add}, which can fail to insert an element only by throwing an exception.
Retrieves, but does not remove, the head of this queue, or returns {@code null} if this queue is empty.
Retrieves and removes the head of this queue, or returns {@code null} if this queue is empty.
Retrieves and removes the head of this queue. This method differs from {@link #poll poll} only in that it throws an exception if this queue is empty.
<p>This interface is a member of the <a href="{@docRoot}/../technotes/guides/collections/index.html"> Java Collections Framework</a>.
@see hunt.collection.Collection @see LinkedList @see PriorityQueue @see hunt.concurrency.LinkedBlockingQueue @see hunt.concurrency.BlockingQueue @see hunt.concurrency.ArrayBlockingQueue @see hunt.concurrency.LinkedBlockingQueue @see hunt.concurrency.PriorityBlockingQueue @author Doug Lea @param !E the type of elements held in this collection
A collection designed for holding elements prior to processing. Besides basic {@link hunt.collection.Collection Collection} operations, queues provide additional insertion, extraction, and inspection operations. Each of these methods exists in two forms: one throws an exception if the operation fails, the other returns a special value (either {@code null} or {@code false}, depending on the operation). The latter form of the insert operation is designed specifically for use with capacity-restricted {@code Queue} implementations; in most implementations, insert operations cannot fail.
<table BORDER CELLPADDING=3 CELLSPACING=1> <caption>Summary of Queue methods</caption> <tr> <td></td> <td ALIGN=CENTER><em>Throws exception</em></td> <td ALIGN=CENTER><em>Returns special value</em></td> </tr> <tr> <td><b>Insert</b></td> <td>{@link Queue#add add(e)}</td> <td>{@link Queue#offer offer(e)}</td> </tr> <tr> <td><b>Remove</b></td> <td>{@link Queue#remove remove()}</td> <td>{@link Queue#poll poll()}</td> </tr> <tr> <td><b>Examine</b></td> <td>{@link Queue#element element()}</td> <td>{@link Queue#peek peek()}</td> </tr> </table>
<p>Queues typically, but do not necessarily, order elements in a FIFO (first-in-first-out) manner. Among the exceptions are priority queues, which order elements according to a supplied comparator, or the elements' natural ordering, and LIFO queues (or stacks) which order the elements LIFO (last-in-first-out). Whatever the ordering used, the <em>head</em> of the queue is that element which would be removed by a call to {@link #remove() } or {@link #poll()}. In a FIFO queue, all new elements are inserted at the <em>tail</em> of the queue. Other kinds of queues may use different placement rules. Every {@code Queue} implementation must specify its ordering properties.
<p>The {@link #offer offer} method inserts an element if possible, otherwise returning {@code false}. This differs from the {@link hunt.collection.Collection#add Collection.add} method, which can fail to add an element only by throwing an unchecked exception. The {@code offer} method is designed for use when failure is a normal, rather than exceptional occurrence, for example, in fixed-capacity (or "bounded") queues.
<p>The {@link #remove()} and {@link #poll()} methods remove and return the head of the queue. Exactly which element is removed from the queue is a function of the queue's ordering policy, which differs from implementation to implementation. The {@code remove()} and {@code poll()} methods differ only in their behavior when the queue is empty: the {@code remove()} method throws an exception, while the {@code poll()} method returns {@code null}.
<p>The {@link #element()} and {@link #peek()} methods return, but do not remove, the head of the queue.
<p>The {@code Queue} interface does not define the <i>blocking queue methods</i>, which are common in concurrent programming. These methods, which wait for elements to appear or for space to become available, are defined in the {@link hunt.concurrency.BlockingQueue} interface, which extends this interface.
<p>{@code Queue} implementations generally do not allow insertion of {@code null} elements, although some implementations, such as {@link LinkedList}, do not prohibit insertion of {@code null}. Even in the implementations that permit it, {@code null} should not be inserted into a {@code Queue}, as {@code null} is also used as a special return value by the {@code poll} method to indicate that the queue contains no elements.
<p>{@code Queue} implementations generally do not define element-based versions of methods {@code equals} and {@code hashCode} but instead inherit the identity based versions from class {@code Object}, because element-based equality is not always well-defined for queues with the same elements but different ordering properties.