KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > util > Queue


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