AbstractQueue.java revision 0
0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 0N/A * published by the Free Software Foundation. Sun designates this 0N/A * particular file as subject to the "Classpath" exception as provided 0N/A * by Sun in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 0N/A * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, 0N/A * CA 95054 USA or visit www.sun.com if you need additional information or 0N/A * have any questions. 0N/A * This file is available under and governed by the GNU General Public 0N/A * License version 2 only, as published by the Free Software Foundation. 0N/A * However, the following notice accompanied the original version of this 0N/A * Written by Doug Lea with assistance from members of JCP JSR-166 0N/A * Expert Group and released to the public domain, as explained at 0N/A * This class provides skeletal implementations of some {@link Queue} 0N/A * operations. The implementations in this class are appropriate when 0N/A * the base implementation does <em>not</em> allow <tt>null</tt> 0N/A * elements. Methods {@link #add add}, {@link #remove remove}, and 0N/A * {@link #element element} are based on {@link #offer offer}, {@link 0N/A * #poll poll}, and {@link #peek peek}, respectively, but throw 0N/A * exceptions instead of indicating failure via <tt>false</tt> or 0N/A * <tt>null</tt> returns. 0N/A * <p>A <tt>Queue</tt> implementation that extends this class must 0N/A * minimally define a method {@link Queue#offer} which does not permit 0N/A * insertion of <tt>null</tt> elements, along with methods {@link 0N/A * Queue#peek}, {@link Queue#poll}, {@link Collection#size}, and 0N/A * {@link Collection#iterator}. Typically, additional methods will be 0N/A * overridden as well. If these requirements cannot be met, consider 0N/A * instead subclassing {@link AbstractCollection}. 0N/A * <p>This class is a member of the 0N/A * Java Collections Framework</a>. 0N/A * @param <E> the type of elements held in this collection 0N/A * Constructor for use by subclasses. 0N/A * Inserts the specified element into this queue if it is possible to do so 0N/A * immediately without violating capacity restrictions, returning 0N/A * <tt>true</tt> upon success and throwing an <tt>IllegalStateException</tt> 0N/A * if no space is currently available. 0N/A * <p>This implementation returns <tt>true</tt> if <tt>offer</tt> succeeds, 0N/A * else throws an <tt>IllegalStateException</tt>. 0N/A * @param e the element to add 0N/A * @return <tt>true</tt> (as specified by {@link Collection#add}) 0N/A * @throws IllegalStateException if the element cannot be added at this 0N/A * time due to capacity restrictions 0N/A * @throws ClassCastException if the class of the specified element 0N/A * prevents it from being added to this queue 0N/A * @throws NullPointerException if the specified element is null and 0N/A * this queue does not permit null elements 0N/A * @throws IllegalArgumentException if some property of this element 0N/A * prevents it from being added to this queue 0N/A * Retrieves and removes the head of this queue. This method differs 0N/A * from {@link #poll poll} only in that it throws an exception if this 0N/A * <p>This implementation returns the result of <tt>poll</tt> 0N/A * unless the queue is empty. 0N/A * @return the head of this queue 0N/A * @throws NoSuchElementException if this queue is empty 0N/A * Retrieves, but does not remove, the head of this queue. This method 0N/A * differs from {@link #peek peek} only in that it throws an exception if 0N/A * this queue is empty. 0N/A * <p>This implementation returns the result of <tt>peek</tt> 0N/A * unless the queue is empty. 0N/A * @return the head of this queue 0N/A * @throws NoSuchElementException if this queue is empty 0N/A * Removes all of the elements from this queue. 0N/A * The queue will be empty after this call returns. 0N/A * <p>This implementation repeatedly invokes {@link #poll poll} until it 0N/A * returns <tt>null</tt>. 0N/A * Adds all of the elements in the specified collection to this 0N/A * queue. Attempts to addAll of a queue to itself result in 0N/A * <tt>IllegalArgumentException</tt>. Further, the behavior of 0N/A * this operation is undefined if the specified collection is 0N/A * modified while the operation is in progress. 0N/A * <p>This implementation iterates over the specified collection, 0N/A * and adds each element returned by the iterator to this 0N/A * queue, in turn. A runtime exception encountered while 0N/A * trying to add an element (including, in particular, a 0N/A * <tt>null</tt> element) may result in only some of the elements 0N/A * having been successfully added when the associated exception is 0N/A * @param c collection containing elements to be added to this queue 0N/A * @return <tt>true</tt> if this queue changed as a result of the call 0N/A * @throws ClassCastException if the class of an element of the specified 0N/A * collection prevents it from being added to this queue 0N/A * @throws NullPointerException if the specified collection contains a 0N/A * null element and this queue does not permit null elements, 0N/A * or if the specified collection is null 0N/A * @throws IllegalArgumentException if some property of an element of the 0N/A * specified collection prevents it from being added to this 0N/A * queue, or if the specified collection is this queue 0N/A * @throws IllegalStateException if not all the elements can be added at 0N/A * this time due to insertion restrictions