--- jsr166/src/main/java/util/Deque.java 2005/05/17 07:29:01 1.10
+++ 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;
* Object.
*
*
This interface is a member of the Java Collections
+ * href="{@docRoot}/../technotes/guides/collections/index.html"> Java Collections
* Framework.
*
* @author Doug Lea
@@ -161,7 +161,6 @@ package java.util;
* @since 1.6
* @param the type of elements held in this collection
*/
-
public interface Deque extends Queue {
/**
* Inserts the specified element at the front of this deque if it is
@@ -182,11 +181,13 @@ public interface Deque 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}.
*
+ * 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
@@ -206,8 +207,8 @@ public interface Deque extends Queue<
* which can fail to insert an element only by throwing an exception.
*
* @param e the element to add
- * @return true if it was possible to insert the element,
- * else false
+ * @return true if the element was added to this deque, else
+ * false
* @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
@@ -224,8 +225,8 @@ public interface Deque extends Queue<
* which can fail to insert an element only by throwing an exception.
*
* @param e the element to add
- * @return true if it was possible to insert the element,
- * else false
+ * @return true if the element was added to this deque, else
+ * false
* @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
@@ -237,8 +238,8 @@ public interface Deque 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 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 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 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 extends Queue<
* More formally, removes the first element e such that
* (o==null ? e==null : o.equals(e))
* (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 true 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 true if an element was removed as a result of this call
@@ -331,8 +333,8 @@ public interface Deque extends Queue<
* More formally, removes the last element e such that
* (o==null ? e==null : o.equals(e))
* (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 true 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 true if an element was removed as a result of this call
@@ -354,10 +356,10 @@ public interface Deque extends Queue<
* When using a capacity-restricted deque, it is generally preferable to
* use {@link #offer(Object) offer}.
*
- * This method is equivalent to {@link #addLast(Object) addLast}.
+ *
This method is equivalent to {@link #addLast}.
*
* @param e the element to add
- * @return true (as per the spec for {@link Collection#add})
+ * @return true (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 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.
*
* This method is equivalent to {@link #removeFirst()}.
@@ -420,7 +422,7 @@ public interface Deque 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.
*
* This method is equivalent to {@link #getFirst()}.
@@ -487,8 +489,8 @@ public interface Deque extends Queue<
* More formally, removes the first element e such that
* (o==null ? e==null : o.equals(e))
* (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 true if this deque contained the specified element
+ * (or equivalently, if this deque changed as a result of the call).
*
* This method is equivalent to {@link #removeFirstOccurrence}.
*
@@ -530,4 +532,15 @@ public interface Deque extends Queue<
* @return an iterator over the elements in this deque in proper sequence
*/
Iterator 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 descendingIterator();
+
}