--- jsr166/src/main/java/util/Deque.java 2005/05/17 07:29:01 1.10 +++ jsr166/src/main/java/util/Deque.java 2005/09/14 23:49:59 1.17 @@ -5,6 +5,7 @@ */ package java.util; +import java.util.*; // for javadoc (till 6280605 is fixed) /** * A linear collection that supports element insertion and removal at @@ -182,11 +183,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 +209,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 +227,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 +240,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 +250,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 +276,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 +287,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 +317,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 +335,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 +358,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 +399,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 +424,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 +491,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 +534,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(); + }