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