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

Diff Legend

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