/* * Written by Doug Lea with assistance from members of JCP JSR-166 * Expert Group and released to the public domain. Use, modify, and * redistribute this code in any way without acknowledgement. */ package java.util; /** * This class provides skeletal implementations of some {@link Queue} * operations. The implementations in this class are appropriate when * the base implementation does not allow null * elements. Methods {@link #add add}, {@link #remove remove}, and * {@link #element element} are based on {@link #offer offer}, {@link * #poll poll}, and {@link #peek peek}, respectively but throw * exceptions instead of indicating failure via false or * null returns. * *
A Queue implementation that extends this class must
* minimally define a method {@link Queue#offer} which does not permit
* insertion of null elements, along with methods {@link
* Queue#peek}, {@link Queue#poll}, {@link Collection#size}, {@link
* Collection#remove}, and a {@link Collection#iterator} supporting
* {@link Iterator#remove}. If these requirements cannot be met,
* consider instead subclassing {@link AbstractCollection}.
*
* @since 1.5
* @author Doug Lea
*/
public abstract class AbstractQueue This implementation repeatedly invokes {@link #poll poll} until it
* returns null.
*/
public void clear() {
while (poll() != null)
;
}
// Declarations that mostly just remove optionality clauses.
/**
* Removes a single instance of the specified element from this
* queue, if one is present. More formally, removes an element
* e such that (o==null ? e==null :
* o.equals(e)), if the queue contains such an element.
* Returns true if the queue contained the specified
* element (or equivalently, if the queue changed as a result of
* the call).
*
* @param o the element to remove
* @return true if the element was removed
*/
public abstract boolean remove(Object o);
/**
* Removes from this queue all of its elements that are contained in
* the specified collection.
*
* This implementation iterates over this queue, checking each
* element returned by the iterator in turn to see if it's contained
* in the specified collection. If it's so contained, it's removed from
* this queue with the iterator's remove method.
*
* @param c elements to be removed from this collection.
* @return true if this queue changed as a result of the
* call.
* @throws NullPointerException if the specified collection is null.
*/
public boolean removeAll(Collection> c) {
return super.removeAll(c);
}
/**
* Retains only the elements in this queue that are contained in the
* specified collection. In other words, removes
* from this queue all of its elements that are not contained in the
* specified collection.
*
* This implementation iterates over this queue, checking each
* element returned by the iterator in turn to see if it's contained
* in the specified collection. If it's not so contained, it's removed
* from this queue with the iterator's remove method.
*
* @param c elements to be retained in this collection.
* @return true if this queue changed as a result of the
* call.
* @throws NullPointerException if the specified collection is null.
*
*/
public boolean retainAll(Collection> c) {
return super.retainAll(c);
}
/**
* Adds all of the elements in the specified collection to this
* queue. The behavior of this operation is undefined if the
* specified collection is modified while the operation is in
* progress. (This implies that the behavior of this call is
* undefined if the specified collection is this queue, and this
* queue is nonempty.)
*
* This implementation iterates over the specified collection,
* and uses the add method to insert each object returned by
* the iterator to this queue, in turn.
*
* @param c collection whose elements are to be added to this queue
* @return true if this queue changed as a result of the
* call.
* @throws NullPointerException if c or any element in c
* is null
* @throws IllegalStateException if any element cannot be added.
*
*/
public boolean addAll(Collection extends E> c) {
return super.addAll(c);
}
}