Source for java.util.AbstractQueue

   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: }