* |
* Throws exception |
@@ -49,7 +50,7 @@ package java.util;
* Whatever the ordering used, the head of the queue is that
* element which would be removed by a call to {@link #remove() } or
* {@link #poll()}. In a FIFO queue, all new elements are inserted at
- * the tail of the queue. Other kinds of queues may use
+ * the tail of the queue. Other kinds of queues may use
* different placement rules. Every Queue implementation
* must specify its ordering properties.
*
@@ -96,7 +97,7 @@ package java.util;
*
*
* This interface is a member of the
- *
+ *
* Java Collections Framework.
*
* @see java.util.Collection
@@ -112,55 +113,77 @@ package java.util;
* @param the type of elements held in this collection
*/
public interface Queue extends Collection {
-
/**
- * Inserts the specified element into this queue, if possible. When
- * using queues that may impose insertion restrictions (for
- * example capacity bounds), method offer is generally
- * preferable to method {@link Collection#add}, which can fail to
- * insert an element only by throwing an exception.
- *
- * @param e the element to insert.
- * @return true if it was possible to add the element to
- * this queue, else false
+ * Inserts the specified element into this queue if it is possible to do so
+ * immediately without violating capacity restrictions, returning
+ * true upon success and throwing an IllegalStateException
+ * if no space is currently available.
+ *
+ * @param e the element to 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
+ * prevents it from being added to this queue
+ * @throws NullPointerException if the specified element is null and
+ * this queue does not permit null elements
+ * @throws IllegalArgumentException if some property of this element
+ * prevents it from being added to this queue
*/
- boolean offer(E e);
+ boolean add(E e);
/**
- * Retrieves and removes the head of this queue, or null
- * if this queue is empty.
+ * Inserts the specified element into this queue if it is possible to do
+ * so immediately without violating capacity restrictions.
+ * When using a capacity-restricted queue, this method is generally
+ * preferable to {@link #add}, which can fail to insert an element only
+ * by throwing an exception.
*
- * @return the head of this queue, or null if this
- * queue is empty.
+ * @param e the element to add
+ * @return true if the element was added to this queue, else
+ * false
+ * @throws ClassCastException if the class of the specified element
+ * prevents it from being added to this queue
+ * @throws NullPointerException if the specified element is null and
+ * this queue does not permit null elements
+ * @throws IllegalArgumentException if some property of this element
+ * prevents it from being added to this queue
*/
- E poll();
+ boolean offer(E e);
/**
- * Retrieves and removes the head of this queue. This method
- * differs from the {@link #poll} method only in that it throws an
- * exception if this queue is empty.
+ * Retrieves and removes the head of this queue. This method differs
+ * from {@link #poll poll} only in that it throws an exception if this
+ * queue is empty.
*
- * @return the head of this queue.
- * @throws NoSuchElementException if this queue is empty.
+ * @return the head of this queue
+ * @throws NoSuchElementException if this queue is empty
*/
E remove();
/**
- * Retrieves, but does not remove, the head of this queue,
- * returning null if this queue is empty.
+ * Retrieves and removes the head of this queue,
+ * or returns null if this queue is empty.
*
- * @return the head of this queue, or null if this queue
- * is empty.
+ * @return the head of this queue, or null if this queue is empty
*/
- E peek();
+ E poll();
/**
* Retrieves, but does not remove, the head of this queue. This method
- * differs from the {@link #peek} method only in that it throws an
- * exception if this queue is empty.
+ * differs from {@link #peek peek} only in that it throws an exception
+ * if this queue is empty.
*
- * @return the head of this queue.
- * @throws NoSuchElementException if this queue is empty.
+ * @return the head of this queue
+ * @throws NoSuchElementException if this queue is empty
*/
E element();
+
+ /**
+ * Retrieves, but does not remove, the head of this queue,
+ * or returns null if this queue is empty.
+ *
+ * @return the head of this queue, or null if this queue is empty
+ */
+ E peek();
}