Parent Directory
| 
Revision Log
Revision 1.30 - (view) (download)
| 1 : | dl | 1.3 | /* |
| 2 : | * Written by Doug Lea with assistance from members of JCP JSR-166 | ||
| 3 : | dl | 1.22 | * Expert Group and released to the public domain, as explained at |
| 4 : | * http://creativecommons.org/licenses/publicdomain | ||
| 5 : | dl | 1.3 | */ |
| 6 : | |||
| 7 : | tim | 1.1 | package java.util; |
| 8 : | |||
| 9 : | /** | ||
| 10 : | dholmes | 1.8 | * A collection designed for holding elements prior to processing. |
| 11 : | dl | 1.24 | * 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 : | dl | 1.23 | * |
| 21 : | jsr166 | 1.28 | * <p> |
| 22 : | * <table BORDER CELLPADDING=3 CELLSPACING=1> | ||
| 23 : | dl | 1.23 | * <tr> |
| 24 : | dl | 1.24 | * <td></td> |
| 25 : | * <td ALIGN=CENTER><em>Throws exception</em></td> | ||
| 26 : | jsr166 | 1.29 | * <td ALIGN=CENTER><em>Special value</em></td> |
| 27 : | dl | 1.23 | * </tr> |
| 28 : | * <tr> | ||
| 29 : | dl | 1.24 | * <td><b>Insert</b></td> |
| 30 : | * <td>{@link #add add(e)}</td> | ||
| 31 : | * <td>{@link #offer offer(e)}</td> | ||
| 32 : | dl | 1.23 | * </tr> |
| 33 : | * <tr> | ||
| 34 : | dl | 1.24 | * <td><b>Remove</b></td> |
| 35 : | * <td>{@link #remove remove()}</td> | ||
| 36 : | * <td>{@link #poll poll()}</td> | ||
| 37 : | dl | 1.23 | * </tr> |
| 38 : | * <tr> | ||
| 39 : | dl | 1.24 | * <td><b>Examine</b></td> |
| 40 : | * <td>{@link #element element()}</td> | ||
| 41 : | * <td>{@link #peek peek()}</td> | ||
| 42 : | dl | 1.23 | * </tr> |
| 43 : | dl | 1.24 | * </table> |
| 44 : | dholmes | 1.8 | * |
| 45 : | tim | 1.2 | * <p>Queues typically, but do not necessarily, order elements in a |
| 46 : | dl | 1.5 | * FIFO (first-in-first-out) manner. Among the exceptions are |
| 47 : | * priority queues, which order elements according to a supplied | ||
| 48 : | dholmes | 1.8 | * comparator, or the elements' natural ordering, and LIFO queues (or |
| 49 : | * stacks) which order the elements LIFO (last-in-first-out). | ||
| 50 : | dl | 1.17 | * 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 "bounded") queues. | ||
| 64 : | tim | 1.9 | * |
| 65 : | dl | 1.7 | * <p>The {@link #remove()} and {@link #poll()} methods remove and |
| 66 : | dholmes | 1.8 | * return the head of the queue. |
| 67 : | * Exactly which element is removed from the queue is a | ||
| 68 : | dl | 1.7 | * function of the queue's ordering policy, which differs from |
| 69 : | dholmes | 1.8 | * implementation to implementation. The <tt>remove()</tt> and |
| 70 : | dl | 1.7 | * <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 : | tim | 1.1 | * |
| 74 : | dholmes | 1.8 | * <p>The {@link #element()} and {@link #peek()} methods return, but do |
| 75 : | dholmes | 1.10 | * not remove, the head of the queue. |
| 76 : | tim | 1.1 | * |
| 77 : | tim | 1.2 | * <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 : | dl | 1.7 | * <p><tt>Queue</tt> implementations generally do not allow insertion |
| 84 : | * of <tt>null</tt> elements, although some implementations, such as | ||
| 85 : | brian | 1.6 | * {@link LinkedList}, do not prohibit insertion of <tt>null</tt>. |
| 86 : | dl | 1.7 | * 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 : | tim | 1.2 | * |
| 91 : | dl | 1.16 | * <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 : | tim | 1.2 | * <p>This interface is a member of the |
| 100 : | * <a href="{@docRoot}/../guide/collections/index.html"> | ||
| 101 : | * Java Collections Framework</a>. | ||
| 102 : | * | ||
| 103 : | tim | 1.11 | * @see java.util.Collection |
| 104 : | tim | 1.2 | * @see LinkedList |
| 105 : | * @see PriorityQueue | ||
| 106 : | dholmes | 1.15 | * @see java.util.concurrent.LinkedBlockingQueue |
| 107 : | tim | 1.2 | * @see java.util.concurrent.BlockingQueue |
| 108 : | * @see java.util.concurrent.ArrayBlockingQueue | ||
| 109 : | * @see java.util.concurrent.LinkedBlockingQueue | ||
| 110 : | * @see java.util.concurrent.PriorityBlockingQueue | ||
| 111 : | dl | 1.7 | * @since 1.5 |
| 112 : | * @author Doug Lea | ||
| 113 : | dl | 1.21 | * @param <E> the type of elements held in this collection |
| 114 : | tim | 1.2 | */ |
| 115 : | tim | 1.1 | public interface Queue<E> extends Collection<E> { |
| 116 : | /** | ||
| 117 : | jsr166 | 1.29 | * 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 per the spec for {@link Collection#add}) | ||
| 124 : | * @throws IllegalStateException if the element cannot be added at this | ||
| 125 : | * time due to capacity restrictions | ||
| 126 : | jsr166 | 1.30 | * @throws ClassCastException if the class of the specified element |
| 127 : | * prevents it from being added to this queue | ||
| 128 : | jsr166 | 1.29 | * @throws NullPointerException if the specified element is null and |
| 129 : | * this queue not permit null elements | ||
| 130 : | * @throws IllegalArgumentException if some property of this element | ||
| 131 : | * prevents it from being added to this queue | ||
| 132 : | tim | 1.2 | */ |
| 133 : | jsr166 | 1.29 | boolean add(E e); |
| 134 : | tim | 1.1 | |
| 135 : | /** | ||
| 136 : | jsr166 | 1.29 | * 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 deque, this method is generally | ||
| 139 : | * preferable to {@link #add}, which can fail to insert an element only | ||
| 140 : | * by throwing an exception. | ||
| 141 : | tim | 1.2 | * |
| 142 : | jsr166 | 1.29 | * @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 : | jsr166 | 1.30 | * @throws ClassCastException if the class of the specified element |
| 146 : | * prevents it from being added to this queue | ||
| 147 : | jsr166 | 1.29 | * @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 : | tim | 1.2 | */ |
| 152 : | jsr166 | 1.29 | boolean offer(E e); |
| 153 : | tim | 1.1 | |
| 154 : | /** | ||
| 155 : | jsr166 | 1.29 | * Retrieves and removes the head of this queue. This method differs |
| 156 : | * from {@link #poll} only in that it throws an exception if this queue | ||
| 157 : | * is empty. | ||
| 158 : | tim | 1.2 | * |
| 159 : | jsr166 | 1.29 | * @return the head of this queue |
| 160 : | * @throws NoSuchElementException if this queue is empty | ||
| 161 : | tim | 1.2 | */ |
| 162 : | tim | 1.9 | E remove(); |
| 163 : | tim | 1.1 | |
| 164 : | /** | ||
| 165 : | jsr166 | 1.29 | * Retrieves and removes the head of this queue, |
| 166 : | * or returns <tt>null</tt> if this queue is empty. | ||
| 167 : | tim | 1.2 | * |
| 168 : | jsr166 | 1.29 | * @return the head of this queue, or <tt>null</tt> if this queue is empty |
| 169 : | tim | 1.2 | */ |
| 170 : | jsr166 | 1.29 | E poll(); |
| 171 : | tim | 1.1 | |
| 172 : | /** | ||
| 173 : | dholmes | 1.14 | * Retrieves, but does not remove, the head of this queue. This method |
| 174 : | jsr166 | 1.29 | * differs from {@link #peek} only in that it throws an exception if |
| 175 : | * this queue is empty. | ||
| 176 : | tim | 1.2 | * |
| 177 : | jsr166 | 1.29 | * @return the head of this queue |
| 178 : | * @throws NoSuchElementException if this queue is empty | ||
| 179 : | tim | 1.2 | */ |
| 180 : | tim | 1.9 | E element(); |
| 181 : | jsr166 | 1.29 | |
| 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 : | tim | 1.1 | } |
| Doug Lea | ViewVC Help |
| Powered by ViewVC 1.0.8 |