[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.16, Sat Aug 30 11:40:04 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 54  Line 54 
54   * used as a special return value by the <tt>poll</tt> method to   * used as a special return value by the <tt>poll</tt> method to
55   * indicate that the queue contains no elements.   * indicate that the queue contains no elements.
56   *   *
57     * <p><tt>Queue</tt> implementations generally do not define
58     * element-based versions of methods <tt>equals</tt> and
59     * <tt>hashCode</tt> but instead inherit the identity based versions
60     * from class <tt>Object</tt>, because element-based equality is not
61     * always well-defined for queues with the same elements but different
62     * ordering properties.
63     *
64     *
65   * <p>This interface is a member of the   * <p>This interface is a member of the
66   * <a href="{@docRoot}/../guide/collections/index.html">   * <a href="{@docRoot}/../guide/collections/index.html">
67   * Java Collections Framework</a>.   * Java Collections Framework</a>.
68   *   *
69   * @see Collection   * @see java.util.Collection
70   * @see LinkedList   * @see LinkedList
71   * @see PriorityQueue   * @see PriorityQueue
72   * @see java.util.concurrent.LinkedQueue   * @see java.util.concurrent.LinkedBlockingQueue
73   * @see java.util.concurrent.BlockingQueue   * @see java.util.concurrent.BlockingQueue
74   * @see java.util.concurrent.ArrayBlockingQueue   * @see java.util.concurrent.ArrayBlockingQueue
75   * @see java.util.concurrent.LinkedBlockingQueue   * @see java.util.concurrent.LinkedBlockingQueue
# Line 70  Line 78 
78   * @author Doug Lea   * @author Doug Lea
79   */   */
80  public interface Queue<E> extends Collection<E> {  public interface Queue<E> extends Collection<E> {
81    
82      /**      /**
83       * Add the specified element to this queue, if possible.       * Adds the specified element to this queue, if possible.
84       *       *
85       * @param element the element to add.       * @param o the element to add.
86       * @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
87         * this queue, else <tt>false</tt>
88       */       */
89      boolean offer(E element);      boolean offer(E o);
90    
91      /**      /**
92       * Remove and return an element from the queue if one is available.       * Retrieves and removes the head of this queue, if it is available.
93       *       *
94       * @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
95       *         queue is empty.       *         queue is empty.
96       */       */
97      E poll();      E poll();
98    
99      /**      /**
100       * Remove and return an element from the queue.  This method differs       * Retrieves and removes the head of this queue.
101       * from the <tt>poll</tt> method in that it throws an exception if the       * This method differs
102         * from the <tt>poll</tt> method in that it throws an exception if this
103       * queue is empty.       * queue is empty.
104       *       *
105       * @return an element previously on the queue.       * @return the head of this queue.
106       * @throws NoSuchElementException if the queue is empty.       * @throws NoSuchElementException if this queue is empty.
107       */       */
108      E remove() throws NoSuchElementException;      E remove();
109    
110      /**      /**
111       * Return, but do not remove, an element from the queue, or <tt>null</tt>       * Retrieves, but does not remove, the head of this queue.
112       * if the queue is empty.  This method returns the same object reference       * This method differs from the <tt>poll</tt>
113       * 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
114       * differ in that this method does not remove the element from the queue.       * this queue.
115       *       *
116       * @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.
117       */       */
118      E peek();      E peek();
119    
120      /**      /**
121       * Return, but do not remove, an element from the queue.  This method       * Retrieves, but does not remove, the head of this queue.  This method
122       * 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
123       * the queue is empty.       * exception if this queue is empty.
124       *       *
125       * @return an element on the queue.       * @return the head of this queue.
126       * @throws NoSuchElementException if the queue is empty.       * @throws NoSuchElementException if this queue is empty.
127       */       */
128      E element() throws NoSuchElementException;      E element();
129  }  }
130    
131    
132    
133    
134    
135    
136    
137    
138    
139    

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

Doug Lea
ViewVC Help
Powered by ViewVC 1.0.8