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.base/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      */
addFirst(E e)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      */
addLast(E e)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      */
offerFirst(E e)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      */
offerLast(E e)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      */
putFirst(E e)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      */
putLast(E e)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      */
offerFirst(E e, long timeout, TimeUnit unit)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      */
offerLast(E e, long timeout, TimeUnit unit)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      */
takeFirst()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      */
takeLast()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      */
pollFirst(long timeout, TimeUnit unit)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      */
pollLast(long timeout, TimeUnit unit)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.base/java/util/Collection.html#optional-restrictions">optional</a>)
403      * @throws NullPointerException if the specified element is null
404      * (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>)
405      */
removeFirstOccurrence(Object o)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.base/java/util/Collection.html#optional-restrictions">optional</a>)
421      * @throws NullPointerException if the specified element is null
422      * (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>)
423      */
removeLastOccurrence(Object o)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      */
add(E e)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      */
offer(E e)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      */
put(E e)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      */
offer(E e, long timeout, TimeUnit unit)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      */
remove()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      */
poll()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      */
take()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      */
poll(long timeout, TimeUnit unit)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      */
element()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      */
peek()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.base/java/util/Collection.html#optional-restrictions">optional</a>)
598      * @throws NullPointerException if the specified element is null
599      * (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>)
600      */
remove(Object o)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.base/java/util/Collection.html#optional-restrictions">optional</a>)
613      * @throws NullPointerException if the specified element is null
614      * (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>)
615      */
contains(Object o)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      */
size()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      */
iterator()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      */
push(E e)648     void push(E e);
649 }
650