Source for java.util.Queue

   1: /*
   2:  * Written by Doug Lea with assistance from members of JCP JSR-166
   3:  * Expert Group and released to the public domain, as explained at
   4:  * http://creativecommons.org/licenses/publicdomain
   5:  */
   6: 
   7: package java.util;
   8: 
   9: /**
  10:  * A collection designed for holding elements prior to processing.
  11:  * Besides basic {@link java.util.Collection Collection} operations,
  12:  * queues provide additional insertion, extraction, and inspection
  13:  * operations.  Each of these methods exists in two forms: one throws
  14:  * an exception if the operation fails, the other returns a special
  15:  * value (either <tt>null</tt> or <tt>false</tt>, depending on the
  16:  * operation).  The latter form of the insert operation is designed
  17:  * specifically for use with capacity-restricted <tt>Queue</tt>
  18:  * implementations; in most implementations, insert operations cannot
  19:  * fail.
  20:  *
  21:  * <p>
  22:  * <table BORDER CELLPADDING=3 CELLSPACING=1>
  23:  *  <tr>
  24:  *    <td></td>
  25:  *    <td ALIGN=CENTER><em>Throws exception</em></td>
  26:  *    <td ALIGN=CENTER><em>Returns special value</em></td>
  27:  *  </tr>
  28:  *  <tr>
  29:  *    <td><b>Insert</b></td>
  30:  *    <td>{@link #add add(e)}</td>
  31:  *    <td>{@link #offer offer(e)}</td>
  32:  *  </tr>
  33:  *  <tr>
  34:  *    <td><b>Remove</b></td>
  35:  *    <td>{@link #remove remove()}</td>
  36:  *    <td>{@link #poll poll()}</td>
  37:  *  </tr>
  38:  *  <tr>
  39:  *    <td><b>Examine</b></td>
  40:  *    <td>{@link #element element()}</td>
  41:  *    <td>{@link #peek peek()}</td>
  42:  *  </tr>
  43:  * </table>
  44:  *
  45:  * <p>Queues typically, but do not necessarily, order elements in a
  46:  * FIFO (first-in-first-out) manner.  Among the exceptions are
  47:  * priority queues, which order elements according to a supplied
  48:  * comparator, or the elements' natural ordering, and LIFO queues (or
  49:  * stacks) which order the elements LIFO (last-in-first-out).
  50:  * Whatever the ordering used, the <em>head</em> of the queue is that
  51:  * element which would be removed by a call to {@link #remove() } or
  52:  * {@link #poll()}.  In a FIFO queue, all new elements are inserted at
  53:  * the <em> tail</em> of the queue. Other kinds of queues may use
  54:  * different placement rules.  Every <tt>Queue</tt> implementation
  55:  * must specify its ordering properties.
  56:  *
  57:  * <p>The {@link #offer offer} method inserts an element if possible,
  58:  * otherwise returning <tt>false</tt>.  This differs from the {@link
  59:  * java.util.Collection#add Collection.add} method, which can fail to
  60:  * add an element only by throwing an unchecked exception.  The
  61:  * <tt>offer</tt> method is designed for use when failure is a normal,
  62:  * rather than exceptional occurrence, for example, in fixed-capacity
  63:  * (or &quot;bounded&quot;) queues.
  64:  *
  65:  * <p>The {@link #remove()} and {@link #poll()} methods remove and
  66:  * return the head of the queue.
  67:  * Exactly which element is removed from the queue is a
  68:  * function of the queue's ordering policy, which differs from
  69:  * implementation to implementation. The <tt>remove()</tt> and
  70:  * <tt>poll()</tt> methods differ only in their behavior when the
  71:  * queue is empty: the <tt>remove()</tt> method throws an exception,
  72:  * while the <tt>poll()</tt> method returns <tt>null</tt>.
  73:  *
  74:  * <p>The {@link #element()} and {@link #peek()} methods return, but do
  75:  * not remove, the head of the queue.
  76:  *
  77:  * <p>The <tt>Queue</tt> interface does not define the <i>blocking queue
  78:  * methods</i>, which are common in concurrent programming.  These methods,
  79:  * which wait for elements to appear or for space to become available, are
  80:  * defined in the {@link java.util.concurrent.BlockingQueue} interface, which
  81:  * extends this interface.
  82:  *
  83:  * <p><tt>Queue</tt> implementations generally do not allow insertion
  84:  * of <tt>null</tt> elements, although some implementations, such as
  85:  * {@link LinkedList}, do not prohibit insertion of <tt>null</tt>.
  86:  * Even in the implementations that permit it, <tt>null</tt> should
  87:  * not be inserted into a <tt>Queue</tt>, as <tt>null</tt> is also
  88:  * used as a special return value by the <tt>poll</tt> method to
  89:  * indicate that the queue contains no elements.
  90:  *
  91:  * <p><tt>Queue</tt> implementations generally do not define
  92:  * element-based versions of methods <tt>equals</tt> and
  93:  * <tt>hashCode</tt> but instead inherit the identity based versions
  94:  * from class <tt>Object</tt>, because element-based equality is not
  95:  * always well-defined for queues with the same elements but different
  96:  * ordering properties.
  97:  *
  98:  *
  99:  * <p>This interface is a member of the
 100:  * <a href="{@docRoot}/../technotes/guides/collections/index.html">
 101:  * Java Collections Framework</a>.
 102:  *
 103:  * @see java.util.Collection
 104:  * @see LinkedList
 105:  * @see PriorityQueue
 106:  * @see java.util.concurrent.LinkedBlockingQueue
 107:  * @see java.util.concurrent.BlockingQueue
 108:  * @see java.util.concurrent.ArrayBlockingQueue
 109:  * @see java.util.concurrent.LinkedBlockingQueue
 110:  * @see java.util.concurrent.PriorityBlockingQueue
 111:  * @since 1.5
 112:  * @author Doug Lea
 113:  * @param <E> the type of elements held in this collection
 114:  */
 115: public interface Queue<E> extends Collection<E> {
 116:     /**
 117:      * Inserts the specified element into this queue if it is possible to do so
 118:      * immediately without violating capacity restrictions, returning
 119:      * <tt>true</tt> upon success and throwing an <tt>IllegalStateException</tt>
 120:      * if no space is currently available.
 121:      *
 122:      * @param e the element to add
 123:      * @return <tt>true</tt> (as specified by {@link Collection#add})
 124:      * @throws IllegalStateException if the element cannot be added at this
 125:      *         time due to capacity restrictions
 126:      * @throws ClassCastException if the class of the specified element
 127:      *         prevents it from being added to this queue
 128:      * @throws NullPointerException if the specified element is null and
 129:      *         this queue does not permit null elements
 130:      * @throws IllegalArgumentException if some property of this element
 131:      *         prevents it from being added to this queue
 132:      */
 133:     boolean add(E e);
 134: 
 135:     /**
 136:      * Inserts the specified element into this queue if it is possible to do
 137:      * so immediately without violating capacity restrictions.
 138:      * When using a capacity-restricted queue, this method is generally
 139:      * preferable to {@link #add}, which can fail to insert an element only
 140:      * by throwing an exception.
 141:      *
 142:      * @param e the element to add
 143:      * @return <tt>true</tt> if the element was added to this queue, else
 144:      *         <tt>false</tt>
 145:      * @throws ClassCastException if the class of the specified element
 146:      *         prevents it from being added to this queue
 147:      * @throws NullPointerException if the specified element is null and
 148:      *         this queue does not permit null elements
 149:      * @throws IllegalArgumentException if some property of this element
 150:      *         prevents it from being added to this queue
 151:      */
 152:     boolean offer(E e);
 153: 
 154:     /**
 155:      * Retrieves and removes the head of this queue.  This method differs
 156:      * from {@link #poll poll} only in that it throws an exception if this
 157:      * queue is empty.
 158:      *
 159:      * @return the head of this queue
 160:      * @throws NoSuchElementException if this queue is empty
 161:      */
 162:     E remove();
 163: 
 164:     /**
 165:      * Retrieves and removes the head of this queue,
 166:      * or returns <tt>null</tt> if this queue is empty.
 167:      *
 168:      * @return the head of this queue, or <tt>null</tt> if this queue is empty
 169:      */
 170:     E poll();
 171: 
 172:     /**
 173:      * Retrieves, but does not remove, the head of this queue.  This method
 174:      * differs from {@link #peek peek} only in that it throws an exception
 175:      * if this queue is empty.
 176:      *
 177:      * @return the head of this queue
 178:      * @throws NoSuchElementException if this queue is empty
 179:      */
 180:     E element();
 181: 
 182:     /**
 183:      * Retrieves, but does not remove, the head of this queue,
 184:      * or returns <tt>null</tt> if this queue is empty.
 185:      *
 186:      * @return the head of this queue, or <tt>null</tt> if this queue is empty
 187:      */
 188:     E peek();
 189: }