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.14 by dl, Fri Sep 12 15:38:26 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;
#	Line 19 | Line 19 | package java.util;
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}.
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		public abstract class AbstractQueue<E>
37		extends AbstractCollection<E>
#	Line 38 | Line 44 | public abstract class AbstractQueue<E>
44		}
45
46		/**
47	<	* Inserts the specified element to this queue, if possible.
48	<	*
49	<	* @param o the element to add.
50	<	* @return <tt>true</tt> if it was possible to add the element to
51	<	*         this queue, else <tt>false</tt>
52	<	* @throws NullPointerException if the specified element is <tt>null</tt>
53	<	*/
54	<	//    public boolean offer(E o) { return false; }
55	<	// FIXME: Replace above no-op with following abstract version
56	<	// when javac allows it.
57	<	public abstract boolean offer(E o);
58	<
59	<	/**
60	<	* Adds the specified element to this queue. This implementation
61	<	* returns <tt>true</tt> if <tt>offer</tt> succeeds, else
62	<	* throws an IllegalStateException.
63	<	* th
64	<	* @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
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 o) {
67	<	if (offer(o))
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.
75	<	* This implementation returns the result of <tt>poll</tt>
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.
81	>	* @return the head of this queue
82	>	* @throws NoSuchElementException if this queue is empty
83		*/
84		public E remove() {
85		E x = poll();
#	Line 85 | Line 89 | public abstract class AbstractQueue<E>
89		throw new NoSuchElementException();
90		}
91
88	–
92		/**
93	<	* Retrieves, but does not remove, the head of this queue.
94	<	* This implementation returns the result of <tt>peek</tt>
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.
100	>	* @return the head of this queue
101	>	* @throws NoSuchElementException if this queue is empty
102		*/
103		public E element() {
104		E x = peek();
#	Line 103 | Line 109 | public abstract class AbstractQueue<E>
109		}
110
111		/**
112	<	* Removes all of the elements from this collection.
113	<	* The collection will be empty after this call returns.
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		*/
#	Line 113 | Line 120 | public abstract class AbstractQueue<E>
120		;
121		}
122
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	–
123		/**
124		* Adds all of the elements in the specified collection to this
125	<	* queue.  The behavior of this operation is undefined if the
126	<	* specified collection is modified while the operation is in
127	<	* progress.  (This implies that the behavior of this call is
128	<	* undefined if the specified collection is this queue, and this
129	<	* queue is nonempty.)
130	<	*
131	<	* <p> This implementation iterates over the specified collection,
132	<	* and uses the <tt>add</tt> method to insert each object returned by
133	<	* the iterator to this queue, in turn.
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
140	<	*         call.
141	<	* @throws NullPointerException if <tt>c</tt> or any element in <tt>c</tt>
142	<	* is <tt>null</tt>
143	<	* @throws IllegalStateException if any element cannot be added.
144	<	*
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	<	return super.addAll(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