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 * <td style="text-align:center" COLSPAN = 5> <b>First Element (Head)</b></td>
60 * </tr>
61 * <tr>
62 * <td></td>
63 * <td style="text-align:center"><em>Throws exception</em></td>
64 * <td style="text-align:center"><em>Special value</em></td>
65 * <td style="text-align:center"><em>Blocks</em></td>
66 * <td style="text-align:center"><em>Times out</em></td>
67 * </tr>
68 * <tr>
69 * <td><b>Insert</b></td>
70 * <td>{@link #addFirst addFirst(e)}</td>
71 * <td>{@link #offerFirst(Object) offerFirst(e)}</td>
72 * <td>{@link #putFirst putFirst(e)}</td>
73 * <td>{@link #offerFirst(Object, long, TimeUnit) offerFirst(e, time, unit)}</td>
74 * </tr>
75 * <tr>
76 * <td><b>Remove</b></td>
77 * <td>{@link #removeFirst removeFirst()}</td>
78 * <td>{@link #pollFirst pollFirst()}</td>
79 * <td>{@link #takeFirst takeFirst()}</td>
80 * <td>{@link #pollFirst(long, TimeUnit) pollFirst(time, unit)}</td>
81 * </tr>
82 * <tr>
83 * <td><b>Examine</b></td>
84 * <td>{@link #getFirst getFirst()}</td>
85 * <td>{@link #peekFirst peekFirst()}</td>
86 * <td><em>not applicable</em></td>
87 * <td><em>not applicable</em></td>
88 * </tr>
89 * <tr>
90 * <td style="text-align:center" COLSPAN = 5> <b>Last Element (Tail)</b></td>
91 * </tr>
92 * <tr>
93 * <td></td>
94 * <td style="text-align:center"><em>Throws exception</em></td>
95 * <td style="text-align:center"><em>Special value</em></td>
96 * <td style="text-align:center"><em>Blocks</em></td>
97 * <td style="text-align:center"><em>Times out</em></td>
98 * </tr>
99 * <tr>
100 * <td><b>Insert</b></td>
101 * <td>{@link #addLast addLast(e)}</td>
102 * <td>{@link #offerLast(Object) offerLast(e)}</td>
103 * <td>{@link #putLast putLast(e)}</td>
104 * <td>{@link #offerLast(Object, long, TimeUnit) offerLast(e, time, unit)}</td>
105 * </tr>
106 * <tr>
107 * <td><b>Remove</b></td>
108 * <td>{@link #removeLast() removeLast()}</td>
109 * <td>{@link #pollLast() pollLast()}</td>
110 * <td>{@link #takeLast takeLast()}</td>
111 * <td>{@link #pollLast(long, TimeUnit) pollLast(time, unit)}</td>
112 * </tr>
113 * <tr>
114 * <td><b>Examine</b></td>
115 * <td>{@link #getLast getLast()}</td>
116 * <td>{@link #peekLast peekLast()}</td>
117 * <td><em>not applicable</em></td>
118 * <td><em>not applicable</em></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 style="text-align:center"> <b>{@code BlockingQueue} Method</b></td>
135 * <td style="text-align:center"> <b>Equivalent {@code BlockingDeque} Method</b></td>
136 * </tr>
137 * <tr>
138 * <td style="text-align:center" COLSPAN = 2> <b>Insert</b></td>
139 * </tr>
140 * <tr>
141 * <td>{@link #add(Object) add(e)}</td>
142 * <td>{@link #addLast(Object) addLast(e)}</td>
143 * </tr>
144 * <tr>
145 * <td>{@link #offer(Object) offer(e)}</td>
146 * <td>{@link #offerLast(Object) offerLast(e)}</td>
147 * </tr>
148 * <tr>
149 * <td>{@link #put(Object) put(e)}</td>
150 * <td>{@link #putLast(Object) putLast(e)}</td>
151 * </tr>
152 * <tr>
153 * <td>{@link #offer(Object, long, TimeUnit) offer(e, time, unit)}</td>
154 * <td>{@link #offerLast(Object, long, TimeUnit) offerLast(e, time, unit)}</td>
155 * </tr>
156 * <tr>
157 * <td style="text-align:center" COLSPAN = 2> <b>Remove</b></td>
158 * </tr>
159 * <tr>
160 * <td>{@link #remove() remove()}</td>
161 * <td>{@link #removeFirst() removeFirst()}</td>
162 * </tr>
163 * <tr>
164 * <td>{@link #poll() poll()}</td>
165 * <td>{@link #pollFirst() pollFirst()}</td>
166 * </tr>
167 * <tr>
168 * <td>{@link #take() take()}</td>
169 * <td>{@link #takeFirst() takeFirst()}</td>
170 * </tr>
171 * <tr>
172 * <td>{@link #poll(long, TimeUnit) poll(time, unit)}</td>
173 * <td>{@link #pollFirst(long, TimeUnit) pollFirst(time, unit)}</td>
174 * </tr>
175 * <tr>
176 * <td style="text-align:center" COLSPAN = 2> <b>Examine</b></td>
177 * </tr>
178 * <tr>
179 * <td>{@link #element() element()}</td>
180 * <td>{@link #getFirst() getFirst()}</td>
181 * </tr>
182 * <tr>
183 * <td>{@link #peek() peek()}</td>
184 * <td>{@link #peekFirst() peekFirst()}</td>
185 * </tr>
186 * </table>
187 *
188 * <p>Memory consistency effects: As with other concurrent
189 * collections, actions in a thread prior to placing an object into a
190 * {@code BlockingDeque}
191 * <a href="package-summary.html#MemoryVisibility"><i>happen-before</i></a>
192 * actions subsequent to the access or removal of that element from
193 * the {@code BlockingDeque} in another thread.
194 *
195 * <p>This interface is a member of the
196 * <a href="{@docRoot}/java/util/package-summary.html#CollectionsFramework">
197 * Java Collections Framework</a>.
198 *
199 * @since 1.6
200 * @author Doug Lea
201 * @param <E> the type of elements held in this deque
202 */
203 public interface BlockingDeque<E> extends BlockingQueue<E>, Deque<E> {
204 /*
205 * We have "diamond" multiple interface inheritance here, and that
206 * introduces ambiguities. Methods might end up with different
207 * specs depending on the branch chosen by javadoc. Thus a lot of
208 * methods specs here are copied from superinterfaces.
209 */
210
211 /**
212 * Inserts the specified element at the front of this deque if it is
213 * possible to do so immediately without violating capacity restrictions,
214 * throwing an {@code IllegalStateException} if no space is currently
215 * available. When using a capacity-restricted deque, it is generally
216 * preferable to use {@link #offerFirst(Object) offerFirst}.
217 *
218 * @param e the element to add
219 * @throws IllegalStateException {@inheritDoc}
220 * @throws ClassCastException {@inheritDoc}
221 * @throws NullPointerException if the specified element is null
222 * @throws IllegalArgumentException {@inheritDoc}
223 */
224 void addFirst(E e);
225
226 /**
227 * Inserts the specified element at the end of this deque if it is
228 * possible to do so immediately without violating capacity restrictions,
229 * throwing an {@code IllegalStateException} if no space is currently
230 * available. When using a capacity-restricted deque, it is generally
231 * preferable to use {@link #offerLast(Object) offerLast}.
232 *
233 * @param e the element to add
234 * @throws IllegalStateException {@inheritDoc}
235 * @throws ClassCastException {@inheritDoc}
236 * @throws NullPointerException if the specified element is null
237 * @throws IllegalArgumentException {@inheritDoc}
238 */
239 void addLast(E e);
240
241 /**
242 * Inserts the specified element at the front of this deque if it is
243 * possible to do so immediately without violating capacity restrictions,
244 * returning {@code true} upon success and {@code false} if no space is
245 * currently available.
246 * When using a capacity-restricted deque, this method is generally
247 * preferable to the {@link #addFirst(Object) addFirst} method, which can
248 * fail to insert an element only by throwing an exception.
249 *
250 * @param e the element to add
251 * @throws ClassCastException {@inheritDoc}
252 * @throws NullPointerException if the specified element is null
253 * @throws IllegalArgumentException {@inheritDoc}
254 */
255 boolean offerFirst(E e);
256
257 /**
258 * Inserts the specified element at the end of this deque if it is
259 * possible to do so immediately without violating capacity restrictions,
260 * returning {@code true} upon success and {@code false} if no space is
261 * currently available.
262 * When using a capacity-restricted deque, this method is generally
263 * preferable to the {@link #addLast(Object) addLast} method, which can
264 * fail to insert an element only by throwing an exception.
265 *
266 * @param e the element to add
267 * @throws ClassCastException {@inheritDoc}
268 * @throws NullPointerException if the specified element is null
269 * @throws IllegalArgumentException {@inheritDoc}
270 */
271 boolean offerLast(E e);
272
273 /**
274 * Inserts the specified element at the front of this deque,
275 * waiting if necessary for space to become available.
276 *
277 * @param e the element to add
278 * @throws InterruptedException if interrupted while waiting
279 * @throws ClassCastException if the class of the specified element
280 * prevents it from being added to this deque
281 * @throws NullPointerException if the specified element is null
282 * @throws IllegalArgumentException if some property of the specified
283 * element prevents it from being added to this deque
284 */
285 void putFirst(E e) throws InterruptedException;
286
287 /**
288 * Inserts the specified element at the end of this deque,
289 * waiting if necessary for space to become available.
290 *
291 * @param e the element to add
292 * @throws InterruptedException if interrupted while waiting
293 * @throws ClassCastException if the class of the specified element
294 * prevents it from being added to this deque
295 * @throws NullPointerException if the specified element is null
296 * @throws IllegalArgumentException if some property of the specified
297 * element prevents it from being added to this deque
298 */
299 void putLast(E e) throws InterruptedException;
300
301 /**
302 * Inserts the specified element at the front of this deque,
303 * waiting up to the specified wait time if necessary for space to
304 * become available.
305 *
306 * @param e the element to add
307 * @param timeout how long to wait before giving up, in units of
308 * {@code unit}
309 * @param unit a {@code TimeUnit} determining how to interpret the
310 * {@code timeout} parameter
311 * @return {@code true} if successful, or {@code false} if
312 * the specified waiting time elapses before space is available
313 * @throws InterruptedException if interrupted while waiting
314 * @throws ClassCastException if the class of the specified element
315 * prevents it from being added to this deque
316 * @throws NullPointerException if the specified element is null
317 * @throws IllegalArgumentException if some property of the specified
318 * element prevents it from being added to this deque
319 */
320 boolean offerFirst(E e, long timeout, TimeUnit unit)
321 throws InterruptedException;
322
323 /**
324 * Inserts the specified element at the end of this deque,
325 * waiting up to the specified wait time if necessary for space to
326 * become available.
327 *
328 * @param e the element to add
329 * @param timeout how long to wait before giving up, in units of
330 * {@code unit}
331 * @param unit a {@code TimeUnit} determining how to interpret the
332 * {@code timeout} parameter
333 * @return {@code true} if successful, or {@code false} if
334 * the specified waiting time elapses before space is available
335 * @throws InterruptedException if interrupted while waiting
336 * @throws ClassCastException if the class of the specified element
337 * prevents it from being added to this deque
338 * @throws NullPointerException if the specified element is null
339 * @throws IllegalArgumentException if some property of the specified
340 * element prevents it from being added to this deque
341 */
342 boolean offerLast(E e, long timeout, TimeUnit unit)
343 throws InterruptedException;
344
345 /**
346 * Retrieves and removes the first element of this deque, waiting
347 * if necessary until an element becomes available.
348 *
349 * @return the head of this deque
350 * @throws InterruptedException if interrupted while waiting
351 */
352 E takeFirst() throws InterruptedException;
353
354 /**
355 * Retrieves and removes the last element of this deque, waiting
356 * if necessary until an element becomes available.
357 *
358 * @return the tail of this deque
359 * @throws InterruptedException if interrupted while waiting
360 */
361 E takeLast() throws InterruptedException;
362
363 /**
364 * Retrieves and removes the first element of this deque, waiting
365 * up to the specified wait time if necessary for an element to
366 * become available.
367 *
368 * @param timeout how long to wait before giving up, in units of
369 * {@code unit}
370 * @param unit a {@code TimeUnit} determining how to interpret the
371 * {@code timeout} parameter
372 * @return the head of this deque, or {@code null} if the specified
373 * waiting time elapses before an element is available
374 * @throws InterruptedException if interrupted while waiting
375 */
376 E pollFirst(long timeout, TimeUnit unit)
377 throws InterruptedException;
378
379 /**
380 * Retrieves and removes the last element of this deque, waiting
381 * up to the specified wait time if necessary for an element to
382 * become available.
383 *
384 * @param timeout how long to wait before giving up, in units of
385 * {@code unit}
386 * @param unit a {@code TimeUnit} determining how to interpret the
387 * {@code timeout} parameter
388 * @return the tail of this deque, or {@code null} if the specified
389 * waiting time elapses before an element is available
390 * @throws InterruptedException if interrupted while waiting
391 */
392 E pollLast(long timeout, TimeUnit unit)
393 throws InterruptedException;
394
395 /**
396 * Removes the first occurrence of the specified element from this deque.
397 * If the deque does not contain the element, it is unchanged.
398 * More formally, removes the first element {@code e} such that
399 * {@code o.equals(e)} (if such an element exists).
400 * Returns {@code true} if this deque contained the specified element
401 * (or equivalently, if this deque changed as a result of the call).
402 *
403 * @param o element to be removed from this deque, if present
404 * @return {@code true} if an element was removed as a result of this call
405 * @throws ClassCastException if the class of the specified element
406 * is incompatible with this deque
407 * (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
408 * @throws NullPointerException if the specified element is null
409 * (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
410 */
411 boolean removeFirstOccurrence(Object o);
412
413 /**
414 * Removes the last occurrence of the specified element from this deque.
415 * If the deque does not contain the element, it is unchanged.
416 * More formally, removes the last element {@code e} such that
417 * {@code o.equals(e)} (if such an element exists).
418 * Returns {@code true} if this deque contained the specified element
419 * (or equivalently, if this deque changed as a result of the call).
420 *
421 * @param o element to be removed from this deque, if present
422 * @return {@code true} if an element was removed as a result of this call
423 * @throws ClassCastException if the class of the specified element
424 * is incompatible with this deque
425 * (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
426 * @throws NullPointerException if the specified element is null
427 * (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
428 */
429 boolean removeLastOccurrence(Object o);
430
431 // *** BlockingQueue methods ***
432
433 /**
434 * Inserts the specified element into the queue represented by this deque
435 * (in other words, at the tail of this deque) if it is possible to do so
436 * immediately without violating capacity restrictions, returning
437 * {@code true} upon success and throwing an
438 * {@code IllegalStateException} if no space is currently available.
439 * When using a capacity-restricted deque, it is generally preferable to
440 * use {@link #offer(Object) offer}.
441 *
442 * <p>This method is equivalent to {@link #addLast(Object) addLast}.
443 *
444 * @param e the element to add
445 * @throws IllegalStateException {@inheritDoc}
446 * @throws ClassCastException if the class of the specified element
447 * prevents it from being added to this deque
448 * @throws NullPointerException if the specified element is null
449 * @throws IllegalArgumentException if some property of the specified
450 * element prevents it from being added to this deque
451 */
452 boolean add(E e);
453
454 /**
455 * Inserts the specified element into the queue represented by this deque
456 * (in other words, at the tail of this deque) if it is possible to do so
457 * immediately without violating capacity restrictions, returning
458 * {@code true} upon success and {@code false} if no space is currently
459 * available. When using a capacity-restricted deque, this method is
460 * generally preferable to the {@link #add} method, which can fail to
461 * insert an element only by throwing an exception.
462 *
463 * <p>This method is equivalent to {@link #offerLast(Object) offerLast}.
464 *
465 * @param e the element to add
466 * @throws ClassCastException if the class of the specified element
467 * prevents it from being added to this deque
468 * @throws NullPointerException if the specified element is null
469 * @throws IllegalArgumentException if some property of the specified
470 * element prevents it from being added to this deque
471 */
472 boolean offer(E e);
473
474 /**
475 * Inserts the specified element into the queue represented by this deque
476 * (in other words, at the tail of this deque), waiting if necessary for
477 * space to become available.
478 *
479 * <p>This method is equivalent to {@link #putLast(Object) putLast}.
480 *
481 * @param e the element to add
482 * @throws InterruptedException {@inheritDoc}
483 * @throws ClassCastException if the class of the specified element
484 * prevents it from being added to this deque
485 * @throws NullPointerException if the specified element is null
486 * @throws IllegalArgumentException if some property of the specified
487 * element prevents it from being added to this deque
488 */
489 void put(E e) throws InterruptedException;
490
491 /**
492 * Inserts the specified element into the queue represented by this deque
493 * (in other words, at the tail of this deque), waiting up to the
494 * specified wait time if necessary for space to become available.
495 *
496 * <p>This method is equivalent to
497 * {@link #offerLast(Object,long,TimeUnit) offerLast}.
498 *
499 * @param e the element to add
500 * @return {@code true} if the element was added to this deque, else
501 * {@code false}
502 * @throws InterruptedException {@inheritDoc}
503 * @throws ClassCastException if the class of the specified element
504 * prevents it from being added to this deque
505 * @throws NullPointerException if the specified element is null
506 * @throws IllegalArgumentException if some property of the specified
507 * element prevents it from being added to this deque
508 */
509 boolean offer(E e, long timeout, TimeUnit unit)
510 throws InterruptedException;
511
512 /**
513 * Retrieves and removes the head of the queue represented by this deque
514 * (in other words, the first element of this deque).
515 * This method differs from {@link #poll poll} only in that it
516 * throws an exception if this deque is empty.
517 *
518 * <p>This method is equivalent to {@link #removeFirst() removeFirst}.
519 *
520 * @return the head of the queue represented by this deque
521 * @throws NoSuchElementException if this deque is empty
522 */
523 E remove();
524
525 /**
526 * Retrieves and removes the head of the queue represented by this deque
527 * (in other words, the first element of this deque), or returns
528 * {@code null} if this deque is empty.
529 *
530 * <p>This method is equivalent to {@link #pollFirst()}.
531 *
532 * @return the head of this deque, or {@code null} if this deque is empty
533 */
534 E poll();
535
536 /**
537 * Retrieves and removes the head of the queue represented by this deque
538 * (in other words, the first element of this deque), waiting if
539 * necessary until an element becomes available.
540 *
541 * <p>This method is equivalent to {@link #takeFirst() takeFirst}.
542 *
543 * @return the head of this deque
544 * @throws InterruptedException if interrupted while waiting
545 */
546 E take() throws InterruptedException;
547
548 /**
549 * Retrieves and removes the head of the queue represented by this deque
550 * (in other words, the first element of this deque), waiting up to the
551 * specified wait time if necessary for an element to become available.
552 *
553 * <p>This method is equivalent to
554 * {@link #pollFirst(long,TimeUnit) pollFirst}.
555 *
556 * @return the head of this deque, or {@code null} if the
557 * specified waiting time elapses before an element is available
558 * @throws InterruptedException if interrupted while waiting
559 */
560 E poll(long timeout, TimeUnit unit)
561 throws InterruptedException;
562
563 /**
564 * Retrieves, but does not remove, the head of the queue represented by
565 * this deque (in other words, the first element of this deque).
566 * This method differs from {@link #peek peek} only in that it throws an
567 * exception if this deque is empty.
568 *
569 * <p>This method is equivalent to {@link #getFirst() getFirst}.
570 *
571 * @return the head of this deque
572 * @throws NoSuchElementException if this deque is empty
573 */
574 E element();
575
576 /**
577 * Retrieves, but does not remove, the head of the queue represented by
578 * this deque (in other words, the first element of this deque), or
579 * returns {@code null} if this deque is empty.
580 *
581 * <p>This method is equivalent to {@link #peekFirst() peekFirst}.
582 *
583 * @return the head of this deque, or {@code null} if this deque is empty
584 */
585 E peek();
586
587 /**
588 * Removes the first occurrence of the specified element from this deque.
589 * If the deque does not contain the element, it is unchanged.
590 * More formally, removes the first element {@code e} such that
591 * {@code o.equals(e)} (if such an element exists).
592 * Returns {@code true} if this deque contained the specified element
593 * (or equivalently, if this deque changed as a result of the call).
594 *
595 * <p>This method is equivalent to
596 * {@link #removeFirstOccurrence(Object) removeFirstOccurrence}.
597 *
598 * @param o element to be removed from this deque, if present
599 * @return {@code true} if this deque changed as a result of the call
600 * @throws ClassCastException if the class of the specified element
601 * is incompatible with this deque
602 * (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
603 * @throws NullPointerException if the specified element is null
604 * (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
605 */
606 boolean remove(Object o);
607
608 /**
609 * Returns {@code true} if this deque contains the specified element.
610 * More formally, returns {@code true} if and only if this deque contains
611 * at least one element {@code e} such that {@code o.equals(e)}.
612 *
613 * @param o object to be checked for containment in this deque
614 * @return {@code true} if this deque contains the specified element
615 * @throws ClassCastException if the class of the specified element
616 * is incompatible with this deque
617 * (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
618 * @throws NullPointerException if the specified element is null
619 * (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
620 */
621 boolean contains(Object o);
622
623 /**
624 * Returns the number of elements in this deque.
625 *
626 * @return the number of elements in this deque
627 */
628 int size();
629
630 /**
631 * Returns an iterator over the elements in this deque in proper sequence.
632 * The elements will be returned in order from first (head) to last (tail).
633 *
634 * @return an iterator over the elements in this deque in proper sequence
635 */
636 Iterator<E> iterator();
637
638 // *** Stack methods ***
639
640 /**
641 * Pushes an element onto the stack represented by this deque (in other
642 * words, at the head of this deque) if it is possible to do so
643 * immediately without violating capacity restrictions, throwing an
644 * {@code IllegalStateException} if no space is currently available.
645 *
646 * <p>This method is equivalent to {@link #addFirst(Object) addFirst}.
647 *
648 * @throws IllegalStateException {@inheritDoc}
649 * @throws ClassCastException {@inheritDoc}
650 * @throws NullPointerException if the specified element is null
651 * @throws IllegalArgumentException {@inheritDoc}
652 */
653 void push(E e);
654 }