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

    //    /**
    //     * @throws NullPointerException if the specified element is <tt>null</tt>
    //     */
    //    public abstract boolean offer(E o);

    /**
     * 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 queue, 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.13
Committed:	Wed Aug 6 10:27:19 2003 UTC (20 years, 9 months ago) by dl
Branch:	MAIN
CVS Tags:	JSR166_CR1
Changes since 1.12:	+4 -4 lines
Log Message:	Commented out offer decl for now to please compiler
#	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	dl	1.13	// /**
31			// * @throws NullPointerException if the specified element is <tt>null</tt>
32			// */
33			// public abstract boolean offer(E o);
34	dholmes	1.12
35			/**
36	dholmes	1.9	* Adds the specified element to this queue.
37	tim	1.10	* @return <tt>true</tt> (as per the general contract of
38	dholmes	1.9	* <tt>Collection.add</tt>).
39			*
40	dholmes	1.11	* @throws NullPointerException if the specified element is <tt>null</tt>
41	dholmes	1.9	*/
42			public boolean add(E o) {
43			if (offer(o))
44	tim	1.1	return true;
45			else
46			throw new IllegalStateException("Queue full");
47			}
48
49	dholmes	1.9	/**
50			* Adds all of the elements in the specified collection to this queue.
51			* The behavior of this operation is undefined if
52			* the specified collection is modified while the operation is in
53			* progress. (This implies that the behavior of this call is undefined if
54			* the specified collection is this queue, and this queue is nonempty.)
55			* <p>
56			* This implementation iterates over the specified collection, and adds
57	dholmes	1.12	* each object returned by the iterator to this queue, in turn.
58	dholmes	1.9	*
59			* @param c collection whose elements are to be added to this queue
60			* @return <tt>true</tt> if this collection changed as a result of the
61			* call.
62	dholmes	1.11	* @throws NullPointerException if <tt>c</tt> or any element in <tt>c</tt>
63			* is <tt>null</tt>
64			*
65	dholmes	1.9	*/
66	tim	1.10	public boolean addAll(Collection<? extends E> c) {
67	dholmes	1.9	return super.addAll(c);
68			}
69
70			/** @throws NoSuchElementException {@inheritDoc} */
71	tim	1.8	public E remove() {
72	tim	1.1	E x = poll();
73			if (x != null)
74			return x;
75			else
76			throw new NoSuchElementException();
77			}
78
79	dholmes	1.9	/** @throws NoSuchElementException {@inheritDoc} */
80	tim	1.8	public E element() {
81	tim	1.1	E x = peek();
82			if (x != null)
83			return x;
84			else
85			throw new NoSuchElementException();
86			}
87
88	dholmes	1.9	/**
89			* Removes all of the elements from this collection.
90			* The collection will be empty after this call returns.
91			* <p>This implementation repeatedly invokes {@link #poll poll} until it
92			* returns <tt>null</tt>.
93			*/
94	tim	1.1	public void clear() {
95			while (poll() != null)
96			;
97			}
98
99	tim	1.7	// XXX Remove this redundant declaration, pending response from Neal Gafter.
100	tim	1.5	public abstract Iterator<E> iterator();
101	tim	1.1	}
102	dholmes	1.6
103
104
105
106