KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > util > AbstractQueue


1 /*
2  * @(#)AbstractQueue.java 1.6 04/01/27
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7
8 package java.util;
9
10 /**
11  * This class provides skeletal implementations of some {@link Queue}
12  * operations. The implementations in this class are appropriate when
13  * the base implementation does <em>not</em> allow <tt>null</tt>
14  * elements. Methods {@link #add add}, {@link #remove remove}, and
15  * {@link #element element} are based on {@link #offer offer}, {@link
16  * #poll poll}, and {@link #peek peek}, respectively but throw
17  * exceptions instead of indicating failure via <tt>false</tt> or
18  * <tt>null</tt> returns.
19  *
20  * <p> A <tt>Queue</tt> implementation that extends this class must
21  * minimally define a method {@link Queue#offer} which does not permit
22  * insertion of <tt>null</tt> elements, along with methods {@link
23  * Queue#peek}, {@link Queue#poll}, {@link Collection#size}, and a
24  * {@link Collection#iterator} supporting {@link
25  * Iterator#remove}. Typically, additional methods will be overridden
26  * as well. If these requirements cannot be met, consider instead
27  * subclassing {@link AbstractCollection}.
28  *
29  * <p>This class is a member of the
30  * <a HREF="{@docRoot}/../guide/collections/index.html">
31  * Java Collections Framework</a>.
32  *
33  * @since 1.5
34  * @author Doug Lea
35  * @param <E> the type of elements held in this collection
36  */
37 public abstract class AbstractQueue<E>
38     extends AbstractCollection JavaDoc<E>
39     implements Queue JavaDoc<E> {
40
41     /**
42      * Constructor for use by subclasses.
43      */
44     protected AbstractQueue() {
45     }
46
47
48     /**
49      * Adds the specified element to this queue. This implementation
50      * returns <tt>true</tt> if <tt>offer</tt> succeeds, else
51      * throws an IllegalStateException.
52      *
53      * @param o the element
54      * @return <tt>true</tt> (as per the general contract of
55      * <tt>Collection.add</tt>).
56      *
57      * @throws NullPointerException if the specified element is <tt>null</tt>
58      * @throws IllegalStateException if element cannot be added
59      */
60     public boolean add(E o) {
61         if (offer(o))
62             return true;
63         else
64             throw new IllegalStateException JavaDoc("Queue full");
65     }
66
67     /**
68      * Retrieves and removes the head of this queue.
69      * This implementation returns the result of <tt>poll</tt>
70      * unless the queue is empty.
71      *
72      * @return the head of this queue.
73      * @throws NoSuchElementException if this queue is empty.
74      */
75     public E remove() {
76         E x = poll();
77         if (x != null)
78             return x;
79         else
80             throw new NoSuchElementException JavaDoc();
81     }
82
83
84     /**
85      * Retrieves, but does not remove, the head of this queue.
86      * This implementation returns the result of <tt>peek</tt>
87      * unless the queue is empty.
88      *
89      * @return the head of this queue.
90      * @throws NoSuchElementException if this queue is empty.
91      */
92     public E element() {
93         E x = peek();
94         if (x != null)
95             return x;
96         else
97             throw new NoSuchElementException JavaDoc();
98     }
99
100     /**
101      * Removes all of the elements from this collection.
102      * The collection will be empty after this call returns.
103      * <p>This implementation repeatedly invokes {@link #poll poll} until it
104      * returns <tt>null</tt>.
105      */
106     public void clear() {
107         while (poll() != null)
108             ;
109     }
110
111     /**
112      * Adds all of the elements in the specified collection to this
113      * queue. Attempts to addAll of a queue to itself result in
114      * <tt>IllegalArgumentException</tt>. Further, the behavior of
115      * this operation is undefined if the specified collection is
116      * modified while the operation is in progress.
117      *
118      * <p>This implementation iterates over the specified collection,
119      * and adds each element returned by the iterator to this
120      * collection, in turn. A runtime exception encountered while
121      * trying to add an element (including, in particular, a
122      * <tt>null</tt> element) may result in only some of the elements
123      * having been successfully added when the associated exception is
124      * thrown.
125      *
126      * @param c collection whose elements are to be added to this collection.
127      * @return <tt>true</tt> if this collection changed as a result of the
128      * call.
129      * @throws NullPointerException if the specified collection or
130      * any of its elements are null.
131      * @throws IllegalArgumentException if c is this queue.
132      *
133      * @see #add(Object)
134      */
135     public boolean addAll(Collection JavaDoc<? extends E> c) {
136         if (c == null)
137             throw new NullPointerException JavaDoc();
138         if (c == this)
139             throw new IllegalArgumentException JavaDoc();
140         boolean modified = false;
141         Iterator JavaDoc<? extends E> e = c.iterator();
142         while (e.hasNext()) {
143             if (add(e.next()))
144                 modified = true;
145         }
146         return modified;
147     }
148
149 }
150
Popular Tags