--- jsr166/src/main/java/util/Queue.java 2003/07/31 19:49:42 1.11
+++ jsr166/src/main/java/util/Queue.java 2004/12/26 20:13:57 1.24
@@ -1,31 +1,65 @@
/*
* Written by Doug Lea with assistance from members of JCP JSR-166
- * Expert Group and released to the public domain. Use, modify, and
- * redistribute this code in any way without acknowledgement.
+ * Expert Group and released to the public domain, as explained at
+ * http://creativecommons.org/licenses/publicdomain
*/
package java.util;
/**
* A collection designed for holding elements prior to processing.
- * Besides basic {@link java.util.Collection Collection} operations, queues provide
- * additional insertion, extraction, and inspection operations.
+ * Besides basic {@link java.util.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 null or false, depending on the
+ * operation). The latter form of the insert operation is designed
+ * specifically for use with capacity-restricted Queue
+ * implementations; in most implementations, insert operations cannot
+ * fail.
+ *
+ *
+ *
+ * |
+ * Throws exception |
+ * Returns special value |
+ *
+ *
+ * | Insert |
+ * {@link #add add(e)} |
+ * {@link #offer offer(e)} |
+ *
+ *
+ * | Remove |
+ * {@link #remove remove()} |
+ * {@link #poll poll()} |
+ *
+ *
+ * | Examine |
+ * {@link #element element()} |
+ * {@link #peek peek()} |
+ *
+ *
*
* 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 head of the queue is that element
- * which would be removed by a call to {@link #remove() } or {@link #poll()}.
- * Every Queue implementation must specify its ordering guarantees.
- *
- *
The {@link #offer(E)} method adds an element if possible, otherwise
- * returning false. This differs from the {@link java.util.Collection#add Collection.add(E)}
- * method, which throws an unchecked exception upon
- * failure. It is designed for use in collections in which failure to
- * add is a normal, rather than exceptional occurrence, for example,
- * in fixed-capacity (or "bounded") queues.
+ * Whatever the ordering used, the head 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 tail of the queue. Other kinds of queues may use
+ * different placement rules. Every 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
+ * 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,
+ * rather than exceptional occurrence, for example, in fixed-capacity
+ * (or "bounded") queues.
*
*
The {@link #remove()} and {@link #poll()} methods remove and
* return the head of the queue.
@@ -53,6 +87,14 @@ package java.util;
* used as a special return value by the 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
+ * always well-defined for queues with the same elements but different
+ * ordering properties.
+ *
+ *
*
This interface is a member of the
*
* Java Collections Framework.
@@ -60,27 +102,33 @@ package java.util;
* @see java.util.Collection
* @see LinkedList
* @see PriorityQueue
- * @see java.util.concurrent.LinkedQueue
+ * @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
*/
public interface Queue extends Collection {
/**
- * Add the specified element to this queue, if possible.
+ * 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.
*
- * @param o the element to add.
+ * @param o the element to insert.
* @return true if it was possible to add the element to
* this queue, else false
*/
boolean offer(E o);
/**
- * Retrieve and remove the head of this queue, if it is available.
+ * Retrieves and removes the head of this queue, or null
+ * if this queue is empty.
*
* @return the head of this queue, or null if this
* queue is empty.
@@ -88,10 +136,9 @@ public interface Queue extends Collec
E poll();
/**
- * Retrieve and remove 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 the poll method in that it throws an
+ * exception if this queue is empty.
*
* @return the head of this queue.
* @throws NoSuchElementException if this queue is empty.
@@ -99,17 +146,16 @@ public interface Queue extends Collec
E remove();
/**
- * Retrieve, but do not remove, the head of this queue.
- * This method differs from the poll
- * method only in that this method does not remove the head element from
- * this queue.
+ * Retrieves, but does not remove, the head of this queue,
+ * returning 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 null if this queue
+ * is empty.
*/
E peek();
/**
- * Retrieve, but do not remove, the head of this queue. This method
+ * 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.
*
@@ -118,13 +164,3 @@ public interface Queue extends Collec
*/
E element();
}
-
-
-
-
-
-
-
-
-
-