Parent Directory
|
Revision Log
Revision 1.47 - (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 : | jsr166 | 1.36 | * http://creativecommons.org/publicdomain/zero/1.0/ |
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 : | jsr166 | 1.45 | * 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 : | dl | 1.23 | * |
20 : | jsr166 | 1.28 | * <table BORDER CELLPADDING=3 CELLSPACING=1> |
21 : | jsr166 | 1.39 | * <caption>Summary of Queue methods</caption> |
22 : | dl | 1.23 | * <tr> |
23 : | dl | 1.24 | * <td></td> |
24 : | jsr166 | 1.47 | * <td style="text-align:center"><em>Throws exception</em></td> |
25 : | * <td style="text-align:center"><em>Returns special value</em></td> | ||
26 : | dl | 1.23 | * </tr> |
27 : | * <tr> | ||
28 : | dl | 1.24 | * <td><b>Insert</b></td> |
29 : | jsr166 | 1.45 | * <td>{@link #add(Object) add(e)}</td> |
30 : | * <td>{@link #offer(Object) offer(e)}</td> | ||
31 : | dl | 1.23 | * </tr> |
32 : | * <tr> | ||
33 : | dl | 1.24 | * <td><b>Remove</b></td> |
34 : | jsr166 | 1.45 | * <td>{@link #remove() remove()}</td> |
35 : | * <td>{@link #poll() poll()}</td> | ||
36 : | dl | 1.23 | * </tr> |
37 : | * <tr> | ||
38 : | dl | 1.24 | * <td><b>Examine</b></td> |
39 : | jsr166 | 1.45 | * <td>{@link #element() element()}</td> |
40 : | * <td>{@link #peek() peek()}</td> | ||
41 : | dl | 1.23 | * </tr> |
42 : | dl | 1.24 | * </table> |
43 : | dholmes | 1.8 | * |
44 : | tim | 1.2 | * <p>Queues typically, but do not necessarily, order elements in a |
45 : | dl | 1.5 | * FIFO (first-in-first-out) manner. Among the exceptions are |
46 : | * priority queues, which order elements according to a supplied | ||
47 : | dholmes | 1.8 | * comparator, or the elements' natural ordering, and LIFO queues (or |
48 : | * stacks) which order the elements LIFO (last-in-first-out). | ||
49 : | dl | 1.17 | * Whatever the ordering used, the <em>head</em> of the queue is that |
50 : | jsr166 | 1.45 | * element which would be removed by a call to {@link #remove()} or |
51 : | dl | 1.17 | * {@link #poll()}. In a FIFO queue, all new elements are inserted at |
52 : | jsr166 | 1.37 | * the <em>tail</em> of the queue. Other kinds of queues may use |
53 : | jsr166 | 1.38 | * different placement rules. Every {@code Queue} implementation |
54 : | dl | 1.17 | * must specify its ordering properties. |
55 : | * | ||
56 : | * <p>The {@link #offer offer} method inserts an element if possible, | ||
57 : | jsr166 | 1.38 | * otherwise returning {@code false}. This differs from the {@link |
58 : | dl | 1.17 | * java.util.Collection#add Collection.add} method, which can fail to |
59 : | * add an element only by throwing an unchecked exception. The | ||
60 : | jsr166 | 1.38 | * {@code offer} method is designed for use when failure is a normal, |
61 : | dl | 1.17 | * rather than exceptional occurrence, for example, in fixed-capacity |
62 : | * (or "bounded") queues. | ||
63 : | tim | 1.9 | * |
64 : | dl | 1.7 | * <p>The {@link #remove()} and {@link #poll()} methods remove and |
65 : | dholmes | 1.8 | * return the head of the queue. |
66 : | * Exactly which element is removed from the queue is a | ||
67 : | dl | 1.7 | * function of the queue's ordering policy, which differs from |
68 : | jsr166 | 1.38 | * 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 : | tim | 1.1 | * |
73 : | dholmes | 1.8 | * <p>The {@link #element()} and {@link #peek()} methods return, but do |
74 : | dholmes | 1.10 | * not remove, the head of the queue. |
75 : | tim | 1.1 | * |
76 : | jsr166 | 1.38 | * <p>The {@code Queue} interface does not define the <i>blocking queue |
77 : | tim | 1.2 | * 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 : | jsr166 | 1.38 | * <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 : | dl | 1.7 | * indicate that the queue contains no elements. |
89 : | tim | 1.2 | * |
90 : | jsr166 | 1.38 | * <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 : | dl | 1.16 | * always well-defined for queues with the same elements but different |
95 : | * ordering properties. | ||
96 : | * | ||
97 : | tim | 1.2 | * <p>This interface is a member of the |
98 : | jsr166 | 1.46 | * <a href="{@docRoot}/java/util/package-summary.html#CollectionsFramework"> |
99 : | tim | 1.2 | * Java Collections Framework</a>. |
100 : | * | ||
101 : | dl | 1.7 | * @since 1.5 |
102 : | * @author Doug Lea | ||
103 : | jsr166 | 1.42 | * @param <E> the type of elements held in this queue |
104 : | tim | 1.2 | */ |
105 : | tim | 1.1 | public interface Queue<E> extends Collection<E> { |
106 : | /** | ||
107 : | jsr166 | 1.29 | * Inserts the specified element into this queue if it is possible to do so |
108 : | * immediately without violating capacity restrictions, returning | ||
109 : | jsr166 | 1.38 | * {@code true} upon success and throwing an {@code IllegalStateException} |
110 : | jsr166 | 1.29 | * if no space is currently available. |
111 : | * | ||
112 : | * @param e the element to add | ||
113 : | jsr166 | 1.38 | * @return {@code true} (as specified by {@link Collection#add}) |
114 : | jsr166 | 1.29 | * @throws IllegalStateException if the element cannot be added at this |
115 : | * time due to capacity restrictions | ||
116 : | jsr166 | 1.30 | * @throws ClassCastException if the class of the specified element |
117 : | * prevents it from being added to this queue | ||
118 : | jsr166 | 1.29 | * @throws NullPointerException if the specified element is null and |
119 : | jsr166 | 1.34 | * this queue does not permit null elements |
120 : | jsr166 | 1.29 | * @throws IllegalArgumentException if some property of this element |
121 : | * prevents it from being added to this queue | ||
122 : | tim | 1.2 | */ |
123 : | jsr166 | 1.29 | boolean add(E e); |
124 : | tim | 1.1 | |
125 : | /** | ||
126 : | jsr166 | 1.29 | * Inserts the specified element into this queue if it is possible to do |
127 : | * so immediately without violating capacity restrictions. | ||
128 : | jsr166 | 1.31 | * When using a capacity-restricted queue, this method is generally |
129 : | jsr166 | 1.29 | * preferable to {@link #add}, which can fail to insert an element only |
130 : | * by throwing an exception. | ||
131 : | tim | 1.2 | * |
132 : | jsr166 | 1.29 | * @param e the element to add |
133 : | jsr166 | 1.38 | * @return {@code true} if the element was added to this queue, else |
134 : | * {@code false} | ||
135 : | jsr166 | 1.30 | * @throws ClassCastException if the class of the specified element |
136 : | * prevents it from being added to this queue | ||
137 : | jsr166 | 1.29 | * @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 : | tim | 1.2 | */ |
142 : | jsr166 | 1.29 | boolean offer(E e); |
143 : | tim | 1.1 | |
144 : | /** | ||
145 : | jsr166 | 1.29 | * Retrieves and removes the head of this queue. This method differs |
146 : | jsr166 | 1.45 | * from {@link #poll() poll()} only in that it throws an exception if |
147 : | * this queue is empty. | ||
148 : | tim | 1.2 | * |
149 : | jsr166 | 1.29 | * @return the head of this queue |
150 : | * @throws NoSuchElementException if this queue is empty | ||
151 : | tim | 1.2 | */ |
152 : | tim | 1.9 | E remove(); |
153 : | tim | 1.1 | |
154 : | /** | ||
155 : | jsr166 | 1.29 | * Retrieves and removes the head of this queue, |
156 : | jsr166 | 1.38 | * or returns {@code null} if this queue is empty. |
157 : | tim | 1.2 | * |
158 : | jsr166 | 1.38 | * @return the head of this queue, or {@code null} if this queue is empty |
159 : | tim | 1.2 | */ |
160 : | jsr166 | 1.29 | E poll(); |
161 : | tim | 1.1 | |
162 : | /** | ||
163 : | dholmes | 1.14 | * Retrieves, but does not remove, the head of this queue. This method |
164 : | jsr166 | 1.33 | * differs from {@link #peek peek} only in that it throws an exception |
165 : | * if this queue is empty. | ||
166 : | tim | 1.2 | * |
167 : | jsr166 | 1.29 | * @return the head of this queue |
168 : | * @throws NoSuchElementException if this queue is empty | ||
169 : | tim | 1.2 | */ |
170 : | tim | 1.9 | E element(); |
171 : | jsr166 | 1.29 | |
172 : | /** | ||
173 : | * Retrieves, but does not remove, the head of this queue, | ||
174 : | jsr166 | 1.38 | * or returns {@code null} if this queue is empty. |
175 : | jsr166 | 1.29 | * |
176 : | jsr166 | 1.38 | * @return the head of this queue, or {@code null} if this queue is empty |
177 : | jsr166 | 1.29 | */ |
178 : | E peek(); | ||
179 : | tim | 1.1 | } |
Doug Lea | ViewVC Help |
Powered by ViewVC 1.0.8 |