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

Diff Legend

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