1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/rt/emul/compact/src/main/java/java/util/concurrent/BlockingDeque.java Sat Mar 19 10:46:31 2016 +0100
1.3 @@ -0,0 +1,650 @@
1.4 +/*
1.5 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.6 + *
1.7 + * This code is free software; you can redistribute it and/or modify it
1.8 + * under the terms of the GNU General Public License version 2 only, as
1.9 + * published by the Free Software Foundation. Oracle designates this
1.10 + * particular file as subject to the "Classpath" exception as provided
1.11 + * by Oracle in the LICENSE file that accompanied this code.
1.12 + *
1.13 + * This code is distributed in the hope that it will be useful, but WITHOUT
1.14 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.15 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.16 + * version 2 for more details (a copy is included in the LICENSE file that
1.17 + * accompanied this code).
1.18 + *
1.19 + * You should have received a copy of the GNU General Public License version
1.20 + * 2 along with this work; if not, write to the Free Software Foundation,
1.21 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.22 + *
1.23 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
1.24 + * or visit www.oracle.com if you need additional information or have any
1.25 + * questions.
1.26 + */
1.27 +
1.28 +/*
1.29 + * This file is available under and governed by the GNU General Public
1.30 + * License version 2 only, as published by the Free Software Foundation.
1.31 + * However, the following notice accompanied the original version of this
1.32 + * file:
1.33 + *
1.34 + * Written by Doug Lea with assistance from members of JCP JSR-166
1.35 + * Expert Group and released to the public domain, as explained at
1.36 + * http://creativecommons.org/publicdomain/zero/1.0/
1.37 + */
1.38 +
1.39 +package java.util.concurrent;
1.40 +import java.util.*;
1.41 +
1.42 +/**
1.43 + * A {@link Deque} that additionally supports blocking operations that wait
1.44 + * for the deque to become non-empty when retrieving an element, and wait for
1.45 + * space to become available in the deque when storing an element.
1.46 + *
1.47 + * <p><tt>BlockingDeque</tt> methods come in four forms, with different ways
1.48 + * of handling operations that cannot be satisfied immediately, but may be
1.49 + * satisfied at some point in the future:
1.50 + * one throws an exception, the second returns a special value (either
1.51 + * <tt>null</tt> or <tt>false</tt>, depending on the operation), the third
1.52 + * blocks the current thread indefinitely until the operation can succeed,
1.53 + * and the fourth blocks for only a given maximum time limit before giving
1.54 + * up. These methods are summarized in the following table:
1.55 + *
1.56 + * <p>
1.57 + * <table BORDER CELLPADDING=3 CELLSPACING=1>
1.58 + * <tr>
1.59 + * <td ALIGN=CENTER COLSPAN = 5> <b>First Element (Head)</b></td>
1.60 + * </tr>
1.61 + * <tr>
1.62 + * <td></td>
1.63 + * <td ALIGN=CENTER><em>Throws exception</em></td>
1.64 + * <td ALIGN=CENTER><em>Special value</em></td>
1.65 + * <td ALIGN=CENTER><em>Blocks</em></td>
1.66 + * <td ALIGN=CENTER><em>Times out</em></td>
1.67 + * </tr>
1.68 + * <tr>
1.69 + * <td><b>Insert</b></td>
1.70 + * <td>{@link #addFirst addFirst(e)}</td>
1.71 + * <td>{@link #offerFirst(Object) offerFirst(e)}</td>
1.72 + * <td>{@link #putFirst putFirst(e)}</td>
1.73 + * <td>{@link #offerFirst(Object, long, TimeUnit) offerFirst(e, time, unit)}</td>
1.74 + * </tr>
1.75 + * <tr>
1.76 + * <td><b>Remove</b></td>
1.77 + * <td>{@link #removeFirst removeFirst()}</td>
1.78 + * <td>{@link #pollFirst pollFirst()}</td>
1.79 + * <td>{@link #takeFirst takeFirst()}</td>
1.80 + * <td>{@link #pollFirst(long, TimeUnit) pollFirst(time, unit)}</td>
1.81 + * </tr>
1.82 + * <tr>
1.83 + * <td><b>Examine</b></td>
1.84 + * <td>{@link #getFirst getFirst()}</td>
1.85 + * <td>{@link #peekFirst peekFirst()}</td>
1.86 + * <td><em>not applicable</em></td>
1.87 + * <td><em>not applicable</em></td>
1.88 + * </tr>
1.89 + * <tr>
1.90 + * <td ALIGN=CENTER COLSPAN = 5> <b>Last Element (Tail)</b></td>
1.91 + * </tr>
1.92 + * <tr>
1.93 + * <td></td>
1.94 + * <td ALIGN=CENTER><em>Throws exception</em></td>
1.95 + * <td ALIGN=CENTER><em>Special value</em></td>
1.96 + * <td ALIGN=CENTER><em>Blocks</em></td>
1.97 + * <td ALIGN=CENTER><em>Times out</em></td>
1.98 + * </tr>
1.99 + * <tr>
1.100 + * <td><b>Insert</b></td>
1.101 + * <td>{@link #addLast addLast(e)}</td>
1.102 + * <td>{@link #offerLast(Object) offerLast(e)}</td>
1.103 + * <td>{@link #putLast putLast(e)}</td>
1.104 + * <td>{@link #offerLast(Object, long, TimeUnit) offerLast(e, time, unit)}</td>
1.105 + * </tr>
1.106 + * <tr>
1.107 + * <td><b>Remove</b></td>
1.108 + * <td>{@link #removeLast() removeLast()}</td>
1.109 + * <td>{@link #pollLast() pollLast()}</td>
1.110 + * <td>{@link #takeLast takeLast()}</td>
1.111 + * <td>{@link #pollLast(long, TimeUnit) pollLast(time, unit)}</td>
1.112 + * </tr>
1.113 + * <tr>
1.114 + * <td><b>Examine</b></td>
1.115 + * <td>{@link #getLast getLast()}</td>
1.116 + * <td>{@link #peekLast peekLast()}</td>
1.117 + * <td><em>not applicable</em></td>
1.118 + * <td><em>not applicable</em></td>
1.119 + * </tr>
1.120 + * </table>
1.121 + *
1.122 + * <p>Like any {@link BlockingQueue}, a <tt>BlockingDeque</tt> is thread safe,
1.123 + * does not permit null elements, and may (or may not) be
1.124 + * capacity-constrained.
1.125 + *
1.126 + * <p>A <tt>BlockingDeque</tt> implementation may be used directly as a FIFO
1.127 + * <tt>BlockingQueue</tt>. The methods inherited from the
1.128 + * <tt>BlockingQueue</tt> interface are precisely equivalent to
1.129 + * <tt>BlockingDeque</tt> methods as indicated in the following table:
1.130 + *
1.131 + * <p>
1.132 + * <table BORDER CELLPADDING=3 CELLSPACING=1>
1.133 + * <tr>
1.134 + * <td ALIGN=CENTER> <b><tt>BlockingQueue</tt> Method</b></td>
1.135 + * <td ALIGN=CENTER> <b>Equivalent <tt>BlockingDeque</tt> Method</b></td>
1.136 + * </tr>
1.137 + * <tr>
1.138 + * <td ALIGN=CENTER COLSPAN = 2> <b>Insert</b></td>
1.139 + * </tr>
1.140 + * <tr>
1.141 + * <td>{@link #add(Object) add(e)}</td>
1.142 + * <td>{@link #addLast(Object) addLast(e)}</td>
1.143 + * </tr>
1.144 + * <tr>
1.145 + * <td>{@link #offer(Object) offer(e)}</td>
1.146 + * <td>{@link #offerLast(Object) offerLast(e)}</td>
1.147 + * </tr>
1.148 + * <tr>
1.149 + * <td>{@link #put(Object) put(e)}</td>
1.150 + * <td>{@link #putLast(Object) putLast(e)}</td>
1.151 + * </tr>
1.152 + * <tr>
1.153 + * <td>{@link #offer(Object, long, TimeUnit) offer(e, time, unit)}</td>
1.154 + * <td>{@link #offerLast(Object, long, TimeUnit) offerLast(e, time, unit)}</td>
1.155 + * </tr>
1.156 + * <tr>
1.157 + * <td ALIGN=CENTER COLSPAN = 2> <b>Remove</b></td>
1.158 + * </tr>
1.159 + * <tr>
1.160 + * <td>{@link #remove() remove()}</td>
1.161 + * <td>{@link #removeFirst() removeFirst()}</td>
1.162 + * </tr>
1.163 + * <tr>
1.164 + * <td>{@link #poll() poll()}</td>
1.165 + * <td>{@link #pollFirst() pollFirst()}</td>
1.166 + * </tr>
1.167 + * <tr>
1.168 + * <td>{@link #take() take()}</td>
1.169 + * <td>{@link #takeFirst() takeFirst()}</td>
1.170 + * </tr>
1.171 + * <tr>
1.172 + * <td>{@link #poll(long, TimeUnit) poll(time, unit)}</td>
1.173 + * <td>{@link #pollFirst(long, TimeUnit) pollFirst(time, unit)}</td>
1.174 + * </tr>
1.175 + * <tr>
1.176 + * <td ALIGN=CENTER COLSPAN = 2> <b>Examine</b></td>
1.177 + * </tr>
1.178 + * <tr>
1.179 + * <td>{@link #element() element()}</td>
1.180 + * <td>{@link #getFirst() getFirst()}</td>
1.181 + * </tr>
1.182 + * <tr>
1.183 + * <td>{@link #peek() peek()}</td>
1.184 + * <td>{@link #peekFirst() peekFirst()}</td>
1.185 + * </tr>
1.186 + * </table>
1.187 + *
1.188 + * <p>Memory consistency effects: As with other concurrent
1.189 + * collections, actions in a thread prior to placing an object into a
1.190 + * {@code BlockingDeque}
1.191 + * <a href="package-summary.html#MemoryVisibility"><i>happen-before</i></a>
1.192 + * actions subsequent to the access or removal of that element from
1.193 + * the {@code BlockingDeque} in another thread.
1.194 + *
1.195 + * <p>This interface is a member of the
1.196 + * <a href="{@docRoot}/../technotes/guides/collections/index.html">
1.197 + * Java Collections Framework</a>.
1.198 + *
1.199 + * @since 1.6
1.200 + * @author Doug Lea
1.201 + * @param <E> the type of elements held in this collection
1.202 + */
1.203 +public interface BlockingDeque<E> extends BlockingQueue<E>, Deque<E> {
1.204 + /*
1.205 + * We have "diamond" multiple interface inheritance here, and that
1.206 + * introduces ambiguities. Methods might end up with different
1.207 + * specs depending on the branch chosen by javadoc. Thus a lot of
1.208 + * methods specs here are copied from superinterfaces.
1.209 + */
1.210 +
1.211 + /**
1.212 + * Inserts the specified element at the front of this deque if it is
1.213 + * possible to do so immediately without violating capacity restrictions,
1.214 + * throwing an <tt>IllegalStateException</tt> if no space is currently
1.215 + * available. When using a capacity-restricted deque, it is generally
1.216 + * preferable to use {@link #offerFirst(Object) offerFirst}.
1.217 + *
1.218 + * @param e the element to add
1.219 + * @throws IllegalStateException {@inheritDoc}
1.220 + * @throws ClassCastException {@inheritDoc}
1.221 + * @throws NullPointerException if the specified element is null
1.222 + * @throws IllegalArgumentException {@inheritDoc}
1.223 + */
1.224 + void addFirst(E e);
1.225 +
1.226 + /**
1.227 + * Inserts the specified element at the end of this deque if it is
1.228 + * possible to do so immediately without violating capacity restrictions,
1.229 + * throwing an <tt>IllegalStateException</tt> if no space is currently
1.230 + * available. When using a capacity-restricted deque, it is generally
1.231 + * preferable to use {@link #offerLast(Object) offerLast}.
1.232 + *
1.233 + * @param e the element to add
1.234 + * @throws IllegalStateException {@inheritDoc}
1.235 + * @throws ClassCastException {@inheritDoc}
1.236 + * @throws NullPointerException if the specified element is null
1.237 + * @throws IllegalArgumentException {@inheritDoc}
1.238 + */
1.239 + void addLast(E e);
1.240 +
1.241 + /**
1.242 + * Inserts the specified element at the front of this deque if it is
1.243 + * possible to do so immediately without violating capacity restrictions,
1.244 + * returning <tt>true</tt> upon success and <tt>false</tt> if no space is
1.245 + * currently available.
1.246 + * When using a capacity-restricted deque, this method is generally
1.247 + * preferable to the {@link #addFirst(Object) addFirst} method, which can
1.248 + * fail to insert an element only by throwing an exception.
1.249 + *
1.250 + * @param e the element to add
1.251 + * @throws ClassCastException {@inheritDoc}
1.252 + * @throws NullPointerException if the specified element is null
1.253 + * @throws IllegalArgumentException {@inheritDoc}
1.254 + */
1.255 + boolean offerFirst(E e);
1.256 +
1.257 + /**
1.258 + * Inserts the specified element at the end of this deque if it is
1.259 + * possible to do so immediately without violating capacity restrictions,
1.260 + * returning <tt>true</tt> upon success and <tt>false</tt> if no space is
1.261 + * currently available.
1.262 + * When using a capacity-restricted deque, this method is generally
1.263 + * preferable to the {@link #addLast(Object) addLast} method, which can
1.264 + * fail to insert an element only by throwing an exception.
1.265 + *
1.266 + * @param e the element to add
1.267 + * @throws ClassCastException {@inheritDoc}
1.268 + * @throws NullPointerException if the specified element is null
1.269 + * @throws IllegalArgumentException {@inheritDoc}
1.270 + */
1.271 + boolean offerLast(E e);
1.272 +
1.273 + /**
1.274 + * Inserts the specified element at the front of this deque,
1.275 + * waiting if necessary for space to become available.
1.276 + *
1.277 + * @param e the element to add
1.278 + * @throws InterruptedException if interrupted while waiting
1.279 + * @throws ClassCastException if the class of the specified element
1.280 + * prevents it from being added to this deque
1.281 + * @throws NullPointerException if the specified element is null
1.282 + * @throws IllegalArgumentException if some property of the specified
1.283 + * element prevents it from being added to this deque
1.284 + */
1.285 + void putFirst(E e) throws InterruptedException;
1.286 +
1.287 + /**
1.288 + * Inserts the specified element at the end of this deque,
1.289 + * waiting if necessary for space to become available.
1.290 + *
1.291 + * @param e the element to add
1.292 + * @throws InterruptedException if interrupted while waiting
1.293 + * @throws ClassCastException if the class of the specified element
1.294 + * prevents it from being added to this deque
1.295 + * @throws NullPointerException if the specified element is null
1.296 + * @throws IllegalArgumentException if some property of the specified
1.297 + * element prevents it from being added to this deque
1.298 + */
1.299 + void putLast(E e) throws InterruptedException;
1.300 +
1.301 + /**
1.302 + * Inserts the specified element at the front of this deque,
1.303 + * waiting up to the specified wait time if necessary for space to
1.304 + * become available.
1.305 + *
1.306 + * @param e the element to add
1.307 + * @param timeout how long to wait before giving up, in units of
1.308 + * <tt>unit</tt>
1.309 + * @param unit a <tt>TimeUnit</tt> determining how to interpret the
1.310 + * <tt>timeout</tt> parameter
1.311 + * @return <tt>true</tt> if successful, or <tt>false</tt> if
1.312 + * the specified waiting time elapses before space is available
1.313 + * @throws InterruptedException if interrupted while waiting
1.314 + * @throws ClassCastException if the class of the specified element
1.315 + * prevents it from being added to this deque
1.316 + * @throws NullPointerException if the specified element is null
1.317 + * @throws IllegalArgumentException if some property of the specified
1.318 + * element prevents it from being added to this deque
1.319 + */
1.320 + boolean offerFirst(E e, long timeout, TimeUnit unit)
1.321 + throws InterruptedException;
1.322 +
1.323 + /**
1.324 + * Inserts the specified element at the end of this deque,
1.325 + * waiting up to the specified wait time if necessary for space to
1.326 + * become available.
1.327 + *
1.328 + * @param e the element to add
1.329 + * @param timeout how long to wait before giving up, in units of
1.330 + * <tt>unit</tt>
1.331 + * @param unit a <tt>TimeUnit</tt> determining how to interpret the
1.332 + * <tt>timeout</tt> parameter
1.333 + * @return <tt>true</tt> if successful, or <tt>false</tt> if
1.334 + * the specified waiting time elapses before space is available
1.335 + * @throws InterruptedException if interrupted while waiting
1.336 + * @throws ClassCastException if the class of the specified element
1.337 + * prevents it from being added to this deque
1.338 + * @throws NullPointerException if the specified element is null
1.339 + * @throws IllegalArgumentException if some property of the specified
1.340 + * element prevents it from being added to this deque
1.341 + */
1.342 + boolean offerLast(E e, long timeout, TimeUnit unit)
1.343 + throws InterruptedException;
1.344 +
1.345 + /**
1.346 + * Retrieves and removes the first element of this deque, waiting
1.347 + * if necessary until an element becomes available.
1.348 + *
1.349 + * @return the head of this deque
1.350 + * @throws InterruptedException if interrupted while waiting
1.351 + */
1.352 + E takeFirst() throws InterruptedException;
1.353 +
1.354 + /**
1.355 + * Retrieves and removes the last element of this deque, waiting
1.356 + * if necessary until an element becomes available.
1.357 + *
1.358 + * @return the tail of this deque
1.359 + * @throws InterruptedException if interrupted while waiting
1.360 + */
1.361 + E takeLast() throws InterruptedException;
1.362 +
1.363 + /**
1.364 + * Retrieves and removes the first element of this deque, waiting
1.365 + * up to the specified wait time if necessary for an element to
1.366 + * become available.
1.367 + *
1.368 + * @param timeout how long to wait before giving up, in units of
1.369 + * <tt>unit</tt>
1.370 + * @param unit a <tt>TimeUnit</tt> determining how to interpret the
1.371 + * <tt>timeout</tt> parameter
1.372 + * @return the head of this deque, or <tt>null</tt> if the specified
1.373 + * waiting time elapses before an element is available
1.374 + * @throws InterruptedException if interrupted while waiting
1.375 + */
1.376 + E pollFirst(long timeout, TimeUnit unit)
1.377 + throws InterruptedException;
1.378 +
1.379 + /**
1.380 + * Retrieves and removes the last element of this deque, waiting
1.381 + * up to the specified wait time if necessary for an element to
1.382 + * become available.
1.383 + *
1.384 + * @param timeout how long to wait before giving up, in units of
1.385 + * <tt>unit</tt>
1.386 + * @param unit a <tt>TimeUnit</tt> determining how to interpret the
1.387 + * <tt>timeout</tt> parameter
1.388 + * @return the tail of this deque, or <tt>null</tt> if the specified
1.389 + * waiting time elapses before an element is available
1.390 + * @throws InterruptedException if interrupted while waiting
1.391 + */
1.392 + E pollLast(long timeout, TimeUnit unit)
1.393 + throws InterruptedException;
1.394 +
1.395 + /**
1.396 + * Removes the first occurrence of the specified element from this deque.
1.397 + * If the deque does not contain the element, it is unchanged.
1.398 + * More formally, removes the first element <tt>e</tt> such that
1.399 + * <tt>o.equals(e)</tt> (if such an element exists).
1.400 + * Returns <tt>true</tt> if this deque contained the specified element
1.401 + * (or equivalently, if this deque changed as a result of the call).
1.402 + *
1.403 + * @param o element to be removed from this deque, if present
1.404 + * @return <tt>true</tt> if an element was removed as a result of this call
1.405 + * @throws ClassCastException if the class of the specified element
1.406 + * is incompatible with this deque
1.407 + * (<a href="../Collection.html#optional-restrictions">optional</a>)
1.408 + * @throws NullPointerException if the specified element is null
1.409 + * (<a href="../Collection.html#optional-restrictions">optional</a>)
1.410 + */
1.411 + boolean removeFirstOccurrence(Object o);
1.412 +
1.413 + /**
1.414 + * Removes the last occurrence of the specified element from this deque.
1.415 + * If the deque does not contain the element, it is unchanged.
1.416 + * More formally, removes the last element <tt>e</tt> such that
1.417 + * <tt>o.equals(e)</tt> (if such an element exists).
1.418 + * Returns <tt>true</tt> if this deque contained the specified element
1.419 + * (or equivalently, if this deque changed as a result of the call).
1.420 + *
1.421 + * @param o element to be removed from this deque, if present
1.422 + * @return <tt>true</tt> if an element was removed as a result of this call
1.423 + * @throws ClassCastException if the class of the specified element
1.424 + * is incompatible with this deque
1.425 + * (<a href="../Collection.html#optional-restrictions">optional</a>)
1.426 + * @throws NullPointerException if the specified element is null
1.427 + * (<a href="../Collection.html#optional-restrictions">optional</a>)
1.428 + */
1.429 + boolean removeLastOccurrence(Object o);
1.430 +
1.431 + // *** BlockingQueue methods ***
1.432 +
1.433 + /**
1.434 + * Inserts the specified element into the queue represented by this deque
1.435 + * (in other words, at the tail of this deque) if it is possible to do so
1.436 + * immediately without violating capacity restrictions, returning
1.437 + * <tt>true</tt> upon success and throwing an
1.438 + * <tt>IllegalStateException</tt> if no space is currently available.
1.439 + * When using a capacity-restricted deque, it is generally preferable to
1.440 + * use {@link #offer(Object) offer}.
1.441 + *
1.442 + * <p>This method is equivalent to {@link #addLast(Object) addLast}.
1.443 + *
1.444 + * @param e the element to add
1.445 + * @throws IllegalStateException {@inheritDoc}
1.446 + * @throws ClassCastException if the class of the specified element
1.447 + * prevents it from being added to this deque
1.448 + * @throws NullPointerException if the specified element is null
1.449 + * @throws IllegalArgumentException if some property of the specified
1.450 + * element prevents it from being added to this deque
1.451 + */
1.452 + boolean add(E e);
1.453 +
1.454 + /**
1.455 + * Inserts the specified element into the queue represented by this deque
1.456 + * (in other words, at the tail of this deque) if it is possible to do so
1.457 + * immediately without violating capacity restrictions, returning
1.458 + * <tt>true</tt> upon success and <tt>false</tt> if no space is currently
1.459 + * available. When using a capacity-restricted deque, this method is
1.460 + * generally preferable to the {@link #add} method, which can fail to
1.461 + * insert an element only by throwing an exception.
1.462 + *
1.463 + * <p>This method is equivalent to {@link #offerLast(Object) offerLast}.
1.464 + *
1.465 + * @param e the element to add
1.466 + * @throws ClassCastException if the class of the specified element
1.467 + * prevents it from being added to this deque
1.468 + * @throws NullPointerException if the specified element is null
1.469 + * @throws IllegalArgumentException if some property of the specified
1.470 + * element prevents it from being added to this deque
1.471 + */
1.472 + boolean offer(E e);
1.473 +
1.474 + /**
1.475 + * Inserts the specified element into the queue represented by this deque
1.476 + * (in other words, at the tail of this deque), waiting if necessary for
1.477 + * space to become available.
1.478 + *
1.479 + * <p>This method is equivalent to {@link #putLast(Object) putLast}.
1.480 + *
1.481 + * @param e the element to add
1.482 + * @throws InterruptedException {@inheritDoc}
1.483 + * @throws ClassCastException if the class of the specified element
1.484 + * prevents it from being added to this deque
1.485 + * @throws NullPointerException if the specified element is null
1.486 + * @throws IllegalArgumentException if some property of the specified
1.487 + * element prevents it from being added to this deque
1.488 + */
1.489 + void put(E e) throws InterruptedException;
1.490 +
1.491 + /**
1.492 + * Inserts the specified element into the queue represented by this deque
1.493 + * (in other words, at the tail of this deque), waiting up to the
1.494 + * specified wait time if necessary for space to become available.
1.495 + *
1.496 + * <p>This method is equivalent to
1.497 + * {@link #offerLast(Object,long,TimeUnit) offerLast}.
1.498 + *
1.499 + * @param e the element to add
1.500 + * @return <tt>true</tt> if the element was added to this deque, else
1.501 + * <tt>false</tt>
1.502 + * @throws InterruptedException {@inheritDoc}
1.503 + * @throws ClassCastException if the class of the specified element
1.504 + * prevents it from being added to this deque
1.505 + * @throws NullPointerException if the specified element is null
1.506 + * @throws IllegalArgumentException if some property of the specified
1.507 + * element prevents it from being added to this deque
1.508 + */
1.509 + boolean offer(E e, long timeout, TimeUnit unit)
1.510 + throws InterruptedException;
1.511 +
1.512 + /**
1.513 + * Retrieves and removes the head of the queue represented by this deque
1.514 + * (in other words, the first element of this deque).
1.515 + * This method differs from {@link #poll poll} only in that it
1.516 + * throws an exception if this deque is empty.
1.517 + *
1.518 + * <p>This method is equivalent to {@link #removeFirst() removeFirst}.
1.519 + *
1.520 + * @return the head of the queue represented by this deque
1.521 + * @throws NoSuchElementException if this deque is empty
1.522 + */
1.523 + E remove();
1.524 +
1.525 + /**
1.526 + * Retrieves and removes the head of the queue represented by this deque
1.527 + * (in other words, the first element of this deque), or returns
1.528 + * <tt>null</tt> if this deque is empty.
1.529 + *
1.530 + * <p>This method is equivalent to {@link #pollFirst()}.
1.531 + *
1.532 + * @return the head of this deque, or <tt>null</tt> if this deque is empty
1.533 + */
1.534 + E poll();
1.535 +
1.536 + /**
1.537 + * Retrieves and removes the head of the queue represented by this deque
1.538 + * (in other words, the first element of this deque), waiting if
1.539 + * necessary until an element becomes available.
1.540 + *
1.541 + * <p>This method is equivalent to {@link #takeFirst() takeFirst}.
1.542 + *
1.543 + * @return the head of this deque
1.544 + * @throws InterruptedException if interrupted while waiting
1.545 + */
1.546 + E take() throws InterruptedException;
1.547 +
1.548 + /**
1.549 + * Retrieves and removes the head of the queue represented by this deque
1.550 + * (in other words, the first element of this deque), waiting up to the
1.551 + * specified wait time if necessary for an element to become available.
1.552 + *
1.553 + * <p>This method is equivalent to
1.554 + * {@link #pollFirst(long,TimeUnit) pollFirst}.
1.555 + *
1.556 + * @return the head of this deque, or <tt>null</tt> if the
1.557 + * specified waiting time elapses before an element is available
1.558 + * @throws InterruptedException if interrupted while waiting
1.559 + */
1.560 + E poll(long timeout, TimeUnit unit)
1.561 + throws InterruptedException;
1.562 +
1.563 + /**
1.564 + * Retrieves, but does not remove, the head of the queue represented by
1.565 + * this deque (in other words, the first element of this deque).
1.566 + * This method differs from {@link #peek peek} only in that it throws an
1.567 + * exception if this deque is empty.
1.568 + *
1.569 + * <p>This method is equivalent to {@link #getFirst() getFirst}.
1.570 + *
1.571 + * @return the head of this deque
1.572 + * @throws NoSuchElementException if this deque is empty
1.573 + */
1.574 + E element();
1.575 +
1.576 + /**
1.577 + * Retrieves, but does not remove, the head of the queue represented by
1.578 + * this deque (in other words, the first element of this deque), or
1.579 + * returns <tt>null</tt> if this deque is empty.
1.580 + *
1.581 + * <p>This method is equivalent to {@link #peekFirst() peekFirst}.
1.582 + *
1.583 + * @return the head of this deque, or <tt>null</tt> if this deque is empty
1.584 + */
1.585 + E peek();
1.586 +
1.587 + /**
1.588 + * Removes the first occurrence of the specified element from this deque.
1.589 + * If the deque does not contain the element, it is unchanged.
1.590 + * More formally, removes the first element <tt>e</tt> such that
1.591 + * <tt>o.equals(e)</tt> (if such an element exists).
1.592 + * Returns <tt>true</tt> if this deque contained the specified element
1.593 + * (or equivalently, if this deque changed as a result of the call).
1.594 + *
1.595 + * <p>This method is equivalent to
1.596 + * {@link #removeFirstOccurrence(Object) removeFirstOccurrence}.
1.597 + *
1.598 + * @param o element to be removed from this deque, if present
1.599 + * @return <tt>true</tt> if this deque changed as a result of the call
1.600 + * @throws ClassCastException if the class of the specified element
1.601 + * is incompatible with this deque
1.602 + * (<a href="../Collection.html#optional-restrictions">optional</a>)
1.603 + * @throws NullPointerException if the specified element is null
1.604 + * (<a href="../Collection.html#optional-restrictions">optional</a>)
1.605 + */
1.606 + boolean remove(Object o);
1.607 +
1.608 + /**
1.609 + * Returns <tt>true</tt> if this deque contains the specified element.
1.610 + * More formally, returns <tt>true</tt> if and only if this deque contains
1.611 + * at least one element <tt>e</tt> such that <tt>o.equals(e)</tt>.
1.612 + *
1.613 + * @param o object to be checked for containment in this deque
1.614 + * @return <tt>true</tt> if this deque contains the specified element
1.615 + * @throws ClassCastException if the class of the specified element
1.616 + * is incompatible with this deque
1.617 + * (<a href="../Collection.html#optional-restrictions">optional</a>)
1.618 + * @throws NullPointerException if the specified element is null
1.619 + * (<a href="../Collection.html#optional-restrictions">optional</a>)
1.620 + */
1.621 + public boolean contains(Object o);
1.622 +
1.623 + /**
1.624 + * Returns the number of elements in this deque.
1.625 + *
1.626 + * @return the number of elements in this deque
1.627 + */
1.628 + public int size();
1.629 +
1.630 + /**
1.631 + * Returns an iterator over the elements in this deque in proper sequence.
1.632 + * The elements will be returned in order from first (head) to last (tail).
1.633 + *
1.634 + * @return an iterator over the elements in this deque in proper sequence
1.635 + */
1.636 + Iterator<E> iterator();
1.637 +
1.638 + // *** Stack methods ***
1.639 +
1.640 + /**
1.641 + * Pushes an element onto the stack represented by this deque. In other
1.642 + * words, inserts the element at the front of this deque unless it would
1.643 + * violate capacity restrictions.
1.644 + *
1.645 + * <p>This method is equivalent to {@link #addFirst(Object) addFirst}.
1.646 + *
1.647 + * @throws IllegalStateException {@inheritDoc}
1.648 + * @throws ClassCastException {@inheritDoc}
1.649 + * @throws NullPointerException if the specified element is null
1.650 + * @throws IllegalArgumentException {@inheritDoc}
1.651 + */
1.652 + void push(E e);
1.653 +}