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 element is null
     */
    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> is <tt>null</tt>
     * 
     */
    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.9
Committed:	Thu Jul 31 07:18:02 2003 UTC (20 years, 9 months ago) by dholmes
Branch:	MAIN
Changes since 1.8:	+51 -7 lines
Log Message:	Continued updates to explicit and inherited doc comments. Consistency over remove(null) Some inherited doc is still not right.
#	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	dholmes	1.9	* <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			* <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	dholmes	1.9	public abstract class AbstractQueue<E>
23			extends AbstractCollection<E>
24			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			* @return <tt>true</tt> (as per the general contract of
33			* <tt>Collection.add</tt>).
34			*
35			* @throws NullPointerException if the element is null
36			*/
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			* @throws NullPointerException if <tt>c</tt> is <tt>null</tt>
58			*
59			*/
60			boolean addAll(Collection<? extends E> c) {
61			return super.addAll(c);
62			}
63
64			/** @throws NoSuchElementException {@inheritDoc} */
65	tim	1.8	public E remove() {
66	tim	1.1	E x = poll();
67			if (x != null)
68			return x;
69			else
70			throw new NoSuchElementException();
71			}
72
73	dholmes	1.9	/** @throws NoSuchElementException {@inheritDoc} */
74	tim	1.8	public E element() {
75	tim	1.1	E x = peek();
76			if (x != null)
77			return x;
78			else
79			throw new NoSuchElementException();
80			}
81
82	dholmes	1.9	/**
83			* Removes all of the elements from this collection.
84			* The collection will be empty after this call returns.
85			* <p>This implementation repeatedly invokes {@link #poll poll} until it
86			* returns <tt>null</tt>.
87			*/
88	tim	1.1	public void clear() {
89			while (poll() != null)
90			;
91			}
92
93	tim	1.7	// XXX Remove this redundant declaration, pending response from Neal Gafter.
94	tim	1.5	public abstract Iterator<E> iterator();
95	tim	1.1	}
96	dholmes	1.6
97
98
99
100