001 /*
002 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
003 *
004 * This code is free software; you can redistribute it and/or modify it
005 * under the terms of the GNU General Public License version 2 only, as
006 * published by the Free Software Foundation. Sun designates this
007 * particular file as subject to the "Classpath" exception as provided
008 * by Sun in the LICENSE file that accompanied this code.
009 *
010 * This code is distributed in the hope that it will be useful, but WITHOUT
011 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
012 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
013 * version 2 for more details (a copy is included in the LICENSE file that
014 * accompanied this code).
015 *
016 * You should have received a copy of the GNU General Public License version
017 * 2 along with this work; if not, write to the Free Software Foundation,
018 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
019 *
020 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
021 * CA 95054 USA or visit www.sun.com if you need additional information or
022 * have any questions.
023 */
024
025 /*
026 * This file is available under and governed by the GNU General Public
027 * License version 2 only, as published by the Free Software Foundation.
028 * However, the following notice accompanied the original version of this
029 * file:
030 *
031 * Written by Doug Lea with assistance from members of JCP JSR-166
032 * Expert Group and released to the public domain, as explained at
033 * http://creativecommons.org/licenses/publicdomain
034 */
035
036 package java.util.concurrent;
037
038 import java.util.*;
039
040 /**
041 * A {@link Deque} that additionally supports blocking operations that wait
042 * for the deque to become non-empty when retrieving an element, and wait for
043 * space to become available in the deque when storing an element.
044 *
045 * <p><tt>BlockingDeque</tt> methods come in four forms, with different ways
046 * of handling operations that cannot be satisfied immediately, but may be
047 * satisfied at some point in the future:
048 * one throws an exception, the second returns a special value (either
049 * <tt>null</tt> or <tt>false</tt>, depending on the operation), the third
050 * blocks the current thread indefinitely until the operation can succeed,
051 * and the fourth blocks for only a given maximum time limit before giving
052 * up. These methods are summarized in the following table:
053 *
054 * <p>
055 * <table BORDER CELLPADDING=3 CELLSPACING=1>
056 * <tr>
057 * <td ALIGN=CENTER COLSPAN = 5> <b>First Element (Head)</b></td>
058 * </tr>
059 * <tr>
060 * <td></td>
061 * <td ALIGN=CENTER><em>Throws exception</em></td>
062 * <td ALIGN=CENTER><em>Special value</em></td>
063 * <td ALIGN=CENTER><em>Blocks</em></td>
064 * <td ALIGN=CENTER><em>Times out</em></td>
065 * </tr>
066 * <tr>
067 * <td><b>Insert</b></td>
068 * <td>{@link #addFirst addFirst(e)}</td>
069 * <td>{@link #offerFirst(Object) offerFirst(e)}</td>
070 * <td>{@link #putFirst putFirst(e)}</td>
071 * <td>{@link #offerFirst(Object, long, TimeUnit) offerFirst(e, time, unit)}</td>
072 * </tr>
073 * <tr>
074 * <td><b>Remove</b></td>
075 * <td>{@link #removeFirst removeFirst()}</td>
076 * <td>{@link #pollFirst pollFirst()}</td>
077 * <td>{@link #takeFirst takeFirst()}</td>
078 * <td>{@link #pollFirst(long, TimeUnit) pollFirst(time, unit)}</td>
079 * </tr>
080 * <tr>
081 * <td><b>Examine</b></td>
082 * <td>{@link #getFirst getFirst()}</td>
083 * <td>{@link #peekFirst peekFirst()}</td>
084 * <td><em>not applicable</em></td>
085 * <td><em>not applicable</em></td>
086 * </tr>
087 * <tr>
088 * <td ALIGN=CENTER COLSPAN = 5> <b>Last Element (Tail)</b></td>
089 * </tr>
090 * <tr>
091 * <td></td>
092 * <td ALIGN=CENTER><em>Throws exception</em></td>
093 * <td ALIGN=CENTER><em>Special value</em></td>
094 * <td ALIGN=CENTER><em>Blocks</em></td>
095 * <td ALIGN=CENTER><em>Times out</em></td>
096 * </tr>
097 * <tr>
098 * <td><b>Insert</b></td>
099 * <td>{@link #addLast addLast(e)}</td>
100 * <td>{@link #offerLast(Object) offerLast(e)}</td>
101 * <td>{@link #putLast putLast(e)}</td>
102 * <td>{@link #offerLast(Object, long, TimeUnit) offerLast(e, time, unit)}</td>
103 * </tr>
104 * <tr>
105 * <td><b>Remove</b></td>
106 * <td>{@link #removeLast() removeLast()}</td>
107 * <td>{@link #pollLast() pollLast()}</td>
108 * <td>{@link #takeLast takeLast()}</td>
109 * <td>{@link #pollLast(long, TimeUnit) pollLast(time, unit)}</td>
110 * </tr>
111 * <tr>
112 * <td><b>Examine</b></td>
113 * <td>{@link #getLast getLast()}</td>
114 * <td>{@link #peekLast peekLast()}</td>
115 * <td><em>not applicable</em></td>
116 * <td><em>not applicable</em></td>
117 * </tr>
118 * </table>
119 *
120 * <p>Like any {@link BlockingQueue}, a <tt>BlockingDeque</tt> is thread safe,
121 * does not permit null elements, and may (or may not) be
122 * capacity-constrained.
123 *
124 * <p>A <tt>BlockingDeque</tt> implementation may be used directly as a FIFO
125 * <tt>BlockingQueue</tt>. The methods inherited from the
126 * <tt>BlockingQueue</tt> interface are precisely equivalent to
127 * <tt>BlockingDeque</tt> methods as indicated in the following table:
128 *
129 * <p>
130 * <table BORDER CELLPADDING=3 CELLSPACING=1>
131 * <tr>
132 * <td ALIGN=CENTER> <b><tt>BlockingQueue</tt> Method</b></td>
133 * <td ALIGN=CENTER> <b>Equivalent <tt>BlockingDeque</tt> Method</b></td>
134 * </tr>
135 * <tr>
136 * <td ALIGN=CENTER COLSPAN = 2> <b>Insert</b></td>
137 * </tr>
138 * <tr>
139 * <td>{@link #add(Object) add(e)}</td>
140 * <td>{@link #addLast(Object) addLast(e)}</td>
141 * </tr>
142 * <tr>
143 * <td>{@link #offer(Object) offer(e)}</td>
144 * <td>{@link #offerLast(Object) offerLast(e)}</td>
145 * </tr>
146 * <tr>
147 * <td>{@link #put(Object) put(e)}</td>
148 * <td>{@link #putLast(Object) putLast(e)}</td>
149 * </tr>
150 * <tr>
151 * <td>{@link #offer(Object, long, TimeUnit) offer(e, time, unit)}</td>
152 * <td>{@link #offerLast(Object, long, TimeUnit) offerLast(e, time, unit)}</td>
153 * </tr>
154 * <tr>
155 * <td ALIGN=CENTER COLSPAN = 2> <b>Remove</b></td>
156 * </tr>
157 * <tr>
158 * <td>{@link #remove() remove()}</td>
159 * <td>{@link #removeFirst() removeFirst()}</td>
160 * </tr>
161 * <tr>
162 * <td>{@link #poll() poll()}</td>
163 * <td>{@link #pollFirst() pollFirst()}</td>
164 * </tr>
165 * <tr>
166 * <td>{@link #take() take()}</td>
167 * <td>{@link #takeFirst() takeFirst()}</td>
168 * </tr>
169 * <tr>
170 * <td>{@link #poll(long, TimeUnit) poll(time, unit)}</td>
171 * <td>{@link #pollFirst(long, TimeUnit) pollFirst(time, unit)}</td>
172 * </tr>
173 * <tr>
174 * <td ALIGN=CENTER COLSPAN = 2> <b>Examine</b></td>
175 * </tr>
176 * <tr>
177 * <td>{@link #element() element()}</td>
178 * <td>{@link #getFirst() getFirst()}</td>
179 * </tr>
180 * <tr>
181 * <td>{@link #peek() peek()}</td>
182 * <td>{@link #peekFirst() peekFirst()}</td>
183 * </tr>
184 * </table>
185 *
186 * <p>Memory consistency effects: As with other concurrent
187 * collections, actions in a thread prior to placing an object into a
188 * {@code BlockingDeque}
189 * <a href="package-summary.html#MemoryVisibility"><i>happen-before</i></a>
190 * actions subsequent to the access or removal of that element from
191 * the {@code BlockingDeque} in another thread.
192 *
193 * <p>This interface is a member of the
194 * <a href="{@docRoot}/../technotes/guides/collections/index.html">
195 * Java Collections Framework</a>.
196 *
197 * @since 1.6
198 * @author Doug Lea
199 * @param <E> the type of elements held in this collection
200 */
201 public interface BlockingDeque<E> extends BlockingQueue<E>, Deque<E> {
202 /*
203 * We have "diamond" multiple interface inheritance here, and that
204 * introduces ambiguities. Methods might end up with different
205 * specs depending on the branch chosen by javadoc. Thus a lot of
206 * methods specs here are copied from superinterfaces.
207 */
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 * throwing an <tt>IllegalStateException</tt> if no space is currently
213 * available. When using a capacity-restricted deque, it is generally
214 * preferable to use {@link #offerFirst(Object) offerFirst}.
215 *
216 * @param e the element to add
217 * @throws IllegalStateException {@inheritDoc}
218 * @throws ClassCastException {@inheritDoc}
219 * @throws NullPointerException if the specified element is null
220 * @throws IllegalArgumentException {@inheritDoc}
221 */
222 void addFirst(E e);
223
224 /**
225 * Inserts the specified element at the end of this deque if it is
226 * possible to do so immediately without violating capacity restrictions,
227 * throwing an <tt>IllegalStateException</tt> if no space is currently
228 * available. When using a capacity-restricted deque, it is generally
229 * preferable to use {@link #offerLast(Object) offerLast}.
230 *
231 * @param e the element to add
232 * @throws IllegalStateException {@inheritDoc}
233 * @throws ClassCastException {@inheritDoc}
234 * @throws NullPointerException if the specified element is null
235 * @throws IllegalArgumentException {@inheritDoc}
236 */
237 void addLast(E e);
238
239 /**
240 * Inserts the specified element at the front of this deque if it is
241 * possible to do so immediately without violating capacity restrictions,
242 * returning <tt>true</tt> upon success and <tt>false</tt> if no space is
243 * currently available.
244 * When using a capacity-restricted deque, this method is generally
245 * preferable to the {@link #addFirst(Object) addFirst} method, which can
246 * fail to insert an element only by throwing an exception.
247 *
248 * @param e the element to add
249 * @throws ClassCastException {@inheritDoc}
250 * @throws NullPointerException if the specified element is null
251 * @throws IllegalArgumentException {@inheritDoc}
252 */
253 boolean offerFirst(E e);
254
255 /**
256 * Inserts the specified element at the end of this deque if it is
257 * possible to do so immediately without violating capacity restrictions,
258 * returning <tt>true</tt> upon success and <tt>false</tt> if no space is
259 * currently available.
260 * When using a capacity-restricted deque, this method is generally
261 * preferable to the {@link #addLast(Object) addLast} method, which can
262 * fail to insert an element only by throwing an exception.
263 *
264 * @param e the element to add
265 * @throws ClassCastException {@inheritDoc}
266 * @throws NullPointerException if the specified element is null
267 * @throws IllegalArgumentException {@inheritDoc}
268 */
269 boolean offerLast(E e);
270
271 /**
272 * Inserts the specified element at the front of this deque,
273 * waiting if necessary for space to become available.
274 *
275 * @param e the element to add
276 * @throws InterruptedException if interrupted while waiting
277 * @throws ClassCastException if the class of the specified element
278 * prevents it from being added to this deque
279 * @throws NullPointerException if the specified element is null
280 * @throws IllegalArgumentException if some property of the specified
281 * element prevents it from being added to this deque
282 */
283 void putFirst(E e) throws InterruptedException;
284
285 /**
286 * Inserts the specified element at the end of this deque,
287 * waiting if necessary for space to become available.
288 *
289 * @param e the element to add
290 * @throws InterruptedException if interrupted while waiting
291 * @throws ClassCastException if the class of the specified element
292 * prevents it from being added to this deque
293 * @throws NullPointerException if the specified element is null
294 * @throws IllegalArgumentException if some property of the specified
295 * element prevents it from being added to this deque
296 */
297 void putLast(E e) throws InterruptedException;
298
299 /**
300 * Inserts the specified element at the front of this deque,
301 * waiting up to the specified wait time if necessary for space to
302 * become available.
303 *
304 * @param e the element to add
305 * @param timeout how long to wait before giving up, in units of
306 * <tt>unit</tt>
307 * @param unit a <tt>TimeUnit</tt> determining how to interpret the
308 * <tt>timeout</tt> parameter
309 * @return <tt>true</tt> if successful, or <tt>false</tt> if
310 * the specified waiting time elapses before space is available
311 * @throws InterruptedException if interrupted while waiting
312 * @throws ClassCastException if the class of the specified element
313 * prevents it from being added to this deque
314 * @throws NullPointerException if the specified element is null
315 * @throws IllegalArgumentException if some property of the specified
316 * element prevents it from being added to this deque
317 */
318 boolean offerFirst(E e, long timeout, TimeUnit unit)
319 throws InterruptedException;
320
321 /**
322 * Inserts the specified element at the end of this deque,
323 * waiting up to the specified wait time if necessary for space to
324 * become available.
325 *
326 * @param e the element to add
327 * @param timeout how long to wait before giving up, in units of
328 * <tt>unit</tt>
329 * @param unit a <tt>TimeUnit</tt> determining how to interpret the
330 * <tt>timeout</tt> parameter
331 * @return <tt>true</tt> if successful, or <tt>false</tt> if
332 * the specified waiting time elapses before space is available
333 * @throws InterruptedException if interrupted while waiting
334 * @throws ClassCastException if the class of the specified element
335 * prevents it from being added to this deque
336 * @throws NullPointerException if the specified element is null
337 * @throws IllegalArgumentException if some property of the specified
338 * element prevents it from being added to this deque
339 */
340 boolean offerLast(E e, long timeout, TimeUnit unit)
341 throws InterruptedException;
342
343 /**
344 * Retrieves and removes the first element of this deque, waiting
345 * if necessary until an element becomes available.
346 *
347 * @return the head of this deque
348 * @throws InterruptedException if interrupted while waiting
349 */
350 E takeFirst() throws InterruptedException;
351
352 /**
353 * Retrieves and removes the last element of this deque, waiting
354 * if necessary until an element becomes available.
355 *
356 * @return the tail of this deque
357 * @throws InterruptedException if interrupted while waiting
358 */
359 E takeLast() throws InterruptedException;
360
361 /**
362 * Retrieves and removes the first element of this deque, waiting
363 * up to the specified wait time if necessary for an element to
364 * become available.
365 *
366 * @param timeout how long to wait before giving up, in units of
367 * <tt>unit</tt>
368 * @param unit a <tt>TimeUnit</tt> determining how to interpret the
369 * <tt>timeout</tt> parameter
370 * @return the head of this deque, or <tt>null</tt> if the specified
371 * waiting time elapses before an element is available
372 * @throws InterruptedException if interrupted while waiting
373 */
374 E pollFirst(long timeout, TimeUnit unit)
375 throws InterruptedException;
376
377 /**
378 * Retrieves and removes the last element of this deque, waiting
379 * up to the specified wait time if necessary for an element to
380 * become available.
381 *
382 * @param timeout how long to wait before giving up, in units of
383 * <tt>unit</tt>
384 * @param unit a <tt>TimeUnit</tt> determining how to interpret the
385 * <tt>timeout</tt> parameter
386 * @return the tail of this deque, or <tt>null</tt> if the specified
387 * waiting time elapses before an element is available
388 * @throws InterruptedException if interrupted while waiting
389 */
390 E pollLast(long timeout, TimeUnit unit) 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 <tt>e</tt> such that
396 * <tt>o.equals(e)</tt> (if such an element exists).
397 * Returns <tt>true</tt> 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 <tt>true</tt> 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 (optional)
404 * @throws NullPointerException if the specified element is null (optional)
405 */
406 boolean removeFirstOccurrence(Object o);
407
408 /**
409 * Removes the last occurrence of the specified element from this deque.
410 * If the deque does not contain the element, it is unchanged.
411 * More formally, removes the last element <tt>e</tt> such that
412 * <tt>o.equals(e)</tt> (if such an element exists).
413 * Returns <tt>true</tt> 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 <tt>true</tt> 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 (optional)
420 * @throws NullPointerException if the specified element is null (optional)
421 */
422 boolean removeLastOccurrence(Object o);
423
424 // *** BlockingQueue methods ***
425
426 /**
427 * Inserts the specified element into the queue represented by this deque
428 * (in other words, at the tail of this deque) if it is possible to do so
429 * immediately without violating capacity restrictions, returning
430 * <tt>true</tt> upon success and throwing an
431 * <tt>IllegalStateException</tt> if no space is currently available.
432 * When using a capacity-restricted deque, it is generally preferable to
433 * use {@link #offer(Object) offer}.
434 *
435 * <p>This method is equivalent to {@link #addLast(Object) addLast}.
436 *
437 * @param e the element to add
438 * @throws IllegalStateException {@inheritDoc}
439 * @throws ClassCastException if the class of the specified element
440 * prevents it from being added to this deque
441 * @throws NullPointerException if the specified element is null
442 * @throws IllegalArgumentException if some property of the specified
443 * element prevents it from being added to this deque
444 */
445 boolean add(E e);
446
447 /**
448 * Inserts the specified element into the queue represented by this deque
449 * (in other words, at the tail of this deque) if it is possible to do so
450 * immediately without violating capacity restrictions, returning
451 * <tt>true</tt> upon success and <tt>false</tt> if no space is currently
452 * available. When using a capacity-restricted deque, this method is
453 * generally preferable to the {@link #add} method, which can fail to
454 * insert an element only by throwing an exception.
455 *
456 * <p>This method is equivalent to {@link #offerLast(Object) offerLast}.
457 *
458 * @param e the element to add
459 * @throws ClassCastException if the class of the specified element
460 * prevents it from being added to this deque
461 * @throws NullPointerException if the specified element is null
462 * @throws IllegalArgumentException if some property of the specified
463 * element prevents it from being added to this deque
464 */
465 boolean offer(E e);
466
467 /**
468 * Inserts the specified element into the queue represented by this deque
469 * (in other words, at the tail of this deque), waiting if necessary for
470 * space to become available.
471 *
472 * <p>This method is equivalent to {@link #putLast(Object) putLast}.
473 *
474 * @param e the element to add
475 * @throws InterruptedException {@inheritDoc}
476 * @throws ClassCastException if the class of the specified element
477 * prevents it from being added to this deque
478 * @throws NullPointerException if the specified element is null
479 * @throws IllegalArgumentException if some property of the specified
480 * element prevents it from being added to this deque
481 */
482 void put(E e) throws InterruptedException;
483
484 /**
485 * Inserts the specified element into the queue represented by this deque
486 * (in other words, at the tail of this deque), waiting up to the
487 * specified wait time if necessary for space to become available.
488 *
489 * <p>This method is equivalent to
490 * {@link #offerLast(Object,long,TimeUnit) offerLast}.
491 *
492 * @param e the element to add
493 * @return <tt>true</tt> if the element was added to this deque, else
494 * <tt>false</tt>
495 * @throws InterruptedException {@inheritDoc}
496 * @throws ClassCastException if the class of the specified element
497 * prevents it from being added to this deque
498 * @throws NullPointerException if the specified element is null
499 * @throws IllegalArgumentException if some property of the specified
500 * element prevents it from being added to this deque
501 */
502 boolean offer(E e, long timeout, TimeUnit unit)
503 throws InterruptedException;
504
505 /**
506 * Retrieves and removes the head of the queue represented by this deque
507 * (in other words, the first element of this deque).
508 * This method differs from {@link #poll poll} only in that it
509 * throws an exception if this deque is empty.
510 *
511 * <p>This method is equivalent to {@link #removeFirst() removeFirst}.
512 *
513 * @return the head of the queue represented by this deque
514 * @throws NoSuchElementException if this deque is empty
515 */
516 E remove();
517
518 /**
519 * Retrieves and removes the head of the queue represented by this deque
520 * (in other words, the first element of this deque), or returns
521 * <tt>null</tt> if this deque is empty.
522 *
523 * <p>This method is equivalent to {@link #pollFirst()}.
524 *
525 * @return the head of this deque, or <tt>null</tt> if this deque is empty
526 */
527 E poll();
528
529 /**
530 * Retrieves and removes the head of the queue represented by this deque
531 * (in other words, the first element of this deque), waiting if
532 * necessary until an element becomes available.
533 *
534 * <p>This method is equivalent to {@link #takeFirst() takeFirst}.
535 *
536 * @return the head of this deque
537 * @throws InterruptedException if interrupted while waiting
538 */
539 E take() throws InterruptedException;
540
541 /**
542 * Retrieves and removes the head of the queue represented by this deque
543 * (in other words, the first element of this deque), waiting up to the
544 * specified wait time if necessary for an element to become available.
545 *
546 * <p>This method is equivalent to
547 * {@link #pollFirst(long,TimeUnit) pollFirst}.
548 *
549 * @return the head of this deque, or <tt>null</tt> if the
550 * specified waiting time elapses before an element is available
551 * @throws InterruptedException if interrupted while waiting
552 */
553 E poll(long timeout, TimeUnit unit) throws InterruptedException;
554
555 /**
556 * Retrieves, but does not remove, the head of the queue represented by
557 * this deque (in other words, the first element of this deque).
558 * This method differs from {@link #peek peek} only in that it throws an
559 * exception if this deque is empty.
560 *
561 * <p>This method is equivalent to {@link #getFirst() getFirst}.
562 *
563 * @return the head of this deque
564 * @throws NoSuchElementException if this deque is empty
565 */
566 E element();
567
568 /**
569 * Retrieves, but does not remove, the head of the queue represented by
570 * this deque (in other words, the first element of this deque), or
571 * returns <tt>null</tt> if this deque is empty.
572 *
573 * <p>This method is equivalent to {@link #peekFirst() peekFirst}.
574 *
575 * @return the head of this deque, or <tt>null</tt> if this deque is empty
576 */
577 E peek();
578
579 /**
580 * Removes the first occurrence of the specified element from this deque.
581 * If the deque does not contain the element, it is unchanged.
582 * More formally, removes the first element <tt>e</tt> such that
583 * <tt>o.equals(e)</tt> (if such an element exists).
584 * Returns <tt>true</tt> if this deque contained the specified element
585 * (or equivalently, if this deque changed as a result of the call).
586 *
587 * <p>This method is equivalent to
588 * {@link #removeFirstOccurrence(Object) removeFirstOccurrence}.
589 *
590 * @param o element to be removed from this deque, if present
591 * @return <tt>true</tt> if this deque changed as a result of the call
592 * @throws ClassCastException if the class of the specified element
593 * is incompatible with this deque (optional)
594 * @throws NullPointerException if the specified element is null (optional)
595 */
596 boolean remove(Object o);
597
598 /**
599 * Returns <tt>true</tt> if this deque contains the specified element.
600 * More formally, returns <tt>true</tt> if and only if this deque contains
601 * at least one element <tt>e</tt> such that <tt>o.equals(e)</tt>.
602 *
603 * @param o object to be checked for containment in this deque
604 * @return <tt>true</tt> if this deque contains the specified element
605 * @throws ClassCastException if the class of the specified element
606 * is incompatible with this deque (optional)
607 * @throws NullPointerException if the specified element is null (optional)
608 */
609 public boolean contains(Object o);
610
611 /**
612 * Returns the number of elements in this deque.
613 *
614 * @return the number of elements in this deque
615 */
616 public int size();
617
618 /**
619 * Returns an iterator over the elements in this deque in proper sequence.
620 * The elements will be returned in order from first (head) to last (tail).
621 *
622 * @return an iterator over the elements in this deque in proper sequence
623 */
624 Iterator<E> iterator();
625
626 // *** Stack methods ***
627
628 /**
629 * Pushes an element onto the stack represented by this deque. In other
630 * words, inserts the element at the front of this deque unless it would
631 * violate capacity restrictions.
632 *
633 * <p>This method is equivalent to {@link #addFirst(Object) addFirst}.
634 *
635 * @throws IllegalStateException {@inheritDoc}
636 * @throws ClassCastException {@inheritDoc}
637 * @throws NullPointerException if the specified element is null
638 * @throws IllegalArgumentException {@inheritDoc}
639 */
640 void push(E e);
641 }
|