+ *
+ * Summary of Queue methods
*
* |
- * Throws exception |
- * Returns special value |
+ * Throws exception |
+ * Returns special value |
*
*
* | Insert |
- * {@link #add add(e)} |
- * {@link #offer offer(e)} |
+ * {@link #add(Object) add(e)} |
+ * {@link #offer(Object) offer(e)} |
*
*
* | Remove |
- * {@link #remove remove()} |
- * {@link #poll poll()} |
+ * {@link #remove() remove()} |
+ * {@link #poll() poll()} |
*
*
* | Examine |
- * {@link #element element()} |
- * {@link #peek peek()} |
+ * {@link #element() element()} |
+ * {@link #peek() peek()} |
*
*
*
@@ -47,17 +47,17 @@ package java.util;
* 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 head of the queue is that
- * element which would be removed by a call to {@link #remove() } or
+ * 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 tail of the queue. Other kinds of queues may use
- * different placement rules. Every Queue implementation
+ * the tail of the queue. Other kinds of queues may use
+ * different placement rules. Every {@code Queue} implementation
* must specify its ordering properties.
*
* The {@link #offer offer} method inserts an element if possible,
- * otherwise returning false. This differs from the {@link
+ * otherwise returning {@code false}. This differs from the {@link
* java.util.Collection#add Collection.add} method, which can fail to
* add an element only by throwing an unchecked exception. The
- * offer method is designed for use when failure is a normal,
+ * {@code offer} method is designed for use when failure is a normal,
* rather than exceptional occurrence, for example, in fixed-capacity
* (or "bounded") queues.
*
@@ -65,102 +65,115 @@ package java.util;
* 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 remove() and
- * poll() methods differ only in their behavior when the
- * queue is empty: the remove() method throws an exception,
- * while the poll() method returns null.
+ * 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}.
*
*
The {@link #element()} and {@link #peek()} methods return, but do
* not remove, the head of the queue.
*
- *
The Queue interface does not define the blocking queue
+ *
The {@code Queue} interface does not define the blocking queue
* methods, 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 java.util.concurrent.BlockingQueue} interface, which
* extends this interface.
*
- *
Queue implementations generally do not allow insertion
- * of null elements, although some implementations, such as
- * {@link LinkedList}, do not prohibit insertion of null.
- * Even in the implementations that permit it, null should
- * not be inserted into a Queue, as null is also
- * used as a special return value by the poll method to
+ *
{@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.
*
- *
Queue implementations generally do not define
- * element-based versions of methods equals and
- * hashCode but instead inherit the identity based versions
- * from class Object, because element-based equality is not
+ *
{@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.
*
- *
*
This interface is a member of the
- *
+ *
* Java Collections Framework.
*
- * @see java.util.Collection
- * @see LinkedList
- * @see PriorityQueue
- * @see java.util.concurrent.LinkedBlockingQueue
- * @see java.util.concurrent.BlockingQueue
- * @see java.util.concurrent.ArrayBlockingQueue
- * @see java.util.concurrent.LinkedBlockingQueue
- * @see java.util.concurrent.PriorityBlockingQueue
* @since 1.5
* @author Doug Lea
- * @param the type of elements held in this collection
+ * @param the type of elements held in this queue
*/
public interface Queue extends Collection {
-
/**
- * Inserts the specified element into this queue, if possible. When
- * using queues that may impose insertion restrictions (for
- * example capacity bounds), method offer is generally
- * preferable to method {@link Collection#add}, which can fail to
- * insert an element only by throwing an exception.
+ * 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.
*
- * @param o the element to insert.
- * @return true if it was possible to add the element to
- * this queue, else false
+ * @param e the element to add
+ * @return {@code true} (as specified by {@link Collection#add})
+ * @throws IllegalStateException if the element cannot be added at this
+ * time due to capacity restrictions
+ * @throws ClassCastException if the class of the specified element
+ * prevents it from being added to this queue
+ * @throws NullPointerException if the specified element is null and
+ * this queue does not permit null elements
+ * @throws IllegalArgumentException if some property of this element
+ * prevents it from being added to this queue
*/
- boolean offer(E o);
+ boolean add(E e);
/**
- * Retrieves and removes the head of this queue, or null
- * 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.
*
- * @return the head of this queue, or null if this
- * queue is empty.
+ * @param e the element to add
+ * @return {@code true} if the element was added to this queue, else
+ * {@code false}
+ * @throws ClassCastException if the class of the specified element
+ * prevents it from being added to this queue
+ * @throws NullPointerException if the specified element is null and
+ * this queue does not permit null elements
+ * @throws IllegalArgumentException if some property of this element
+ * prevents it from being added to this queue
*/
- E poll();
+ boolean offer(E e);
/**
- * Retrieves and removes the head of this queue. This method
- * differs from the poll method in that it throws an
- * exception 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.
*
- * @return the head of this queue.
- * @throws NoSuchElementException if this queue is empty.
+ * @return the head of this queue
+ * @throws NoSuchElementException if this queue is empty
*/
E remove();
/**
- * Retrieves, but does not remove, the head of this queue,
- * returning null if this queue is empty.
+ * Retrieves and removes the head of this queue,
+ * or returns {@code null} if this queue is empty.
*
- * @return the head of this queue, or null if this queue
- * is empty.
+ * @return the head of this queue, or {@code null} if this queue is empty
*/
- E peek();
+ E poll();
/**
* Retrieves, but does not remove, the head of this queue. This method
- * differs from the peek method only in that it throws an
- * exception if this queue is empty.
+ * differs from {@link #peek peek} only in that it throws an exception
+ * if this queue is empty.
*
- * @return the head of this queue.
- * @throws NoSuchElementException if this queue is empty.
+ * @return the head of this queue
+ * @throws NoSuchElementException if this queue is empty
*/
E element();
+
+ /**
+ * Retrieves, but does not remove, the head of this queue,
+ * or returns {@code null} if this queue is empty.
+ *
+ * @return the head of this queue, or {@code null} if this queue is empty
+ */
+ E peek();
}