--- jsr166/src/main/java/util/PriorityQueue.java	2003/08/30 11:40:04	1.36
+++ jsr166/src/main/java/util/PriorityQueue.java	2004/06/02 23:45:46	1.50
@@ -1,31 +1,42 @@
- package java.util;
+/*
+ * %W% %E%
+ *
+ * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
+ * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
+ */
+
+package java.util;
 
 /**
- * An unbounded priority {@linkplain Queue queue} based on a priority heap.
- * This queue orders elements according to an order specified at construction
- * time, which is specified in the same manner as {@link java.util.TreeSet}
- * and {@link java.util.TreeMap}: elements are ordered either according to
- * their <i>natural order</i> (see {@link Comparable}), or according to a
- * {@link java.util.Comparator}, depending on which constructor is used.
- * <p>The <em>head</em> of this queue is the <em>least</em> element with
- * respect to the specified ordering.  If multiple elements are tied for least
- * value, the head is one of those elements. A priority queue does not permit
- * <tt>null</tt> elements.
- *
- * <p>The {@link #remove()} and {@link #poll()} methods remove and
- * return the head of the queue.
+ * An unbounded priority {@linkplain Queue queue} based on a priority
+ * heap.  This queue orders elements according to an order specified
+ * at construction time, which is specified either according to their
+ * <i>natural order</i> (see {@link Comparable}), or according to a
+ * {@link java.util.Comparator}, depending on which constructor is
+ * used. A priority queue does not permit <tt>null</tt> elements.
+ * A priority queue relying on natural ordering also does not
+ * permit insertion of non-comparable objects (doing so may result
+ * in <tt>ClassCastException</tt>). 
  *
- * <p>The {@link #element()} and {@link #peek()} methods return, but do
- * not delete, the head of the queue.
+ * <p>The <em>head</em> of this queue is the <em>least</em> element
+ * with respect to the specified ordering.  If multiple elements are
+ * tied for least value, the head is one of those elements -- ties are
+ * broken arbitrarily.  The queue retrieval operations <tt>poll</tt>,
+ * <tt>remove</tt>, <tt>peek</tt>, and <tt>element</tt> access the
+ * element at the head of the queue.
  *
- * <p>A priority queue has a <i>capacity</i>.  The capacity is the
- * size of the array used internally to store the elements on the
- * queue.
- * It is always at least as large as the queue size.  As
- * elements are added to a priority queue, its capacity grows
- * automatically.  The details of the growth policy are not specified.
+ * <p>A priority queue is unbounded, but has an internal
+ * <i>capacity</i> governing the size of an array used to store the
+ * elements on the queue.  It is always at least as large as the queue
+ * size.  As elements are added to a priority queue, its capacity
+ * grows automatically.  The details of the growth policy are not
+ * specified.
  *
- * <p>The Iterator provided in method {@link #iterator()} is <em>not</em>
+ * <p>This class and its iterator implement all of the
+ * <em>optional</em> methods of the {@link Collection} and {@link
+ * Iterator} interfaces. 
+ * The
+ * Iterator provided in method {@link #iterator()} is <em>not</em>
  * guaranteed to traverse the elements of the PriorityQueue in any
  * particular order. If you need ordered traversal, consider using
  * <tt>Arrays.sort(pq.toArray())</tt>.
@@ -48,10 +59,12 @@
  * <a href="{@docRoot}/../guide/collections/index.html">
  * Java Collections Framework</a>.
  * @since 1.5
+ * @version %I%, %G%
  * @author Josh Bloch
+ * @param <E> the type of elements held in this collection
  */
 public class PriorityQueue<E> extends AbstractQueue<E>
