/[cvs]/jsr166/src/main/java/util/Queue.java
ViewVC logotype

Contents of /jsr166/src/main/java/util/Queue.java

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.17 - (show annotations)
Fri Sep 12 15:38:26 2003 UTC (15 years, 11 months ago) by dl
Branch: MAIN
Changes since 1.16: +20 -23 lines
AbstractQueue revisions for sake of producing better javadoc

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 java.util;
8
9 /**
10 * A collection designed for holding elements prior to processing.
11 * Besides basic {@link java.util.Collection Collection} operations, queues provide
12 * additional insertion, extraction, and inspection operations.
13 *
14 * <p>Queues typically, but do not necessarily, order elements in a
15 * FIFO (first-in-first-out) manner. Among the exceptions are
16 * priority queues, which order elements according to a supplied
17 * comparator, or the elements' natural ordering, and LIFO queues (or
18 * stacks) which order the elements LIFO (last-in-first-out).
19 * Whatever the ordering used, the <em>head</em> of the queue is that
20 * element which would be removed by a call to {@link #remove() } or
21 * {@link #poll()}. In a FIFO queue, all new elements are inserted at
22 * the <em> tail</em> of the queue. Other kinds of queues may use
23 * different placement rules. Every <tt>Queue</tt> implementation
24 * must specify its ordering properties.
25 *
26 * <p>The {@link #offer offer} method inserts an element if possible,
27 * otherwise returning <tt>false</tt>. This differs from the {@link
28 * java.util.Collection#add Collection.add} method, which can fail to
29 * add an element only by throwing an unchecked exception. The
30 * <tt>offer</tt> method is designed for use when failure is a normal,
31 * rather than exceptional occurrence, for example, in fixed-capacity
32 * (or &quot;bounded&quot;) queues.
33 *
34 * <p>The {@link #remove()} and {@link #poll()} methods remove and
35 * return the head of the queue.
36 * Exactly which element is removed from the queue is a
37 * function of the queue's ordering policy, which differs from
38 * implementation to implementation. The <tt>remove()</tt> and
39 * <tt>poll()</tt> methods differ only in their behavior when the
40 * queue is empty: the <tt>remove()</tt> method throws an exception,
41 * while the <tt>poll()</tt> method returns <tt>null</tt>.
42 *
43 * <p>The {@link #element()} and {@link #peek()} methods return, but do
44 * not remove, the head of the queue.
45 *
46 * <p>The <tt>Queue</tt> interface does not define the <i>blocking queue
47 * methods</i>, which are common in concurrent programming. These methods,
48 * which wait for elements to appear or for space to become available, are
49 * defined in the {@link java.util.concurrent.BlockingQueue} interface, which
50 * extends this interface.
51 *
52 * <p><tt>Queue</tt> implementations generally do not allow insertion
53 * of <tt>null</tt> elements, although some implementations, such as
54 * {@link LinkedList}, do not prohibit insertion of <tt>null</tt>.
55 * Even in the implementations that permit it, <tt>null</tt> should
56 * not be inserted into a <tt>Queue</tt>, as <tt>null</tt> is also
57 * used as a special return value by the <tt>poll</tt> method to
58 * indicate that the queue contains no elements.
59 *
60 * <p><tt>Queue</tt> implementations generally do not define
61 * element-based versions of methods <tt>equals</tt> and
62 * <tt>hashCode</tt> but instead inherit the identity based versions
63 * from class <tt>Object</tt>, because element-based equality is not
64 * always well-defined for queues with the same elements but different
65 * ordering properties.
66 *
67 *
68 * <p>This interface is a member of the
69 * <a href="{@docRoot}/../guide/collections/index.html">
70 * Java Collections Framework</a>.
71 *
72 * @see java.util.Collection
73 * @see LinkedList
74 * @see PriorityQueue
75 * @see java.util.concurrent.LinkedBlockingQueue
76 * @see java.util.concurrent.BlockingQueue
77 * @see java.util.concurrent.ArrayBlockingQueue
78 * @see java.util.concurrent.LinkedBlockingQueue
79 * @see java.util.concurrent.PriorityBlockingQueue
80 * @since 1.5
81 * @author Doug Lea
82 */
83 public interface Queue<E> extends Collection<E> {
84
85 /**
86 * Inserts the specified element to this queue, if possible. When
87 * using queues that may impose insertion restrictions (for
88 * example capacity bounds), method <tt>offer</tt> is generally
89 * preferable to method {@link Collection#add}, which can fail to
90 * insert an element only by throwing an exception.
91 *
92 * @param o the element to insert.
93 * @return <tt>true</tt> if it was possible to add the element to
94 * this queue, else <tt>false</tt>
95 */
96 boolean offer(E o);
97
98 /**
99 * Retrieves and removes the head of this queue, if it is available.
100 *
101 * @return the head of this queue, or <tt>null</tt> if this
102 * queue is empty.
103 */
104 E poll();
105
106 /**
107 * Retrieves and removes the head of this queue.
108 * This method differs
109 * from the <tt>poll</tt> method in that it throws an exception if this
110 * queue is empty.
111 *
112 * @return the head of this queue.
113 * @throws NoSuchElementException if this queue is empty.
114 */
115 E remove();
116
117 /**
118 * Retrieves, but does not remove, the head of this queue.
119 * This method differs from the <tt>poll</tt>
120 * method only in that this method does not remove the head element from
121 * this queue.
122 *
123 * @return the head of this queue, or <tt>null</tt> if this queue is empty.
124 */
125 E peek();
126
127 /**
128 * Retrieves, but does not remove, the head of this queue. This method
129 * differs from the <tt>peek</tt> method only in that it throws an
130 * exception if this queue is empty.
131 *
132 * @return the head of this queue.
133 * @throws NoSuchElementException if this queue is empty.
134 */
135 E element();
136 }

dl@cs.oswego.edu
ViewVC Help
Powered by ViewVC 1.1.27