Parent Directory
|
Revision Log
Revision 1.30 - (view) (download)
1 : | dl | 1.3 | /* |
2 : | * Written by Doug Lea with assistance from members of JCP JSR-166 | ||
3 : | dl | 1.22 | * Expert Group and released to the public domain, as explained at |
4 : | * http://creativecommons.org/licenses/publicdomain | ||
5 : | dl | 1.3 | */ |
6 : | |||
7 : | tim | 1.1 | package java.util; |
8 : | |||
9 : | /** | ||
10 : | dholmes | 1.8 | * A collection designed for holding elements prior to processing. |
11 : | dl | 1.24 | * Besides basic {@link java.util.Collection Collection} operations, |
12 : | * queues provide additional insertion, extraction, and inspection | ||
13 : | * operations. Each of these methods exists in two forms: one throws | ||
14 : | * an exception if the operation fails, the other returns a special | ||
15 : | * value (either <tt>null</tt> or <tt>false</tt>, depending on the | ||
16 : | * operation). The latter form of the insert operation is designed | ||
17 : | * specifically for use with capacity-restricted <tt>Queue</tt> | ||
18 : | * implementations; in most implementations, insert operations cannot | ||
19 : | * fail. | ||
20 : | dl | 1.23 | * |
21 : | jsr166 | 1.28 | * <p> |
22 : | * <table BORDER CELLPADDING=3 CELLSPACING=1> | ||
23 : | dl | 1.23 | * <tr> |
24 : | dl | 1.24 | * <td></td> |
25 : | * <td ALIGN=CENTER><em>Throws exception</em></td> | ||
26 : | jsr166 | 1.29 | * <td ALIGN=CENTER><em>Special value</em></td> |
27 : | dl | 1.23 | * </tr> |
28 : | * <tr> | ||
29 : | dl | 1.24 | * <td><b>Insert</b></td> |
30 : | * <td>{@link #add add(e)}</td> | ||
31 : | * <td>{@link #offer offer(e)}</td> | ||
32 : | dl | 1.23 | * </tr> |
33 : | * <tr> | ||
34 : | dl | 1.24 | * <td><b>Remove</b></td> |
35 : | * <td>{@link #remove remove()}</td> | ||
36 : | * <td>{@link #poll poll()}</td> | ||
37 : | dl | 1.23 | * </tr> |
38 : | * <tr> | ||
39 : | dl | 1.24 | * <td><b>Examine</b></td> |
40 : | * <td>{@link #element element()}</td> | ||
41 : | * <td>{@link #peek peek()}</td> | ||
42 : | dl | 1.23 | * </tr> |
43 : | dl | 1.24 | * </table> |
44 : | dholmes | 1.8 | * |
45 : | tim | 1.2 | * <p>Queues typically, but do not necessarily, order elements in a |
46 : | dl | 1.5 | * FIFO (first-in-first-out) manner. Among the exceptions are |
47 : | * priority queues, which order elements according to a supplied | ||
48 : | dholmes | 1.8 | * comparator, or the elements' natural ordering, and LIFO queues (or |
49 : | * stacks) which order the elements LIFO (last-in-first-out). | ||
50 : | dl | 1.17 | * Whatever the ordering used, the <em>head</em> of the queue is that |
51 : | * element which would be removed by a call to {@link #remove() } or | ||
52 : | * {@link #poll()}. In a FIFO queue, all new elements are inserted at | ||
53 : | * the <em> tail</em> of the queue. Other kinds of queues may use | ||
54 : | * different placement rules. Every <tt>Queue</tt> implementation | ||
55 : | * must specify its ordering properties. | ||
56 : | * | ||
57 : | * <p>The {@link #offer offer} method inserts an element if possible, | ||
58 : | * otherwise returning <tt>false</tt>. This differs from the {@link | ||
59 : | * java.util.Collection#add Collection.add} method, which can fail to | ||
60 : | * add an element only by throwing an unchecked exception. The | ||
61 : | * <tt>offer</tt> method is designed for use when failure is a normal, | ||
62 : | * rather than exceptional occurrence, for example, in fixed-capacity | ||
63 : | * (or "bounded") queues. | ||
64 : | tim | 1.9 | * |
65 : | dl | 1.7 | * <p>The {@link #remove()} and {@link #poll()} methods remove and |
66 : | dholmes | 1.8 | * return the head of the queue. |
67 : | * Exactly which element is removed from the queue is a | ||
68 : | dl | 1.7 | * function of the queue's ordering policy, which differs from |
69 : | dholmes | 1.8 | * implementation to implementation. The <tt>remove()</tt> and |
70 : | dl | 1.7 | * <tt>poll()</tt> methods differ only in their behavior when the |
71 : | * queue is empty: the <tt>remove()</tt> method throws an exception, | ||
72 : | * while the <tt>poll()</tt> method returns <tt>null</tt>. | ||
73 : | tim | 1.1 | * |
74 : | dholmes | 1.8 | * <p>The {@link #element()} and {@link #peek()} methods return, but do |
75 : | dholmes | 1.10 | * not remove, the head of the queue. |
76 : | tim | 1.1 | * |
77 : | tim | 1.2 | * <p>The <tt>Queue</tt> interface does not define the <i>blocking queue |
78 : | * methods</i>, which are common in concurrent programming. These methods, | ||
79 : | * which wait for elements to appear or for space to become available, are | ||
80 : | * defined in the {@link java.util.concurrent.BlockingQueue} interface, which | ||
81 : | * extends this interface. | ||
82 : | * | ||
83 : | dl | 1.7 | * <p><tt>Queue</tt> implementations generally do not allow insertion |
84 : | * of <tt>null</tt> elements, although some implementations, such as | ||
85 : | brian | 1.6 | * {@link LinkedList}, do not prohibit insertion of <tt>null</tt>. |
86 : | dl | 1.7 | * Even in the implementations that permit it, <tt>null</tt> should |
87 : | * not be inserted into a <tt>Queue</tt>, as <tt>null</tt> is also | ||
88 : | * used as a special return value by the <tt>poll</tt> method to | ||
89 : | * indicate that the queue contains no elements. | ||
90 : | tim | 1.2 | * |
91 : | dl | 1.16 | * <p><tt>Queue</tt> implementations generally do not define |
92 : | * element-based versions of methods <tt>equals</tt> and | ||
93 : | * <tt>hashCode</tt> but instead inherit the identity based versions | ||
94 : | * from class <tt>Object</tt>, because element-based equality is not | ||
95 : | * always well-defined for queues with the same elements but different | ||
96 : | * ordering properties. | ||
97 : | * | ||
98 : | * | ||
99 : | tim | 1.2 | * <p>This interface is a member of the |
100 : | * <a href="{@docRoot}/../guide/collections/index.html"> | ||
101 : | * Java Collections Framework</a>. | ||
102 : | * | ||
103 : | tim | 1.11 | * @see java.util.Collection |
104 : | tim | 1.2 | * @see LinkedList |
105 : | * @see PriorityQueue | ||
106 : | dholmes | 1.15 | * @see java.util.concurrent.LinkedBlockingQueue |
107 : | tim | 1.2 | * @see java.util.concurrent.BlockingQueue |
108 : | * @see java.util.concurrent.ArrayBlockingQueue | ||
109 : | * @see java.util.concurrent.LinkedBlockingQueue | ||
110 : | * @see java.util.concurrent.PriorityBlockingQueue | ||
111 : | dl | 1.7 | * @since 1.5 |
112 : | * @author Doug Lea | ||
113 : | dl | 1.21 | * @param <E> the type of elements held in this collection |
114 : | tim | 1.2 | */ |
115 : | tim | 1.1 | public interface Queue<E> extends Collection<E> { |
116 : | /** | ||
117 : | jsr166 | 1.29 | * Inserts the specified element into this queue if it is possible to do so |
118 : | * immediately without violating capacity restrictions, returning | ||
119 : | * <tt>true</tt> upon success and throwing an <tt>IllegalStateException</tt> | ||
120 : | * if no space is currently available. | ||
121 : | * | ||
122 : | * @param e the element to add | ||
123 : | * @return <tt>true</tt> (as per the spec for {@link Collection#add}) | ||
124 : | * @throws IllegalStateException if the element cannot be added at this | ||
125 : | * time due to capacity restrictions | ||
126 : | jsr166 | 1.30 | * @throws ClassCastException if the class of the specified element |
127 : | * prevents it from being added to this queue | ||
128 : | jsr166 | 1.29 | * @throws NullPointerException if the specified element is null and |
129 : | * this queue not permit null elements | ||
130 : | * @throws IllegalArgumentException if some property of this element | ||
131 : | * prevents it from being added to this queue | ||
132 : | tim | 1.2 | */ |
133 : | jsr166 | 1.29 | boolean add(E e); |
134 : | tim | 1.1 | |
135 : | /** | ||
136 : | jsr166 | 1.29 | * Inserts the specified element into this queue if it is possible to do |
137 : | * so immediately without violating capacity restrictions. | ||
138 : | * When using a capacity-restricted deque, this method is generally | ||
139 : | * preferable to {@link #add}, which can fail to insert an element only | ||
140 : | * by throwing an exception. | ||
141 : | tim | 1.2 | * |
142 : | jsr166 | 1.29 | * @param e the element to add |
143 : | * @return <tt>true</tt> if the element was added to this queue, else | ||
144 : | * <tt>false</tt> | ||
145 : | jsr166 | 1.30 | * @throws ClassCastException if the class of the specified element |
146 : | * prevents it from being added to this queue | ||
147 : | jsr166 | 1.29 | * @throws NullPointerException if the specified element is null and |
148 : | * this queue does not permit null elements | ||
149 : | * @throws IllegalArgumentException if some property of this element | ||
150 : | * prevents it from being added to this queue | ||
151 : | tim | 1.2 | */ |
152 : | jsr166 | 1.29 | boolean offer(E e); |
153 : | tim | 1.1 | |
154 : | /** | ||
155 : | jsr166 | 1.29 | * Retrieves and removes the head of this queue. This method differs |
156 : | * from {@link #poll} only in that it throws an exception if this queue | ||
157 : | * is empty. | ||
158 : | tim | 1.2 | * |
159 : | jsr166 | 1.29 | * @return the head of this queue |
160 : | * @throws NoSuchElementException if this queue is empty | ||
161 : | tim | 1.2 | */ |
162 : | tim | 1.9 | E remove(); |
163 : | tim | 1.1 | |
164 : | /** | ||
165 : | jsr166 | 1.29 | * Retrieves and removes the head of this queue, |
166 : | * or returns <tt>null</tt> if this queue is empty. | ||
167 : | tim | 1.2 | * |
168 : | jsr166 | 1.29 | * @return the head of this queue, or <tt>null</tt> if this queue is empty |
169 : | tim | 1.2 | */ |
170 : | jsr166 | 1.29 | E poll(); |
171 : | tim | 1.1 | |
172 : | /** | ||
173 : | dholmes | 1.14 | * Retrieves, but does not remove, the head of this queue. This method |
174 : | jsr166 | 1.29 | * differs from {@link #peek} only in that it throws an exception if |
175 : | * this queue is empty. | ||
176 : | tim | 1.2 | * |
177 : | jsr166 | 1.29 | * @return the head of this queue |
178 : | * @throws NoSuchElementException if this queue is empty | ||
179 : | tim | 1.2 | */ |
180 : | tim | 1.9 | E element(); |
181 : | jsr166 | 1.29 | |
182 : | /** | ||
183 : | * Retrieves, but does not remove, the head of this queue, | ||
184 : | * or returns <tt>null</tt> if this queue is empty. | ||
185 : | * | ||
186 : | * @return the head of this queue, or <tt>null</tt> if this queue is empty | ||
187 : | */ | ||
188 : | E peek(); | ||
189 : | tim | 1.1 | } |
Doug Lea | ViewVC Help |
Powered by ViewVC 1.0.8 |