--- jsr166/src/main/java/util/Queue.java 2003/10/19 13:38:29 1.21
+++ jsr166/src/main/java/util/Queue.java 2004/12/26 20:13:57 1.24
@@ -1,15 +1,45 @@
/*
* 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