--- jsr166/src/main/java/util/AbstractQueue.java 2003/11/16 15:57:39 1.23 +++ 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} @@ -25,6 +26,10 @@ 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 @@ -39,33 +44,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 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(); @@ -75,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(); @@ -93,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. */ @@ -112,19 +130,24 @@ public abstract class AbstractQueue * *

This implementation iterates over the specified collection, * and adds each element returned by the iterator to this - * collection, in turn. A runtime exception encountered while + * 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 collection. - * @return true if this collection changed as a result of the - * call. - * @throws NullPointerException if the specified collection or - * any of its elements are null. - * @throws IllegalArgumentException if c is this queue. - * + * @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) {