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