java/util/AbstractQueue.java

/*
 * 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.
 */

package java.util;

/**
 * <tt>AbstractQueue</tt> 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 <tt>false</tt> or
 * <tt>null</tt> returns.
 * <p>The provided implementations all assume that the base implementation
 * does <em>not</em> allow <tt>null</tt> elements.
 * @since 1.5
 * @author Doug Lea
 */
public abstract class AbstractQueue<E>
    extends AbstractCollection<E>
    implements Queue<E> {

    // 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

    /**
     * Adds the specified element to this queue.
     * @return <tt>true</tt> (as per the general contract of
     * <tt>Collection.add</tt>).
     *
     * @throws NullPointerException if the specified element is <tt>null</tt>
     */
    public boolean add(E o) {
        if (offer(o))
            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.)
     * <p>
     * This implementation iterates over the specified collection, and adds
     * each object returned by the iterator to this collection, in turn.
     *
     * @param c collection whose elements are to be added to this queue
     * @return <tt>true</tt> if this collection changed as a result of the
     *         call.
     * @throws NullPointerException if <tt>c</tt> or any element in <tt>c</tt>
     * is <tt>null</tt>
     * 
     */
    public boolean addAll(Collection<? extends E> c) {
        return super.addAll(c);
    }

    /** @throws NoSuchElementException {@inheritDoc} */
    public E remove() {
        E x = poll();
        if (x != null)
            return x;
        else
            throw new NoSuchElementException();
    }

    /** @throws NoSuchElementException {@inheritDoc} */
    public E element() {
        E x = peek();
        if (x != null)
            return x;
        else
            throw new NoSuchElementException();
    }

    /**
     * Removes all of the elements from this collection.
     * The collection will be empty after this call returns.
     * <p>This implementation repeatedly invokes {@link #poll poll} until it
     * returns <tt>null</tt>.
     */
    public void clear() {
        while (poll() != null)
            ;
    }

    // XXX Remove this redundant declaration, pending response from Neal Gafter.
    public abstract Iterator<E> iterator();
}


Revision:	1.11
Committed:	Mon Aug 4 01:50:33 2003 UTC (20 years, 9 months ago) by dholmes
Branch:	MAIN
Changes since 1.10:	+4 -3 lines
Log Message:	Updated @throws
#	User	Rev	Content
1	dl	1.2	/*
2			* Written by Doug Lea with assistance from members of JCP JSR-166
3			* Expert Group and released to the public domain. Use, modify, and
4			* redistribute this code in any way without acknowledgement.
5			*/
6
7	tim	1.1	package java.util;
8
9			/**
10	tim	1.10	* <tt>AbstractQueue</tt> provides default implementations of
11			* {@link #add add}, {@link #remove remove}, and {@link #element element}
12			* based on
13			* {@link #offer offer}, {@link #poll poll}, and {@link #peek peek},
14			* respectively but that
15			* throw exceptions instead of indicating failure via <tt>false</tt> or
16	dholmes	1.9	* <tt>null</tt> returns.
17			* <p>The provided implementations all assume that the base implementation
18	brian	1.3	* does <em>not</em> allow <tt>null</tt> elements.
19	dl	1.4	* @since 1.5
20			* @author Doug Lea
21	tim	1.1	*/
22	tim	1.10	public abstract class AbstractQueue<E>
23			extends AbstractCollection<E>
24	dholmes	1.9	implements Queue<E> {
25	tim	1.5
26	dholmes	1.9	// note that optional methods are not optional here or in our subclasses,
27			// so we redefine each optional method to document that it is not optional
28			// We also inherit, or define, all necessary @throws comments
29	tim	1.1
30	dholmes	1.9	/**
31			* Adds the specified element to this queue.
32	tim	1.10	* @return <tt>true</tt> (as per the general contract of
33	dholmes	1.9	* <tt>Collection.add</tt>).
34			*
35	dholmes	1.11	* @throws NullPointerException if the specified element is <tt>null</tt>
36	dholmes	1.9	*/
37			public boolean add(E o) {
38			if (offer(o))
39	tim	1.1	return true;
40			else
41			throw new IllegalStateException("Queue full");
42			}
43
44	dholmes	1.9	/**
45			* Adds all of the elements in the specified collection to this queue.
46			* The behavior of this operation is undefined if
47			* the specified collection is modified while the operation is in
48			* progress. (This implies that the behavior of this call is undefined if
49			* the specified collection is this queue, and this queue is nonempty.)
50			* <p>
51			* This implementation iterates over the specified collection, and adds
52			* each object returned by the iterator to this collection, in turn.
53			*
54			* @param c collection whose elements are to be added to this queue
55			* @return <tt>true</tt> if this collection changed as a result of the
56			* call.
57	dholmes	1.11	* @throws NullPointerException if <tt>c</tt> or any element in <tt>c</tt>
58			* is <tt>null</tt>
59			*
60	dholmes	1.9	*/
61	tim	1.10	public boolean addAll(Collection<? extends E> c) {
62	dholmes	1.9	return super.addAll(c);
63			}
64
65			/** @throws NoSuchElementException {@inheritDoc} */
66	tim	1.8	public E remove() {
67	tim	1.1	E x = poll();
68			if (x != null)
69			return x;
70			else
71			throw new NoSuchElementException();
72			}
73
74	dholmes	1.9	/** @throws NoSuchElementException {@inheritDoc} */
75	tim	1.8	public E element() {
76	tim	1.1	E x = peek();
77			if (x != null)
78			return x;
79			else
80			throw new NoSuchElementException();
81			}
82
83	dholmes	1.9	/**
84			* Removes all of the elements from this collection.
85			* The collection will be empty after this call returns.
86			* <p>This implementation repeatedly invokes {@link #poll poll} until it
87			* returns <tt>null</tt>.
88			*/
89	tim	1.1	public void clear() {
90			while (poll() != null)
91			;
92			}
93
94	tim	1.7	// XXX Remove this redundant declaration, pending response from Neal Gafter.
95	tim	1.5	public abstract Iterator<E> iterator();
96	tim	1.1	}
97	dholmes	1.6
98
99
100
101