Source code: edu/emory/mathcs/util/Queue.java
1 /*
2 * Written by Doug Lea with assistance from members of JCP JSR-166
3 * Expert Group and released to the public domain. Use, modify, and
4 * redistribute this code in any way without acknowledgement.
5 */
6
7 package edu.emory.mathcs.util;
8
9 import java.util.*;
10
11 /**
12 * A Collection designed for holding elements prior to processing.
13 * Besides basic {@link Collection} operations, queues provide
14 * additional insertion, extraction, and inspection operations.
15 0 *
16 * <p>Queues typically, but do not necessarily, order elements in a
17 * FIFO (first-in-first-out) manner. Among the exceptions are
18 * priority queues, which order elements according to a supplied
19 * comparator, or the elements' natural ordering. Every Queue
20 * implementation must specify its ordering guarantees.
21 *
22 * <p>The {@link #offer(E)} method adds an element if possible, otherwise
23 * returning <tt>false</tt>. This differs from the {@link
24 * Collections#add(Object)} method, which throws an unchecked exception upon
25 * failure. It is designed for use in collections in which failure to
26 * add is a normal, rather than exceptional occurrence, for example,
27 * in fixed-capacity (or “bounded”) queues.
28
29 *
30 * <p>The {@link #remove()} and {@link #poll()} methods remove and
31 * return an element in accord with the implementation's ordering
32 * policy. Exactly which element is removed from the queue is a
33 * function of the queue's ordering policy, which differs from
34 * implementation to implementation. Possible orderings include (but
35 * are not limited to) first-in-first-out (FIFO), last-in-first-out
36 * (LIFO), element priority, and arbitrary. The <tt>remove()</tt> and
37 * <tt>poll()</tt> methods differ only in their behavior when the
38 * queue is empty: the <tt>remove()</tt> method throws an exception,
39 * while the <tt>poll()</tt> method returns <tt>null</tt>.
40 *
41 * <p>The {@link #element()} and {@link #peek()} methods return but do
42 * not delete the element that would be obtained by a call to
43 * the <tt>remove</tt> and <tt>poll</tt> methods respectively.
44 *
45 * <p>The <tt>Queue</tt> interface does not define the <i>blocking queue
46 * methods</i>, which are common in concurrent programming. These methods,
47 * which wait for elements to appear or for space to become available, are
48 * defined in the {@link java.util.concurrent.BlockingQueue} interface, which
49 * extends this interface.
50 *
51 * <p><tt>Queue</tt> implementations generally do not allow insertion
52 * of <tt>null</tt> elements, although some implementations, such as
53 * {@link LinkedList}, do not prohibit insertion of <tt>null</tt>.
54 * Even in the implementations that permit it, <tt>null</tt> should
55 * not be inserted into a <tt>Queue</tt>, as <tt>null</tt> is also
56 * used as a special return value by the <tt>poll</tt> method to
57 * indicate that the queue contains no elements.
58 *
59 * <p>This interface is a member of the
60 * <a href="{@docRoot}/../guide/collections/index.html">
61 * Java Collections Framework</a>.
62 *
63 * @see Collection
64 * @see LinkedList
65 * @see PriorityQueue
66 * @see java.util.concurrent.LinkedQueue
67 * @see java.util.concurrent.BlockingQueue
68 * @see java.util.concurrent.ArrayBlockingQueue
69 * @see java.util.concurrent.LinkedBlockingQueue
70 * @see java.util.concurrent.PriorityBlockingQueue
71 * @since 1.5
72 * @author Doug Lea
73 */
74 public interface Queue extends Collection {
75 /**
76 * Add the specified element to this queue, if possible.
77 *
78 * @param element the element to add.
79 * @return true if it was possible to add the element to the queue.
80 */
81 boolean offer(Object element);
82
83 /**
84 * Remove and return an element from the queue if one is available.
85 *
86 * @return an element previously on the queue, or <tt>null</tt> if the
87 * queue is empty.
88 */
89 Object poll();
90
91 /**
92 * Remove and return an element from the queue. This method differs
93 * from the <tt>poll</tt> method in that it throws an exception if the
94 * queue is empty.
95 *
96 * @return an element previously on the queue.
97 * @throws NoSuchElementException if the queue is empty.
98 */
99 Object remove() throws NoSuchElementException;
100
101 /**
102 * Return, but do not remove, an element from the queue, or <tt>null</tt>
103 * if the queue is empty. This method returns the same object reference
104 * that would be returned by by the <tt>poll</tt> method. The two methods
105 * differ in that this method does not remove the element from the queue.
106 *
107 * @return an element on the queue, or <tt>null</tt> if the queue is empty.
108 */
109 Object peek();
110
111 /**
112 * Return, but do not remove, an element from the queue. This method
113 * differs from the <tt>peek</tt> method in that it throws an exception if
114 * the queue is empty.
115 *
116 * @return an element on the queue.
117 * @throws NoSuchElementException if the queue is empty.
118 */
119 Object element() throws NoSuchElementException;
120 }