ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/main/java/util/Queue.java
(Generate patch)

Comparing jsr166/src/main/java/util/Queue.java (file contents):
Revision 1.26 by jsr166, Mon May 2 04:19:58 2005 UTC vs.
Revision 1.37 by jsr166, Sun Nov 18 19:33:08 2012 UTC

# Line 1 | Line 1
1   /*
2   * Written by Doug Lea with assistance from members of JCP JSR-166
3   * Expert Group and released to the public domain, as explained at
4 < * http://creativecommons.org/licenses/publicdomain
4 > * http://creativecommons.org/publicdomain/zero/1.0/
5   */
6  
7   package java.util;
# Line 18 | Line 18 | package java.util;
18   * implementations; in most implementations, insert operations cannot
19   * fail.
20   *
21 < * <p><table BORDER CELLPADDING=3 CELLSPACING=1>
21 > * <p>
22 > * <table BORDER CELLPADDING=3 CELLSPACING=1>
23   *  <tr>
24   *    <td></td>
25   *    <td ALIGN=CENTER><em>Throws exception</em></td>
# Line 49 | Line 50 | package java.util;
50   * Whatever the ordering used, the <em>head</em> of the queue is that
51   * element which would be removed by a call to {@link #remove() } or
52   * {@link #poll()}.  In a FIFO queue, all new elements are inserted at
53 < * the <em> tail</em> of the queue. Other kinds of queues may use
53 > * the <em>tail</em> of the queue. Other kinds of queues may use
54   * different placement rules.  Every <tt>Queue</tt> implementation
55   * must specify its ordering properties.
56   *
# Line 96 | Line 97 | package java.util;
97   *
98   *
99   * <p>This interface is a member of the
100 < * <a href="{@docRoot}/../guide/collections/index.html">
100 > * <a href="{@docRoot}/../technotes/guides/collections/index.html">
101   * Java Collections Framework</a>.
102   *
103   * @see java.util.Collection
# Line 112 | Line 113 | package java.util;
113   * @param <E> the type of elements held in this collection
114   */
115   public interface Queue<E> extends Collection<E> {
115 –
116      /**
117 <     * Inserts the specified element into this queue, if possible.  When
118 <     * using queues that may impose insertion restrictions (for
119 <     * example capacity bounds), method <tt>offer</tt> is generally
120 <     * preferable to method {@link Collection#add}, which can fail to
121 <     * insert an element only by throwing an exception.
117 >     * Inserts the specified element into this queue if it is possible to do so
118 >     * immediately without violating capacity restrictions, returning
119 >     * <tt>true</tt> upon success and throwing an <tt>IllegalStateException</tt>
120 >     * if no space is currently available.
121       *
122 <     * @param o the element to insert.
123 <     * @return <tt>true</tt> if it was possible to add the element to
124 <     * this queue, else <tt>false</tt>
122 >     * @param e the element to add
123 >     * @return <tt>true</tt> (as specified by {@link Collection#add})
124 >     * @throws IllegalStateException if the element cannot be added at this
125 >     *         time due to capacity restrictions
126 >     * @throws ClassCastException if the class of the specified element
127 >     *         prevents it from being added to this queue
128 >     * @throws NullPointerException if the specified element is null and
129 >     *         this queue does not permit null elements
130 >     * @throws IllegalArgumentException if some property of this element
131 >     *         prevents it from being added to this queue
132       */
133 <    boolean offer(E o);
133 >    boolean add(E e);
134  
135      /**
136 <     * Retrieves and removes the head of this queue, or <tt>null</tt>
137 <     * if this queue is empty.
136 >     * Inserts the specified element into this queue if it is possible to do
137 >     * so immediately without violating capacity restrictions.
138 >     * When using a capacity-restricted queue, this method is generally
139 >     * preferable to {@link #add}, which can fail to insert an element only
140 >     * by throwing an exception.
141       *
142 <     * @return the head of this queue, or <tt>null</tt> if this
143 <     *         queue is empty.
142 >     * @param e the element to add
143 >     * @return <tt>true</tt> if the element was added to this queue, else
144 >     *         <tt>false</tt>
145 >     * @throws ClassCastException if the class of the specified element
146 >     *         prevents it from being added to this queue
147 >     * @throws NullPointerException if the specified element is null and
148 >     *         this queue does not permit null elements
149 >     * @throws IllegalArgumentException if some property of this element
150 >     *         prevents it from being added to this queue
151       */
152 <    E poll();
152 >    boolean offer(E e);
153  
154      /**
155 <     * Retrieves and removes the head of this queue.  This method
156 <     * differs from the {@link #poll} method only in that it throws an
157 <     * exception if this queue is empty.
155 >     * Retrieves and removes the head of this queue.  This method differs
156 >     * from {@link #poll poll} only in that it throws an exception if this
157 >     * queue is empty.
158       *
159 <     * @return the head of this queue.
160 <     * @throws NoSuchElementException if this queue is empty.
159 >     * @return the head of this queue
160 >     * @throws NoSuchElementException if this queue is empty
161       */
162      E remove();
163  
164      /**
165 <     * Retrieves, but does not remove, the head of this queue,
166 <     * returning <tt>null</tt> if this queue is empty.
165 >     * Retrieves and removes the head of this queue,
166 >     * or returns <tt>null</tt> if this queue is empty.
167       *
168 <     * @return the head of this queue, or <tt>null</tt> if this queue
153 <     * is empty.
168 >     * @return the head of this queue, or <tt>null</tt> if this queue is empty
169       */
170 <    E peek();
170 >    E poll();
171  
172      /**
173       * Retrieves, but does not remove, the head of this queue.  This method
174 <     * differs from the {@link #peek} method only in that it throws an
175 <     * exception if this queue is empty.
174 >     * differs from {@link #peek peek} only in that it throws an exception
175 >     * if this queue is empty.
176       *
177 <     * @return the head of this queue.
178 <     * @throws NoSuchElementException if this queue is empty.
177 >     * @return the head of this queue
178 >     * @throws NoSuchElementException if this queue is empty
179       */
180      E element();
181 +
182 +    /**
183 +     * Retrieves, but does not remove, the head of this queue,
184 +     * or returns <tt>null</tt> if this queue is empty.
185 +     *
186 +     * @return the head of this queue, or <tt>null</tt> if this queue is empty
187 +     */
188 +    E peek();
189   }

Diff Legend

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