--- jsr166/src/main/java/util/Queue.java 2004/11/21 01:40:39 1.23 +++ jsr166/src/main/java/util/Queue.java 2004/12/26 20:13:57 1.24 @@ -8,32 +8,38 @@ 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. The names - * of the operations vary with their policies: + * 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. * - *
Operation | - *Attempt | - *Throw | + *+ * | Throws exception | + *Returns special value | *
insert | - *offer(x) | - *add(x) | + *Insert | + *{@link #add add(e)} | + *{@link #offer offer(e)} | *
extract | - *poll() | - *remove() | + *Remove | + *{@link #remove remove()} | + *{@link #poll poll()} | *
inspect | - *peek() | - *element() | + *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