-    implements Queue<E>, java.io.Serializable {
+    implements java.io.Serializable {
 
     private static final long serialVersionUID = -7720805057305804111L;
 
@@ -188,8 +201,7 @@ public class PriorityQueue<E> extends Ab
     public PriorityQueue(Collection<? extends E> c) {
         initializeArray(c);
         if (c instanceof SortedSet) {
-            // @fixme double-cast workaround for compiler
-            SortedSet<? extends E> s = (SortedSet<? extends E>) (SortedSet)c;
+            SortedSet<? extends E> s = (SortedSet<? extends E>)c;
             comparator = (Comparator<? super E>)s.comparator();
             fillFromSorted(s);
         } else if (c instanceof PriorityQueue) {
@@ -269,10 +281,8 @@ public class PriorityQueue<E> extends Ab
     }
             
 
-    // Queue Methods
-
     /**
-     * Add the specified element to this priority queue.
+     * Inserts the specified element into this priority queue.
      *
      * @return <tt>true</tt>
      * @throws ClassCastException if the specified element cannot be compared
@@ -295,13 +305,9 @@ public class PriorityQueue<E> extends Ab
         return true;
     }
 
-    public E poll() {
+    public E peek() {
         if (size == 0)
             return null;
-        return remove();
-    }
-
-    public E peek() {
         return (E) queue[1];
     }
 
@@ -312,48 +318,18 @@ public class PriorityQueue<E> extends Ab
      * @return <tt>true</tt> (as per the general contract of
      * <tt>Collection.add</tt>).
      *
-     * @throws NullPointerException {@inheritDoc}
+     * @throws NullPointerException if the specified element is <tt>null</tt>.
      * @throws ClassCastException if the specified element cannot be compared
      * with elements currently in the priority queue according
      * to the priority queue's ordering.
      */
     public boolean add(E o) {
-        return super.add(o);
+        return offer(o);
     }
 
-   
-    /**
-     * Adds all of the elements in the specified collection to this queue.
-     * The behavior of this operation is undefined if
-     * the specified collection is modified while the operation is in
-     * progress.  (This implies that the behavior of this call is undefined if
-     * the specified collection is this queue, and this queue is nonempty.)
-     * <p>
-     * This implementation iterates over the specified collection, and adds
-     * each object returned by the iterator to this collection, in turn.
-     * @throws NullPointerException {@inheritDoc}
-     * @throws ClassCastException if any element cannot be compared
-     * with elements currently in the priority queue according
-     * to the priority queue's ordering.
-     */
-    public boolean addAll(Collection<? extends E> c) {
-        return super.addAll(c);
-    }
-
-
     /**
      * Removes a single instance of the specified element from this
-     * queue, if it is present.  More formally,
-     * removes an element <tt>e</tt> such that <tt>(o==null ? e==null :
-     * o.equals(e))</tt>, if the queue contains one or more such
-     * elements.  Returns <tt>true</tt> if the queue contained the
-     * specified element (or equivalently, if the queue changed as a
-     * result of the call).
-     *
-     * <p>This implementation iterates over the queue looking for the
-     * specified element.  If it finds the element, it removes the element
-     * from the queue using the iterator's remove method.<p>
-     *
+     * queue, if it is present.
      */
     public boolean remove(Object o) {
         if (o == null)
@@ -462,7 +438,7 @@ public class PriorityQueue<E> extends Ab
                     cursor--;
                 } else {
                     if (forgetMeNot == null)
-                        forgetMeNot = new ArrayList();
+                        forgetMeNot = new ArrayList<E>();
                     forgetMeNot.add(moved);
                 }
             } else if (lastRetElt != null) {
@@ -486,7 +462,8 @@ public class PriorityQueue<E> extends Ab
     }
 
     /**
-     * Remove all elements from the priority queue.
+     * Removes all elements from the priority queue.
+     * The queue will be empty after this call returns.
      */
     public void clear() {
         modCount++;
@@ -498,12 +475,9 @@ public class PriorityQueue<E> extends Ab
         size = 0;
     }
 
-    /**
-     * Removes and returns the first element from queue.
-     */
-    public E remove() {
+    public E poll() {
         if (size == 0)
-            throw new NoSuchElementException();
+            return null;
         modCount++;
 
         E result = (E) queue[1];
@@ -649,7 +623,7 @@ public class PriorityQueue<E> extends Ab
         s.writeInt(queue.length);
 
         // Write out all elements in the proper order.
-        for (int i=0; i<size; i++)
+        for (int i=1; i<=size; i++)
             s.writeObject(queue[i]);
     }
 
@@ -668,8 +642,8 @@ public class PriorityQueue<E> extends Ab
         queue = new Object[arrayLength];
 
         // Read in all elements in the proper order.
-        for (int i=0; i<size; i++)
-            queue[i] = s.readObject();
+        for (int i=1; i<=size; i++)
+            queue[i] = (E) s.readObject();
     }
 
 }