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.15 by dholmes, Wed Aug 6 01:57:53 2003 UTC vs.
Revision 1.21 by dl, Sun Oct 19 13:38:29 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} method adds an element if possible, otherwise
24	<	* returning <tt>false</tt>.  This differs from the
25	<	* {@link java.util.Collection#add Collection.add}
26	<	* method, which throws an unchecked exception upon
27	<	* failure. It is designed for use in collections in which failure to
28	<	* add is a normal, rather than exceptional occurrence, for example,
29	<	* 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 54 | 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 68 | Line 79 | package java.util;
79		* @see java.util.concurrent.PriorityBlockingQueue
80		* @since 1.5
81		* @author Doug Lea
82	+	* @param <E> the type of elements held in this collection
83		*/
84		public interface Queue<E> extends Collection<E> {
85
86		/**
87	<	* Adds the specified element to this queue, if possible.
87	>	* Inserts the specified element into this queue, if possible.  When
88	>	* using queues that may impose insertion restrictions (for
89	>	* example capacity bounds), method <tt>offer</tt> is generally
90	>	* preferable to method {@link Collection#add}, which can fail to
91	>	* insert an element only by throwing an exception.
92		*
93	<	* @param o the element to add.
93	>	* @param o the element to insert.
94		* @return <tt>true</tt> if it was possible to add the element to
95		* this queue, else <tt>false</tt>
96		*/
97		boolean offer(E o);
98
99		/**
100	<	* Retrieves and removes the head of this queue, if it is available.
100	>	* Retrieves and removes the head of this queue, or <tt>null</tt>
101	>	* if this queue is empty.
102		*
103		* @return the head of this queue, or <tt>null</tt> if this
104		*         queue is empty.
#	Line 89 | Line 106 | public interface Queue<E> extends Collec
106		E poll();
107
108		/**
109	<	* Retrieves and removes the head of this queue.
110	<	* This method differs
111	<	* from the <tt>poll</tt> method in that it throws an exception if this
95	<	* queue is empty.
109	>	* Retrieves and removes the head of this queue.  This method
110	>	* differs from the <tt>poll</tt> method in that it throws an
111	>	* exception if this queue is empty.
112		*
113		* @return the head of this queue.
114		* @throws NoSuchElementException if this queue is empty.
#	Line 100 | Line 116 | public interface Queue<E> extends Collec
116		E remove();
117
118		/**
119	<	* Retrieves, but does not remove, the head of this queue.
120	<	* This method differs from the <tt>poll</tt>
105	<	* method only in that this method does not remove the head element from
106	<	* this queue.
119	>	* Retrieves, but does not remove, the head of this queue,
120	>	* returning <tt>null</tt> if this queue is empty.
121		*
122	<	* @return the head of this queue, or <tt>null</tt> if this queue is empty.
122	>	* @return the head of this queue, or <tt>null</tt> if this queue
123	>	* is empty.
124		*/
125		E peek();
126
#	Line 119 | Line 134 | public interface Queue<E> extends Collec
134		*/
135		E element();
136		}
122	–
123	–
124	–
125	–
126	–
127	–
128	–
129	–
130	–
131	–

Diff Legend

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