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

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

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.7, Tue Jun 24 14:34:30 2003 UTC revision 1.15, Wed Aug 6 01:57:53 2003 UTC
# Line 7  Line 7 
7  package java.util;  package java.util;
8    
9  /**  /**
10   * A Collection designed for holding elements prior to processing.   * A collection designed for holding elements prior to processing.
11   * Besides basic {@link Collection} operations, queues provide   * Besides basic {@link java.util.Collection Collection} operations, queues provide
12   * additional insertion, extraction, and inspection operations.   * additional insertion, extraction, and inspection operations.
13  0 *   *
14   * <p>Queues typically, but do not necessarily, order elements in a   * <p>Queues typically, but do not necessarily, order elements in a
15   * FIFO (first-in-first-out) manner.  Among the exceptions are   * FIFO (first-in-first-out) manner.  Among the exceptions are
16   * priority queues, which order elements according to a supplied   * priority queues, which order elements according to a supplied
17   * comparator, or the elements' natural ordering.  Every Queue   * comparator, or the elements' natural ordering, and LIFO queues (or
18   * implementation must specify its ordering guarantees.   * 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   * <p>The {@link #offer(E)} method adds an element if possible, otherwise   * which would be removed by a call to {@link #remove() } or {@link #poll()}.
21   * returning <tt>false</tt>.  This differs from the {@link   * Every <tt>Queue</tt> implementation must specify its ordering guarantees.
22   * Collections#add(Object)} method, which throws an unchecked exception upon   *
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   * failure. It is designed for use in collections in which failure to
28   * add is a normal, rather than exceptional occurrence, for example,   * add is a normal, rather than exceptional occurrence, for example,
29   * in fixed-capacity (or &ldquo;bounded&rdquo;) queues.   * in fixed-capacity (or &quot;bounded&quot;) queues.
   
30   *   *
31   * <p>The {@link #remove()} and {@link #poll()} methods remove and   * <p>The {@link #remove()} and {@link #poll()} methods remove and
32   * return an element in accord with the implementation's ordering   * return the head of the queue.
33   * policy.  Exactly which element is removed from the queue is a   * Exactly which element is removed from the queue is a
34   * function of the queue's ordering policy, which differs from   * function of the queue's ordering policy, which differs from
35   * implementation to implementation.  Possible orderings include (but   * implementation to implementation. The <tt>remove()</tt> and
  * are not limited to) first-in-first-out (FIFO), last-in-first-out  
  * (LIFO), element priority, and arbitrary.  The <tt>remove()</tt> and  
36   * <tt>poll()</tt> methods differ only in their behavior when the   * <tt>poll()</tt> methods differ only in their behavior when the
37   * queue is empty: the <tt>remove()</tt> method throws an exception,   * queue is empty: the <tt>remove()</tt> method throws an exception,
38   * while the <tt>poll()</tt> method returns <tt>null</tt>.   * while the <tt>poll()</tt> method returns <tt>null</tt>.
39   *   *
40   * <p>The {@link #element()} and {@link #peek()} methods return but do   * <p>The {@link #element()} and {@link #peek()} methods return, but do
41   * not delete the element that would be obtained by a call to   * not remove, the head of the queue.
  * the <tt>remove</tt> and <tt>poll</tt> methods respectively.  
42   *   *
43   * <p>The <tt>Queue</tt> interface does not define the <i>blocking queue   * <p>The <tt>Queue</tt> interface does not define the <i>blocking queue
44   * methods</i>, which are common in concurrent programming.  These methods,   * methods</i>, which are common in concurrent programming.  These methods,
# Line 58  Line 58 
58   * <a href="{@docRoot}/../guide/collections/index.html">   * <a href="{@docRoot}/../guide/collections/index.html">
59   * Java Collections Framework</a>.   * Java Collections Framework</a>.
60   *   *
61   * @see Collection   * @see java.util.Collection
62   * @see LinkedList   * @see LinkedList
63   * @see PriorityQueue   * @see PriorityQueue
64   * @see java.util.concurrent.LinkedQueue   * @see java.util.concurrent.LinkedBlockingQueue
65   * @see java.util.concurrent.BlockingQueue   * @see java.util.concurrent.BlockingQueue
66   * @see java.util.concurrent.ArrayBlockingQueue   * @see java.util.concurrent.ArrayBlockingQueue
67   * @see java.util.concurrent.LinkedBlockingQueue   * @see java.util.concurrent.LinkedBlockingQueue
# Line 70  Line 70 
70   * @author Doug Lea   * @author Doug Lea
71   */   */
72  public interface Queue<E> extends Collection<E> {  public interface Queue<E> extends Collection<E> {
73    
74      /**      /**
75       * Add the specified element to this queue, if possible.       * Adds the specified element to this queue, if possible.
76       *       *
77       * @param element the element to add.       * @param o the element to add.
78       * @return true if it was possible to add the element to the queue.       * @return <tt>true</tt> if it was possible to add the element to
79         * this queue, else <tt>false</tt>
80       */       */
81      boolean offer(E element);      boolean offer(E o);
82    
83      /**      /**
84       * Remove and return an element from the queue if one is available.       * Retrieves and removes the head of this queue, if it is available.
85       *       *
86       * @return an element previously on the queue, or <tt>null</tt> if the       * @return the head of this queue, or <tt>null</tt> if this
87       *         queue is empty.       *         queue is empty.
88       */       */
89      E poll();      E poll();
90    
91      /**      /**
92       * Remove and return an element from the queue.  This method differs       * Retrieves and removes the head of this queue.
93       * from the <tt>poll</tt> method in that it throws an exception if the       * This method differs
94         * from the <tt>poll</tt> method in that it throws an exception if this
95       * queue is empty.       * queue is empty.
96       *       *
97       * @return an element previously on the queue.       * @return the head of this queue.
98       * @throws NoSuchElementException if the queue is empty.       * @throws NoSuchElementException if this queue is empty.
99       */       */
100      E remove() throws NoSuchElementException;      E remove();
101    
102      /**      /**
103       * Return, but do not remove, an element from the queue, or <tt>null</tt>       * Retrieves, but does not remove, the head of this queue.
104       * if the queue is empty.  This method returns the same object reference       * This method differs from the <tt>poll</tt>
105       * that would be returned by by the <tt>poll</tt> method.  The two methods       * method only in that this method does not remove the head element from
106       * differ in that this method does not remove the element from the queue.       * this queue.
107       *       *
108       * @return an element on the queue, or <tt>null</tt> if the queue is empty.       * @return the head of this queue, or <tt>null</tt> if this queue is empty.
109       */       */
110      E peek();      E peek();
111    
112      /**      /**
113       * Return, but do not remove, an element from the queue.  This method       * Retrieves, but does not remove, the head of this queue.  This method
114       * differs from the <tt>peek</tt> method in that it throws an exception if       * differs from the <tt>peek</tt> method only in that it throws an
115       * the queue is empty.       * exception if this queue is empty.
116       *       *
117       * @return an element on the queue.       * @return the head of this queue.
118       * @throws NoSuchElementException if the queue is empty.       * @throws NoSuchElementException if this queue is empty.
119       */       */
120      E element() throws NoSuchElementException;      E element();
121  }  }
122    
123    
124    
125    
126    
127    
128    
129    
130    
131    

Legend:
Removed from v.1.7  
changed lines
  Added in v.1.15

Doug Lea
ViewVC Help
Powered by ViewVC 1.0.8