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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.1 - (show annotations)
Wed May 14 21:30:45 2003 UTC (16 years, 3 months ago) by tim
Branch: MAIN
Moved main source rooted at . to ./src/main
Moved test source rooted at ./etc/testcases to ./src/test

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 }

dl@cs.oswego.edu
ViewVC Help
Powered by ViewVC 1.1.27