ViewVC Help

View File | Revision Log | Show Annotations | Download File | Root Listing

root/jsr166/jsr166/src/main/java/util/Queue.java

Comparing jsr166/src/main/java/util/Queue.java (file contents):
Revision 1.12 by tim, Fri Aug 1 19:34:05 2003 UTC vs.
Revision 1.19 by dl, Mon Sep 15 12:02:23 2003 UTC

#	Line 16 | Line 16 | package java.util;
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 element
20	<	* which would be removed by a call to {@link #remove() } or {@link #poll()}.
21	<	* Every <tt>Queue</tt> implementation must specify its ordering guarantees.
22	<	*
23	<	* <p>The {@link #offer offer(E)} method adds an element if possible, otherwise
24	<	* returning <tt>false</tt>.  This differs from the {@link java.util.Collection#add Collection.add(E)}
25	<	* method, which throws an unchecked exception upon
26	<	* failure. It is designed for use in collections in which failure to
27	<	* add is a normal, rather than exceptional occurrence, for example,
28	<	* in fixed-capacity (or &quot;bounded&quot;) queues.
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.
#	Line 53 | Line 57 | package java.util;
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>.
#	Line 60 | Line 72 | package java.util;
72		* @see java.util.Collection
73		* @see LinkedList
74		* @see PriorityQueue
75	<	* @see java.util.concurrent.LinkedQueue
75	>	* @see java.util.concurrent.LinkedBlockingQueue
76		* @see java.util.concurrent.BlockingQueue
77		* @see java.util.concurrent.ArrayBlockingQueue
78		* @see java.util.concurrent.LinkedBlockingQueue
#	Line 71 | Line 83 | package java.util;
83		public interface Queue<E> extends Collection<E> {
84
85		/**
86	<	* Add the specified element to this queue, if possible.
86	>	* Inserts the specified element into 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 add.
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	<	* Retrieve and remove the head of this queue, if it is available.
99	>	* Retrieves and removes the head of this queue, or <tt>null</tt>
100	>	* if this queue is empty.
101		*
102		* @return the head of this queue, or <tt>null</tt> if this
103		*         queue is empty.
#	Line 88 | Line 105 | public interface Queue<E> extends Collec
105		E poll();
106
107		/**
108	<	* Retrieve and remove the head of this queue.
109	<	* This method differs
110	<	* from the <tt>poll</tt> method in that it throws an exception if this
94	<	* queue is empty.
108	>	* Retrieves and removes the head of this queue.  This method
109	>	* differs from the <tt>poll</tt> method in that it throws an
110	>	* exception if this queue is empty.
111		*
112		* @return the head of this queue.
113		* @throws NoSuchElementException if this queue is empty.
#	Line 99 | Line 115 | public interface Queue<E> extends Collec
115		E remove();
116
117		/**
118	<	* Retrieve, but do not remove, the head of this queue.
119	<	* This method differs from the <tt>poll</tt>
104	<	* method only in that this method does not remove the head element from
105	<	* this queue.
118	>	* Retrieves, but does not remove, the head of this queue,
119	>	* returning <tt>null</tt> if this queue is empty.
120		*
121	<	* @return the head of this queue, or <tt>null</tt> if this queue is empty.
121	>	* @return the head of this queue, or <tt>null</tt> if this queue
122	>	* is empty.
123		*/
124		E peek();
125
126		/**
127	<	* Retrieve, but do not remove, the head of this queue.  This method
127	>	* Retrieves, but does not remove, the head of this queue.  This method
128		* differs from the <tt>peek</tt> method only in that it throws an
129		* exception if this queue is empty.
130		*
#	Line 118 | Line 133 | public interface Queue<E> extends Collec
133		*/
134		E element();
135		}
121	–
122	–
123	–
124	–
125	–
126	–
127	–
128	–
129	–
130	–

Diff Legend

–	Removed lines
+	Added lines
<	Changed lines
>	Changed lines