[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.1, Wed May 14 21:30:45 2003 UTC revision 1.2, Sun May 18 18:10:02 2003 UTC
# Line 1  Line 1 
1  package java.util;  package java.util;
2    
3  /**  /**
4   * Queues are Collections supporting additional basic insertion,   * A Collection designed for holding elements prior to processing.
5   * extraction, and inspection operations.   * Besides basic {@link Collection} operations, queues provide
6     * additional insertion, extraction, and inspection operations.
7   *   *
8   * <p> Queues typically, but do not necessarily order elements in a   * <p>Queues typically, but do not necessarily, order elements in a
9   * FIFO (first-in-first-out) manner. Among the exceptions are priority   * FIFO (first-in-first-out) manner. Among the exceptions are priority
10   * queues, that order elements in accord with supplied   * queues, which order elements according to a supplied comparators, or
11   * Comparators. Every Queue implementation must specify its ordering   * the elements natural ordering.  Every Queue implementation must specify
12   * guarantees,   * its ordering guarantees.
13   *   *
14   * <p> The <tt>offer</tt> method adds an element if possible,   * <p>The {@link #offer(E)} method adds an element if possible, otherwise
15   * otherwise returning <tt>false</tt>. This differs from the   * returning <tt>false</tt>.  This differs from the {@link
16   * Collections.add method, that throws an unchecked exception upon   * Collections#add(Object)} method, which throws an unchecked exception upon
17   * failure. It is designed for use in collections in which failure to   * failure. It is designed for use in collections in which failure to
18   * add is a normal, rather than exceptional occurrence, for example,   * add is a normal, rather than exceptional occurrence, for example,
19   * in fixed-capacity queues.   * in fixed-capacity (or &ldquo;bounded&rdquo;) queues.
20   *   *
21   * <p> The <tt>remove</tt> and <tt>poll</tt> methods delete and return   * <p>The {@link #remove()} and {@link #poll()} methods remove and return an
22   * an element in accord with the implementation's ordering policies --   * element in accord with the implementation's ordering policy. For example,
23   * for example, in FIFO queues, it will return the oldest element.   * in FIFO queues, they remove and return the oldest element in the queue.
24   * The <tt>remove</tt> and <tt>poll</tt> differ only in their behavior   * The <tt>remove()</tt> and <tt>poll()</tt> methods differ only in their
25   * when the queue is empty: <tt>poll</tt> returns <tt>null</tt> while   * behavior when the queue is empty: the <tt>remove()</tt> method throws an
26   * <tt>remove</tt> throws an exception. These are designed for usage   * exception, while the <tt>poll()</tt> method returns <tt>null</tt>.
  * contexts in which emptiness is considered to be normal versus  
  * exceptional.  
27   *   *
28   * <p> The <tt>element</tt> and <tt>peek</tt> methods return but do   * <p>The {@link #element()} and {@link #peek()} methods return but do
29   * not delete the element that would be obtained by a call to   * not delete the element that would be obtained by a call to
30   * <tt>remove</tt> and <tt>poll</tt> respectively.   * the <tt>remove</tt> and <tt>poll</tt> methods respectively.
31   *   *
32   * <p> The Queue interface does not define blocking queue methods   * <p>The <tt>Queue</tt> interface does not define the <i>blocking queue
33   * (i.e., those that wait for elements to appear and/or for space to   * methods</i>, which are common in concurrent programming.  These methods,
34   * be available) that are common in concurrent programming. These are   * which wait for elements to appear or for space to become available, are
35   * defined in the extended java.util.concurrent.BlockingQueue   * defined in the {@link java.util.concurrent.BlockingQueue} interface, which
36   * interface.   * extends this interface.
37   *   *
38   * <p> Queue implementations generally do not allow insertion of   * <p><tt>Queue</tt> implementations generally do not allow insertion of
39   * <tt>null</tt>. Even in those that allow it, it is a very bad idea   * <tt>null</tt> elements.  Even in the few implementations that permit it,
40   * to do so, since <tt>null</tt> is also used as a sentinel by   * it is a bad idea, as <tt>null</tt> is also used as a special return value
41   * <tt>poll</tt> to indicate that no elements exist.   * by the <tt>poll</tt> method to indicate that the queue contains no
42   **/   * elements.
43     *
44     * <p>This interface is a member of the
45     * <a href="{@docRoot}/../guide/collections/index.html">
46     * Java Collections Framework</a>.
47     *
48     * @see Collection
49     * @see LinkedList
50     * @see PriorityQueue
51     * @see LinkedQueue
52     * @see java.util.concurrent.BlockingQueue
53     * @see java.util.concurrent.ArrayBlockingQueue
54     * @see java.util.concurrent.LinkedBlockingQueue
55     * @see java.util.concurrent.PriorityBlockingQueue
56     */
57  public interface Queue<E> extends Collection<E> {  public interface Queue<E> extends Collection<E> {
   
     /**  
      * Add the given object to this queue if possible.  
      * @param x the object to add  
      * @return true if successful  
      **/  
     public boolean offer(E x);  
   
58      /**      /**
59       * Delete and return an object from the queue if one is available.       * Add the specified element to this queue, if possible.
60       * @return the object, or null if the queue is empty.       *
61       **/       * @param element the element to add.
62         * @return true if it was possible to add the element to the queue.
63         */
64        public boolean offer(E element);
65    
66        /**
67         * Remove and return an element from the queue if one is available.
68         * Exactly which element is removed from the queue is a function
69         * of the queue's ordering policy, which differs from implementation
70         * to implementation.  Possible orderings include (but are not limited
71         * to) first-in-first-out (FIFO), element priority, and arbitrary.
72         *
73         * @return an element previously on the queue, or <tt>null</tt> if the
74         *         queue is empty.
75         */
76      public E poll();      public E poll();
77    
78      /**      /**
79       * Delete and return the element produced by poll, if the queue is       * Remove and return an element from the queue.  This method differs
80       * not empty.       * from the <tt>poll</tt> method in that it throws an exception if the
81       * @return an element       * queue is empty.
82       * @throws NoSuchElementException if empty       *
83       **/       * @return an element previously on the queue.
84         * @throws NoSuchElementException if the queue is empty.
85         */
86      public E remove() throws NoSuchElementException;      public E remove() throws NoSuchElementException;
87    
88      /**      /**
89       * Return but do not delete the element that will be returned by       * Return, but do not remove, an element from the queue, or <tt>null</tt>
90       * the next call to poll.       * if the queue is empty.  This method returns the same object reference
91       * @return an element, or null if empty       * that would be returned by by the <tt>poll</tt> method.  The two methods
92       **/       * differ in that this method does not remove the element from the queue.
93         *
94         * @return an element on the queue, or <tt>null</tt> if the queue is empty.
95         */
96      public E peek();      public E peek();
97    
98      /**      /**
99       * Return but do not delete the element that will be returned by       * Return, but do not remove, an element from the queue.  This method
100       * the next call to poll, if the queue is not empty.       * differs from the <tt>peek</tt> method in that it throws an exception if
101       * @return an element       * the queue is empty.
102       * @throws NoSuchElementException if empty       *
103       **/       * @return an element on the queue.
104         * @throws NoSuchElementException if the queue is empty.
105         */
106      public E element() throws NoSuchElementException;      public E element() throws NoSuchElementException;
107  }  }

Legend:
Removed from v.1.1  
changed lines
  Added in v.1.2

Doug Lea
ViewVC Help
Powered by ViewVC 1.0.8