[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.17, Fri Sep 12 15:38:26 2003 UTC revision 1.23, Sun Nov 21 01:40:39 2004 UTC
# Line 1  Line 1 
1  /*  /*
2   * Written by Doug Lea with assistance from members of JCP JSR-166   * Written by Doug Lea with assistance from members of JCP JSR-166
3   * Expert Group and released to the public domain. Use, modify, and   * Expert Group and released to the public domain, as explained at
4   * redistribute this code in any way without acknowledgement.   * http://creativecommons.org/licenses/publicdomain
5   */   */
6    
7  package java.util;  package java.util;
# Line 9  Line 9 
9  /**  /**
10   * A collection designed for holding elements prior to processing.   * A collection designed for holding elements prior to processing.
11   * Besides basic {@link java.util.Collection 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. The names
13     * of the operations vary with their policies:
14     *
15     *<table BORDER CELLPADDING=3 CELLSPACING=1>
16     *  <tr>
17     *    <td><em>Operation</em></td>
18     *    <td ALIGN=CENTER><em>Attempt</em></td>
19     *    <td ALIGN=CENTER><em>Throw</em></td>
20     *  </tr>
21     *  <tr>
22     *    <td><em>insert</em></td>
23     *    <td>offer(x)</td>
24     *    <td>add(x)</td>
25     *  </tr>
26     *  <tr>
27     *    <td><em>extract</em></td>
28     *    <td>poll()</td>
29     *    <td>remove()</td>
30     *  </tr>
31     *  <tr>
32     *    <td><em>inspect</em></td>
33     *    <td>peek()</td>
34     *    <td>element()</td>
35     *  </tr>
36     *</table>
37   *   *
38   * <p>Queues typically, but do not necessarily, order elements in a   * <p>Queues typically, but do not necessarily, order elements in a
39   * FIFO (first-in-first-out) manner.  Among the exceptions are   * FIFO (first-in-first-out) manner.  Among the exceptions are
# Line 79  Line 103 
103   * @see java.util.concurrent.PriorityBlockingQueue   * @see java.util.concurrent.PriorityBlockingQueue
104   * @since 1.5   * @since 1.5
105   * @author Doug Lea   * @author Doug Lea
106     * @param <E> the type of elements held in this collection
107   */   */
108  public interface Queue<E> extends Collection<E> {  public interface Queue<E> extends Collection<E> {
109    
110      /**      /**
111       * Inserts the specified element to this queue, if possible.  When       * Inserts the specified element into this queue, if possible.  When
112       * using queues that may impose insertion restrictions (for       * using queues that may impose insertion restrictions (for
113       * example capacity bounds), method <tt>offer</tt> is generally       * example capacity bounds), method <tt>offer</tt> is generally
114       * preferable to method {@link Collection#add}, which can fail to       * preferable to method {@link Collection#add}, which can fail to
# Line 96  Line 121 
121      boolean offer(E o);      boolean offer(E o);
122    
123      /**      /**
124       * Retrieves and removes the head of this queue, if it is available.       * Retrieves and removes the head of this queue, or <tt>null</tt>
125         * if this queue is empty.
126       *       *
127       * @return the head of this queue, or <tt>null</tt> if this       * @return the head of this queue, or <tt>null</tt> if this
128       *         queue is empty.       *         queue is empty.
# Line 104  Line 130 
130      E poll();      E poll();
131    
132      /**      /**
133       * Retrieves and removes the head of this queue.       * Retrieves and removes the head of this queue.  This method
134       * This method differs       * differs from the <tt>poll</tt> method in that it throws an
135       * from the <tt>poll</tt> method in that it throws an exception if this       * exception if this queue is empty.
      * queue is empty.  
136       *       *
137       * @return the head of this queue.       * @return the head of this queue.
138       * @throws NoSuchElementException if this queue is empty.       * @throws NoSuchElementException if this queue is empty.
# Line 115  Line 140 
140      E remove();      E remove();
141    
142      /**      /**
143       * Retrieves, but does not remove, the head of this queue.       * Retrieves, but does not remove, the head of this queue,
144       * This method differs from the <tt>poll</tt>       * returning <tt>null</tt> if this queue is empty.
      * method only in that this method does not remove the head element from  
      * this queue.  
145       *       *
146       * @return the head of this queue, or <tt>null</tt> if this queue is empty.       * @return the head of this queue, or <tt>null</tt> if this queue
147         * is empty.
148       */       */
149      E peek();      E peek();
150    

Legend:
Removed from v.1.17  
changed lines
  Added in v.1.23

Doug Lea
ViewVC Help
Powered by ViewVC 1.0.8