--- jsr166/src/main/java/util/Deque.java	2005/05/17 16:00:48	1.11
+++ jsr166/src/main/java/util/Deque.java	2012/10/21 06:40:20	1.21
@@ -1,7 +1,7 @@
 /*
  * 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
+ * at http://creativecommons.org/publicdomain/zero/1.0/
  */
 
 package java.util;
@@ -153,7 +153,7 @@ package java.util;
  * <tt>Object</tt>.
  *
  * <p>This interface is a member of the <a
- * href="{@docRoot}/../guide/collections/index.html"> Java Collections
+ * href="{@docRoot}/../technotes/guides/collections/index.html"> Java Collections
  * Framework</a>.
  *
  * @author Doug Lea
@@ -161,7 +161,6 @@ package java.util;
  * @since  1.6
  * @param <E> the type of elements held in this collection
  */
-
 public interface Deque<E> extends Queue<E> {
     /**
      * Inserts the specified element at the front of this deque if it is
@@ -182,11 +181,13 @@ public interface Deque<E> extends Queue<
     void addFirst(E e);
 
     /**
-     * Inserts the specified element at the end of this deque  if it is
+     * 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
@@ -237,8 +238,8 @@ public interface Deque<E> extends Queue<
 
     /**
      * Retrieves and removes the first element of this deque.  This method
-     * differs from {@link #pollFirst} only in that it throws an exception
-     * if this deque is empty.
+     * differs from {@link #pollFirst pollFirst} only in that it throws an
+     * exception if this deque is empty.
      *
      * @return the head of this deque
      * @throws NoSuchElementException if this deque is empty
@@ -247,8 +248,8 @@ public interface Deque<E> extends Queue<
 
     /**
      * Retrieves and removes the last element of this deque.  This method
-     * differs from {@link #pollLast} only in that it throws an exception if
-     * this deque is empty.
+     * differs from {@link #pollLast pollLast} only in that it throws an
+     * exception if this deque is empty.
      *
      * @return the tail of this deque
      * @throws NoSuchElementException if this deque is empty
@@ -273,8 +274,9 @@ public interface Deque<E> extends Queue<
 
     /**
      * Retrieves, but does not remove, the first element of this deque.
-     * This method differs from {@link #peekFirst} only in that it throws an
-     * exception if this deque is empty.
+     *
+     * 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
      * @throws NoSuchElementException if this deque is empty
@@ -283,8 +285,8 @@ public interface Deque<E> extends Queue<
 
     /**
      * Retrieves, but does not remove, the last element of this deque.
-     * This method differs from {@link #peekLast} only in that it throws an
-     * exception if this deque is empty.
+     * This method differs from {@link #peekLast peekLast} only in that it
+     * throws an exception if this deque is empty.
      *
      * @return the tail of this deque
      * @throws NoSuchElementException if this deque is empty
@@ -313,8 +315,8 @@ public interface Deque<E> extends Queue<
      * More formally, removes the first element <tt>e</tt> such that
      * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>
      * (if such an element exists).
-     * Returns true if this deque contained the specified element (or
-     * equivalently, if this deque changed as a result of the call).
+     * 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
@@ -331,8 +333,8 @@ public interface Deque<E> extends Queue<
      * More formally, removes the last element <tt>e</tt> such that
      * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>
      * (if such an element exists).
-     * Returns true if this deque contained the specified element (or
-     * equivalently, if this deque changed as a result of the call).
+     * 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
@@ -354,10 +356,10 @@ public interface Deque<E> extends Queue<
      * 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}.
+     * <p>This method is equivalent to {@link #addLast}.
      *
      * @param e the element to add
-     * @return <tt>true</tt> (as per the spec for {@link Collection#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
@@ -395,7 +397,7 @@ public interface Deque<E> extends Queue<
     /**
      * 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} only in that it throws an
+     * 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()}.
@@ -420,7 +422,7 @@ public interface Deque<E> extends Queue<
     /**
      * 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} only in that it throws an
+     * 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()}.
@@ -487,8 +489,8 @@ public interface Deque<E> extends Queue<
      * More formally, removes the first element <tt>e</tt> such that
      * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>
      * (if such an element exists).
-     * Returns true if this deque contained the specified element (or
-     * equivalently, if this deque changed as a result of the call).
+     * 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}.
      *
@@ -530,4 +532,15 @@ public interface Deque<E> extends Queue<
      * @return an iterator over the elements in this deque in proper sequence
      */
     Iterator<E> iterator();
+
+    /**
+     * 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();
+
 }