--- jsr166/src/main/java/util/Queue.java 2003/09/12 15:38:26 1.17
+++ jsr166/src/main/java/util/Queue.java 2004/11/21 01:40:39 1.23
@@ -1,7 +1,7 @@
/*
* 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;
@@ -9,7 +9,31 @@ 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.
+ * additional insertion, extraction, and inspection operations. The names
+ * of the operations vary with their policies:
+ *
+ *
+ *
+ * Operation |
+ * Attempt |
+ * Throw |
+ *
+ *
+ * insert |
+ * offer(x) |
+ * add(x) |
+ *
+ *
+ * extract |
+ * poll() |
+ * remove() |
+ *
+ *
+ * inspect |
+ * peek() |
+ * element() |
+ *
+ *
*
* Queues typically, but do not necessarily, order elements in a
* FIFO (first-in-first-out) manner. Among the exceptions are
@@ -79,11 +103,12 @@ package java.util;
* @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 {
/**
- * Inserts the specified element to this queue, if possible. When
+ * 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
@@ -96,7 +121,8 @@ public interface Queue extends Collec
boolean offer(E o);
/**
- * Retrieves and removes 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.
@@ -104,10 +130,9 @@ public interface Queue extends Collec
E poll();
/**
- * 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 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.
@@ -115,12 +140,11 @@ public interface Queue extends Collec
E remove();
/**
- * Retrieves, but does 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();