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