[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.6, Mon Jun 23 02:26:15 2003 UTC revision 1.7, Tue Jun 24 14:34:30 2003 UTC
# Line 25  Line 25 
25   * in fixed-capacity (or “bounded”) queues.   * in fixed-capacity (or “bounded”) queues.
26    
27   *   *
28   * <p>The {@link #remove()} and {@link #poll()} methods remove and return an   * <p>The {@link #remove()} and {@link #poll()} methods remove and
29   * element in accord with the implementation's ordering policy.   * return an element in accord with the implementation's ordering
30   * Exactly which element is removed from the queue is a function   * policy.  Exactly which element is removed from the queue is a
31   * of the queue's ordering policy, which differs from implementation   * function of the queue's ordering policy, which differs from
32   * to implementation.  Possible orderings include (but are not limited   * implementation to implementation.  Possible orderings include (but
33   * to) first-in-first-out (FIFO), last-in-first-out (LIFO), element priority, and arbitrary.   * are not limited to) first-in-first-out (FIFO), last-in-first-out
34   * The <tt>remove()</tt> and <tt>poll()</tt> methods differ only in their   * (LIFO), element priority, and arbitrary.  The <tt>remove()</tt> and
35   * behavior when the queue is empty: the <tt>remove()</tt> method throws an   * <tt>poll()</tt> methods differ only in their behavior when the
36   * exception, while the <tt>poll()</tt> method returns <tt>null</tt>.   * queue is empty: the <tt>remove()</tt> method throws an exception,
37     * while the <tt>poll()</tt> method returns <tt>null</tt>.
38   *   *
39   * <p>The {@link #element()} and {@link #peek()} methods return but do   * <p>The {@link #element()} and {@link #peek()} methods return but do
40   * not delete the element that would be obtained by a call to   * not delete the element that would be obtained by a call to
# Line 45  Line 46 
46   * defined in the {@link java.util.concurrent.BlockingQueue} interface, which   * defined in the {@link java.util.concurrent.BlockingQueue} interface, which
47   * extends this interface.   * extends this interface.
48   *   *
49   * <p><tt>Queue</tt> implementations generally do not allow insertion of   * <p><tt>Queue</tt> implementations generally do not allow insertion
50   * <tt>null</tt> elements, although some implementations, such as   * of <tt>null</tt> elements, although some implementations, such as
51   * {@link LinkedList}, do not prohibit insertion of <tt>null</tt>.   * {@link LinkedList}, do not prohibit insertion of <tt>null</tt>.
52   * Even in the implementations that permit it, <tt>null</tt> should not be inserted into   * Even in the implementations that permit it, <tt>null</tt> should
53   * a <tt>Queue</tt>, as <tt>null</tt> is also used as a special return value   * not be inserted into a <tt>Queue</tt>, as <tt>null</tt> is also
54   * by the <tt>poll</tt> method to indicate that the queue contains no   * used as a special return value by the <tt>poll</tt> method to
55   * elements.   * indicate that the queue contains no elements.
56   *   *
57   * <p>This interface is a member of the   * <p>This interface is a member of the
58   * <a href="{@docRoot}/../guide/collections/index.html">   * <a href="{@docRoot}/../guide/collections/index.html">
# Line 65  Line 66 
66   * @see java.util.concurrent.ArrayBlockingQueue   * @see java.util.concurrent.ArrayBlockingQueue
67   * @see java.util.concurrent.LinkedBlockingQueue   * @see java.util.concurrent.LinkedBlockingQueue
68   * @see java.util.concurrent.PriorityBlockingQueue   * @see java.util.concurrent.PriorityBlockingQueue
69     * @since 1.5
70     * @author Doug Lea
71   */   */
72  public interface Queue<E> extends Collection<E> {  public interface Queue<E> extends Collection<E> {
73      /**      /**
# Line 73  Line 76 
76       * @param element the element to add.       * @param element the element to add.
77       * @return true if it was possible to add the element to the queue.       * @return true if it was possible to add the element to the queue.
78       */       */
79      public boolean offer(E element);      boolean offer(E element);
80    
81      /**      /**
82       * Remove and return an element from the queue if one is available.       * Remove and return an element from the queue if one is available.
# Line 81  Line 84 
84       * @return an element previously on the queue, or <tt>null</tt> if the       * @return an element previously on the queue, or <tt>null</tt> if the
85       *         queue is empty.       *         queue is empty.
86       */       */
87      public E poll();      E poll();
88    
89      /**      /**
90       * Remove and return an element from the queue.  This method differs       * Remove and return an element from the queue.  This method differs
# Line 91  Line 94 
94       * @return an element previously on the queue.       * @return an element previously on the queue.
95       * @throws NoSuchElementException if the queue is empty.       * @throws NoSuchElementException if the queue is empty.
96       */       */
97      public E remove() throws NoSuchElementException;      E remove() throws NoSuchElementException;
98    
99      /**      /**
100       * Return, but do not remove, an element from the queue, or <tt>null</tt>       * Return, but do not remove, an element from the queue, or <tt>null</tt>
# Line 101  Line 104 
104       *       *
105       * @return an element on the queue, or <tt>null</tt> if the queue is empty.       * @return an element on the queue, or <tt>null</tt> if the queue is empty.
106       */       */
107      public E peek();      E peek();
108    
109      /**      /**
110       * Return, but do not remove, an element from the queue.  This method       * Return, but do not remove, an element from the queue.  This method
# Line 111  Line 114 
114       * @return an element on the queue.       * @return an element on the queue.
115       * @throws NoSuchElementException if the queue is empty.       * @throws NoSuchElementException if the queue is empty.
116       */       */
117      public E element() throws NoSuchElementException;      E element() throws NoSuchElementException;
118  }  }

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

Doug Lea
ViewVC Help
Powered by ViewVC 1.0.8