1 /*
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
3 *
4 * This code is free software; you can redistribute it and/or modify it
5 * under the terms of the GNU General Public License version 2 only, as
6 * published by the Free Software Foundation. Oracle designates this
7 * particular file as subject to the "Classpath" exception as provided
8 * by Oracle in the LICENSE file that accompanied this code.
9 *
10 * This code is distributed in the hope that it will be useful, but WITHOUT
11 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
13 * version 2 for more details (a copy is included in the LICENSE file that
14 * accompanied this code).
15 *
16 * You should have received a copy of the GNU General Public License version
17 * 2 along with this work; if not, write to the Free Software Foundation,
18 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
19 *
20 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
21 * or visit www.oracle.com if you need additional information or have any
22 * questions.
23 */
24
25 /*
26 * This file is available under and governed by the GNU General Public
27 * License version 2 only, as published by the Free Software Foundation.
28 * However, the following notice accompanied the original version of this
29 * file:
30 *
31 * Written by Doug Lea with assistance from members of JCP JSR-166
32 * Expert Group and released to the public domain, as explained at
33 * http://creativecommons.org/publicdomain/zero/1.0/
34 */
35
36 package java.util.concurrent;
37
38 import java.util.Deque;
39 import java.util.Iterator;
40 import java.util.NoSuchElementException;
41
42 /**
43 * A {@link Deque} that additionally supports blocking operations that wait
44 * for the deque to become non-empty when retrieving an element, and wait for
45 * space to become available in the deque when storing an element.
46 *
47 * <p>{@code BlockingDeque} methods come in four forms, with different ways
48 * of handling operations that cannot be satisfied immediately, but may be
49 * satisfied at some point in the future:
50 * one throws an exception, the second returns a special value (either
51 * {@code null} or {@code false}, depending on the operation), the third
52 * blocks the current thread indefinitely until the operation can succeed,
53 * and the fourth blocks for only a given maximum time limit before giving
54 * up. These methods are summarized in the following table:
55 *
56 * <table class="plain">
57 * <caption>Summary of BlockingDeque methods</caption>
58 * <tr>
59 * <th id="First" colspan="5"> First Element (Head)</th>
60 * </tr>
61 * <tr>
62 * <td></td>
63 * <th id="FThrow" style="font-weight:normal; font-style: italic">Throws exception</th>
64 * <th id="FValue" style="font-weight:normal; font-style: italic">Special value</th>
65 * <th id="FBlock" style="font-weight:normal; font-style: italic">Blocks</th>
66 * <th id="FTimes" style="font-weight:normal; font-style: italic">Times out</th>
67 * </tr>
68 * <tr>
69 * <th id="FInsert" style="text-align:left">Insert</th>
70 * <td headers="First FInsert FThrow">{@link #addFirst(Object) addFirst(e)}</td>
71 * <td headers="First FInsert FValue">{@link #offerFirst(Object) offerFirst(e)}</td>
72 * <td headers="First FInsert FBlock">{@link #putFirst(Object) putFirst(e)}</td>
73 * <td headers="First FInsert FTimes">{@link #offerFirst(Object, long, TimeUnit) offerFirst(e, time, unit)}</td>
74 * </tr>
75 * <tr>
76 * <th id="FRemove" style="text-align:left">Remove</th>
77 * <td headers="First FRemove FThrow">{@link #removeFirst() removeFirst()}</td>
78 * <td headers="First FRemove FValue">{@link #pollFirst() pollFirst()}</td>
79 * <td headers="First FRemove FBlock">{@link #takeFirst() takeFirst()}</td>
80 * <td headers="First FRemove FTimes">{@link #pollFirst(long, TimeUnit) pollFirst(time, unit)}</td>
81 * </tr>
82 * <tr>
83 * <th id="FExamine" style="text-align:left">Examine</th>
84 * <td headers="First FExamine FThrow">{@link #getFirst() getFirst()}</td>
85 * <td headers="First FExamine FValue">{@link #peekFirst() peekFirst()}</td>
86 * <td headers="First FExamine FBlock" style="font-style:italic">not applicable</td>
87 * <td headers="First FExamine FTimes" style="font-style:italic">not applicable</td>
88 * </tr>
89 * <tr>
90 * <th id="Last" colspan="5"> Last Element (Tail)</th>
91 * </tr>
92 * <tr>
93 * <td></td>
94 * <th id="LThrow" style="font-weight:normal; font-style: italic">Throws exception</th>
95 * <th id="LValue" style="font-weight:normal; font-style: italic">Special value</th>
96 * <th id="LBlock" style="font-weight:normal; font-style: italic">Blocks</th>
97 * <th id="LTimes" style="font-weight:normal; font-style: italic">Times out</th>
98 * </tr>
99 * <tr>
100 * <th id="LInsert" style="text-align:left">Insert</th>
101 * <td headers="Last LInsert LThrow">{@link #addLast(Object) addLast(e)}</td>
102 * <td headers="Last LInsert LValue">{@link #offerLast(Object) offerLast(e)}</td>
103 * <td headers="Last LInsert LBlock">{@link #putLast(Object) putLast(e)}</td>
104 * <td headers="Last LInsert LTimes">{@link #offerLast(Object, long, TimeUnit) offerLast(e, time, unit)}</td>
105 * </tr>
106 * <tr>
107 * <th id="LRemove" style="text-align:left">Remove</th>
108 * <td headers="Last LRemove LThrow">{@link #removeLast() removeLast()}</td>
109 * <td headers="Last LRemove LValue">{@link #pollLast() pollLast()}</td>
110 * <td headers="Last LRemove LBlock">{@link #takeLast() takeLast()}</td>
111 * <td headers="Last LRemove LTimes">{@link #pollLast(long, TimeUnit) pollLast(time, unit)}</td>
112 * </tr>
113 * <tr>
114 * <th id="LExamine" style="text-align:left">Examine</th>
115 * <td headers="Last LExamine LThrow">{@link #getLast() getLast()}</td>
116 * <td headers="Last LExamine LValue">{@link #peekLast() peekLast()}</td>
117 * <td headers="Last LExamine LBlock" style="font-style:italic">not applicable</td>
118 * <td headers="Last LExamine LTimes" style="font-style:italic">not applicable</td>
119 * </tr>
120 * </table>
121 *
122 * <p>Like any {@link BlockingQueue}, a {@code BlockingDeque} is thread safe,
123 * does not permit null elements, and may (or may not) be
124 * capacity-constrained.
125 *
126 * <p>A {@code BlockingDeque} implementation may be used directly as a FIFO
127 * {@code BlockingQueue}. The methods inherited from the
128 * {@code BlockingQueue} interface are precisely equivalent to
129 * {@code BlockingDeque} methods as indicated in the following table:
130 *
131 * <table class="plain">
132 * <caption>Comparison of BlockingQueue and BlockingDeque methods</caption>
133 * <tr>
134 * <td></td>
135 * <th id="BQueue"> {@code BlockingQueue} Method</th>
136 * <th id="BDeque"> Equivalent {@code BlockingDeque} Method</th>
137 * </tr>
138 * <tr>
139 * <th id="Insert" rowspan="4" style="text-align:left; vertical-align:top">Insert</th>
140 * <th id="add" style="font-weight:normal; text-align:left">{@link #add(Object) add(e)}</th>
141 * <td headers="Insert BDeque add">{@link #addLast(Object) addLast(e)}</td>
142 * </tr>
143 * <tr>
144 * <th id="offer1" style="font-weight:normal; text-align:left">{@link #offer(Object) offer(e)}</th>
145 * <td headers="Insert BDeque offer1">{@link #offerLast(Object) offerLast(e)}</td>
146 * </tr>
147 * <tr>
148 * <th id="put" style="font-weight:normal; text-align:left">{@link #put(Object) put(e)}</th>
149 * <td headers="Insert BDeque put">{@link #putLast(Object) putLast(e)}</td>
150 * </tr>
151 * <tr>
152 * <th id="offer2" style="font-weight:normal; text-align:left">{@link #offer(Object, long, TimeUnit) offer(e, time, unit)}</th>
153 * <td headers="Insert BDeque offer2">{@link #offerLast(Object, long, TimeUnit) offerLast(e, time, unit)}</td>
154 * </tr>
155 * <tr>
156 * <th id="Remove" rowspan="4" style="text-align:left; vertical-align:top">Remove</th>
157 * <th id="remove" style="font-weight:normal; text-align:left">{@link #remove() remove()}</th>
158 * <td headers="Remove BDeque remove">{@link #removeFirst() removeFirst()}</td>
159 * </tr>
160 * <tr>
161 * <th id="poll1" style="font-weight:normal; text-align:left">{@link #poll() poll()}</th>
162 * <td headers="Remove BDeque poll1">{@link #pollFirst() pollFirst()}</td>
163 * </tr>
164 * <tr>
165 * <th id="take" style="font-weight:normal; text-align:left">{@link #take() take()}</th>
166 * <td headers="Remove BDeque take">{@link #takeFirst() takeFirst()}</td>
167 * </tr>
168 * <tr>
169 * <th id="poll2" style="font-weight:normal; text-align:left">{@link #poll(long, TimeUnit) poll(time, unit)}</th>
170 * <td headers="Remove BDeque poll2">{@link #pollFirst(long, TimeUnit) pollFirst(time, unit)}</td>
171 * </tr>
172 * <tr>
173 * <th id="Examine" rowspan="2" style="text-align:left; vertical-align:top">Examine</th>
174 * <th id="element" style="font-weight:normal; text-align:left">{@link #element() element()}</th>
175 * <td headers="Examine BDeque element">{@link #getFirst() getFirst()}</td>
176 * </tr>
177 * <tr>
178 * <th id="peek" style="font-weight:normal; text-align:left">{@link #peek() peek()}</th>
179 * <td headers="Examine BDeque peek">{@link #peekFirst() peekFirst()}</td>
180 * </tr>
181 * </table>
182 *
183 * <p>Memory consistency effects: As with other concurrent
184 * collections, actions in a thread prior to placing an object into a
185 * {@code BlockingDeque}
186 * <a href="package-summary.html#MemoryVisibility"><i>happen-before</i></a>
187 * actions subsequent to the access or removal of that element from
188 * the {@code BlockingDeque} in another thread.
189 *
190 * <p>This interface is a member of the
191 * <a href="{@docRoot}/java/util/package-summary.html#CollectionsFramework">
192 * Java Collections Framework</a>.
193 *
194 * @since 1.6
195 * @author Doug Lea
196 * @param <E> the type of elements held in this deque
197 */
198 public interface BlockingDeque<E> extends BlockingQueue<E>, Deque<E> {
199 /*
200 * We have "diamond" multiple interface inheritance here, and that
201 * introduces ambiguities. Methods might end up with different
202 * specs depending on the branch chosen by javadoc. Thus a lot of
203 * methods specs here are copied from superinterfaces.
204 */
205
206 /**
207 * Inserts the specified element at the front of this deque if it is
208 * possible to do so immediately without violating capacity restrictions,
209 * throwing an {@code IllegalStateException} if no space is currently
210 * available. When using a capacity-restricted deque, it is generally
211 * preferable to use {@link #offerFirst(Object) offerFirst}.
212 *
213 * @param e the element to add
214 * @throws IllegalStateException {@inheritDoc}
215 * @throws ClassCastException {@inheritDoc}
216 * @throws NullPointerException if the specified element is null
217 * @throws IllegalArgumentException {@inheritDoc}
218 */
219 void addFirst(E e);
220
221 /**
222 * Inserts the specified element at the end of this deque if it is
223 * possible to do so immediately without violating capacity restrictions,
224 * throwing an {@code IllegalStateException} if no space is currently
225 * available. When using a capacity-restricted deque, it is generally
226 * preferable to use {@link #offerLast(Object) offerLast}.
227 *
228 * @param e the element to add
229 * @throws IllegalStateException {@inheritDoc}
230 * @throws ClassCastException {@inheritDoc}
231 * @throws NullPointerException if the specified element is null
232 * @throws IllegalArgumentException {@inheritDoc}
233 */
234 void addLast(E e);
235
236 /**
237 * Inserts the specified element at the front of this deque if it is
238 * possible to do so immediately without violating capacity restrictions,
239 * returning {@code true} upon success and {@code false} if no space is
240 * currently available.
241 * When using a capacity-restricted deque, this method is generally
242 * preferable to the {@link #addFirst(Object) addFirst} method, which can
243 * fail to insert an element only by throwing an exception.
244 *
245 * @param e the element to add
246 * @throws ClassCastException {@inheritDoc}
247 * @throws NullPointerException if the specified element is null
248 * @throws IllegalArgumentException {@inheritDoc}
249 */
250 boolean offerFirst(E e);
251
252 /**
253 * Inserts the specified element at the end of this deque if it is
254 * possible to do so immediately without violating capacity restrictions,
255 * returning {@code true} upon success and {@code false} if no space is
256 * currently available.
257 * When using a capacity-restricted deque, this method is generally
258 * preferable to the {@link #addLast(Object) addLast} method, which can
259 * fail to insert an element only by throwing an exception.
260 *
261 * @param e the element to add
262 * @throws ClassCastException {@inheritDoc}
263 * @throws NullPointerException if the specified element is null
264 * @throws IllegalArgumentException {@inheritDoc}
265 */
266 boolean offerLast(E e);
267
268 /**
269 * Inserts the specified element at the front of this deque,
270 * waiting if necessary for space to become available.
271 *
272 * @param e the element to add
273 * @throws InterruptedException if interrupted while waiting
274 * @throws ClassCastException if the class of the specified element
275 * prevents it from being added to this deque
276 * @throws NullPointerException if the specified element is null
277 * @throws IllegalArgumentException if some property of the specified
278 * element prevents it from being added to this deque
279 */
280 void putFirst(E e) throws InterruptedException;
281
282 /**
283 * Inserts the specified element at the end of this deque,
284 * waiting if necessary for space to become available.
285 *
286 * @param e the element to add
287 * @throws InterruptedException if interrupted while waiting
288 * @throws ClassCastException if the class of the specified element
289 * prevents it from being added to this deque
290 * @throws NullPointerException if the specified element is null
291 * @throws IllegalArgumentException if some property of the specified
292 * element prevents it from being added to this deque
293 */
294 void putLast(E e) throws InterruptedException;
295
296 /**
297 * Inserts the specified element at the front of this deque,
298 * waiting up to the specified wait time if necessary for space to
299 * become available.
300 *
301 * @param e the element to add
302 * @param timeout how long to wait before giving up, in units of
303 * {@code unit}
304 * @param unit a {@code TimeUnit} determining how to interpret the
305 * {@code timeout} parameter
306 * @return {@code true} if successful, or {@code false} if
307 * the specified waiting time elapses before space is available
308 * @throws InterruptedException if interrupted while waiting
309 * @throws ClassCastException if the class of the specified element
310 * prevents it from being added to this deque
311 * @throws NullPointerException if the specified element is null
312 * @throws IllegalArgumentException if some property of the specified
313 * element prevents it from being added to this deque
314 */
315 boolean offerFirst(E e, long timeout, TimeUnit unit)
316 throws InterruptedException;
317
318 /**
319 * Inserts the specified element at the end of this deque,
320 * waiting up to the specified wait time if necessary for space to
321 * become available.
322 *
323 * @param e the element to add
324 * @param timeout how long to wait before giving up, in units of
325 * {@code unit}
326 * @param unit a {@code TimeUnit} determining how to interpret the
327 * {@code timeout} parameter
328 * @return {@code true} if successful, or {@code false} if
329 * the specified waiting time elapses before space is available
330 * @throws InterruptedException if interrupted while waiting
331 * @throws ClassCastException if the class of the specified element
332 * prevents it from being added to this deque
333 * @throws NullPointerException if the specified element is null
334 * @throws IllegalArgumentException if some property of the specified
335 * element prevents it from being added to this deque
336 */
337 boolean offerLast(E e, long timeout, TimeUnit unit)
338 throws InterruptedException;
339
340 /**
341 * Retrieves and removes the first element of this deque, waiting
342 * if necessary until an element becomes available.
343 *
344 * @return the head of this deque
345 * @throws InterruptedException if interrupted while waiting
346 */
347 E takeFirst() throws InterruptedException;
348
349 /**
350 * Retrieves and removes the last element of this deque, waiting
351 * if necessary until an element becomes available.
352 *
353 * @return the tail of this deque
354 * @throws InterruptedException if interrupted while waiting
355 */
356 E takeLast() throws InterruptedException;
357
358 /**
359 * Retrieves and removes the first element of this deque, waiting
360 * up to the specified wait time if necessary for an element to
361 * become available.
362 *
363 * @param timeout how long to wait before giving up, in units of
364 * {@code unit}
365 * @param unit a {@code TimeUnit} determining how to interpret the
366 * {@code timeout} parameter
367 * @return the head of this deque, or {@code null} if the specified
368 * waiting time elapses before an element is available
369 * @throws InterruptedException if interrupted while waiting
370 */
371 E pollFirst(long timeout, TimeUnit unit)
372 throws InterruptedException;
373
374 /**
375 * Retrieves and removes the last element of this deque, waiting
376 * up to the specified wait time if necessary for an element to
377 * become available.
378 *
379 * @param timeout how long to wait before giving up, in units of
380 * {@code unit}
381 * @param unit a {@code TimeUnit} determining how to interpret the
382 * {@code timeout} parameter
383 * @return the tail of this deque, or {@code null} if the specified
384 * waiting time elapses before an element is available
385 * @throws InterruptedException if interrupted while waiting
386 */
387 E pollLast(long timeout, TimeUnit unit)
388 throws InterruptedException;
389
390 /**
391 * Removes the first occurrence of the specified element from this deque.
392 * If the deque does not contain the element, it is unchanged.
393 * More formally, removes the first element {@code e} such that
394 * {@code o.equals(e)} (if such an element exists).
395 * Returns {@code true} if this deque contained the specified element
396 * (or equivalently, if this deque changed as a result of the call).
397 *
398 * @param o element to be removed from this deque, if present
399 * @return {@code true} if an element was removed as a result of this call
400 * @throws ClassCastException if the class of the specified element
401 * is incompatible with this deque
402 * (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
403 * @throws NullPointerException if the specified element is null
404 * (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
405 */
406 boolean removeFirstOccurrence(Object o);
407
408 /**
409 * Removes the last occurrence of the specified element from this deque.
410 * If the deque does not contain the element, it is unchanged.
411 * More formally, removes the last element {@code e} such that
412 * {@code o.equals(e)} (if such an element exists).
413 * Returns {@code true} if this deque contained the specified element
414 * (or equivalently, if this deque changed as a result of the call).
415 *
416 * @param o element to be removed from this deque, if present
417 * @return {@code true} if an element was removed as a result of this call
418 * @throws ClassCastException if the class of the specified element
419 * is incompatible with this deque
420 * (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
421 * @throws NullPointerException if the specified element is null
422 * (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
423 */
424 boolean removeLastOccurrence(Object o);
425
426 // *** BlockingQueue methods ***
427
428 /**
429 * Inserts the specified element into the queue represented by this deque
430 * (in other words, at the tail of this deque) if it is possible to do so
431 * immediately without violating capacity restrictions, returning
432 * {@code true} upon success and throwing an
433 * {@code IllegalStateException} if no space is currently available.
434 * When using a capacity-restricted deque, it is generally preferable to
435 * use {@link #offer(Object) offer}.
436 *
437 * <p>This method is equivalent to {@link #addLast(Object) addLast}.
438 *
439 * @param e the element to add
440 * @throws IllegalStateException {@inheritDoc}
441 * @throws ClassCastException if the class of the specified element
442 * prevents it from being added to this deque
443 * @throws NullPointerException if the specified element is null
444 * @throws IllegalArgumentException if some property of the specified
445 * element prevents it from being added to this deque
446 */
447 boolean add(E e);
448
449 /**
450 * Inserts the specified element into the queue represented by this deque
451 * (in other words, at the tail of this deque) if it is possible to do so
452 * immediately without violating capacity restrictions, returning
453 * {@code true} upon success and {@code false} if no space is currently
454 * available. When using a capacity-restricted deque, this method is
455 * generally preferable to the {@link #add} method, which can fail to
456 * insert an element only by throwing an exception.
457 *
458 * <p>This method is equivalent to {@link #offerLast(Object) offerLast}.
459 *
460 * @param e the element to add
461 * @throws ClassCastException if the class of the specified element
462 * prevents it from being added to this deque
463 * @throws NullPointerException if the specified element is null
464 * @throws IllegalArgumentException if some property of the specified
465 * element prevents it from being added to this deque
466 */
467 boolean offer(E e);
468
469 /**
470 * Inserts the specified element into the queue represented by this deque
471 * (in other words, at the tail of this deque), waiting if necessary for
472 * space to become available.
473 *
474 * <p>This method is equivalent to {@link #putLast(Object) putLast}.
475 *
476 * @param e the element to add
477 * @throws InterruptedException {@inheritDoc}
478 * @throws ClassCastException if the class of the specified element
479 * prevents it from being added to this deque
480 * @throws NullPointerException if the specified element is null
481 * @throws IllegalArgumentException if some property of the specified
482 * element prevents it from being added to this deque
483 */
484 void put(E e) throws InterruptedException;
485
486 /**
487 * Inserts the specified element into the queue represented by this deque
488 * (in other words, at the tail of this deque), waiting up to the
489 * specified wait time if necessary for space to become available.
490 *
491 * <p>This method is equivalent to
492 * {@link #offerLast(Object,long,TimeUnit) offerLast}.
493 *
494 * @param e the element to add
495 * @return {@code true} if the element was added to this deque, else
496 * {@code false}
497 * @throws InterruptedException {@inheritDoc}
498 * @throws ClassCastException if the class of the specified element
499 * prevents it from being added to this deque
500 * @throws NullPointerException if the specified element is null
501 * @throws IllegalArgumentException if some property of the specified
502 * element prevents it from being added to this deque
503 */
504 boolean offer(E e, long timeout, TimeUnit unit)
505 throws InterruptedException;
506
507 /**
508 * Retrieves and removes the head of the queue represented by this deque
509 * (in other words, the first element of this deque).
510 * This method differs from {@link #poll() poll()} only in that it
511 * throws an exception if this deque is empty.
512 *
513 * <p>This method is equivalent to {@link #removeFirst() removeFirst}.
514 *
515 * @return the head of the queue represented by this deque
516 * @throws NoSuchElementException if this deque is empty
517 */
518 E remove();
519
520 /**
521 * Retrieves and removes the head of the queue represented by this deque
522 * (in other words, the first element of this deque), or returns
523 * {@code null} if this deque is empty.
524 *
525 * <p>This method is equivalent to {@link #pollFirst()}.
526 *
527 * @return the head of this deque, or {@code null} if this deque is empty
528 */
529 E poll();
530
531 /**
532 * Retrieves and removes the head of the queue represented by this deque
533 * (in other words, the first element of this deque), waiting if
534 * necessary until an element becomes available.
535 *
536 * <p>This method is equivalent to {@link #takeFirst() takeFirst}.
537 *
538 * @return the head of this deque
539 * @throws InterruptedException if interrupted while waiting
540 */
541 E take() throws InterruptedException;
542
543 /**
544 * Retrieves and removes the head of the queue represented by this deque
545 * (in other words, the first element of this deque), waiting up to the
546 * specified wait time if necessary for an element to become available.
547 *
548 * <p>This method is equivalent to
549 * {@link #pollFirst(long,TimeUnit) pollFirst}.
550 *
551 * @return the head of this deque, or {@code null} if the
552 * specified waiting time elapses before an element is available
553 * @throws InterruptedException if interrupted while waiting
554 */
555 E poll(long timeout, TimeUnit unit)
556 throws InterruptedException;
557
558 /**
559 * Retrieves, but does not remove, the head of the queue represented by
560 * this deque (in other words, the first element of this deque).
561 * This method differs from {@link #peek() peek} only in that it throws an
562 * exception if this deque is empty.
563 *
564 * <p>This method is equivalent to {@link #getFirst() getFirst}.
565 *
566 * @return the head of this deque
567 * @throws NoSuchElementException if this deque is empty
568 */
569 E element();
570
571 /**
572 * Retrieves, but does not remove, the head of the queue represented by
573 * this deque (in other words, the first element of this deque), or
574 * returns {@code null} if this deque is empty.
575 *
576 * <p>This method is equivalent to {@link #peekFirst() peekFirst}.
577 *
578 * @return the head of this deque, or {@code null} if this deque is empty
579 */
580 E peek();
581
582 /**
583 * Removes the first occurrence of the specified element from this deque.
584 * If the deque does not contain the element, it is unchanged.
585 * More formally, removes the first element {@code e} such that
586 * {@code o.equals(e)} (if such an element exists).
587 * Returns {@code true} if this deque contained the specified element
588 * (or equivalently, if this deque changed as a result of the call).
589 *
590 * <p>This method is equivalent to
591 * {@link #removeFirstOccurrence(Object) removeFirstOccurrence}.
592 *
593 * @param o element to be removed from this deque, if present
594 * @return {@code true} if this deque changed as a result of the call
595 * @throws ClassCastException if the class of the specified element
596 * is incompatible with this deque
597 * (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
598 * @throws NullPointerException if the specified element is null
599 * (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
600 */
601 boolean remove(Object o);
602
603 /**
604 * Returns {@code true} if this deque contains the specified element.
605 * More formally, returns {@code true} if and only if this deque contains
606 * at least one element {@code e} such that {@code o.equals(e)}.
607 *
608 * @param o object to be checked for containment in this deque
609 * @return {@code true} if this deque contains the specified element
610 * @throws ClassCastException if the class of the specified element
611 * is incompatible with this deque
612 * (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
613 * @throws NullPointerException if the specified element is null
614 * (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
615 */
616 boolean contains(Object o);
617
618 /**
619 * Returns the number of elements in this deque.
620 *
621 * @return the number of elements in this deque
622 */
623 int size();
624
625 /**
626 * Returns an iterator over the elements in this deque in proper sequence.
627 * The elements will be returned in order from first (head) to last (tail).
628 *
629 * @return an iterator over the elements in this deque in proper sequence
630 */
631 Iterator<E> iterator();
632
633 // *** Stack methods ***
634
635 /**
636 * Pushes an element onto the stack represented by this deque (in other
637 * words, at the head of this deque) if it is possible to do so
638 * immediately without violating capacity restrictions, throwing an
639 * {@code IllegalStateException} if no space is currently available.
640 *
641 * <p>This method is equivalent to {@link #addFirst(Object) addFirst}.
642 *
643 * @throws IllegalStateException {@inheritDoc}
644 * @throws ClassCastException {@inheritDoc}
645 * @throws NullPointerException if the specified element is null
646 * @throws IllegalArgumentException {@inheritDoc}
647 */
648 void push(E e);
649 }