ViewVC Help

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

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

Comparing jsr166/src/main/java/util/Queue.java (file contents):
Revision 1.4 by dl, Sat Jun 7 18:31:00 2003 UTC vs.
Revision 1.46 by jsr166, Sat May 6 06:49:46 2017 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	<	* A Collection designed for holding elements prior to processing.
10	>	* A collection designed for holding elements prior to processing.
11		* Besides basic {@link Collection} operations, queues provide
12		* additional insertion, extraction, and inspection operations.
13	+	* Each of these methods exists in two forms: one throws an exception
14	+	* if the operation fails, the other returns a special value (either
15	+	* {@code null} or {@code false}, depending on the operation).  The
16	+	* latter form of the insert operation is designed specifically for
17	+	* use with capacity-restricted {@code Queue} implementations; in most
18	+	* implementations, insert operations cannot fail.
19	+	*
20	+	* <table BORDER CELLPADDING=3 CELLSPACING=1>
21	+	* <caption>Summary of Queue methods</caption>
22	+	*  <tr>
23	+	*    <td></td>
24	+	*    <td ALIGN=CENTER><em>Throws exception</em></td>
25	+	*    <td ALIGN=CENTER><em>Returns special value</em></td>
26	+	*  </tr>
27	+	*  <tr>
28	+	*    <td><b>Insert</b></td>
29	+	*    <td>{@link #add(Object) add(e)}</td>
30	+	*    <td>{@link #offer(Object) offer(e)}</td>
31	+	*  </tr>
32	+	*  <tr>
33	+	*    <td><b>Remove</b></td>
34	+	*    <td>{@link #remove() remove()}</td>
35	+	*    <td>{@link #poll() poll()}</td>
36	+	*  </tr>
37	+	*  <tr>
38	+	*    <td><b>Examine</b></td>
39	+	*    <td>{@link #element() element()}</td>
40	+	*    <td>{@link #peek() peek()}</td>
41	+	*  </tr>
42	+	* </table>
43		*
44		* <p>Queues typically, but do not necessarily, order elements in a
45	<	* FIFO (first-in-first-out) manner.  Among the exceptions are priority
46	<	* queues, which order elements according to a supplied comparators, or
47	<	* the elements natural ordering.  Every Queue implementation must specify
48	<	* its ordering guarantees.
49	<	*
50	<	* <p>The {@link #offer(E)} method adds an element if possible, otherwise
51	<	* returning <tt>false</tt>.  This differs from the {@link
52	<	* Collections#add(Object)} method, which throws an unchecked exception upon
53	<	* failure. It is designed for use in collections in which failure to
54	<	* add is a normal, rather than exceptional occurrence, for example,
55	<	* in fixed-capacity (or &ldquo;bounded&rdquo;) queues.
56	<
57	<	*
58	<	* <p>The {@link #remove()} and {@link #poll()} methods remove and return an
59	<	* element in accord with the implementation's ordering policy.
60	<	* Exactly which element is removed from the queue is a function
61	<	* of the queue's ordering policy, which differs from implementation
62	<	* to implementation.  Possible orderings include (but are not limited
63	<	* to) first-in-first-out (FIFO), element priority, and arbitrary.
64	<	* The <tt>remove()</tt> and <tt>poll()</tt> methods differ only in their
65	<	* behavior when the queue is empty: the <tt>remove()</tt> method throws an
66	<	* exception, while the <tt>poll()</tt> method returns <tt>null</tt>.
67	<	*
68	<	* <p>The {@link #element()} and {@link #peek()} methods return but do
69	<	* not delete the element that would be obtained by a call to
70	<	* the <tt>remove</tt> and <tt>poll</tt> methods respectively.
45	>	* FIFO (first-in-first-out) manner.  Among the exceptions are
46	>	* priority queues, which order elements according to a supplied
47	>	* comparator, or the elements' natural ordering, and LIFO queues (or
48	>	* stacks) which order the elements LIFO (last-in-first-out).
49	>	* Whatever the ordering used, the <em>head</em> of the queue is that
50	>	* element which would be removed by a call to {@link #remove()} or
51	>	* {@link #poll()}.  In a FIFO queue, all new elements are inserted at
52	>	* the <em>tail</em> of the queue. Other kinds of queues may use
53	>	* different placement rules.  Every {@code Queue} implementation
54	>	* must specify its ordering properties.
55	>	*
56	>	* <p>The {@link #offer offer} method inserts an element if possible,
57	>	* otherwise returning {@code false}.  This differs from the {@link
58	>	* java.util.Collection#add Collection.add} method, which can fail to
59	>	* add an element only by throwing an unchecked exception.  The
60	>	* {@code offer} method is designed for use when failure is a normal,
61	>	* rather than exceptional occurrence, for example, in fixed-capacity
62	>	* (or &quot;bounded&quot;) queues.
63	>	*
64	>	* <p>The {@link #remove()} and {@link #poll()} methods remove and
65	>	* return the head of the queue.
66	>	* Exactly which element is removed from the queue is a
67	>	* function of the queue's ordering policy, which differs from
68	>	* implementation to implementation. The {@code remove()} and
69	>	* {@code poll()} methods differ only in their behavior when the
70	>	* queue is empty: the {@code remove()} method throws an exception,
71	>	* while the {@code poll()} method returns {@code null}.
72		*
73	<	* <p>The <tt>Queue</tt> interface does not define the <i>blocking queue
73	>	* <p>The {@link #element()} and {@link #peek()} methods return, but do
74	>	* not remove, the head of the queue.
75	>	*
76	>	* <p>The {@code Queue} interface does not define the <i>blocking queue
77		* methods</i>, which are common in concurrent programming.  These methods,
78		* which wait for elements to appear or for space to become available, are
79		* defined in the {@link java.util.concurrent.BlockingQueue} interface, which
80		* extends this interface.
81		*
82	<	* <p><tt>Queue</tt> implementations generally do not allow insertion of
83	<	* <tt>null</tt> elements.  Even in the few implementations that permit it,
84	<	* it is a bad idea, as <tt>null</tt> is also used as a special return value
85	<	* by the <tt>poll</tt> method to indicate that the queue contains no
86	<	* elements.
82	>	* <p>{@code Queue} implementations generally do not allow insertion
83	>	* of {@code null} elements, although some implementations, such as
84	>	* {@link LinkedList}, do not prohibit insertion of {@code null}.
85	>	* Even in the implementations that permit it, {@code null} should
86	>	* not be inserted into a {@code Queue}, as {@code null} is also
87	>	* used as a special return value by the {@code poll} method to
88	>	* indicate that the queue contains no elements.
89	>	*
90	>	* <p>{@code Queue} implementations generally do not define
91	>	* element-based versions of methods {@code equals} and
92	>	* {@code hashCode} but instead inherit the identity based versions
93	>	* from class {@code Object}, because element-based equality is not
94	>	* always well-defined for queues with the same elements but different
95	>	* ordering properties.
96		*
97		* <p>This interface is a member of the
98	<	* <a href="{@docRoot}/../guide/collections/index.html">
98	>	* <a href="{@docRoot}/java/util/package-summary.html#CollectionsFramework">
99		* Java Collections Framework</a>.
100		*
101	<	* @see Collection
102	<	* @see LinkedList
103	<	* @see PriorityQueue
61	<	* @see LinkedQueue
62	<	* @see java.util.concurrent.BlockingQueue
63	<	* @see java.util.concurrent.ArrayBlockingQueue
64	<	* @see java.util.concurrent.LinkedBlockingQueue
65	<	* @see java.util.concurrent.PriorityBlockingQueue
101	>	* @since 1.5
102	>	* @author Doug Lea
103	>	* @param <E> the type of elements held in this queue
104		*/
105		public interface Queue<E> extends Collection<E> {
106		/**
107	<	* Add the specified element to this queue, if possible.
107	>	* Inserts the specified element into this queue if it is possible to do so
108	>	* immediately without violating capacity restrictions, returning
109	>	* {@code true} upon success and throwing an {@code IllegalStateException}
110	>	* if no space is currently available.
111	>	*
112	>	* @param e the element to add
113	>	* @return {@code true} (as specified by {@link Collection#add})
114	>	* @throws IllegalStateException if the element cannot be added at this
115	>	*         time due to capacity restrictions
116	>	* @throws ClassCastException if the class of the specified element
117	>	*         prevents it from being added to this queue
118	>	* @throws NullPointerException if the specified element is null and
119	>	*         this queue does not permit null elements
120	>	* @throws IllegalArgumentException if some property of this element
121	>	*         prevents it from being added to this queue
122	>	*/
123	>	boolean add(E e);
124	>
125	>	/**
126	>	* Inserts the specified element into this queue if it is possible to do
127	>	* so immediately without violating capacity restrictions.
128	>	* When using a capacity-restricted queue, this method is generally
129	>	* preferable to {@link #add}, which can fail to insert an element only
130	>	* by throwing an exception.
131		*
132	<	* @param element the element to add.
133	<	* @return true if it was possible to add the element to the queue.
132	>	* @param e the element to add
133	>	* @return {@code true} if the element was added to this queue, else
134	>	*         {@code false}
135	>	* @throws ClassCastException if the class of the specified element
136	>	*         prevents it from being added to this queue
137	>	* @throws NullPointerException if the specified element is null and
138	>	*         this queue does not permit null elements
139	>	* @throws IllegalArgumentException if some property of this element
140	>	*         prevents it from being added to this queue
141		*/
142	<	public boolean offer(E element);
142	>	boolean offer(E e);
143
144		/**
145	<	* Remove and return an element from the queue if one is available.
145	>	* Retrieves and removes the head of this queue.  This method differs
146	>	* from {@link #poll() poll()} only in that it throws an exception if
147	>	* this queue is empty.
148		*
149	<	* @return an element previously on the queue, or <tt>null</tt> if the
150	<	*         queue is empty.
149	>	* @return the head of this queue
150	>	* @throws NoSuchElementException if this queue is empty
151		*/
152	<	public E poll();
152	>	E remove();
153
154		/**
155	<	* Remove and return an element from the queue.  This method differs
156	<	* from the <tt>poll</tt> method in that it throws an exception if the
87	<	* queue is empty.
155	>	* Retrieves and removes the head of this queue,
156	>	* or returns {@code null} if this queue is empty.
157		*
158	<	* @return an element previously on the queue.
90	<	* @throws NoSuchElementException if the queue is empty.
158	>	* @return the head of this queue, or {@code null} if this queue is empty
159		*/
160	<	public E remove() throws NoSuchElementException;
160	>	E poll();
161
162		/**
163	<	* Return, but do not remove, an element from the queue, or <tt>null</tt>
164	<	* if the queue is empty.  This method returns the same object reference
165	<	* that would be returned by by the <tt>poll</tt> method.  The two methods
98	<	* differ in that this method does not remove the element from the queue.
163	>	* Retrieves, but does not remove, the head of this queue.  This method
164	>	* differs from {@link #peek peek} only in that it throws an exception
165	>	* if this queue is empty.
166		*
167	<	* @return an element on the queue, or <tt>null</tt> if the queue is empty.
167	>	* @return the head of this queue
168	>	* @throws NoSuchElementException if this queue is empty
169		*/
170	<	public E peek();
170	>	E element();
171
172		/**
173	<	* Return, but do not remove, an element from the queue.  This method
174	<	* differs from the <tt>peek</tt> method in that it throws an exception if
107	<	* the queue is empty.
173	>	* Retrieves, but does not remove, the head of this queue,
174	>	* or returns {@code null} if this queue is empty.
175		*
176	<	* @return an element on the queue.
110	<	* @throws NoSuchElementException if the queue is empty.
176	>	* @return the head of this queue, or {@code null} if this queue is empty
177		*/
178	<	public E element() throws NoSuchElementException;
178	>	E peek();
179		}

Diff Legend

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