Home » openjdk-7 » java » util » [javadoc | source]

    1   /*
    2    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
    3    *
    4    * This code is free software; you can redistribute it and/or modify it
    5    * under the terms of the GNU General Public License version 2 only, as
    6    * published by the Free Software Foundation.  Oracle designates this
    7    * particular file as subject to the "Classpath" exception as provided
    8    * by Oracle in the LICENSE file that accompanied this code.
    9    *
   10    * This code is distributed in the hope that it will be useful, but WITHOUT
   11    * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
   12    * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
   13    * version 2 for more details (a copy is included in the LICENSE file that
   14    * accompanied this code).
   15    *
   16    * You should have received a copy of the GNU General Public License version
   17    * 2 along with this work; if not, write to the Free Software Foundation,
   18    * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
   19    *
   20    * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
   21    * or visit www.oracle.com if you need additional information or have any
   22    * questions.
   23    */
   24   
   25   /*
   26    * This file is available under and governed by the GNU General Public
   27    * License version 2 only, as published by the Free Software Foundation.
   28    * However, the following notice accompanied the original version of this
   29    * file:
   30    *
   31    * Written by Doug Lea with assistance from members of JCP JSR-166
   32    * Expert Group and released to the public domain, as explained at
   33    * http://creativecommons.org/publicdomain/zero/1.0/
   34    */
   35   
   36   package java.util;
   37   
   38   /**
   39    * This class provides skeletal implementations of some {@link Queue}
   40    * operations. The implementations in this class are appropriate when
   41    * the base implementation does <em>not</em> allow <tt>null</tt>
   42    * elements.  Methods {@link #add add}, {@link #remove remove}, and
   43    * {@link #element element} are based on {@link #offer offer}, {@link
   44    * #poll poll}, and {@link #peek peek}, respectively, but throw
   45    * exceptions instead of indicating failure via <tt>false</tt> or
   46    * <tt>null</tt> returns.
   47    *
   48    * <p>A <tt>Queue</tt> implementation that extends this class must
   49    * minimally define a method {@link Queue#offer} which does not permit
   50    * insertion of <tt>null</tt> elements, along with methods {@link
   51    * Queue#peek}, {@link Queue#poll}, {@link Collection#size}, and
   52    * {@link Collection#iterator}.  Typically, additional methods will be
   53    * overridden as well.  If these requirements cannot be met, consider
   54    * instead subclassing {@link AbstractCollection}.
   55    *
   56    * <p>This class is a member of the
   57    * <a href="{@docRoot}/../technotes/guides/collections/index.html">
   58    * Java Collections Framework</a>.
   59    *
   60    * @since 1.5
   61    * @author Doug Lea
   62    * @param <E> the type of elements held in this collection
   63    */
   64   public abstract class AbstractQueue<E>
   65       extends AbstractCollection<E>
   66       implements Queue<E> {
   67   
   68       /**
   69        * Constructor for use by subclasses.
   70        */
   71       protected AbstractQueue() {
   72       }
   73   
   74       /**
   75        * Inserts the specified element into this queue if it is possible to do so
   76        * immediately without violating capacity restrictions, returning
   77        * <tt>true</tt> upon success and throwing an <tt>IllegalStateException</tt>
   78        * if no space is currently available.
   79        *
   80        * <p>This implementation returns <tt>true</tt> if <tt>offer</tt> succeeds,
   81        * else throws an <tt>IllegalStateException</tt>.
   82        *
   83        * @param e the element to add
   84        * @return <tt>true</tt> (as specified by {@link Collection#add})
   85        * @throws IllegalStateException if the element cannot be added at this
   86        *         time due to capacity restrictions
   87        * @throws ClassCastException if the class of the specified element
   88        *         prevents it from being added to this queue
   89        * @throws NullPointerException if the specified element is null and
   90        *         this queue does not permit null elements
   91        * @throws IllegalArgumentException if some property of this element
   92        *         prevents it from being added to this queue
   93        */
   94       public boolean add(E e) {
   95           if (offer(e))
   96               return true;
   97           else
   98               throw new IllegalStateException("Queue full");
   99       }
  100   
  101       /**
  102        * Retrieves and removes the head of this queue.  This method differs
  103        * from {@link #poll poll} only in that it throws an exception if this
  104        * queue is empty.
  105        *
  106        * <p>This implementation returns the result of <tt>poll</tt>
  107        * unless the queue is empty.
  108        *
  109        * @return the head of this queue
  110        * @throws NoSuchElementException if this queue is empty
  111        */
  112       public E remove() {
  113           E x = poll();
  114           if (x != null)
  115               return x;
  116           else
  117               throw new NoSuchElementException();
  118       }
  119   
  120       /**
  121        * Retrieves, but does not remove, the head of this queue.  This method
  122        * differs from {@link #peek peek} only in that it throws an exception if
  123        * this queue is empty.
  124        *
  125        * <p>This implementation returns the result of <tt>peek</tt>
  126        * unless the queue is empty.
  127        *
  128        * @return the head of this queue
  129        * @throws NoSuchElementException if this queue is empty
  130        */
  131       public E element() {
  132           E x = peek();
  133           if (x != null)
  134               return x;
  135           else
  136               throw new NoSuchElementException();
  137       }
  138   
  139       /**
  140        * Removes all of the elements from this queue.
  141        * The queue will be empty after this call returns.
  142        *
  143        * <p>This implementation repeatedly invokes {@link #poll poll} until it
  144        * returns <tt>null</tt>.
  145        */
  146       public void clear() {
  147           while (poll() != null)
  148               ;
  149       }
  150   
  151       /**
  152        * Adds all of the elements in the specified collection to this
  153        * queue.  Attempts to addAll of a queue to itself result in
  154        * <tt>IllegalArgumentException</tt>. Further, the behavior of
  155        * this operation is undefined if the specified collection is
  156        * modified while the operation is in progress.
  157        *
  158        * <p>This implementation iterates over the specified collection,
  159        * and adds each element returned by the iterator to this
  160        * queue, in turn.  A runtime exception encountered while
  161        * trying to add an element (including, in particular, a
  162        * <tt>null</tt> element) may result in only some of the elements
  163        * having been successfully added when the associated exception is
  164        * thrown.
  165        *
  166        * @param c collection containing elements to be added to this queue
  167        * @return <tt>true</tt> if this queue changed as a result of the call
  168        * @throws ClassCastException if the class of an element of the specified
  169        *         collection prevents it from being added to this queue
  170        * @throws NullPointerException if the specified collection contains a
  171        *         null element and this queue does not permit null elements,
  172        *         or if the specified collection is null
  173        * @throws IllegalArgumentException if some property of an element of the
  174        *         specified collection prevents it from being added to this
  175        *         queue, or if the specified collection is this queue
  176        * @throws IllegalStateException if not all the elements can be added at
  177        *         this time due to insertion restrictions
  178        * @see #add(Object)
  179        */
  180       public boolean addAll(Collection<? extends E> c) {
  181           if (c == null)
  182               throw new NullPointerException();
  183           if (c == this)
  184               throw new IllegalArgumentException();
  185           boolean modified = false;
  186           for (E e : c)
  187               if (add(e))
  188                   modified = true;
  189           return modified;
  190       }
  191   
  192   }

Home » openjdk-7 » java » util » [javadoc | source]