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