--- jsr166/src/main/java/util/AbstractQueue.java 2003/09/26 11:37:06 1.18 +++ jsr166/src/main/java/util/AbstractQueue.java 2006/03/03 17:15:06 1.33 @@ -1,7 +1,7 @@ /* * 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; @@ -25,8 +25,13 @@ package java.util; * 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,33 +43,43 @@ public abstract class AbstractQueue protected AbstractQueue() { } - /** - * Adds the specified element to this queue. This implementation - * returns true if offer succeeds, else - * throws an IllegalStateException. - * - * @param o the element - * @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. * - * @throws NullPointerException if the specified element is null - * @throws IllegalStateException if element cannot be added + *

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 does 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(); @@ -74,14 +89,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(); @@ -92,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. */ @@ -101,4 +119,48 @@ public abstract class AbstractQueue while (poll() != null) ; } + + /** + * 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 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) { + 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; + } + }