lib/classpath/external/jsr166/java/util/AbstractQueue.java

   1 /*
   2  * Written by Doug Lea with assistance from members of JCP JSR-166
   3  * Expert Group and released to the public domain, as explained at
   4  * http://creativecommons.org/licenses/publicdomain
   5  */
   6
   7 package java.util;
   8
   9 /**
  10  * This class provides skeletal implementations of some {@link Queue}
  11  * operations. The implementations in this class are appropriate when
  12  * the base implementation does <em>not</em> allow <tt>null</tt>
  13  * elements.  Methods {@link #add add}, {@link #remove remove}, and
  14  * {@link #element element} are based on {@link #offer offer}, {@link
  15  * #poll poll}, and {@link #peek peek}, respectively but throw
  16  * exceptions instead of indicating failure via <tt>false</tt> or
  17  * <tt>null</tt> returns.
  18  *
  19  * <p> A <tt>Queue</tt> implementation that extends this class must
  20  * minimally define a method {@link Queue#offer} which does not permit
  21  * insertion of <tt>null</tt> elements, along with methods {@link
  22  * Queue#peek}, {@link Queue#poll}, {@link Collection#size}, and a
  23  * {@link Collection#iterator} supporting {@link
  24  * Iterator#remove}. Typically, additional methods will be overridden
  25  * as well. If these requirements cannot be met, consider instead
  26  * subclassing {@link AbstractCollection}.
  27  *
  28  * <p>This class is a member of the
  29  * <a href="{@docRoot}/../technotes/guides/collections/index.html">
  30  * Java Collections Framework</a>.
  31  *
  32  * @since 1.5
  33  * @author Doug Lea
  34  * @param <E> the type of elements held in this collection
  35  */
  36 public abstract class AbstractQueue<E>
  37     extends AbstractCollection<E>
  38     implements Queue<E> {
  39
  40     /**
  41      * Constructor for use by subclasses.
  42      */
  43     protected AbstractQueue() {
  44     }
  45
  46     /**
  47      * Inserts the specified element into this queue if it is possible to do so
  48      * immediately without violating capacity restrictions, returning
  49      * <tt>true</tt> upon success and throwing an <tt>IllegalStateException</tt>
  50      * if no space is currently available.
  51      *
  52      * <p>This implementation returns <tt>true</tt> if <tt>offer</tt> succeeds,
  53      * else throws an <tt>IllegalStateException</tt>.
  54      *
  55      * @param e the element to add
  56      * @return <tt>true</tt> (as specified by {@link Collection#add})
  57      * @throws IllegalStateException if the element cannot be added at this
  58      *         time due to capacity restrictions
  59      * @throws ClassCastException if the class of the specified element
  60      *         prevents it from being added to this queue
  61      * @throws NullPointerException if the specified element is null and
  62      *         this queue does not permit null elements
  63      * @throws IllegalArgumentException if some property of this element
  64      *         prevents it from being added to this queue
  65      */
  66     public boolean add(E e) {
  67         if (offer(e))
  68             return true;
  69         else
  70             throw new IllegalStateException("Queue full");
  71     }
  72
  73     /**
  74      * Retrieves and removes the head of this queue.  This method differs
  75      * from {@link #poll poll} only in that it throws an exception if this
  76      * queue is empty.
  77      *
  78      * <p>This implementation returns the result of <tt>poll</tt>
  79      * unless the queue is empty.
  80      *
  81      * @return the head of this queue
  82      * @throws NoSuchElementException if this queue is empty
  83      */
  84     public E remove() {
  85         E x = poll();
  86         if (x != null)
  87             return x;
  88         else
  89             throw new NoSuchElementException();
  90     }
  91
  92     /**
  93      * Retrieves, but does not remove, the head of this queue.  This method
  94      * differs from {@link #peek peek} only in that it throws an exception if
  95      * this queue is empty.
  96      *
  97      * <p>This implementation returns the result of <tt>peek</tt>
  98      * unless the queue is empty.
  99      *
 100      * @return the head of this queue
 101      * @throws NoSuchElementException if this queue is empty
 102      */
 103     public E element() {
 104         E x = peek();
 105         if (x != null)
 106             return x;
 107         else
 108             throw new NoSuchElementException();
 109     }
 110
 111     /**
 112      * Removes all of the elements from this queue.
 113      * The queue will be empty after this call returns.
 114      *
 115      * <p>This implementation repeatedly invokes {@link #poll poll} until it
 116      * returns <tt>null</tt>.
 117      */
 118     public void clear() {
 119         while (poll() != null)
 120             ;
 121     }
 122
 123     /**
 124      * Adds all of the elements in the specified collection to this
 125      * queue.  Attempts to addAll of a queue to itself result in
 126      * <tt>IllegalArgumentException</tt>. Further, the behavior of
 127      * this operation is undefined if the specified collection is
 128      * modified while the operation is in progress.
 129      *
 130      * <p>This implementation iterates over the specified collection,
 131      * and adds each element returned by the iterator to this
 132      * queue, in turn.  A runtime exception encountered while
 133      * trying to add an element (including, in particular, a
 134      * <tt>null</tt> element) may result in only some of the elements
 135      * having been successfully added when the associated exception is
 136      * thrown.
 137      *
 138      * @param c collection containing elements to be added to this queue
 139      * @return <tt>true</tt> if this queue changed as a result of the call
 140      * @throws ClassCastException if the class of an element of the specified
 141      *         collection prevents it from being added to this queue
 142      * @throws NullPointerException if the specified collection contains a
 143      *         null element and this queue does not permit null elements,
 144      *         or if the specified collection is null
 145      * @throws IllegalArgumentException if some property of an element of the
 146      *         specified collection prevents it from being added to this
 147      *         queue, or if the specified collection is this queue
 148      * @throws IllegalStateException if not all the elements can be added at
 149      *         this time due to insertion restrictions
 150      * @see #add(Object)
 151      */
 152     public boolean addAll(Collection<? extends E> c) {
 153         if (c == null)
 154             throw new NullPointerException();
 155         if (c == this)
 156             throw new IllegalArgumentException();
 157         boolean modified = false;
 158         Iterator<? extends E> e = c.iterator();
 159         while (e.hasNext()) {
 160             if (add(e.next()))
 161                 modified = true;
 162         }
 163         return modified;
 164     }
 165
 166 }