ViewVC Help

View File | Revision Log | Show Annotations | Download File | Root Listing

root/jsr166/jsr166/src/main/java/util/AbstractQueue.java

Comparing jsr166/src/main/java/util/AbstractQueue.java (file contents):
Revision 1.7 by tim, Mon Jul 28 16:00:19 2003 UTC vs.
Revision 1.14 by dl, Fri Sep 12 15:38:26 2003 UTC

#	Line 7 | Line 7
7		package java.util;
8
9		/**
10	<	* AbstractQueue provides default implementations of add, remove, and
11	<	* element based on offer, poll, and peek, respectively but that throw
12	<	* exceptions instead of indicating failure via false or null returns.
13	<	* The provided implementations all assume that the base implementation
14	<	* does <em>not</em> allow <tt>null</tt> elements.
10	>	* This class provides skeletal implementations of some {@link Queue}
11	>	* operations. The implementations in this class are appropriate when
12	>	* the base implementation does <em>not</em> allow <tt>null</tt>
13	>	* elements.  Methods {@link #add add}, {@link #remove remove}, and
14	>	* {@link #element element} are based on {@link #offer offer}, {@link
15	>	* #poll poll}, and {@link #peek peek}, respectively but throw
16	>	* exceptions instead of indicating failure via <tt>false</tt> or
17	>	* <tt>null</tt> returns.
18	>	*
19	>	* <p> A <tt>Queue</tt> implementation that extends this class must
20	>	* minimally define a method {@link Queue#offer} which does not permit
21	>	* insertion of <tt>null</tt> elements, along with methods {@link
22	>	* Queue#peek}, {@link Queue#poll}, {@link Collection#size}, {@link
23	>	* Collection#remove}, and a {@link Collection#iterator} supporting
24	>	* {@link Iterator#remove}. If these requirements cannot be met,
25	>	* consider instead subclassing {@link AbstractCollection}.
26	>	*
27		* @since 1.5
28		* @author Doug Lea
29		*/
30	+	public abstract class AbstractQueue<E>
31	+	extends AbstractCollection<E>
32	+	implements Queue<E> {
33	+
34	+	/**
35	+	* Constructor for use by subclasses.
36	+	*/
37	+	protected AbstractQueue() {
38	+	}
39
40	<	public abstract class AbstractQueue<E> extends AbstractCollection<E> implements Queue<E> {
41	<
42	<	public boolean add(E x) {
43	<	if (offer(x))
40	>	/**
41	>	* Inserts the specified element to this queue, if possible.
42	>	*
43	>	* @param o the element to add.
44	>	* @return <tt>true</tt> if it was possible to add the element to
45	>	*         this queue, else <tt>false</tt>
46	>	* @throws NullPointerException if the specified element is <tt>null</tt>
47	>	*/
48	>	//    public boolean offer(E o) { return false; }
49	>	// FIXME: Replace above no-op with following abstract version
50	>	// when javac allows it.
51	>	public abstract boolean offer(E o);
52	>
53	>	/**
54	>	* Adds the specified element to this queue. This implementation
55	>	* returns <tt>true</tt> if <tt>offer</tt> succeeds, else
56	>	* throws an IllegalStateException.
57	>	* th
58	>	* @param o the element
59	>	* @return <tt>true</tt> (as per the general contract of
60	>	*         <tt>Collection.add</tt>).
61	>	*
62	>	* @throws NullPointerException if the specified element is <tt>null</tt>
63	>	* @throws IllegalStateException if element cannot be added
64	>	*/
65	>	public boolean add(E o) {
66	>	if (offer(o))
67		return true;
68		else
69		throw new IllegalStateException("Queue full");
70		}
71
72	<	public E remove() throws NoSuchElementException {
72	>	/**
73	>	* Retrieves and removes the head of this queue.
74	>	* This implementation returns the result of <tt>poll</tt>
75	>	* unless the queue is empty.
76	>	*
77	>	* @return the head of this queue.
78	>	* @throws NoSuchElementException if this queue is empty.
79	>	*/
80	>	public E remove() {
81		E x = poll();
82		if (x != null)
83		return x;
#	Line 33 | Line 85 | public abstract class AbstractQueue<E> e
85		throw new NoSuchElementException();
86		}
87
88	<	public E element() throws NoSuchElementException {
88	>
89	>	/**
90	>	* Retrieves, but does not remove, the head of this queue.
91	>	* This implementation returns the result of <tt>peek</tt>
92	>	* unless the queue is empty.
93	>	*
94	>	* @return the head of this queue.
95	>	* @throws NoSuchElementException if this queue is empty.
96	>	*/
97	>	public E element() {
98		E x = peek();
99		if (x != null)
100		return x;
#	Line 41 | Line 102 | public abstract class AbstractQueue<E> e
102		throw new NoSuchElementException();
103		}
104
105	+	/**
106	+	* Removes all of the elements from this collection.
107	+	* The collection will be empty after this call returns.
108	+	* <p>This implementation repeatedly invokes {@link #poll poll} until it
109	+	* returns <tt>null</tt>.
110	+	*/
111		public void clear() {
112		while (poll() != null)
113		;
114		}
115
116	<	// XXX Remove this redundant declaration, pending response from Neal Gafter.
50	<	public abstract Iterator<E> iterator();
51	<	}
52	<
116	>	// Declarations that mostly just remove optionality clauses.
117
118	+	/**
119	+	* Removes a single instance of the specified element from this
120	+	* queue, if one is present.  More formally, removes an element
121	+	* <tt>e</tt> such that <tt>(o==null ? e==null :
122	+	* o.equals(e))</tt>, if the queue contains such an element.
123	+	* Returns <tt>true</tt> if the queue contained the specified
124	+	* element (or equivalently, if the queue changed as a result of
125	+	* the call).
126	+	*
127	+	* @param o the element to remove
128	+	* @return true if the element was removed
129	+	*/
130	+	public abstract boolean remove(Object o);
131	+
132	+	/**
133	+	* Removes from this queue all of its elements that are contained in
134	+	* the specified collection. <p>
135	+	*
136	+	* This implementation iterates over this queue, checking each
137	+	* element returned by the iterator in turn to see if it's contained
138	+	* in the specified collection.  If it's so contained, it's removed from
139	+	* this queue with the iterator's <tt>remove</tt> method.<p>
140	+	*
141	+	* @param c elements to be removed from this collection.
142	+	* @return <tt>true</tt> if this queue changed as a result of the
143	+	*         call.
144	+	* @throws NullPointerException if the specified collection is null.
145	+	*/
146	+	public boolean removeAll(Collection<?> c) {
147	+	return super.removeAll(c);
148	+	}
149
150	+	/**
151	+	* Retains only the elements in this queue that are contained in the
152	+	* specified collection.  In other words, removes
153	+	* from this queue all of its elements that are not contained in the
154	+	* specified collection. <p>
155	+	*
156	+	* This implementation iterates over this queue, checking each
157	+	* element returned by the iterator in turn to see if it's contained
158	+	* in the specified collection.  If it's not so contained, it's removed
159	+	* from this queue with the iterator's <tt>remove</tt> method.<p>
160	+	*
161	+	* @param c elements to be retained in this collection.
162	+	* @return <tt>true</tt> if this queue changed as a result of the
163	+	*         call.
164	+	* @throws NullPointerException if the specified collection is null.
165	+	*
166	+	*/
167	+	public boolean retainAll(Collection<?> c) {
168	+	return super.retainAll(c);
169	+	}
170
171	+	/**
172	+	* Adds all of the elements in the specified collection to this
173	+	* queue.  The behavior of this operation is undefined if the
174	+	* specified collection is modified while the operation is in
175	+	* progress.  (This implies that the behavior of this call is
176	+	* undefined if the specified collection is this queue, and this
177	+	* queue is nonempty.)
178	+	*
179	+	* <p> This implementation iterates over the specified collection,
180	+	* and uses the <tt>add</tt> method to insert each object returned by
181	+	* the iterator to this queue, in turn.
182	+	*
183	+	* @param c collection whose elements are to be added to this queue
184	+	* @return <tt>true</tt> if this queue changed as a result of the
185	+	*         call.
186	+	* @throws NullPointerException if <tt>c</tt> or any element in <tt>c</tt>
187	+	* is <tt>null</tt>
188	+	* @throws IllegalStateException if any element cannot be added.
189	+	*
190	+	*/
191	+	public boolean addAll(Collection<? extends E> c) {
192	+	return super.addAll(c);
193	+	}
194
195	+	}

Diff Legend

–	Removed lines
+	Added lines
<	Changed lines
>	Changed lines