Merged gcj-eclipse branch to trunk.
From-SVN: r120621
This commit is contained in:
Tom Tromey
parent
c648dedbde
commit
97b8365caf
17478 changed files with 606493 additions and 100744 deletions
189
libjava/classpath/external/jsr166/java/util/Queue.java
vendored
Normal file
189
libjava/classpath/external/jsr166/java/util/Queue.java
vendored
Normal file
|
|
@ -0,0 +1,189 @@
|
|||
/*
|
||||
* 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/licenses/publicdomain
|
||||
*/
|
||||
|
||||
package java.util;
|
||||
|
||||
/**
|
||||
* A collection designed for holding elements prior to processing.
|
||||
* Besides basic {@link java.util.Collection Collection} operations,
|
||||
* queues provide additional insertion, extraction, and inspection
|
||||
* operations. Each of these methods exists in two forms: one throws
|
||||
* an exception if the operation fails, the other returns a special
|
||||
* value (either <tt>null</tt> or <tt>false</tt>, depending on the
|
||||
* operation). The latter form of the insert operation is designed
|
||||
* specifically for use with capacity-restricted <tt>Queue</tt>
|
||||
* implementations; in most implementations, insert operations cannot
|
||||
* fail.
|
||||
*
|
||||
* <p>
|
||||
* <table BORDER CELLPADDING=3 CELLSPACING=1>
|
||||
* <tr>
|
||||
* <td></td>
|
||||
* <td ALIGN=CENTER><em>Throws exception</em></td>
|
||||
* <td ALIGN=CENTER><em>Returns special value</em></td>
|
||||
* </tr>
|
||||
* <tr>
|
||||
* <td><b>Insert</b></td>
|
||||
* <td>{@link #add add(e)}</td>
|
||||
* <td>{@link #offer offer(e)}</td>
|
||||
* </tr>
|
||||
* <tr>
|
||||
* <td><b>Remove</b></td>
|
||||
* <td>{@link #remove remove()}</td>
|
||||
* <td>{@link #poll poll()}</td>
|
||||
* </tr>
|
||||
* <tr>
|
||||
* <td><b>Examine</b></td>
|
||||
* <td>{@link #element element()}</td>
|
||||
* <td>{@link #peek peek()}</td>
|
||||
* </tr>
|
||||
* </table>
|
||||
*
|
||||
* <p>Queues typically, but do not necessarily, order elements in a
|
||||
* FIFO (first-in-first-out) manner. Among the exceptions are
|
||||
* priority queues, which order elements according to a supplied
|
||||
* comparator, or the elements' natural ordering, and LIFO queues (or
|
||||
* stacks) which order the elements LIFO (last-in-first-out).
|
||||
* Whatever the ordering used, the <em>head</em> of the queue is that
|
||||
* element which would be removed by a call to {@link #remove() } or
|
||||
* {@link #poll()}. In a FIFO queue, all new elements are inserted at
|
||||
* the <em> tail</em> of the queue. Other kinds of queues may use
|
||||
* different placement rules. Every <tt>Queue</tt> implementation
|
||||
* must specify its ordering properties.
|
||||
*
|
||||
* <p>The {@link #offer offer} method inserts an element if possible,
|
||||
* otherwise returning <tt>false</tt>. This differs from the {@link
|
||||
* java.util.Collection#add Collection.add} method, which can fail to
|
||||
* add an element only by throwing an unchecked exception. The
|
||||
* <tt>offer</tt> method is designed for use when failure is a normal,
|
||||
* rather than exceptional occurrence, for example, in fixed-capacity
|
||||
* (or "bounded") queues.
|
||||
*
|
||||
* <p>The {@link #remove()} and {@link #poll()} methods remove and
|
||||
* return the head of the queue.
|
||||
* Exactly which element is removed from the queue is a
|
||||
* function of the queue's ordering policy, which differs from
|
||||
* implementation to implementation. The <tt>remove()</tt> and
|
||||
* <tt>poll()</tt> methods differ only in their behavior when the
|
||||
* queue is empty: the <tt>remove()</tt> method throws an exception,
|
||||
* while the <tt>poll()</tt> method returns <tt>null</tt>.
|
||||
*
|
||||
* <p>The {@link #element()} and {@link #peek()} methods return, but do
|
||||
* not remove, the head of the queue.
|
||||
*
|
||||
* <p>The <tt>Queue</tt> interface does not define the <i>blocking queue
|
||||
* methods</i>, which are common in concurrent programming. These methods,
|
||||
* which wait for elements to appear or for space to become available, are
|
||||
* defined in the {@link java.util.concurrent.BlockingQueue} interface, which
|
||||
* extends this interface.
|
||||
*
|
||||
* <p><tt>Queue</tt> implementations generally do not allow insertion
|
||||
* of <tt>null</tt> elements, although some implementations, such as
|
||||
* {@link LinkedList}, do not prohibit insertion of <tt>null</tt>.
|
||||
* Even in the implementations that permit it, <tt>null</tt> should
|
||||
* not be inserted into a <tt>Queue</tt>, as <tt>null</tt> is also
|
||||
* used as a special return value by the <tt>poll</tt> method to
|
||||
* indicate that the queue contains no elements.
|
||||
*
|
||||
* <p><tt>Queue</tt> implementations generally do not define
|
||||
* element-based versions of methods <tt>equals</tt> and
|
||||
* <tt>hashCode</tt> but instead inherit the identity based versions
|
||||
* from class <tt>Object</tt>, because element-based equality is not
|
||||
* always well-defined for queues with the same elements but different
|
||||
* ordering properties.
|
||||
*
|
||||
*
|
||||
* <p>This interface is a member of the
|
||||
* <a href="{@docRoot}/../technotes/guides/collections/index.html">
|
||||
* Java Collections Framework</a>.
|
||||
*
|
||||
* @see java.util.Collection
|
||||
* @see LinkedList
|
||||
* @see PriorityQueue
|
||||
* @see java.util.concurrent.LinkedBlockingQueue
|
||||
* @see java.util.concurrent.BlockingQueue
|
||||
* @see java.util.concurrent.ArrayBlockingQueue
|
||||
* @see java.util.concurrent.LinkedBlockingQueue
|
||||
* @see java.util.concurrent.PriorityBlockingQueue
|
||||
* @since 1.5
|
||||
* @author Doug Lea
|
||||
* @param <E> the type of elements held in this collection
|
||||
*/
|
||||
public interface Queue<E> extends Collection<E> {
|
||||
/**
|
||||
* 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.
|
||||
*
|
||||
* @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
|
||||
*/
|
||||
boolean add(E e);
|
||||
|
||||
/**
|
||||
* Inserts the specified element into this queue if it is possible to do
|
||||
* so immediately without violating capacity restrictions.
|
||||
* When using a capacity-restricted queue, this method is generally
|
||||
* preferable to {@link #add}, which can fail to insert an element only
|
||||
* by throwing an exception.
|
||||
*
|
||||
* @param e the element to add
|
||||
* @return <tt>true</tt> if the element was added to this queue, else
|
||||
* <tt>false</tt>
|
||||
* @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
|
||||
*/
|
||||
boolean offer(E e);
|
||||
|
||||
/**
|
||||
* 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.
|
||||
*
|
||||
* @return the head of this queue
|
||||
* @throws NoSuchElementException if this queue is empty
|
||||
*/
|
||||
E remove();
|
||||
|
||||
/**
|
||||
* Retrieves and removes the head of this queue,
|
||||
* or returns <tt>null</tt> if this queue is empty.
|
||||
*
|
||||
* @return the head of this queue, or <tt>null</tt> if this queue is empty
|
||||
*/
|
||||
E poll();
|
||||
|
||||
/**
|
||||
* 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.
|
||||
*
|
||||
* @return the head of this queue
|
||||
* @throws NoSuchElementException if this queue is empty
|
||||
*/
|
||||
E element();
|
||||
|
||||
/**
|
||||
* Retrieves, but does not remove, the head of this queue,
|
||||
* or returns <tt>null</tt> if this queue is empty.
|
||||
*
|
||||
* @return the head of this queue, or <tt>null</tt> if this queue is empty
|
||||
*/
|
||||
E peek();
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue