Source for java.util.concurrent.BlockingDeque

   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/licenses/publicdomain
   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><tt>BlockingDeque</tt> 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:  * <tt>null</tt> or <tt>false</tt>, 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 <tt>BlockingDeque</tt> is thread safe,
  91:  * does not permit null elements, and may (or may not) be
  92:  * capacity-constrained.
  93:  *
  94:  * <p>A <tt>BlockingDeque</tt> implementation may be used directly as a FIFO
  95:  * <tt>BlockingQueue</tt>. The methods inherited from the
  96:  * <tt>BlockingQueue</tt> interface are precisely equivalent to
  97:  * <tt>BlockingDeque</tt> methods as indicated in the following table:
  98:  *
  99:  * <p>
 100:  * <table BORDER CELLPADDING=3 CELLSPACING=1>
 101:  *  <tr>
 102:  *    <td ALIGN=CENTER> <b><tt>BlockingQueue</tt> Method</b></td>
 103:  *    <td ALIGN=CENTER> <b>Equivalent <tt>BlockingDeque</tt> 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 <tt>IllegalStateException</tt> 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:      */
 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 <tt>IllegalStateException</tt> 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:      */
 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 <tt>true</tt> upon success and <tt>false</tt> 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:      */
 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 <tt>true</tt> upon success and <tt>false</tt> 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:      */
 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:      */
 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:      */
 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:      *        <tt>unit</tt>
 277:      * @param unit a <tt>TimeUnit</tt> determining how to interpret the
 278:      *        <tt>timeout</tt> parameter
 279:      * @return <tt>true</tt> if successful, or <tt>false</tt> 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:      */
 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:      *        <tt>unit</tt>
 299:      * @param unit a <tt>TimeUnit</tt> determining how to interpret the
 300:      *        <tt>timeout</tt> parameter
 301:      * @return <tt>true</tt> if successful, or <tt>false</tt> 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:      */
 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:      */
 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:      */
 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:      *        <tt>unit</tt>
 338:      * @param unit a <tt>TimeUnit</tt> determining how to interpret the
 339:      *        <tt>timeout</tt> parameter
 340:      * @return the head of this deque, or <tt>null</tt> if the specified
 341:      *         waiting time elapses before an element is available
 342:      * @throws InterruptedException if interrupted while waiting
 343:      */
 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:      *        <tt>unit</tt>
 354:      * @param unit a <tt>TimeUnit</tt> determining how to interpret the
 355:      *        <tt>timeout</tt> parameter
 356:      * @return the tail of this deque, or <tt>null</tt> if the specified
 357:      *         waiting time elapses before an element is available
 358:      * @throws InterruptedException if interrupted while waiting
 359:      */
 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 <tt>e</tt> such that
 367:      * <tt>o.equals(e)</tt> (if such an element exists).
 368:      * Returns <tt>true</tt> 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 <tt>true</tt> 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 (optional)
 375:      * @throws NullPointerException if the specified element is null (optional)
 376:      */
 377:     boolean removeFirstOccurrence(Object o);
 378: 
 379:     /**
 380:      * Removes the last occurrence of the specified element from this deque.
 381:      * If the deque does not contain the element, it is unchanged.
 382:      * More formally, removes the last element <tt>e</tt> such that
 383:      * <tt>o.equals(e)</tt> (if such an element exists).
 384:      * Returns <tt>true</tt> if this deque contained the specified element
 385:      * (or equivalently, if this deque changed as a result of the call).
 386:      *
 387:      * @param o element to be removed from this deque, if present
 388:      * @return <tt>true</tt> if an element was removed as a result of this call
 389:      * @throws ClassCastException if the class of the specified element
 390:      *         is incompatible with this deque (optional)
 391:      * @throws NullPointerException if the specified element is null (optional)
 392:      */
 393:     boolean removeLastOccurrence(Object o);
 394: 
 395:     // *** BlockingQueue methods ***
 396: 
 397:     /**
 398:      * Inserts the specified element into the queue represented by this deque
 399:      * (in other words, at the tail of this deque) if it is possible to do so
 400:      * immediately without violating capacity restrictions, returning
 401:      * <tt>true</tt> upon success and throwing an
 402:      * <tt>IllegalStateException</tt> if no space is currently available.
 403:      * When using a capacity-restricted deque, it is generally preferable to
 404:      * use {@link #offer(Object) offer}.
 405:      *
 406:      * <p>This method is equivalent to {@link #addLast(Object) addLast}.
 407:      *
 408:      * @param e the element to add
 409:      * @throws IllegalStateException {@inheritDoc}
 410:      * @throws ClassCastException if the class of the specified element
 411:      *         prevents it from being added to this deque
 412:      * @throws NullPointerException if the specified element is null
 413:      * @throws IllegalArgumentException if some property of the specified
 414:      *         element prevents it from being added to this deque
 415:      */
 416:     boolean add(E e);
 417: 
 418:     /**
 419:      * Inserts the specified element into the queue represented by this deque
 420:      * (in other words, at the tail of this deque) if it is possible to do so
 421:      * immediately without violating capacity restrictions, returning
 422:      * <tt>true</tt> upon success and <tt>false</tt> if no space is currently
 423:      * available.  When using a capacity-restricted deque, this method is
 424:      * generally preferable to the {@link #add} method, which can fail to
 425:      * insert an element only by throwing an exception.
 426:      *
 427:      * <p>This method is equivalent to {@link #offerLast(Object) offerLast}.
 428:      *
 429:      * @param e the element to add
 430:      * @throws ClassCastException if the class of the specified element
 431:      *         prevents it from being added to this deque
 432:      * @throws NullPointerException if the specified element is null
 433:      * @throws IllegalArgumentException if some property of the specified
 434:      *         element prevents it from being added to this deque
 435:      */
 436:     boolean offer(E e);
 437: 
 438:     /**
 439:      * Inserts the specified element into the queue represented by this deque
 440:      * (in other words, at the tail of this deque), waiting if necessary for
 441:      * space to become available.
 442:      *
 443:      * <p>This method is equivalent to {@link #putLast(Object) putLast}.
 444:      *
 445:      * @param e the element to add
 446:      * @throws InterruptedException {@inheritDoc}
 447:      * @throws ClassCastException if the class of the specified element
 448:      *         prevents it from being added to this deque
 449:      * @throws NullPointerException if the specified element is null
 450:      * @throws IllegalArgumentException if some property of the specified
 451:      *         element prevents it from being added to this deque
 452:      */
 453:     void put(E e) throws InterruptedException;
 454: 
 455:     /**
 456:      * Inserts the specified element into the queue represented by this deque
 457:      * (in other words, at the tail of this deque), waiting up to the
 458:      * specified wait time if necessary for space to become available.
 459:      *
 460:      * <p>This method is equivalent to
 461:      * {@link #offerLast(Object,long,TimeUnit) offerLast}.
 462:      *
 463:      * @param e the element to add
 464:      * @return <tt>true</tt> if the element was added to this deque, else
 465:      *         <tt>false</tt>
 466:      * @throws InterruptedException {@inheritDoc}
 467:      * @throws ClassCastException if the class of the specified element
 468:      *         prevents it from being added to this deque
 469:      * @throws NullPointerException if the specified element is null
 470:      * @throws IllegalArgumentException if some property of the specified
 471:      *         element prevents it from being added to this deque
 472:      */
 473:     boolean offer(E e, long timeout, TimeUnit unit)
 474:         throws InterruptedException;
 475: 
 476:     /**
 477:      * Retrieves and removes the head of the queue represented by this deque
 478:      * (in other words, the first element of this deque).
 479:      * This method differs from {@link #poll poll} only in that it
 480:      * throws an exception if this deque is empty.
 481:      *
 482:      * <p>This method is equivalent to {@link #removeFirst() removeFirst}.
 483:      *
 484:      * @return the head of the queue represented by this deque
 485:      * @throws NoSuchElementException if this deque is empty
 486:      */
 487:     E remove();
 488: 
 489:     /**
 490:      * Retrieves and removes the head of the queue represented by this deque
 491:      * (in other words, the first element of this deque), or returns
 492:      * <tt>null</tt> if this deque is empty.
 493:      *
 494:      * <p>This method is equivalent to {@link #pollFirst()}.
 495:      *
 496:      * @return the head of this deque, or <tt>null</tt> if this deque is empty
 497:      */
 498:     E poll();
 499: 
 500:     /**
 501:      * Retrieves and removes the head of the queue represented by this deque
 502:      * (in other words, the first element of this deque), waiting if
 503:      * necessary until an element becomes available.
 504:      *
 505:      * <p>This method is equivalent to {@link #takeFirst() takeFirst}.
 506:      *
 507:      * @return the head of this deque
 508:      * @throws InterruptedException if interrupted while waiting
 509:      */
 510:     E take() 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), waiting up to the
 515:      * specified wait time if necessary for an element to become available.
 516:      *
 517:      * <p>This method is equivalent to
 518:      * {@link #pollFirst(long,TimeUnit) pollFirst}.
 519:      *
 520:      * @return the head of this deque, or <tt>null</tt> if the
 521:      *         specified waiting time elapses before an element is available
 522:      * @throws InterruptedException if interrupted while waiting
 523:      */
 524:     E poll(long timeout, TimeUnit unit)
 525:         throws InterruptedException;
 526: 
 527:     /**
 528:      * Retrieves, but does not remove, the head of the queue represented by
 529:      * this deque (in other words, the first element of this deque).
 530:      * This method differs from {@link #peek peek} only in that it throws an
 531:      * exception if this deque is empty.
 532:      *
 533:      * <p>This method is equivalent to {@link #getFirst() getFirst}.
 534:      *
 535:      * @return the head of this deque
 536:      * @throws NoSuchElementException if this deque is empty
 537:      */
 538:     E element();
 539: 
 540:     /**
 541:      * Retrieves, but does not remove, the head of the queue represented by
 542:      * this deque (in other words, the first element of this deque), or
 543:      * returns <tt>null</tt> if this deque is empty.
 544:      *
 545:      * <p>This method is equivalent to {@link #peekFirst() peekFirst}.
 546:      *
 547:      * @return the head of this deque, or <tt>null</tt> if this deque is empty
 548:      */
 549:     E peek();
 550: 
 551:     /**
 552:      * Removes the first occurrence of the specified element from this deque.
 553:      * If the deque does not contain the element, it is unchanged.
 554:      * More formally, removes the first element <tt>e</tt> such that
 555:      * <tt>o.equals(e)</tt> (if such an element exists).
 556:      * Returns <tt>true</tt> if this deque contained the specified element
 557:      * (or equivalently, if this deque changed as a result of the call).
 558:      *
 559:      * <p>This method is equivalent to
 560:      * {@link #removeFirstOccurrence(Object) removeFirstOccurrence}.
 561:      *
 562:      * @param o element to be removed from this deque, if present
 563:      * @return <tt>true</tt> if this deque changed as a result of the call
 564:      * @throws ClassCastException if the class of the specified element
 565:      *         is incompatible with this deque (optional)
 566:      * @throws NullPointerException if the specified element is null (optional)
 567:      */
 568:     boolean remove(Object o);
 569: 
 570:     /**
 571:      * Returns <tt>true</tt> if this deque contains the specified element.
 572:      * More formally, returns <tt>true</tt> if and only if this deque contains
 573:      * at least one element <tt>e</tt> such that <tt>o.equals(e)</tt>.
 574:      *
 575:      * @param o object to be checked for containment in this deque
 576:      * @return <tt>true</tt> if this deque contains the specified element
 577:      * @throws ClassCastException if the class of the specified element
 578:      *         is incompatible with this deque (optional)
 579:      * @throws NullPointerException if the specified element is null (optional)
 580:      */
 581:     public boolean contains(Object o);
 582: 
 583:     /**
 584:      * Returns the number of elements in this deque.
 585:      *
 586:      * @return the number of elements in this deque
 587:      */
 588:     public int size();
 589: 
 590:     /**
 591:      * Returns an iterator over the elements in this deque in proper sequence.
 592:      * The elements will be returned in order from first (head) to last (tail).
 593:      *
 594:      * @return an iterator over the elements in this deque in proper sequence
 595:      */
 596:     Iterator<E> iterator();
 597: 
 598:     // *** Stack methods ***
 599: 
 600:     /**
 601:      * Pushes an element onto the stack represented by this deque.  In other
 602:      * words, inserts the element at the front of this deque unless it would
 603:      * violate capacity restrictions.
 604:      *
 605:      * <p>This method is equivalent to {@link #addFirst(Object) addFirst}.
 606:      *
 607:      * @throws IllegalStateException {@inheritDoc}
 608:      * @throws ClassCastException {@inheritDoc}
 609:      * @throws NullPointerException if the specified element is null
 610:      * @throws IllegalArgumentException {@inheritDoc}
 611:      */
 612:     void push(E e);
 613: }