/*

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

/*

 * This file is available under and governed by the GNU General Public

 * License version 2 only, as published by the Free Software Foundation.

 * However, the following notice accompanied the original version of this

 * file:

 *

 * Written by Doug Lea with assistance from members of JCP JSR-166

 * Expert Group and released to the public domain, as explained at

 * http://creativecommons.org/publicdomain/zero/1.0/

 */

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 <em>not</em> allow <tt>null</tt>

 * 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 <tt>false</tt> or

 * <tt>null</tt> returns.

 *

 * <p>A <tt>Queue</tt> implementation that extends this class must

 * minimally define a method {@link Queue#offer} which does not permit

 * insertion of <tt>null</tt> elements, along with methods {@link

 * Queue#peek}, {@link Queue#poll}, {@link Collection#size}, and

 * {@link Collection#iterator}.  Typically, additional methods will be

 * overridden as well.  If these requirements cannot be met, consider

 * instead subclassing {@link AbstractCollection}.

 *

 * <p>This class is a member of the

 * <a href="{@docRoot}/../technotes/guides/collections/index.html">

 * Java Collections Framework</a>.

 *

 * @since 1.5

 * @author Doug Lea

 * @param <E> the type of elements held in this collection

 */

public abstract class AbstractQueue<E>

    extends AbstractCollection<E>

    implements Queue<E> {

    /**

     * Constructor for use by subclasses.

     */

    protected AbstractQueue() {

    }

    /**

     * Inserts the specified element into this queue if it is possible to do so

     * immediately without violating capacity restrictions, returning

     * <tt>true</tt> upon success and throwing an <tt>IllegalStateException</tt>

     * if no space is currently available.

     *

     * <p>This implementation returns <tt>true</tt> if <tt>offer</tt> succeeds,

     * else throws an <tt>IllegalStateException</tt>.

     *

     * @param e the element to add

     * @return <tt>true</tt> (as specified by {@link Collection#add})

     * @throws IllegalStateException if the element cannot be added at this

     *         time due to capacity restrictions

     * @throws ClassCastException if the class of the specified element

     *         prevents it from being added to this queue

     * @throws NullPointerException if the specified element is null and

     *         this queue does not permit null elements

     * @throws IllegalArgumentException if some property of this element

     *         prevents it from being added to this queue

     */

    public boolean add(E e) {

        if (offer(e))

            return true;

        else

            throw new IllegalStateException("Queue full");

    }

    /**

     * Retrieves and removes the head of this queue.  This method differs

     * from {@link #poll poll} only in that it throws an exception if this

     * queue is empty.

     *

     * <p>This implementation returns the result of <tt>poll</tt>

     * unless the queue is empty.

     *

     * @return the head of this queue

     * @throws NoSuchElementException if this queue is empty

     */

    public E remove() {

        E x = poll();

        if (x != null)

            return x;

        else

            throw new NoSuchElementException();

    }

    /**

     * Retrieves, but does not remove, the head of this queue.  This method

     * differs from {@link #peek peek} only in that it throws an exception if

     * this queue is empty.

     *

     * <p>This implementation returns the result of <tt>peek</tt>

     * unless the queue is empty.

     *

     * @return the head of this queue

     * @throws NoSuchElementException if this queue is empty

     */

    public E element() {

        E x = peek();

        if (x != null)

            return x;

        else

            throw new NoSuchElementException();

    }

    /**

     * Removes all of the elements from this queue.

     * The queue will be empty after this call returns.

     *

     * <p>This implementation repeatedly invokes {@link #poll poll} until it

     * returns <tt>null</tt>.

     */

    public void clear() {

        while (poll() != null)

            ;

    }

    /**

     * Adds all of the elements in the specified collection to this

     * queue.  Attempts to addAll of a queue to itself result in

     * <tt>IllegalArgumentException</tt>. Further, the behavior of

     * this operation is undefined if the specified collection is

     * modified while the operation is in progress.

     *

     * <p>This implementation iterates over the specified collection,

     * and adds each element returned by the iterator to this

     * queue, in turn.  A runtime exception encountered while

     * trying to add an element (including, in particular, a

     * <tt>null</tt> element) may result in only some of the elements

     * having been successfully added when the associated exception is

     * thrown.

     *

     * @param c collection containing elements to be added to this queue

     * @return <tt>true</tt> if this queue changed as a result of the call

     * @throws ClassCastException if the class of an element of the specified

     *         collection prevents it from being added to this queue

     * @throws NullPointerException if the specified collection contains a

     *         null element and this queue does not permit null elements,

     *         or if the specified collection is null

     * @throws IllegalArgumentException if some property of an element of the

     *         specified collection prevents it from being added to this

     *         queue, or if the specified collection is this queue

     * @throws IllegalStateException if not all the elements can be added at

     *         this time due to insertion restrictions

     * @see #add(Object)

     */

    public boolean addAll(Collection<? extends E> c) {

        if (c == null)

            throw new NullPointerException();

        if (c == this)

            throw new IllegalArgumentException();

        boolean modified = false;

        for (E e : c)

            if (add(e))

                modified = true;

        return modified;

    }

}