3 Replies Latest reply on Jun 23, 2009 12:20 PM by Trustin Lee

    Diff between doug lea's & java 6 LinkedBlockingDeque

    Jeff Mesnil Master

      For https://jira.jboss.org/jira/browse/JBMESSAGING-1437, we use a LinkedBlockingDeque as the underlying data structures for a Queue's message references.

      This class appeared in Java 6.
      For Java 5, we imported in our code base, the backport from doug lea http://gee.cs.oswego.edu/dl/concurrency-interest/index.html

      Unfortunately, the base interface Deque is only in Java 6 only so it is not possible to have common code which works both on Java 5 and Java 6 (with the deque created through reflection) since Java 5 does not have the required interface hierarchy.
      This means we will use the backport when running on Java 6 too.

      For reference, here is the diff between the backport and the sources in Java 6 of the 3 required types: Deque, BlockingDeque and LinkedBlockingDeque.

      I have not spotted obvious differences in the code but the javadoc and the method orders are different making a lot of noise in the diff

      diff -r lea/BlockingDeque.java java6/BlockingDeque.java
      2,4c2,5
      < * Written by Doug Lea with assistance from members of JCP JSR-166
      < * Expert Group and released to the public domain, as explained at
      < * http://creativecommons.org/licenses/publicdomain
      ---
      > * @(#)BlockingDeque.java 1.5 06/04/21
      > *
      > * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
      > * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
      7,9c8,9
      < package org.jboss.messaging.utils.concurrent; // XXX This belongs in java.util!!! XXX
      < import java.util.concurrent.*; // XXX This import goes away XXX
      < import java.util.*;
      ---
      > package java.util.concurrent;
      > import java.util.*;
      12,15c12,23
      < * A {@link Deque} that additionally supports operations that wait for
      < * the deque to become non-empty when retrieving an element, and wait
      < * for space to become available in the deque when storing an
      < * element. These methods are summarized in the following table:<p>
      ---
      > * A {@link Deque} that additionally supports blocking operations that wait
      > * for the deque to become non-empty when retrieving an element, and wait for
      > * space to become available in the deque when storing an element.
      > *
      > * <p><tt>BlockingDeque</tt> methods come in four forms, with different ways
      > * of handling operations that cannot be satisfied immediately, but may be
      > * satisfied at some point in the future:
      > * one throws an exception, the second returns a special value (either
      > * <tt>null</tt> or <tt>false</tt>, depending on the operation), the third
      > * blocks the current thread indefinitely until the operation can succeed,
      > * and the fourth blocks for only a given maximum time limit before giving
      > * up. These methods are summarized in the following table:
      16a25
      > * <p>
      19,21c28
      < * <td></td>
      < * <td ALIGN=CENTER COLSPAN = 2> <b>First Element (Head)</b></td>
      < * <td ALIGN=CENTER COLSPAN = 2> <b>Last Element (Tail)</b></td>
      ---
      > * <td ALIGN=CENTER COLSPAN = 5> <b>First Element (Head)</b></td>
      25,28c32,35
      < * <td ALIGN=CENTER><em>Block</em></td>
      < * <td ALIGN=CENTER><em>Time out</em></td>
      < * <td ALIGN=CENTER><em>Block</em></td>
      < * <td ALIGN=CENTER><em>Time out</em></td>
      ---
      > * <td ALIGN=CENTER><em>Throws exception</em></td>
      > * <td ALIGN=CENTER><em>Special value</em></td>
      > * <td ALIGN=CENTER><em>Blocks</em></td>
      > * <td ALIGN=CENTER><em>Times out</em></td>
      31a39,40
      > * <td>{@link #addFirst addFirst(e)}</td>
      > * <td>{@link #offerFirst(Object) offerFirst(e)}</td>
      34,35d42
      < * <td>{@link #putLast putLast(e)}</td>
      < * <td>{@link #offerLast(Object, long, TimeUnit) offerLast(e, time, unit)}</td>
      38a46,47
      > * <td>{@link #removeFirst removeFirst()}</td>
      > * <td>{@link #pollFirst pollFirst()}</td>
      40c49,78
      < * <td>{@link #pollFirst(long, TimeUnit) pollFirst(time, unit)}</td>
      ---
      > * <td>{@link #pollFirst(long, TimeUnit) pollFirst(time, unit)}</td>
      > * </tr>
      > * <tr>
      > * <td><b>Examine</b></td>
      > * <td>{@link #getFirst getFirst()}</td>
      > * <td>{@link #peekFirst peekFirst()}</td>
      > * <td><em>not applicable</em></td>
      > * <td><em>not applicable</em></td>
      > * </tr>
      > * <tr>
      > * <td ALIGN=CENTER COLSPAN = 5> <b>Last Element (Tail)</b></td>
      > * </tr>
      > * <tr>
      > * <td></td>
      > * <td ALIGN=CENTER><em>Throws exception</em></td>
      > * <td ALIGN=CENTER><em>Special value</em></td>
      > * <td ALIGN=CENTER><em>Blocks</em></td>
      > * <td ALIGN=CENTER><em>Times out</em></td>
      > * </tr>
      > * <tr>
      > * <td><b>Insert</b></td>
      > * <td>{@link #addLast addLast(e)}</td>
      > * <td>{@link #offerLast(Object) offerLast(e)}</td>
      > * <td>{@link #putLast putLast(e)}</td>
      > * <td>{@link #offerLast(Object, long, TimeUnit) offerLast(e, time, unit)}</td>
      > * </tr>
      > * <tr>
      > * <td><b>Remove</b></td>
      > * <td>{@link #removeLast() removeLast()}</td>
      > * <td>{@link #pollLast() pollLast()}</td>
      43a82,88
      > * <tr>
      > * <td><b>Examine</b></td>
      > * <td>{@link #getLast getLast()}</td>
      > * <td>{@link #peekLast peekLast()}</td>
      > * <td><em>not applicable</em></td>
      > * <td><em>not applicable</em></td>
      > * </tr>
      46,51c91,98
      < * <p>Like any {@link BlockingQueue}, a <tt>BlockingDeque</tt> is
      < * thread safe and may (or may not) be capacity-constrained. A
      < * <tt>BlockingDeque</tt> implementation may be used directly as a
      < * FIFO <tt>BlockingQueue</tt>. The blocking methods inherited from
      < * the <tt>BlockingQueue</tt> interface are precisely equivalent to
      < * <tt>BlockingDeque</tt> methods as indicated in the following table:<p>
      ---
      > * <p>Like any {@link BlockingQueue}, a <tt>BlockingDeque</tt> is thread safe,
      > * does not permit null elements, and may (or may not) be
      > * capacity-constrained.
      > *
      > * <p>A <tt>BlockingDeque</tt> implementation may be used directly as a FIFO
      > * <tt>BlockingQueue</tt>. The methods inherited from the
      > * <tt>BlockingQueue</tt> interface are precisely equivalent to
      > * <tt>BlockingDeque</tt> methods as indicated in the following table:
      52a100
      > * <p>
      59,68c107,122
      < * <tr>
      < * <td>{@link java.util.concurrent.BlockingQueue#put put(e)}</td>
      < * <td>{@link #putLast putLast(e)}</td>
      < * </tr>
      < * <tr>
      < * <td>{@link java.util.concurrent.BlockingQueue#take take()}</td>
      < * <td>{@link #takeFirst takeFirst()}</td>
      < * </tr>
      < * <tr>
      < * <td>{@link java.util.concurrent.BlockingQueue#offer(Object, long, TimeUnit) offer(e, time. unit)}</td>
      ---
      > * <td ALIGN=CENTER COLSPAN = 2> <b>Insert</b></td>
      > * </tr>
      > * <tr>
      > * <td>{@link #add(Object) add(e)}</td>
      > * <td>{@link #addLast(Object) addLast(e)}</td>
      > * </tr>
      > * <tr>
      > * <td>{@link #offer(Object) offer(e)}</td>
      > * <td>{@link #offerLast(Object) offerLast(e)}</td>
      > * </tr>
      > * <tr>
      > * <td>{@link #put(Object) put(e)}</td>
      > * <td>{@link #putLast(Object) putLast(e)}</td>
      > * </tr>
      > * <tr>
      > * <td>{@link #offer(Object, long, TimeUnit) offer(e, time, unit)}</td>
      70,72c124,141
      < * </tr>
      < * <tr>
      < * <td>{@link java.util.concurrent.BlockingQueue#poll(long, TimeUnit) poll(time, unit)}</td>
      ---
      > * </tr>
      > * <tr>
      > * <td ALIGN=CENTER COLSPAN = 2> <b>Remove</b></td>
      > * </tr>
      > * <tr>
      > * <td>{@link #remove() remove()}</td>
      > * <td>{@link #removeFirst() removeFirst()}</td>
      > * </tr>
      > * <tr>
      > * <td>{@link #poll() poll()}</td>
      > * <td>{@link #pollFirst() pollFirst()}</td>
      > * </tr>
      > * <tr>
      > * <td>{@link #take() take()}</td>
      > * <td>{@link #takeFirst() takeFirst()}</td>
      > * </tr>
      > * <tr>
      > * <td>{@link #poll(long, TimeUnit) poll(time, unit)}</td>
      74c143,154
      < * </tr>
      ---
      > * </tr>
      > * <tr>
      > * <td ALIGN=CENTER COLSPAN = 2> <b>Examine</b></td>
      > * </tr>
      > * <tr>
      > * <td>{@link #element() element()}</td>
      > * <td>{@link #getFirst() getFirst()}</td>
      > * </tr>
      > * <tr>
      > * <td>{@link #peek() peek()}</td>
      > * <td>{@link #peekFirst() peekFirst()}</td>
      > * </tr>
      76a157,162
      > * <p>Memory consistency effects: As with other concurrent
      > * collections, actions in a thread prior to placing an object into a
      > * {@code BlockingDeque}
      > * <a href="package-summary.html#MemoryVisibility"><i>happen-before</i></a>
      > * actions subsequent to the access or removal of that element from
      > * the {@code BlockingDeque} in another thread.
      79c165
      < * <a href="{@docRoot}/../guide/collections/index.html">
      ---
      > * <a href="{@docRoot}/../technotes/guides/collections/index.html">
      86c172,178
      < public interface BlockingDeque<E> extends Deque<E>, BlockingQueue<E> {
      ---
      > public interface BlockingDeque<E> extends BlockingQueue<E>, Deque<E> {
      > /*
      > * We have "diamond" multiple interface inheritance here, and that
      > * introduces ambiguities. Methods might end up with different
      > * specs depending on the branch chosen by javadoc. Thus a lot of
      > * methods specs here are copied from superinterfaces.
      > */
      89,95c181,193
      < * Adds the specified element as the first element of this deque,
      < * waiting if necessary for space to become available.
      < * @param o the element to add
      < * @throws InterruptedException if interrupted while waiting.
      < * @throws NullPointerException if the specified element is <tt>null</tt>.
      < */
      < void putFirst(E o) throws InterruptedException;
      ---
      > * Inserts the specified element at the front of this deque if it is
      > * possible to do so immediately without violating capacity restrictions,
      > * throwing an <tt>IllegalStateException</tt> if no space is currently
      > * available. When using a capacity-restricted deque, it is generally
      > * preferable to use {@link #offerFirst(Object) offerFirst}.
      > *
      > * @param e the element to add
      > * @throws IllegalStateException {@inheritDoc}
      > * @throws ClassCastException {@inheritDoc}
      > * @throws NullPointerException if the specified element is null
      > * @throws IllegalArgumentException {@inheritDoc}
      > */
      > void addFirst(E e);
      98,102c196,238
      < * Adds the specified element as the last element of this deque,
      < * waiting if necessary for space to become available.
      < * @param o the element to add
      < * @throws InterruptedException if interrupted while waiting.
      < * @throws NullPointerException if the specified element is <tt>null</tt>.
      ---
      > * Inserts the specified element at the end of this deque if it is
      > * possible to do so immediately without violating capacity restrictions,
      > * throwing an <tt>IllegalStateException</tt> if no space is currently
      > * available. When using a capacity-restricted deque, it is generally
      > * preferable to use {@link #offerLast(Object) offerLast}.
      > *
      > * @param e the element to add
      > * @throws IllegalStateException {@inheritDoc}
      > * @throws ClassCastException {@inheritDoc}
      > * @throws NullPointerException if the specified element is null
      > * @throws IllegalArgumentException {@inheritDoc}
      > */
      > void addLast(E e);
      >
      > /**
      > * Inserts the specified element at the front of this deque if it is
      > * possible to do so immediately without violating capacity restrictions,
      > * returning <tt>true</tt> upon success and <tt>false</tt> if no space is
      > * currently available.
      > * When using a capacity-restricted deque, this method is generally
      > * preferable to the {@link #addFirst(Object) addFirst} method, which can
      > * fail to insert an element only by throwing an exception.
      > *
      > * @param e the element to add
      > * @throws ClassCastException {@inheritDoc}
      > * @throws NullPointerException if the specified element is null
      > * @throws IllegalArgumentException {@inheritDoc}
      > */
      > boolean offerFirst(E e);
      >
      > /**
      > * Inserts the specified element at the end of this deque if it is
      > * possible to do so immediately without violating capacity restrictions,
      > * returning <tt>true</tt> upon success and <tt>false</tt> if no space is
      > * currently available.
      > * When using a capacity-restricted deque, this method is generally
      > * preferable to the {@link #addLast(Object) addLast} method, which can
      > * fail to insert an element only by throwing an exception.
      > *
      > * @param e the element to add
      > * @throws ClassCastException {@inheritDoc}
      > * @throws NullPointerException if the specified element is null
      > * @throws IllegalArgumentException {@inheritDoc}
      104c240
      < void putLast(E o) throws InterruptedException;
      ---
      > boolean offerLast(E e);
      107,110c243,252
      < * Retrieves and removes the first element of this deque, waiting
      < * if no elements are present on this deque.
      < * @return the head of this deque
      < * @throws InterruptedException if interrupted while waiting.
      ---
      > * Inserts the specified element at the front of this deque,
      > * waiting if necessary for space to become available.
      > *
      > * @param e the element to add
      > * @throws InterruptedException if interrupted while waiting
      > * @throws ClassCastException if the class of the specified element
      > * prevents it from being added to this deque
      > * @throws NullPointerException if the specified element is null
      > * @throws IllegalArgumentException if some property of the specified
      > * element prevents it from being added to this deque
      112c254
      < E takeFirst() throws InterruptedException;
      ---
      > void putFirst(E e) throws InterruptedException;
      115,118c257,266
      < * Retrieves and removes the last element of this deque, waiting
      < * if no elements are present on this deque.
      < * @return the head of this deque
      < * @throws InterruptedException if interrupted while waiting.
      ---
      > * Inserts the specified element at the end of this deque,
      > * waiting if necessary for space to become available.
      > *
      > * @param e the element to add
      > * @throws InterruptedException if interrupted while waiting
      > * @throws ClassCastException if the class of the specified element
      > * prevents it from being added to this deque
      > * @throws NullPointerException if the specified element is null
      > * @throws IllegalArgumentException if some property of the specified
      > * element prevents it from being added to this deque
      120c268
      < E takeLast() throws InterruptedException;
      ---
      > void putLast(E e) throws InterruptedException;
      123,124c271,272
      < * Inserts the specified element as the first element of this deque,
      < * waiting if necessary up to the specified wait time for space to
      ---
      > * Inserts the specified element at the front of this deque,
      > * waiting up to the specified wait time if necessary for space to
      126c274,275
      < * @param o the element to add
      ---
      > *
      > * @param e the element to add
      128c277
      < * <tt>unit</tt>
      ---
      > * <tt>unit</tt>
      130c279
      < * <tt>timeout</tt> parameter
      ---
      > * <tt>timeout</tt> parameter
      132,134c281,287
      < * the specified waiting time elapses before space is available.
      < * @throws InterruptedException if interrupted while waiting.
      < * @throws NullPointerException if the specified element is <tt>null</tt>.
      ---
      > * the specified waiting time elapses before space is available
      > * @throws InterruptedException if interrupted while waiting
      > * @throws ClassCastException if the class of the specified element
      > * prevents it from being added to this deque
      > * @throws NullPointerException if the specified element is null
      > * @throws IllegalArgumentException if some property of the specified
      > * element prevents it from being added to this deque
      136c289
      < boolean offerFirst(E o, long timeout, TimeUnit unit)
      ---
      > boolean offerFirst(E e, long timeout, TimeUnit unit)
      140,141c293,294
      < * Inserts the specified element as the last element of this deque,
      < * waiting if necessary up to the specified wait time for space to
      ---
      > * Inserts the specified element at the end of this deque,
      > * waiting up to the specified wait time if necessary for space to
      143c296,297
      < * @param o the element to add
      ---
      > *
      > * @param e the element to add
      145c299
      < * <tt>unit</tt>
      ---
      > * <tt>unit</tt>
      147c301
      < * <tt>timeout</tt> parameter
      ---
      > * <tt>timeout</tt> parameter
      149,151c303,309
      < * the specified waiting time elapses before space is available.
      < * @throws InterruptedException if interrupted while waiting.
      < * @throws NullPointerException if the specified element is <tt>null</tt>.
      ---
      > * the specified waiting time elapses before space is available
      > * @throws InterruptedException if interrupted while waiting
      > * @throws ClassCastException if the class of the specified element
      > * prevents it from being added to this deque
      > * @throws NullPointerException if the specified element is null
      > * @throws IllegalArgumentException if some property of the specified
      > * element prevents it from being added to this deque
      153c311
      < boolean offerLast(E o, long timeout, TimeUnit unit)
      ---
      > boolean offerLast(E e, long timeout, TimeUnit unit)
      155a314,330
      > /**
      > * Retrieves and removes the first element of this deque, waiting
      > * if necessary until an element becomes available.
      > *
      > * @return the head of this deque
      > * @throws InterruptedException if interrupted while waiting
      > */
      > E takeFirst() throws InterruptedException;
      >
      > /**
      > * Retrieves and removes the last element of this deque, waiting
      > * if necessary until an element becomes available.
      > *
      > * @return the tail of this deque
      > * @throws InterruptedException if interrupted while waiting
      > */
      > E takeLast() throws InterruptedException;
      159,160c334,336
      < * if necessary up to the specified wait time if no elements are
      < * present on this deque.
      ---
      > * up to the specified wait time if necessary for an element to
      > * become available.
      > *
      162c338
      < * <tt>unit</tt>
      ---
      > * <tt>unit</tt>
      164,167c340,343
      < * <tt>timeout</tt> parameter
      < * @return the head of this deque, or <tt>null</tt> if the
      < * specified waiting time elapses before an element is present.
      < * @throws InterruptedException if interrupted while waiting.
      ---
      > * <tt>timeout</tt> parameter
      > * @return the head of this deque, or <tt>null</tt> if the specified
      > * waiting time elapses before an element is available
      > * @throws InterruptedException if interrupted while waiting
      174,175c350,352
      < * if necessary up to the specified wait time if no elements are
      < * present on this deque.
      ---
      > * up to the specified wait time if necessary for an element to
      > * become available.
      > *
      177c354
      < * <tt>unit</tt>
      ---
      > * <tt>unit</tt>
      179,182c356,359
      < * <tt>timeout</tt> parameter
      < * @return the head of this deque, or <tt>null</tt> if the
      < * specified waiting time elapses before an element is present.
      < * @throws InterruptedException if interrupted while waiting.
      ---
      > * <tt>timeout</tt> parameter
      > * @return the tail of this deque, or <tt>null</tt> if the specified
      > * waiting time elapses before an element is available
      > * @throws InterruptedException if interrupted while waiting
      188,209c365,472
      < * Adds the specified element as the last element of this deque,
      < * waiting if necessary for space to become available. This
      < * method is equivalent to to putLast
      < * @param o the element to add
      < * @throws InterruptedException if interrupted while waiting.
      < * @throws NullPointerException if the specified element is <tt>null</tt>.
      < */
      < void put(E o) throws InterruptedException;
      <
      < /**
      < * Inserts the specified element as the lest element of this
      < * deque, if possible. When using deques that may impose
      < * insertion restrictions (for example capacity bounds), method
      < * <tt>offer</tt> is generally preferable to method {@link
      < * Collection#add}, which can fail to insert an element only by
      < * throwing an exception. This method is equivalent to to
      < * offerLast
      < *
      < * @param o the element to add.
      < * @return <tt>true</tt> if it was possible to add the element to
      < * this deque, else <tt>false</tt>
      < * @throws NullPointerException if the specified element is <tt>null</tt>
      ---
      > * Removes the first occurrence of the specified element from this deque.
      > * If the deque does not contain the element, it is unchanged.
      > * More formally, removes the first element <tt>e</tt> such that
      > * <tt>o.equals(e)</tt> (if such an element exists).
      > * Returns <tt>true</tt> if this deque contained the specified element
      > * (or equivalently, if this deque changed as a result of the call).
      > *
      > * @param o element to be removed from this deque, if present
      > * @return <tt>true</tt> if an element was removed as a result of this call
      > * @throws ClassCastException if the class of the specified element
      > * is incompatible with this deque (optional)
      > * @throws NullPointerException if the specified element is null (optional)
      > */
      > boolean removeFirstOccurrence(Object o);
      >
      > /**
      > * Removes the last occurrence of the specified element from this deque.
      > * If the deque does not contain the element, it is unchanged.
      > * More formally, removes the last element <tt>e</tt> such that
      > * <tt>o.equals(e)</tt> (if such an element exists).
      > * Returns <tt>true</tt> if this deque contained the specified element
      > * (or equivalently, if this deque changed as a result of the call).
      > *
      > * @param o element to be removed from this deque, if present
      > * @return <tt>true</tt> if an element was removed as a result of this call
      > * @throws ClassCastException if the class of the specified element
      > * is incompatible with this deque (optional)
      > * @throws NullPointerException if the specified element is null (optional)
      > */
      > boolean removeLastOccurrence(Object o);
      >
      > // *** BlockingQueue methods ***
      >
      > /**
      > * Inserts the specified element into the queue represented by this deque
      > * (in other words, at the tail of this deque) if it is possible to do so
      > * immediately without violating capacity restrictions, returning
      > * <tt>true</tt> upon success and throwing an
      > * <tt>IllegalStateException</tt> if no space is currently available.
      > * When using a capacity-restricted deque, it is generally preferable to
      > * use {@link #offer(Object) offer}.
      > *
      > * <p>This method is equivalent to {@link #addLast(Object) addLast}.
      > *
      > * @param e the element to add
      > * @throws IllegalStateException {@inheritDoc}
      > * @throws ClassCastException if the class of the specified element
      > * prevents it from being added to this deque
      > * @throws NullPointerException if the specified element is null
      > * @throws IllegalArgumentException if some property of the specified
      > * element prevents it from being added to this deque
      > */
      > boolean add(E e);
      >
      > /**
      > * Inserts the specified element into the queue represented by this deque
      > * (in other words, at the tail of this deque) if it is possible to do so
      > * immediately without violating capacity restrictions, returning
      > * <tt>true</tt> upon success and <tt>false</tt> if no space is currently
      > * available. When using a capacity-restricted deque, this method is
      > * generally preferable to the {@link #add} method, which can fail to
      > * insert an element only by throwing an exception.
      > *
      > * <p>This method is equivalent to {@link #offerLast(Object) offerLast}.
      > *
      > * @param e the element to add
      > * @throws ClassCastException if the class of the specified element
      > * prevents it from being added to this deque
      > * @throws NullPointerException if the specified element is null
      > * @throws IllegalArgumentException if some property of the specified
      > * element prevents it from being added to this deque
      > */
      > boolean offer(E e);
      >
      > /**
      > * Inserts the specified element into the queue represented by this deque
      > * (in other words, at the tail of this deque), waiting if necessary for
      > * space to become available.
      > *
      > * <p>This method is equivalent to {@link #putLast(Object) putLast}.
      > *
      > * @param e the element to add
      > * @throws InterruptedException {@inheritDoc}
      > * @throws ClassCastException if the class of the specified element
      > * prevents it from being added to this deque
      > * @throws NullPointerException if the specified element is null
      > * @throws IllegalArgumentException if some property of the specified
      > * element prevents it from being added to this deque
      > */
      > void put(E e) throws InterruptedException;
      >
      > /**
      > * Inserts the specified element into the queue represented by this deque
      > * (in other words, at the tail of this deque), waiting up to the
      > * specified wait time if necessary for space to become available.
      > *
      > * <p>This method is equivalent to
      > * {@link #offerLast(Object,long,TimeUnit) offerLast}.
      > *
      > * @param e the element to add
      > * @return <tt>true</tt> if the element was added to this deque, else
      > * <tt>false</tt>
      > * @throws InterruptedException {@inheritDoc}
      > * @throws ClassCastException if the class of the specified element
      > * prevents it from being added to this deque
      > * @throws NullPointerException if the specified element is null
      > * @throws IllegalArgumentException if some property of the specified
      > * element prevents it from being added to this deque
      211c474
      < boolean offer(E o, long timeout, TimeUnit unit)
      ---
      > boolean offer(E e, long timeout, TimeUnit unit)
      215,217c478,507
      < * Retrieves and removes the first element of this deque, waiting
      < * if no elements are present on this deque.
      < * This method is equivalent to to takeFirst
      ---
      > * Retrieves and removes the head of the queue represented by this deque
      > * (in other words, the first element of this deque).
      > * This method differs from {@link #poll poll} only in that it
      > * throws an exception if this deque is empty.
      > *
      > * <p>This method is equivalent to {@link #removeFirst() removeFirst}.
      > *
      > * @return the head of the queue represented by this deque
      > * @throws NoSuchElementException if this deque is empty
      > */
      > E remove();
      >
      > /**
      > * Retrieves and removes the head of the queue represented by this deque
      > * (in other words, the first element of this deque), or returns
      > * <tt>null</tt> if this deque is empty.
      > *
      > * <p>This method is equivalent to {@link #pollFirst()}.
      > *
      > * @return the head of this deque, or <tt>null</tt> if this deque is empty
      > */
      > E poll();
      >
      > /**
      > * Retrieves and removes the head of the queue represented by this deque
      > * (in other words, the first element of this deque), waiting if
      > * necessary until an element becomes available.
      > *
      > * <p>This method is equivalent to {@link #takeFirst() takeFirst}.
      > *
      219c509
      < * @throws InterruptedException if interrupted while waiting.
      ---
      > * @throws InterruptedException if interrupted while waiting
      224,231c514,520
      < * Retrieves and removes the first element of this deque, waiting
      < * if necessary up to the specified wait time if no elements are
      < * present on this deque. This method is equivalent to to
      < * pollFirst
      < * @param timeout how long to wait before giving up, in units of
      < * <tt>unit</tt>
      < * @param unit a <tt>TimeUnit</tt> determining how to interpret the
      < * <tt>timeout</tt> parameter
      ---
      > * Retrieves and removes the head of the queue represented by this deque
      > * (in other words, the first element of this deque), waiting up to the
      > * specified wait time if necessary for an element to become available.
      > *
      > * <p>This method is equivalent to
      > * {@link #pollFirst(long,TimeUnit) pollFirst}.
      > *
      233,234c522,523
      < * specified waiting time elapses before an element is present.
      < * @throws InterruptedException if interrupted while waiting.
      ---
      > * specified waiting time elapses before an element is available
      > * @throws InterruptedException if interrupted while waiting
      237a527,613
      >
      > /**
      > * Retrieves, but does not remove, the head of the queue represented by
      > * this deque (in other words, the first element of this deque).
      > * This method differs from {@link #peek peek} only in that it throws an
      > * exception if this deque is empty.
      > *
      > * <p>This method is equivalent to {@link #getFirst() getFirst}.
      > *
      > * @return the head of this deque
      > * @throws NoSuchElementException if this deque is empty
      > */
      > E element();
      >
      > /**
      > * Retrieves, but does not remove, the head of the queue represented by
      > * this deque (in other words, the first element of this deque), or
      > * returns <tt>null</tt> if this deque is empty.
      > *
      > * <p>This method is equivalent to {@link #peekFirst() peekFirst}.
      > *
      > * @return the head of this deque, or <tt>null</tt> if this deque is empty
      > */
      > E peek();
      >
      > /**
      > * Removes the first occurrence of the specified element from this deque.
      > * If the deque does not contain the element, it is unchanged.
      > * More formally, removes the first element <tt>e</tt> such that
      > * <tt>o.equals(e)</tt> (if such an element exists).
      > * Returns <tt>true</tt> if this deque contained the specified element
      > * (or equivalently, if this deque changed as a result of the call).
      > *
      > * <p>This method is equivalent to
      > * {@link #removeFirstOccurrence(Object) removeFirstOccurrence}.
      > *
      > * @param o element to be removed from this deque, if present
      > * @return <tt>true</tt> if this deque changed as a result of the call
      > * @throws ClassCastException if the class of the specified element
      > * is incompatible with this deque (optional)
      > * @throws NullPointerException if the specified element is null (optional)
      > */
      > boolean remove(Object o);
      >
      > /**
      > * Returns <tt>true</tt> if this deque contains the specified element.
      > * More formally, returns <tt>true</tt> if and only if this deque contains
      > * at least one element <tt>e</tt> such that <tt>o.equals(e)</tt>.
      > *
      > * @param o object to be checked for containment in this deque
      > * @return <tt>true</tt> if this deque contains the specified element
      > * @throws ClassCastException if the class of the specified element
      > * is incompatible with this deque (optional)
      > * @throws NullPointerException if the specified element is null (optional)
      > */
      > public boolean contains(Object o);
      >
      > /**
      > * Returns the number of elements in this deque.
      > *
      > * @return the number of elements in this deque
      > */
      > public int size();
      >
      > /**
      > * Returns an iterator over the elements in this deque in proper sequence.
      > * The elements will be returned in order from first (head) to last (tail).
      > *
      > * @return an iterator over the elements in this deque in proper sequence
      > */
      > Iterator<E> iterator();
      >
      > // *** Stack methods ***
      >
      > /**
      > * Pushes an element onto the stack represented by this deque. In other
      > * words, inserts the element at the front of this deque unless it would
      > * violate capacity restrictions.
      > *
      > * <p>This method is equivalent to {@link #addFirst(Object) addFirst}.
      > *
      > * @throws IllegalStateException {@inheritDoc}
      > * @throws ClassCastException {@inheritDoc}
      > * @throws NullPointerException if the specified element is null
      > * @throws IllegalArgumentException {@inheritDoc}
      > */
      > void push(E e);
      diff -r lea/Deque.java java6/Deque.java
      2,4c2,5
      < * Written by Doug Lea and Josh Bloch with assistance from members of
      < * JCP JSR-166 Expert Group and released to the public domain, as explained
      < * at http://creativecommons.org/licenses/publicdomain
      ---
      > * @(#)Deque.java 1.5 06/04/21
      > *
      > * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
      > * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
      7,8c8
      < package org.jboss.messaging.utils.concurrent; // XXX This belongs in java.util!!! XXX
      < import java.util.*; // XXX This import goes away XXX
      ---
      > package java.util;
      28,30c28,31
      < * <p>The twelve methods described above are are summarized in the
      < * follwoing table:<p>
      < *
      ---
      > * <p>The twelve methods described above are summarized in the
      > * following table:
      > *
      > * <p>
      40c41
      < * <td ALIGN=CENTER><em>Returns special value</em></td>
      ---
      > * <td ALIGN=CENTER><em>Special value</em></td>
      42c43
      < * <td ALIGN=CENTER><em>Returns special value</em></td>
      ---
      > * <td ALIGN=CENTER><em>Special value</em></td>
      69c70
      < * added to the end of the deque and removed from the beginning. The methods
      ---
      > * added at the end of the deque and removed from the beginning. The methods
      71c72
      < * <tt>Deque</tt> methods as indicated in the following table:<p>
      ---
      > * <tt>Deque</tt> methods as indicated in the following table:
      72a74
      > * <p>
      79,83d80
      < * <tr>
      < * <td>{@link java.util.Queue#offer offer(e)}</td>
      < * <td>{@link #offerLast offerLast(e)}</td>
      < * </tr>
      < * <tr>
      86,91c83,88
      < * </tr>
      < * <tr>
      < * <td>{@link java.util.Queue#poll poll()}</td>
      < * <td>{@link #pollFirst pollFirst()}</td>
      < * </tr>
      < * <tr>
      ---
      > * </tr>
      > * <tr>
      > * <td>{@link java.util.Queue#offer offer(e)}</td>
      > * <td>{@link #offerLast offerLast(e)}</td>
      > * </tr>
      > * <tr>
      94,99c91,96
      < * </tr>
      < * <tr>
      < * <td>{@link java.util.Queue#peek peek()}</td>
      < * <td>{@link #peek peekFirst()}</td>
      < * </tr>
      < * <tr>
      ---
      > * </tr>
      > * <tr>
      > * <td>{@link java.util.Queue#poll poll()}</td>
      > * <td>{@link #pollFirst pollFirst()}</td>
      > * </tr>
      > * <tr>
      102c99,103
      < * </tr>
      ---
      > * </tr>
      > * <tr>
      > * <td>{@link java.util.Queue#peek peek()}</td>
      > * <td>{@link #peek peekFirst()}</td>
      > * </tr>
      107c108
      < * When a dequeue is used as a stack, elements are pushed and popped from the
      ---
      > * When a deque is used as a stack, elements are pushed and popped from the
      109c110
      < * <tt>Deque</tt> methods as indicated in the table below:<p>
      ---
      > * <tt>Deque</tt> methods as indicated in the table below:
      110a112
      > * <p>
      117d118
      < * <tr>
      120,121c121,122
      < * </tr>
      < * <tr>
      ---
      > * </tr>
      > * <tr>
      124,125c125,126
      < * </tr>
      < * <tr>
      ---
      > * </tr>
      > * <tr>
      128c129
      < * </tr>
      ---
      > * </tr>
      135c136
      < * <p>This inteface provides two methods to to remove interior
      ---
      > * <p>This interface provides two methods to remove interior
      137,139c138,141
      < * {@link #removeLastOccurrence removeLastOccurrence}. Unlike the
      < * {@link List} interface, this interface does not provide support for
      < * indexed access to elements.
      ---
      > * {@link #removeLastOccurrence removeLastOccurrence}.
      > *
      > * <p>Unlike the {@link List} interface, this interface does not
      > * provide support for indexed access to elements.
      148c150
      < *
      ---
      > *
      155c157
      < * href="{@docRoot}/../guide/collections/index.html"> Java Collections
      ---
      > * href="{@docRoot}/../technotes/guides/collections/index.html"> Java Collections
      162a165
      >
      165c168,206
      < * Inserts the specified element to the front this deque unless it would
      ---
      > * Inserts the specified element at the front of this deque if it is
      > * possible to do so immediately without violating capacity restrictions.
      > * When using a capacity-restricted deque, it is generally preferable to
      > * use method {@link #offerFirst}.
      > *
      > * @param e the element to add
      > * @throws IllegalStateException if the element cannot be added at this
      > * time due to capacity restrictions
      > * @throws ClassCastException if the class of the specified element
      > * prevents it from being added to this deque
      > * @throws NullPointerException if the specified element is null and this
      > * deque does not permit null elements
      > * @throws IllegalArgumentException if some property of the specified
      > * element prevents it from being added to this deque
      > */
      > void addFirst(E e);
      >
      > /**
      > * Inserts the specified element at the end of this deque if it is
      > * possible to do so immediately without violating capacity restrictions.
      > * When using a capacity-restricted deque, it is generally preferable to
      > * use method {@link #offerLast}.
      > *
      > * <p>This method is equivalent to {@link #add}.
      > *
      > * @param e the element to add
      > * @throws IllegalStateException if the element cannot be added at this
      > * time due to capacity restrictions
      > * @throws ClassCastException if the class of the specified element
      > * prevents it from being added to this deque
      > * @throws NullPointerException if the specified element is null and this
      > * deque does not permit null elements
      > * @throws IllegalArgumentException if some property of the specified
      > * element prevents it from being added to this deque
      > */
      > void addLast(E e);
      >
      > /**
      > * Inserts the specified element at the front of this deque unless it would
      167,168c208,209
      < * this method is generally preferable to method <tt>addFirst</tt>, which
      < * can fail to insert an element only by throwing an exception.
      ---
      > * this method is generally preferable to the {@link #addFirst} method,
      > * which can fail to insert an element only by throwing an exception.
      170,174c211,219
      < * @param e the element to insert
      < * @return <tt>true</tt> if it was possible to insert the element,
      < * else <tt>false</tt>
      < * @throws NullPointerException if <tt>e</tt> is null and this
      < * deque does not permit null elements
      ---
      > * @param e the element to add
      > * @return <tt>true</tt> if the element was added to this deque, else
      > * <tt>false</tt>
      > * @throws ClassCastException if the class of the specified element
      > * prevents it from being added to this deque
      > * @throws NullPointerException if the specified element is null and this
      > * deque does not permit null elements
      > * @throws IllegalArgumentException if some property of the specified
      > * element prevents it from being added to this deque
      179c224
      < * Inserts the specified element to the end of this deque unless it would
      ---
      > * Inserts the specified element at the end of this deque unless it would
      181,182c226,227
      < * this method is generally preferable to method <tt>addLast</tt> which
      < * can fail to insert an element only by throwing an exception.
      ---
      > * this method is generally preferable to the {@link #addLast} method,
      > * which can fail to insert an element only by throwing an exception.
      184,188c229,237
      < * @param e the element to insert
      < * @return <tt>true</tt> if it was possible to insert the element,
      < * else <tt>false</tt>
      < * @throws NullPointerException if <tt>e</tt> is null and this
      < * deque does not permit null elements
      ---
      > * @param e the element to add
      > * @return <tt>true</tt> if the element was added to this deque, else
      > * <tt>false</tt>
      > * @throws ClassCastException if the class of the specified element
      > * prevents it from being added to this deque
      > * @throws NullPointerException if the specified element is null and this
      > * deque does not permit null elements
      > * @throws IllegalArgumentException if some property of the specified
      > * element prevents it from being added to this deque
      193,194c242,244
      < * Inserts the specified element to the front of this deque unless it
      < * would violate capacity restrictions.
      ---
      > * Retrieves and removes the first element of this deque. This method
      > * differs from {@link #pollFirst pollFirst} only in that it throws an
      > * exception if this deque is empty.
      196,200c246,247
      < * @param e the element to insert
      < * @throws IllegalStateException if it was not possible to insert
      < * the element due to capacity restrictions
      < * @throws NullPointerException if <tt>e</tt> is null and this
      < * deque does not permit null elements
      ---
      > * @return the head of this deque
      > * @throws NoSuchElementException if this deque is empty
      202c249
      < void addFirst(E e);
      ---
      > E removeFirst();
      205,206c252,254
      < * Inserts the specified element to the end of this deque unless it would
      < * violate capacity restrictions.
      ---
      > * Retrieves and removes the last element of this deque. This method
      > * differs from {@link #pollLast pollLast} only in that it throws an
      > * exception if this deque is empty.
      208,212c256,257
      < * @param e the element to insert
      < * @throws IllegalStateException if it was not possible to insert
      < * the element due to capacity restrictions
      < * @throws NullPointerException if <tt>e</tt> is null and this
      < * deque does not permit null elements
      ---
      > * @return the tail of this deque
      > * @throws NoSuchElementException if this deque is empty
      214c259
      < void addLast(E e);
      ---
      > E removeLast();
      217,218c262,263
      < * Retrieves and removes the first element of this deque, or
      < * <tt>null</tt> if this deque is empty.
      ---
      > * Retrieves and removes the first element of this deque,
      > * or returns <tt>null</tt> if this deque is empty.
      220,221c265
      < * @return the first element of this deque, or <tt>null</tt> if
      < * this deque is empty
      ---
      > * @return the head of this deque, or <tt>null</tt> if this deque is empty
      226,227c270,271
      < * Retrieves and removes the last element of this deque, or
      < * <tt>null</tt> if this deque is empty.
      ---
      > * Retrieves and removes the last element of this deque,
      > * or returns <tt>null</tt> if this deque is empty.
      229,230c273
      < * @return the last element of this deque, or <tt>null</tt> if
      < * this deque is empty
      ---
      > * @return the tail of this deque, or <tt>null</tt> if this deque is empty
      235,237c278
      < * Removes and returns the first element of this deque. This method
      < * differs from the <tt>pollFirst</tt> method only in that it throws an
      < * exception if this deque is empty.
      ---
      > * Retrieves, but does not remove, the first element of this deque.
      239c280,283
      < * @return the first element of this deque
      ---
      > * This method differs from {@link #peekFirst peekFirst} only in that it
      > * throws an exception if this deque is empty.
      > *
      > * @return the head of this deque
      242c286
      < E removeFirst();
      ---
      > E getFirst();
      245,247c289,291
      < * Retrieves and removes the last element of this deque. This method
      < * differs from the <tt>pollLast</tt> method only in that it throws an
      < * exception if this deque is empty.
      ---
      > * Retrieves, but does not remove, the last element of this deque.
      > * This method differs from {@link #peekLast peekLast} only in that it
      > * throws an exception if this deque is empty.
      249c293
      < * @return the last element of this deque
      ---
      > * @return the tail of this deque
      252c296
      < E removeLast();
      ---
      > E getLast();
      256c300
      < * returning <tt>null</tt> if this deque is empty.
      ---
      > * or returns <tt>null</tt> if this deque is empty.
      258,259c302
      < * @return the first element of this deque, or <tt>null</tt> if
      < * this deque is empty
      ---
      > * @return the head of this deque, or <tt>null</tt> if this deque is empty
      265c308
      < * returning <tt>null</tt> if this deque is empty.
      ---
      > * or returns <tt>null</tt> if this deque is empty.
      267,268c310
      < * @return the last element of this deque, or <tt>null</tt> if this deque
      < * is empty
      ---
      > * @return the tail of this deque, or <tt>null</tt> if this deque is empty
      273,278c315,346
      < * Retrieves, but does not remove, the first element of this
      < * deque. This method differs from the <tt>peek</tt> method only
      < * in that it throws an exception if this deque is empty.
      < *
      < * @return the first element of this deque
      < * @throws NoSuchElementException if this deque is empty
      ---
      > * Removes the first occurrence of the specified element from this deque.
      > * If the deque does not contain the element, it is unchanged.
      > * More formally, removes the first element <tt>e</tt> such that
      > * <tt>(o==null ? e==null : o.equals(e))</tt>
      > * (if such an element exists).
      > * Returns <tt>true</tt> if this deque contained the specified element
      > * (or equivalently, if this deque changed as a result of the call).
      > *
      > * @param o element to be removed from this deque, if present
      > * @return <tt>true</tt> if an element was removed as a result of this call
      > * @throws ClassCastException if the class of the specified element
      > * is incompatible with this deque (optional)
      > * @throws NullPointerException if the specified element is null and this
      > * deque does not permit null elements (optional)
      > */
      > boolean removeFirstOccurrence(Object o);
      >
      > /**
      > * Removes the last occurrence of the specified element from this deque.
      > * If the deque does not contain the element, it is unchanged.
      > * More formally, removes the last element <tt>e</tt> such that
      > * <tt>(o==null ? e==null : o.equals(e))</tt>
      > * (if such an element exists).
      > * Returns <tt>true</tt> if this deque contained the specified element
      > * (or equivalently, if this deque changed as a result of the call).
      > *
      > * @param o element to be removed from this deque, if present
      > * @return <tt>true</tt> if an element was removed as a result of this call
      > * @throws ClassCastException if the class of the specified element
      > * is incompatible with this deque (optional)
      > * @throws NullPointerException if the specified element is null and this
      > * deque does not permit null elements (optional)
      280c348
      < E getFirst();
      ---
      > boolean removeLastOccurrence(Object o);
      282,290c350
      < /**
      < * Retrieves, but does not remove, the last element of this
      < * deque. This method differs from the <tt>peek</tt> method only
      < * in that it throws an exception if this deque is empty.
      < *
      < * @return the last element of this deque
      < * @throws NoSuchElementException if this deque is empty
      < */
      < E getLast();
      ---
      > // *** Queue methods ***
      293,314c353,372
      < * Removes the first occurrence of the specified element in this
      < * deque. If the deque does not contain the element, it is
      < * unchanged. More formally, removes the first element <tt>e</tt>
      < * such that <tt>(o==null ? e==null : o.equals(e))</tt> (if
      < * such an element exists).
      < *
      < * @param e element to be removed from this deque, if present
      < * @return <tt>true</tt> if the deque contained the specified element
      < * @throws NullPointerException if the specified element is <tt>null</tt>
      < */
      < boolean removeFirstOccurrence(Object e);
      <
      < /**
      < * Removes the last occurrence of the specified element in this
      < * deque. If the deque does not contain the element, it is
      < * unchanged. More formally, removes the last element <tt>e</tt>
      < * such that <tt>(o==null ? e==null : o.equals(e))</tt> (if
      < * such an element exists).
      < *
      < * @param e element to be removed from this deque, if present
      < * @return <tt>true</tt> if the deque contained the specified element
      < * @throws NullPointerException if the specified element is <tt>null</tt>
      ---
      > * Inserts the specified element into the queue represented by this deque
      > * (in other words, at the tail of this deque) if it is possible to do so
      > * immediately without violating capacity restrictions, returning
      > * <tt>true</tt> upon success and throwing an
      > * <tt>IllegalStateException</tt> if no space is currently available.
      > * When using a capacity-restricted deque, it is generally preferable to
      > * use {@link #offer(Object) offer}.
      > *
      > * <p>This method is equivalent to {@link #addLast}.
      > *
      > * @param e the element to add
      > * @return <tt>true</tt> (as specified by {@link Collection#add})
      > * @throws IllegalStateException if the element cannot be added at this
      > * time due to capacity restrictions
      > * @throws ClassCastException if the class of the specified element
      > * prevents it from being added to this deque
      > * @throws NullPointerException if the specified element is null and this
      > * deque does not permit null elements
      > * @throws IllegalArgumentException if some property of the specified
      > * element prevents it from being added to this deque
      316,319c374
      < boolean removeLastOccurrence(Object e);
      <
      <
      < // *** Queue methods ***
      ---
      > boolean add(E e);
      323,327c378,383
      < * unless it would violate capacity restrictions. In other words, inserts
      < * the specified element to the end of this deque. When using a
      < * capacity-restricted deque, this method is generally preferable to the
      < * {@link #add} method, which can fail to insert an element only by
      < * throwing an exception.
      ---
      > * (in other words, at the tail of this deque) if it is possible to do so
      > * immediately without violating capacity restrictions, returning
      > * <tt>true</tt> upon success and <tt>false</tt> if no space is currently
      > * available. When using a capacity-restricted deque, this method is
      > * generally preferable to the {@link #add} method, which can fail to
      > * insert an element only by throwing an exception.
      331,335c387,395
      < * @param e the element to insert
      < * @return <tt>true</tt> if it was possible to insert the element,
      < * else <tt>false</tt>
      < * @throws NullPointerException if <tt>e</tt> is null and this
      < * deque does not permit null elements
      ---
      > * @param e the element to add
      > * @return <tt>true</tt> if the element was added to this deque, else
      > * <tt>false</tt>
      > * @throws ClassCastException if the class of the specified element
      > * prevents it from being added to this deque
      > * @throws NullPointerException if the specified element is null and this
      > * deque does not permit null elements
      > * @throws IllegalArgumentException if some property of the specified
      > * element prevents it from being added to this deque
      340,342c400,403
      < * Inserts the specified element into the queue represented by this
      < * deque unless it would violate capacity restrictions. In other words,
      < * inserts the specified element as the last element of this deque.
      ---
      > * Retrieves and removes the head of the queue represented by this deque
      > * (in other words, the first element of this deque).
      > * This method differs from {@link #poll poll} only in that it throws an
      > * exception if this deque is empty.
      344c405
      < * <p>This method is equivalent to {@link #addLast}.
      ---
      > * <p>This method is equivalent to {@link #removeFirst()}.
      346,351c407,408
      < * @param e the element to insert
      < * @return <tt>true</tt> (as per the spec for {@link Collection#add})
      < * @throws IllegalStateException if it was not possible to insert
      < * the element due to capacity restrictions
      < * @throws NullPointerException if <tt>e</tt> is null and this
      < * deque does not permit null elements
      ---
      > * @return the head of the queue represented by this deque
      > * @throws NoSuchElementException if this deque is empty
      353c410
      < boolean add(E e);
      ---
      > E remove();
      356,359c413,415
      < * Retrieves and removes the head of the queue represented by
      < * this deque, or <tt>null</tt> if this deque is empty. In other words,
      < * retrieves and removes the first element of this deque, or <tt>null</tt>
      < * if this deque is empty.
      ---
      > * Retrieves and removes the head of the queue represented by this deque
      > * (in other words, the first element of this deque), or returns
      > * <tt>null</tt> if this deque is empty.
      364c420
      < * this deque is empty
      ---
      > * this deque is empty
      369,371c425,428
      < * Retrieves and removes the head of the queue represented by this deque.
      < * This method differs from the <tt>poll</tt> method only in that it
      < * throws an exception if this deque is empty.
      ---
      > * Retrieves, but does not remove, the head of the queue represented by
      > * this deque (in other words, the first element of this deque).
      > * This method differs from {@link #peek peek} only in that it throws an
      > * exception if this deque is empty.
      373c430
      < * <p>This method is equivalent to {@link #removeFirst()}.
      ---
      > * <p>This method is equivalent to {@link #getFirst()}.
      378c435
      < E remove();
      ---
      > E element();
      382c439,440
      < * this deque, returning <tt>null</tt> if this deque is empty.
      ---
      > * this deque (in other words, the first element of this deque), or
      > * returns <tt>null</tt> if this deque is empty.
      384c442
      < * <p>This method is equivalent to {@link #peekFirst()}
      ---
      > * <p>This method is equivalent to {@link #peekFirst()}.
      387c445
      < * <tt>null</tt> if this deque is empty
      ---
      > * <tt>null</tt> if this deque is empty
      391,402d448
      < /**
      < * Retrieves, but does not remove, the head of the queue represented by
      < * this deque. This method differs from the <tt>peek</tt> method only in
      < * that it throws an exception if this deque is empty.
      < *
      < * <p>This method is equivalent to {@link #getFirst()}
      < *
      < * @return the head of the queue represented by this deque
      < * @throws NoSuchElementException if this deque is empty
      < */
      < E element();
      <
      407,409c453,457
      < * Pushes an element onto the stack represented by this deque. In other
      < * words, inserts the element to the front this deque unless it would
      < * violate capacity restrictions.
      ---
      > * Pushes an element onto the stack represented by this deque (in other
      > * words, at the head of this deque) if it is possible to do so
      > * immediately without violating capacity restrictions, returning
      > * <tt>true</tt> upon success and throwing an
      > * <tt>IllegalStateException</tt> if no space is currently available.
      413,416c461,469
      < * @throws IllegalStateException if it was not possible to insert
      < * the element due to capacity restrictions
      < * @throws NullPointerException if <tt>e</tt> is null and this
      < * deque does not permit null elements
      ---
      > * @param e the element to push
      > * @throws IllegalStateException if the element cannot be added at this
      > * time due to capacity restrictions
      > * @throws ClassCastException if the class of the specified element
      > * prevents it from being added to this deque
      > * @throws NullPointerException if the specified element is null and this
      > * deque does not permit null elements
      > * @throws IllegalArgumentException if some property of the specified
      > * element prevents it from being added to this deque
      422c475
      < * words, removes and returns the the first element of this deque.
      ---
      > * words, removes and returns the first element of this deque.
      427c480
      < * of the stack represented by this deque)
      ---
      > * of the stack represented by this deque)
      433c486,528
      < // *** Collection Method ***
      ---
      > // *** Collection methods ***
      >
      > /**
      > * Removes the first occurrence of the specified element from this deque.
      > * If the deque does not contain the element, it is unchanged.
      > * More formally, removes the first element <tt>e</tt> such that
      > * <tt>(o==null ? e==null : o.equals(e))</tt>
      > * (if such an element exists).
      > * Returns <tt>true</tt> if this deque contained the specified element
      > * (or equivalently, if this deque changed as a result of the call).
      > *
      > * <p>This method is equivalent to {@link #removeFirstOccurrence}.
      > *
      > * @param o element to be removed from this deque, if present
      > * @return <tt>true</tt> if an element was removed as a result of this call
      > * @throws ClassCastException if the class of the specified element
      > * is incompatible with this deque (optional)
      > * @throws NullPointerException if the specified element is null and this
      > * deque does not permit null elements (optional)
      > */
      > boolean remove(Object o);
      >
      > /**
      > * Returns <tt>true</tt> if this deque contains the specified element.
      > * More formally, returns <tt>true</tt> if and only if this deque contains
      > * at least one element <tt>e</tt> such that
      > * <tt>(o==null ? e==null : o.equals(e))</tt>.
      > *
      > * @param o element whose presence in this deque is to be tested
      > * @return <tt>true</tt> if this deque contains the specified element
      > * @throws ClassCastException if the type of the specified element
      > * is incompatible with this deque (optional)
      > * @throws NullPointerException if the specified element is null and this
      > * deque does not permit null elements (optional)
      > */
      > boolean contains(Object o);
      >
      > /**
      > * Returns the number of elements in this deque.
      > *
      > * @return the number of elements in this deque
      > */
      > public int size();
      436,439c531,534
      < * Returns an iterator over the elements in this deque. The elements
      < * will be ordered from first (head) to last (tail).
      < *
      < * @return an <tt>Iterator</tt> over the elements in this deque
      ---
      > * Returns an iterator over the elements in this deque in proper sequence.
      > * The elements will be returned in order from first (head) to last (tail).
      > *
      > * @return an iterator over the elements in this deque in proper sequence
      441a537,547
      >
      > /**
      > * Returns an iterator over the elements in this deque in reverse
      > * sequential order. The elements will be returned in order from
      > * last (tail) to first (head).
      > *
      > * @return an iterator over the elements in this deque in reverse
      > * sequence
      > */
      > Iterator<E> descendingIterator();
      >
      diff -r lea/LinkedBlockingDeque.java java6/LinkedBlockingDeque.java
      2,4c2,5
      < * Written by Doug Lea with assistance from members of JCP JSR-166
      < * Expert Group and released to the public domain, as explained at
      < * http://creativecommons.org/licenses/publicdomain
      ---
      > * @(#)LinkedBlockingDeque.java 1.4 06/04/21
      > *
      > * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
      > * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
      7,8c8
      < package org.jboss.messaging.utils.concurrent;
      <
      ---
      > package java.util.concurrent;
      10d9
      < import java.util.concurrent.*;
      27c26
      < * contains }, {@link #iterator iterator.remove()}, and the bulk
      ---
      > * contains}, {@link #iterator iterator.remove()}, and the bulk
      32,34c31,35
      < * Iterator} interfaces. This class is a member of the <a
      < * href="{@docRoot}/../guide/collections/index.html"> Java Collections
      < * Framework</a>.
      ---
      > * Iterator} interfaces.
      > *
      > * <p>This class is a member of the
      > * <a href="{@docRoot}/../technotes/guides/collections/index.html">
      > * Java Collections Framework</a>.
      48a50,56
      > /*
      > * We have "diamond" multiple interface/abstract class inheritance
      > * here, and that introduces ambiguities. Often we want the
      > * BlockingDeque javadoc combined with the AbstractQueue
      > * implementation, so a lot of method specs are duplicated here.
      > */
      >
      53c61
      < E item;
      ---
      > E item;
      87,88c95,96
      < * Creates a <tt>LinkedBlockingDeque</tt> with the given (fixed)
      < * capacity.
      ---
      > * Creates a <tt>LinkedBlockingDeque</tt> with the given (fixed) capacity.
      > *
      99,101c107,110
      < * {@link Integer#MAX_VALUE}, initially containing the elements of the
      < * given collection,
      < * added in traversal order of the collection's iterator.
      ---
      > * {@link Integer#MAX_VALUE}, initially containing the elements of
      > * the given collection, added in traversal order of the
      > * collection's iterator.
      > *
      103,104c112,113
      < * @throws NullPointerException if <tt>c</tt> or any element within it
      < * is <tt>null</tt>
      ---
      > * @throws NullPointerException if the specified collection or any
      > * of its elements are null
      116c125
      < * Link e as first element, or return false if full
      ---
      > * Links e as first element, or returns false if full.
      134c143
      < * Link e as last element, or return false if full
      ---
      > * Links e as last element, or returns false if full.
      152c161
      < * Remove and return first element, or null if empty
      ---
      > * Removes and returns first element, or null if empty.
      160c169
      < if (n == null)
      ---
      > if (n == null)
      162c171
      < else
      ---
      > else
      170c179
      < * Remove and return last element, or null if empty
      ---
      > * Removes and returns last element, or null if empty.
      178c187
      < if (p == null)
      ---
      > if (p == null)
      180c189
      < else
      ---
      > else
      194c203
      < if (n == null)
      ---
      > if (n == null)
      211c220
      < // Deque methods
      ---
      > // BlockingDeque methods
      213,214c222,244
      < public boolean offerFirst(E o) {
      < if (o == null) throw new NullPointerException();
      ---
      > /**
      > * @throws IllegalStateException {@inheritDoc}
      > * @throws NullPointerException {@inheritDoc}
      > */
      > public void addFirst(E e) {
      > if (!offerFirst(e))
      > throw new IllegalStateException("Deque full");
      > }
      >
      > /**
      > * @throws IllegalStateException {@inheritDoc}
      > * @throws NullPointerException {@inheritDoc}
      > */
      > public void addLast(E e) {
      > if (!offerLast(e))
      > throw new IllegalStateException("Deque full");
      > }
      >
      > /**
      > * @throws NullPointerException {@inheritDoc}
      > */
      > public boolean of