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 2362N/A * published by the Free Software Foundation. Oracle designates this 0N/A * particular file as subject to the "Classpath" exception as provided 2362N/A * by Oracle 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. 2362N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2362N/A * or visit www.oracle.com if you need additional information or have any 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 * A collection designed for holding elements prior to processing. 0N/A * Besides basic {@link java.util.Collection Collection} operations, 0N/A * queues provide additional insertion, extraction, and inspection 0N/A * operations. Each of these methods exists in two forms: one throws 0N/A * an exception if the operation fails, the other returns a special 0N/A * value (either <tt>null</tt> or <tt>false</tt>, depending on the 0N/A * operation). The latter form of the insert operation is designed 0N/A * specifically for use with capacity-restricted <tt>Queue</tt> 0N/A * implementations; in most implementations, insert operations cannot 0N/A * <table BORDER CELLPADDING=3 CELLSPACING=1> 0N/A * <td ALIGN=CENTER><em>Throws exception</em></td> 0N/A * <td ALIGN=CENTER><em>Returns special value</em></td> 0N/A * <td><b>Insert</b></td> 0N/A * <td>{@link #add add(e)}</td> 0N/A * <td>{@link #offer offer(e)}</td> 0N/A * <td><b>Remove</b></td> 0N/A * <td>{@link #remove remove()}</td> 0N/A * <td>{@link #poll poll()}</td> 0N/A * <td><b>Examine</b></td> 0N/A * <td>{@link #element element()}</td> 0N/A * <td>{@link #peek peek()}</td> 0N/A * <p>Queues typically, but do not necessarily, order elements in a 0N/A * FIFO (first-in-first-out) manner. Among the exceptions are 0N/A * priority queues, which order elements according to a supplied 0N/A * comparator, or the elements' natural ordering, and LIFO queues (or 0N/A * stacks) which order the elements LIFO (last-in-first-out). 0N/A * Whatever the ordering used, the <em>head</em> of the queue is that 0N/A * element which would be removed by a call to {@link #remove() } or 0N/A * {@link #poll()}. In a FIFO queue, all new elements are inserted at 0N/A * the <em> tail</em> of the queue. Other kinds of queues may use 0N/A * different placement rules. Every <tt>Queue</tt> implementation 0N/A * must specify its ordering properties. 0N/A * <p>The {@link #offer offer} method inserts an element if possible, 0N/A * otherwise returning <tt>false</tt>. This differs from the {@link 0N/A * java.util.Collection#add Collection.add} method, which can fail to 0N/A * add an element only by throwing an unchecked exception. The 0N/A * <tt>offer</tt> method is designed for use when failure is a normal, 0N/A * rather than exceptional occurrence, for example, in fixed-capacity 0N/A * (or "bounded") queues. 0N/A * <p>The {@link #remove()} and {@link #poll()} methods remove and 0N/A * return the head of the queue. 0N/A * Exactly which element is removed from the queue is a 0N/A * function of the queue's ordering policy, which differs from 0N/A * implementation to implementation. The <tt>remove()</tt> and 0N/A * <tt>poll()</tt> methods differ only in their behavior when the 0N/A * queue is empty: the <tt>remove()</tt> method throws an exception, 0N/A * while the <tt>poll()</tt> method returns <tt>null</tt>. 0N/A * <p>The {@link #element()} and {@link #peek()} methods return, but do 0N/A * not remove, the head of the queue. 0N/A * <p>The <tt>Queue</tt> interface does not define the <i>blocking queue 0N/A * methods</i>, which are common in concurrent programming. These methods, 0N/A * which wait for elements to appear or for space to become available, are 0N/A * defined in the {@link java.util.concurrent.BlockingQueue} interface, which 0N/A * extends this interface. 0N/A * <p><tt>Queue</tt> implementations generally do not allow insertion 0N/A * of <tt>null</tt> elements, although some implementations, such as 0N/A * {@link LinkedList}, do not prohibit insertion of <tt>null</tt>. 0N/A * Even in the implementations that permit it, <tt>null</tt> should 0N/A * not be inserted into a <tt>Queue</tt>, as <tt>null</tt> is also 0N/A * used as a special return value by the <tt>poll</tt> method to 0N/A * indicate that the queue contains no elements. 0N/A * <p><tt>Queue</tt> implementations generally do not define 0N/A * element-based versions of methods <tt>equals</tt> and 0N/A * <tt>hashCode</tt> but instead inherit the identity based versions 0N/A * from class <tt>Object</tt>, because element-based equality is not 0N/A * always well-defined for queues with the same elements but different 0N/A * ordering properties. 0N/A * <p>This interface is a member of the 0N/A * Java Collections Framework</a>. 0N/A * @see java.util.Collection 0N/A * @see PriorityQueue 0N/A * @see java.util.concurrent.LinkedBlockingQueue 0N/A * @see java.util.concurrent.BlockingQueue 0N/A * @see java.util.concurrent.ArrayBlockingQueue 0N/A * @see java.util.concurrent.LinkedBlockingQueue 0N/A * @see java.util.concurrent.PriorityBlockingQueue 0N/A * @param <E> the type of elements held in this collection 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 * @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 * Inserts the specified element into this queue if it is possible to do 0N/A * so immediately without violating capacity restrictions. 0N/A * When using a capacity-restricted queue, this method is generally 0N/A * preferable to {@link #add}, which can fail to insert an element only 0N/A * by throwing an exception. 0N/A * @param e the element to add 0N/A * @return <tt>true</tt> if the element was added to this queue, else 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 * @return the head of this queue 0N/A * @throws NoSuchElementException if this queue is empty 0N/A * Retrieves and removes the head of this queue, 0N/A * or returns <tt>null</tt> if this queue is empty. 0N/A * @return the head of this queue, or <tt>null</tt> 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 0N/A * if this 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, 0N/A * or returns <tt>null</tt> if this queue is empty. 0N/A * @return the head of this queue, or <tt>null</tt> if this queue is empty