--- jsr166/src/main/java/util/Queue.java	2003/08/04 01:54:13	1.13
+++ jsr166/src/main/java/util/Queue.java	2003/09/13 18:51:06	1.18
@@ -16,17 +16,20 @@ package java.util;
  * 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 <em>head</em> of the queue is that element
- * which would be removed by a call to {@link #remove() } or {@link #poll()}.
- * Every <tt>Queue</tt> implementation must specify its ordering guarantees.
- *
- * <p>The {@link #offer offer} method adds an element if possible, otherwise
- * returning <tt>false</tt>.  This differs from the 
- * {@link java.util.Collection#add Collection.add}
- * 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 &quot;bounded&quot;) queues.
+ * Whatever the ordering used, the <em>head</em> 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 <em> tail</em> of the queue. Other kinds of queues may use
+ * different placement rules.  Every <tt>Queue</tt> implementation
+ * must specify its ordering properties.
+ *
+ * <p>The {@link #offer offer} method inserts an element if possible,
+ * otherwise returning <tt>false</tt>.  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
+ * <tt>offer</tt> method is designed for use when failure is a normal,
+ * rather than exceptional occurrence, for example, in fixed-capacity
+ * (or &quot;bounded&quot;) queues.
  *
  * <p>The {@link #remove()} and {@link #poll()} methods remove and
  * return the head of the queue.
@@ -54,6 +57,14 @@ package java.util;
  * used as a special return value by the <tt>poll</tt> method to
  * indicate that the queue contains no elements.
  *
+ * <p><tt>Queue</tt> implementations generally do not define
+ * element-based versions of methods <tt>equals</tt> and
+ * <tt>hashCode</tt> but instead inherit the identity based versions
+ * from class <tt>Object</tt>, because element-based equality is not
+ * always well-defined for queues with the same elements but different
+ * ordering properties.
+ *
+ *
  * <p>This interface is a member of the
  * <a href="{@docRoot}/../guide/collections/index.html">
  * Java Collections Framework</a>.
@@ -61,7 +72,7 @@ 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
@@ -72,16 +83,21 @@ package java.util;
 public interface Queue<E> extends Collection<E> {
 
     /**
-     * Add the specified element to this queue, if possible.
+     * Inserts the specified element to this queue, if possible.  When
+     * using queues that may impose insertion restrictions (for
+     * example capacity bounds), method <tt>offer</tt> 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 <tt>true</tt> if it was possible to add the element to
      * this queue, else <tt>false</tt>
      */
     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 <tt>null</tt>
+     * if this queue is empty.
      *
      * @return the head of this queue, or <tt>null</tt> if this
      *         queue is empty.
@@ -89,10 +105,9 @@ public interface Queue<E> extends Collec
     E poll();
 
     /**
-     * Retrieve and remove the head of this queue.
-     * This method differs
-     * from the <tt>poll</tt> 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 <tt>poll</tt> 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.
@@ -100,17 +115,16 @@ public interface Queue<E> extends Collec
     E remove();
 
     /**
-     * Retrieve, but do not remove, the head of this queue.
-     * This method differs from the <tt>poll</tt>
-     * 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 <tt>null</tt> if this queue is empty.
      *
-     * @return the head of this queue, or <tt>null</tt> if this queue is empty.
+     * @return the head of this queue, or <tt>null</tt> 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 <tt>peek</tt> method only in that it throws an
      * exception if this queue is empty.
      *
@@ -119,13 +133,3 @@ public interface Queue<E> extends Collec
      */
     E element();
 }
-
-
-
-
-
-
-
-
-
-