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