--- jsr166/src/main/java/util/Deque.java 2005/05/14 02:22:28 1.8 +++ 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 @@ -172,28 +173,30 @@ public interface Deque extends Queue< * @param e the element to add * @throws IllegalStateException if the element cannot be added at this * time due to capacity restrictions - * @throws NullPointerException if the specified element is null and this - * deque does not permit null elements * @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 + * 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 - * @throws NullPointerException if the specified element is null and this - * deque does not permit null elements * @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 */ @@ -206,12 +209,12 @@ 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 - * @throws NullPointerException if the specified element is null and this - * deque does not permit null elements + * @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 + * deque does not permit null elements * @throws IllegalArgumentException if some property of the specified * element prevents it from being added to this deque */ @@ -224,12 +227,12 @@ 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 - * @throws NullPointerException if the specified element is null and this - * deque does not permit null elements + * @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 + * deque does not permit null elements * @throws IllegalArgumentException if some property of the specified * element prevents it from being added to this deque */ @@ -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 @@ -311,16 +315,17 @@ public interface Deque extends Queue< * 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 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). + * (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). * * @param o element to be removed from this deque, if present * @return true 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) - * @throws ClassCastException if the class of the specified element - * is incompatible with this collection (optional) */ boolean removeFirstOccurrence(Object o); @@ -328,16 +333,17 @@ public interface Deque extends Queue< * 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 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). + * (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). * * @param o element to be removed from this deque, if present * @return true 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) - * @throws ClassCastException if the class of the specified element - * is incompatible with this collection (optional) */ boolean removeLastOccurrence(Object o); @@ -352,16 +358,16 @@ 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 NullPointerException if the specified element is null and this - * deque does not permit null elements * @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 */ @@ -381,10 +387,10 @@ public interface Deque extends Queue< * @param e the element to add * @return true if the element was added to this deque, else * false - * @throws NullPointerException if the specified element is null and this - * deque does not permit null elements * @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 */ @@ -393,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()}. @@ -418,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()}. @@ -455,10 +461,10 @@ public interface Deque extends Queue< * @param e the element to push * @throws IllegalStateException if the element cannot be added at this * time due to capacity restrictions - * @throws NullPointerException if the specified element is null and this - * deque does not permit null elements * @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 */ @@ -483,26 +489,27 @@ public interface Deque extends Queue< * 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 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). + * (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). * *

This method is equivalent to {@link #removeFirstOccurrence}. * * @param o element to be removed from this deque, if present * @return true 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) - * @throws ClassCastException if the class of the specified element - * is incompatible with this collection (optional) */ boolean remove(Object o); /** * Returns true if this deque contains the specified element. - * More formally, returns true if and only if this deque - * contains at least one element e such that (o==null ? - * e==null : o.equals(e)). + * More formally, returns true if and only if this deque contains + * at least one element e such that + * (o==null ? e==null : o.equals(e)). * * @param o element whose presence in this deque is to be tested * @return true if this deque contains the specified element @@ -521,10 +528,21 @@ public interface Deque extends Queue< public int size(); /** - * Returns an iterator over the elements in this deque. The elements - * will be ordered from first (head) to last (tail). + * 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 + * @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(); + }