[cvs] / jsr166 / src / main / java / util / Queue.java Repository:
ViewVC logotype

Annotation of /jsr166/src/main/java/util/Queue.java

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.1 - (view) (download)

1 : tim 1.1 package java.util;
2 :    
3 :     /**
4 :     * Queues are Collections supporting additional basic insertion,
5 :     * extraction, and inspection operations.
6 :     *
7 :     * <p> Queues typically, but do not necessarily order elements in a
8 :     * FIFO (first-in-first-out) manner. Among the exceptions are priority
9 :     * queues, that order elements in accord with supplied
10 :     * Comparators. Every Queue implementation must specify its ordering
11 :     * guarantees,
12 :     *
13 :     * <p> The <tt>offer</tt> method adds an element if possible,
14 :     * otherwise returning <tt>false</tt>. This differs from the
15 :     * Collections.add method, that throws an unchecked exception upon
16 :     * failure. It is designed for use in collections in which failure to
17 :     * add is a normal, rather than exceptional occurrence, for example,
18 :     * in fixed-capacity queues.
19 :     *
20 :     * <p> The <tt>remove</tt> and <tt>poll</tt> methods delete and return
21 :     * an element in accord with the implementation's ordering policies --
22 :     * for example, in FIFO queues, it will return the oldest element.
23 :     * The <tt>remove</tt> and <tt>poll</tt> differ only in their behavior
24 :     * when the queue is empty: <tt>poll</tt> returns <tt>null</tt> while
25 :     * <tt>remove</tt> throws an exception. These are designed for usage
26 :     * contexts in which emptiness is considered to be normal versus
27 :     * exceptional.
28 :     *
29 :     * <p> The <tt>element</tt> and <tt>peek</tt> methods return but do
30 :     * not delete the element that would be obtained by a call to
31 :     * <tt>remove</tt> and <tt>poll</tt> respectively.
32 :     *
33 :     * <p> The Queue interface does not define blocking queue methods
34 :     * (i.e., those that wait for elements to appear and/or for space to
35 :     * be available) that are common in concurrent programming. These are
36 :     * defined in the extended java.util.concurrent.BlockingQueue
37 :     * interface.
38 :     *
39 :     * <p> Queue implementations generally do not allow insertion of
40 :     * <tt>null</tt>. Even in those that allow it, it is a very bad idea
41 :     * to do so, since <tt>null</tt> is also used as a sentinel by
42 :     * <tt>poll</tt> to indicate that no elements exist.
43 :     **/
44 :     public interface Queue<E> extends Collection<E> {
45 :    
46 :     /**
47 :     * Add the given object to this queue if possible.
48 :     * @param x the object to add
49 :     * @return true if successful
50 :     **/
51 :     public boolean offer(E x);
52 :    
53 :     /**
54 :     * Delete and return an object from the queue if one is available.
55 :     * @return the object, or null if the queue is empty.
56 :     **/
57 :     public E poll();
58 :    
59 :     /**
60 :     * Delete and return the element produced by poll, if the queue is
61 :     * not empty.
62 :     * @return an element
63 :     * @throws NoSuchElementException if empty
64 :     **/
65 :     public E remove() throws NoSuchElementException;
66 :    
67 :     /**
68 :     * Return but do not delete the element that will be returned by
69 :     * the next call to poll.
70 :     * @return an element, or null if empty
71 :     **/
72 :     public E peek();
73 :    
74 :     /**
75 :     * Return but do not delete the element that will be returned by
76 :     * the next call to poll, if the queue is not empty.
77 :     * @return an element
78 :     * @throws NoSuchElementException if empty
79 :     **/
80 :     public E element() throws NoSuchElementException;
81 :     }

Doug Lea
ViewVC Help
Powered by ViewVC 1.0.8