--- jsr166/src/main/java/util/AbstractQueue.java 2003/09/12 17:13:11 1.15 +++ jsr166/src/main/java/util/AbstractQueue.java 2005/07/18 19:14:17 1.31 @@ -1,10 +1,11 @@ /* * 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; +import java.util.*; // for javadoc (till 6280605 is fixed) /** * This class provides skeletal implementations of some {@link Queue} @@ -19,13 +20,19 @@ package java.util; *

A Queue implementation that extends this class must * minimally define a method {@link Queue#offer} which does not permit * insertion of null elements, along with methods {@link - * Queue#peek}, {@link Queue#poll}, {@link Collection#size}, {@link - * Collection#remove}, and a {@link Collection#iterator} supporting - * {@link Iterator#remove}. If these requirements cannot be met, - * consider instead subclassing {@link AbstractCollection}. + * Queue#peek}, {@link Queue#poll}, {@link Collection#size}, and a + * {@link Collection#iterator} supporting {@link + * Iterator#remove}. Typically, additional methods will be overridden + * as well. If these requirements cannot be met, consider instead + * subclassing {@link AbstractCollection}. + * + *

This class is a member of the + * + * Java Collections Framework. * * @since 1.5 * @author Doug Lea + * @param the type of elements held in this collection */ public abstract class AbstractQueue extends AbstractCollection @@ -38,44 +45,42 @@ public abstract class AbstractQueue } /** - * Inserts the specified element to this queue, if possible. - * - * @param o the element to add. - * @return true if it was possible to add the element to - * this queue, else false - * @throws NullPointerException if the specified element is null - */ - public boolean offer(E o) { return false; } - // FIXME: Replace above no-op with following abstract version - // when javac allows it. - // public abstract boolean offer(E o); - - /** - * Adds the specified element to this queue. This implementation - * returns true if offer succeeds, else - * throws an IllegalStateException. - * th - * @param o the element - * @return true (as per the general contract of - * Collection.add). - * - * @throws NullPointerException if the specified element is null - * @throws IllegalStateException if element cannot be added + * Inserts the specified element into this queue if it is possible to do so + * immediately without violating capacity restrictions, returning + * true upon success and throwing an IllegalStateException + * if no space is currently available. + * + *

This implementation returns true if offer succeeds, + * else throws an IllegalStateException. + * + * @param e the element to add + * @return true (as specified by {@link Collection#add}) + * @throws IllegalStateException if the element cannot be added at this + * time due to capacity restrictions + * @throws ClassCastException if the class of the specified element + * prevents it from being added to this queue + * @throws NullPointerException if the specified element is null and + * this queue not permit null elements + * @throws IllegalArgumentException if some property of this element + * prevents it from being added to this queue */ - public boolean add(E o) { - if (offer(o)) + public boolean add(E e) { + if (offer(e)) return true; else throw new IllegalStateException("Queue full"); } /** - * Retrieves and removes the head of this queue. - * This implementation returns the result of poll + * Retrieves and removes the head of this queue. This method differs + * from {@link #poll poll} only in that it throws an exception if this + * queue is empty. + * + *

This implementation returns the result of poll * unless the queue is empty. * - * @return the head of this queue. - * @throws NoSuchElementException if this queue is empty. + * @return the head of this queue + * @throws NoSuchElementException if this queue is empty */ public E remove() { E x = poll(); @@ -85,14 +90,16 @@ public abstract class AbstractQueue throw new NoSuchElementException(); } - /** - * Retrieves, but does not remove, the head of this queue. - * This implementation returns the result of peek + * Retrieves, but does not remove, the head of this queue. This method + * differs from {@link #peek peek} only in that it throws an exception if + * this queue is empty. + * + *

This implementation returns the result of peek * unless the queue is empty. * - * @return the head of this queue. - * @throws NoSuchElementException if this queue is empty. + * @return the head of this queue + * @throws NoSuchElementException if this queue is empty */ public E element() { E x = peek(); @@ -103,8 +110,9 @@ public abstract class AbstractQueue } /** - * Removes all of the elements from this collection. - * The collection will be empty after this call returns. + * Removes all of the elements from this queue. + * The queue will be empty after this call returns. + * *

This implementation repeatedly invokes {@link #poll poll} until it * returns null. */ @@ -113,83 +121,47 @@ public abstract class AbstractQueue ; } - // Declarations that mostly just remove optionality clauses. - - /** - * Removes a single instance of the specified element from this - * queue, if one is present. More formally, removes an element - * e such that (o==null ? e==null : - * o.equals(e)), if the queue contains such an element. - * Returns true if the queue contained the specified - * element (or equivalently, if the queue changed as a result of - * the call). - * - * @param o the element to remove - * @return true if the element was removed - */ - public abstract boolean remove(Object o); - - /** - * Removes from this queue all of its elements that are contained in - * the specified collection.

- * - * This implementation iterates over this queue, checking each - * element returned by the iterator in turn to see if it's contained - * in the specified collection. If it's so contained, it's removed from - * this queue with the iterator's remove method.

- * - * @param c elements to be removed from this collection. - * @return true if this queue changed as a result of the - * call. - * @throws NullPointerException if the specified collection is null. - */ - public boolean removeAll(Collection c) { - return super.removeAll(c); - } - - /** - * Retains only the elements in this queue that are contained in the - * specified collection. In other words, removes - * from this queue all of its elements that are not contained in the - * specified collection.

- * - * This implementation iterates over this queue, checking each - * element returned by the iterator in turn to see if it's contained - * in the specified collection. If it's not so contained, it's removed - * from this queue with the iterator's remove method.

- * - * @param c elements to be retained in this collection. - * @return true if this queue changed as a result of the - * call. - * @throws NullPointerException if the specified collection is null. - * - */ - public boolean retainAll(Collection c) { - return super.retainAll(c); - } - /** * 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.) - * - *

This implementation iterates over the specified collection, - * and uses the add method to insert each object returned by - * the iterator to this queue, in turn. - * - * @param c collection whose elements are to be added to this queue - * @return true if this queue changed as a result of the - * call. - * @throws NullPointerException if c or any element in c - * is null - * @throws IllegalStateException if any element cannot be added. - * + * queue. Attempts to addAll of a queue to itself result in + * IllegalArgumentException. Further, the behavior of + * this operation is undefined if the specified collection is + * modified while the operation is in progress. + * + *

This implementation iterates over the specified collection, + * and adds each element returned by the iterator to this + * queue, in turn. A runtime exception encountered while + * trying to add an element (including, in particular, a + * null element) may result in only some of the elements + * having been successfully added when the associated exception is + * thrown. + * + * @param c collection containing elements to be added to this queue + * @return true if this queue changed as a result of the call + * @throws ClassCastException if the class of an element of the specified + * collection prevents it from being added to this queue + * @throws NullPointerException if the specified collection contains a + * null element and this queue does not permit null elements, + * or if the specified collection is null + * @throws IllegalArgumentException if some property of an element of the + * specified collection prevents it from being added to this + * queue, or if the specified collection is this queue + * @throws IllegalStateException if not all the elements can be added at + * this time due to insertion restrictions + * @see #add(Object) */ public boolean addAll(Collection c) { - return super.addAll(c); + if (c == null) + throw new NullPointerException(); + if (c == this) + throw new IllegalArgumentException(); + boolean modified = false; + Iterator e = c.iterator(); + while (e.hasNext()) { + if (add(e.next())) + modified = true; + } + return modified; } }