--- jsr166/src/main/java/util/AbstractQueue.java 2003/08/04 01:50:33 1.11 +++ jsr166/src/main/java/util/AbstractQueue.java 2005/05/16 04:55:20 1.29 @@ -1,68 +1,86 @@ /* * 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; /** - * AbstractQueue provides default implementations of - * {@link #add add}, {@link #remove remove}, and {@link #element element} - * based on - * {@link #offer offer}, {@link #poll poll}, and {@link #peek peek}, - * respectively but that - * throw exceptions instead of indicating failure via false or + * This class provides skeletal implementations of some {@link Queue} + * operations. The implementations in this class are appropriate when + * the base implementation does not allow null + * elements. Methods {@link #add add}, {@link #remove remove}, and + * {@link #element element} are based on {@link #offer offer}, {@link + * #poll poll}, and {@link #peek peek}, respectively but throw + * exceptions instead of indicating failure via false or * null returns. - *

The provided implementations all assume that the base implementation - * does not allow null elements. + * + *

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}, 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 implements Queue { - // note that optional methods are not optional here or in our subclasses, - // so we redefine each optional method to document that it is not optional - // We also inherit, or define, all necessary @throws comments + /** + * Constructor for use by subclasses. + */ + protected AbstractQueue() { + } /** - * Adds the specified element to this queue. - * @return true (as per the general contract of - * Collection.add). + * 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. * - * @throws NullPointerException if the specified element is null + * @param e the element to add + * @return true (as per the spec for {@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"); } /** - * 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 adds - * each object returned by the iterator to this collection, in turn. + * Retrieves and removes the head of this queue. This method differs + * from {@link #poll} only in that it throws an exception if this queue + * is empty. * - * @param c collection whose elements are to be added to this queue - * @return true if this collection changed as a result of the - * call. - * @throws NullPointerException if c or any element in c - * is null - * + *

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 */ - public boolean addAll(Collection c) { - return super.addAll(c); - } - - /** @throws NoSuchElementException {@inheritDoc} */ public E remove() { E x = poll(); if (x != null) @@ -71,7 +89,17 @@ public abstract class AbstractQueue throw new NoSuchElementException(); } - /** @throws NoSuchElementException {@inheritDoc} */ + /** + * Retrieves, but does not remove, the head of this queue. This method + * differs from {@link #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 + */ public E element() { E x = peek(); if (x != null) @@ -81,8 +109,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. */ @@ -91,11 +120,47 @@ public abstract class AbstractQueue ; } - // XXX Remove this redundant declaration, pending response from Neal Gafter. - public abstract Iterator iterator(); -} - - - - + /** + * Adds all of the elements in the specified collection to this + * 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 whose elements are 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) { + 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; + } +}