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.3 by brian, Mon Jun 23 02:26:15 2003 UTC vs.
Revision 1.29 by jsr166, Mon May 16 04:55:20 2005 UTC

#	Line 1 | Line 1
1		/*
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.
3	>	* Expert Group and released to the public domain, as explained at
4	>	* http://creativecommons.org/licenses/publicdomain
5		*/
6
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}, and a
23	>	* {@link Collection#iterator} supporting {@link
24	>	* Iterator#remove}. Typically, additional methods will be overridden
25	>	* as well. If these requirements cannot be met, consider instead
26	>	* subclassing {@link AbstractCollection}.
27	>	*
28	>	* <p>This class is a member of the
29	>	* <a href="{@docRoot}/../guide/collections/index.html">
30	>	* Java Collections Framework</a>.
31	>	*
32	>	* @since 1.5
33	>	* @author Doug Lea
34	>	* @param <E> the type of elements held in this collection
35		*/
36	<
37	<	public abstract class AbstractQueue<E> extends AbstractCollection<E> implements Queue<E> {
36	>	public abstract class AbstractQueue<E>
37	>	extends AbstractCollection<E>
38	>	implements Queue<E> {
39	>
40	>	/**
41	>	* Constructor for use by subclasses.
42	>	*/
43	>	protected AbstractQueue() {
44	>	}
45
46	<	public boolean add(E x) {
47	<	if (offer(x))
46	>	/**
47	>	* Inserts the specified element into this queue if it is possible to do so
48	>	* immediately without violating capacity restrictions, returning
49	>	* <tt>true</tt> upon success and throwing an <tt>IllegalStateException</tt>
50	>	* if no space is currently available.
51	>	*
52	>	* <p>This implementation returns <tt>true</tt> if <tt>offer</tt> succeeds,
53	>	* else throws an <tt>IllegalStateException</tt>.
54	>	*
55	>	* @param e the element to add
56	>	* @return <tt>true</tt> (as per the spec for {@link Collection#add})
57	>	* @throws IllegalStateException if the element cannot be added at this
58	>	*         time due to capacity restrictions
59	>	* @throws ClassCastException if the class of the specified element
60	>	*         prevents it from being added to this queue
61	>	* @throws NullPointerException if the specified element is null and
62	>	*         this queue not permit null elements
63	>	* @throws IllegalArgumentException if some property of this element
64	>	*         prevents it from being added to this queue
65	>	*/
66	>	public boolean add(E e) {
67	>	if (offer(e))
68		return true;
69		else
70		throw new IllegalStateException("Queue full");
71		}
72
73	+	/**
74	+	* Retrieves and removes the head of this queue.  This method differs
75	+	* from {@link #poll} only in that it throws an exception if this queue
76	+	* is empty.
77	+	*
78	+	* <p>This implementation returns the result of <tt>poll</tt>
79	+	* unless the queue is empty.
80	+	*
81	+	* @return the head of this queue
82	+	* @throws NoSuchElementException if this queue is empty
83	+	*/
84		public E remove() {
85		E x = poll();
86		if (x != null)
#	Line 31 | Line 89 | public abstract class AbstractQueue<E> e
89		throw new NoSuchElementException();
90		}
91
92	+	/**
93	+	* Retrieves, but does not remove, the head of this queue.  This method
94	+	* differs from {@link #peek} only in that it throws an exception if
95	+	* this queue is empty.
96	+	*
97	+	* <p>This implementation returns the result of <tt>peek</tt>
98	+	* unless the queue is empty.
99	+	*
100	+	* @return the head of this queue
101	+	* @throws NoSuchElementException if this queue is empty
102	+	*/
103		public E element() {
104		E x = peek();
105		if (x != null)
#	Line 39 | Line 108 | public abstract class AbstractQueue<E> e
108		throw new NoSuchElementException();
109		}
110
111	+	/**
112	+	* Removes all of the elements from this queue.
113	+	* The queue will be empty after this call returns.
114	+	*
115	+	* <p>This implementation repeatedly invokes {@link #poll poll} until it
116	+	* returns <tt>null</tt>.
117	+	*/
118		public void clear() {
119		while (poll() != null)
120		;
121		}
122
123	+	/**
124	+	* Adds all of the elements in the specified collection to this
125	+	* queue.  Attempts to addAll of a queue to itself result in
126	+	* <tt>IllegalArgumentException</tt>. Further, the behavior of
127	+	* this operation is undefined if the specified collection is
128	+	* modified while the operation is in progress.
129	+	*
130	+	* <p>This implementation iterates over the specified collection,
131	+	* and adds each element returned by the iterator to this
132	+	* queue, in turn.  A runtime exception encountered while
133	+	* trying to add an element (including, in particular, a
134	+	* <tt>null</tt> element) may result in only some of the elements
135	+	* having been successfully added when the associated exception is
136	+	* thrown.
137	+	*
138	+	* @param c collection whose elements are to be added to this queue
139	+	* @return <tt>true</tt> if this queue changed as a result of the call
140	+	* @throws ClassCastException if the class of an element of the specified
141	+	*         collection prevents it from being added to this queue
142	+	* @throws NullPointerException if the specified collection contains a
143	+	*         null element and this queue does not permit null elements,
144	+	*         or if the specified collection is null
145	+	* @throws IllegalArgumentException if some property of an element of the
146	+	*         specified collection prevents it from being added to this
147	+	*         queue, or if the specified collection is this queue
148	+	* @throws IllegalStateException if not all the elements can be added at
149	+	*         this time due to insertion restrictions
150	+	* @see #add(Object)
151	+	*/
152	+	public boolean addAll(Collection<? extends E> c) {
153	+	if (c == null)
154	+	throw new NullPointerException();
155	+	if (c == this)
156	+	throw new IllegalArgumentException();
157	+	boolean modified = false;
158	+	Iterator<? extends E> e = c.iterator();
159	+	while (e.hasNext()) {
160	+	if (add(e.next()))
161	+	modified = true;
162	+	}
163	+	return modified;
164	+	}
165	+
166		}

Diff Legend

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