[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.2, Sun May 18 18:10:02 2003 UTC revision 1.7, Tue Jun 24 14:34:30 2003 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. Use, modify, and
4     * redistribute this code in any way without acknowledgement.
5     */
6    
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 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 priority   * FIFO (first-in-first-out) manner.  Among the exceptions are
16   * queues, which order elements according to a supplied comparators, or   * priority queues, which order elements according to a supplied
17   * the elements natural ordering.  Every Queue implementation must specify   * comparator, or the elements' natural ordering.  Every Queue
18   * its ordering guarantees.   * implementation must specify its ordering guarantees.
19   *   *
20   * <p>The {@link #offer(E)} method adds an element if possible, otherwise   * <p>The {@link #offer(E)} method adds an element if possible, otherwise
21   * returning <tt>false</tt>.  This differs from the {@link   * returning <tt>false</tt>.  This differs from the {@link
# Line 17  Line 23 
23   * failure. It is designed for use in collections in which failure to   * failure. It is designed for use in collections in which failure to
24   * add is a normal, rather than exceptional occurrence, for example,   * add is a normal, rather than exceptional occurrence, for example,
25   * in fixed-capacity (or &ldquo;bounded&rdquo;) queues.   * in fixed-capacity (or &ldquo;bounded&rdquo;) 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. For example,   * return an element in accord with the implementation's ordering
30   * in FIFO queues, they remove and return the oldest element in the queue.   * policy.  Exactly which element is removed from the queue is a
31   * The <tt>remove()</tt> and <tt>poll()</tt> methods differ only in their   * function of the queue's ordering policy, which differs from
32   * behavior when the queue is empty: the <tt>remove()</tt> method throws an   * implementation to implementation.  Possible orderings include (but
33   * exception, while the <tt>poll()</tt> method returns <tt>null</tt>.   * are not limited to) first-in-first-out (FIFO), last-in-first-out
34     * (LIFO), element priority, and arbitrary.  The <tt>remove()</tt> and
35     * <tt>poll()</tt> methods differ only in their behavior when the
36     * 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 35  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.  Even in the few implementations that permit it,   * of <tt>null</tt> elements, although some implementations, such as
51   * it is a bad idea, as <tt>null</tt> is also used as a special return value   * {@link LinkedList}, do not prohibit insertion of <tt>null</tt>.
52   * by the <tt>poll</tt> method to indicate that the queue contains no   * Even in the implementations that permit it, <tt>null</tt> should
53   * elements.   * not be inserted into a <tt>Queue</tt>, as <tt>null</tt> is also
54     * used as a special return value by the <tt>poll</tt> method to
55     * 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 48  Line 61 
61   * @see Collection   * @see Collection
62   * @see LinkedList   * @see LinkedList
63   * @see PriorityQueue   * @see PriorityQueue
64   * @see LinkedQueue   * @see java.util.concurrent.LinkedQueue
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
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 61  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.
      * Exactly which element is removed from the queue is a function  
      * of the queue's ordering policy, which differs from implementation  
      * to implementation.  Possible orderings include (but are not limited  
      * to) first-in-first-out (FIFO), element priority, and arbitrary.  
83       *       *
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 83  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 93  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 103  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.2  
changed lines
  Added in v.1.7

Doug Lea
ViewVC Help
Powered by ViewVC 1.0.8