001: /*
002: * Written by Doug Lea with assistance from members of JCP JSR-166
003: * Expert Group and released to the public domain, as explained at
004: * http://creativecommons.org/licenses/publicdomain
005: */
006:
007: package org.drools.util.concurrent.locks;
008:
009: import java.util.Collection;
010:
011: /**
012: * A collection designed for holding elements prior to processing.
013: * Besides basic {@link java.util.Collection Collection} operations,
014: * queues provide additional insertion, extraction, and inspection
015: * operations. Each of these methods exists in two forms: one throws
016: * an exception if the operation fails, the other returns a special
017: * value (either <tt>null</tt> or <tt>false</tt>, depending on the
018: * operation). The latter form of the insert operation is designed
019: * specifically for use with capacity-restricted <tt>Queue</tt>
020: * implementations; in most implementations, insert operations cannot
021: * fail.
022: *
023: * <p>
024: * <table BORDER CELLPADDING=3 CELLSPACING=1>
025: * <tr>
026: * <td></td>
027: * <td ALIGN=CENTER><em>Throws exception</em></td>
028: * <td ALIGN=CENTER><em>Returns special value</em></td>
029: * </tr>
030: * <tr>
031: * <td><b>Insert</b></td>
032: * <td>{@link #add add(e)}</td>
033: * <td>{@link #offer offer(e)}</td>
034: * </tr>
035: * <tr>
036: * <td><b>Remove</b></td>
037: * <td>{@link #remove remove()}</td>
038: * <td>{@link #poll poll()}</td>
039: * </tr>
040: * <tr>
041: * <td><b>Examine</b></td>
042: * <td>{@link #element element()}</td>
043: * <td>{@link #peek peek()}</td>
044: * </tr>
045: * </table>
046: *
047: * <p>Queues typically, but do not necessarily, order elements in a
048: * FIFO (first-in-first-out) manner. Among the exceptions are
049: * priority queues, which order elements according to a supplied
050: * comparator, or the elements' natural ordering, and LIFO queues (or
051: * stacks) which order the elements LIFO (last-in-first-out).
052: * Whatever the ordering used, the <em>head</em> of the queue is that
053: * element which would be removed by a call to {@link #remove() } or
054: * {@link #poll()}. In a FIFO queue, all new elements are inserted at
055: * the <em> tail</em> of the queue. Other kinds of queues may use
056: * different placement rules. Every <tt>Queue</tt> implementation
057: * must specify its ordering properties.
058: *
059: * <p>The {@link #offer offer} method inserts an element if possible,
060: * otherwise returning <tt>false</tt>. This differs from the {@link
061: * java.util.Collection#add Collection.add} method, which can fail to
062: * add an element only by throwing an unchecked exception. The
063: * <tt>offer</tt> method is designed for use when failure is a normal,
064: * rather than exceptional occurrence, for example, in fixed-capacity
065: * (or "bounded") queues.
066: *
067: * <p>The {@link #remove()} and {@link #poll()} methods remove and
068: * return the head of the queue.
069: * Exactly which element is removed from the queue is a
070: * function of the queue's ordering policy, which differs from
071: * implementation to implementation. The <tt>remove()</tt> and
072: * <tt>poll()</tt> methods differ only in their behavior when the
073: * queue is empty: the <tt>remove()</tt> method throws an exception,
074: * while the <tt>poll()</tt> method returns <tt>null</tt>.
075: *
076: * <p>The {@link #element()} and {@link #peek()} methods return, but do
077: * not remove, the head of the queue.
078: *
079: * <p>The <tt>Queue</tt> interface does not define the <i>blocking queue
080: * methods</i>, which are common in concurrent programming. These methods,
081: * which wait for elements to appear or for space to become available, are
082: * defined in the {@link edu.emory.mathcs.backport.java.util.concurrent.BlockingQueue} interface, which
083: * extends this interface.
084: *
085: * <p><tt>Queue</tt> implementations generally do not allow insertion
086: * of <tt>null</tt> elements, although some implementations, such as
087: * {@link LinkedList}, do not prohibit insertion of <tt>null</tt>.
088: * Even in the implementations that permit it, <tt>null</tt> should
089: * not be inserted into a <tt>Queue</tt>, as <tt>null</tt> is also
090: * used as a special return value by the <tt>poll</tt> method to
091: * indicate that the queue contains no elements.
092: *
093: * <p><tt>Queue</tt> implementations generally do not define
094: * element-based versions of methods <tt>equals</tt> and
095: * <tt>hashCode</tt> but instead inherit the identity based versions
096: * from class <tt>Object</tt>, because element-based equality is not
097: * always well-defined for queues with the same elements but different
098: * ordering properties.
099: *
100: *
101: * <p>This interface is a member of the
102: * <a href="{@docRoot}/../technotes/guides/collections/index.html">
103: * Java Collections Framework</a>.
104: *
105: * @see java.util.Collection
106: * @see LinkedList
107: * @see PriorityQueue
108: * @see edu.emory.mathcs.backport.java.util.concurrent.LinkedBlockingQueue
109: * @see edu.emory.mathcs.backport.java.util.concurrent.BlockingQueue
110: * @see edu.emory.mathcs.backport.java.util.concurrent.ArrayBlockingQueue
111: * @see edu.emory.mathcs.backport.java.util.concurrent.LinkedBlockingQueue
112: * @see edu.emory.mathcs.backport.java.util.concurrent.PriorityBlockingQueue
113: * @since 1.5
114: * @author Doug Lea
115: */
116: public interface Queue extends Collection {
117: /**
118: * Inserts the specified element into this queue if it is possible to do so
119: * immediately without violating capacity restrictions, returning
120: * <tt>true</tt> upon success and throwing an <tt>IllegalStateException</tt>
121: * if no space is currently available.
122: *
123: * @param e the element to add
124: * @return <tt>true</tt> (as specified by {@link Collection#add})
125: * @throws IllegalStateException if the element cannot be added at this
126: * time due to capacity restrictions
127: * @throws ClassCastException if the class of the specified element
128: * prevents it from being added to this queue
129: * @throws NullPointerException if the specified element is null and
130: * this queue not permit null elements
131: * @throws IllegalArgumentException if some property of this element
132: * prevents it from being added to this queue
133: */
134: boolean add(Object e);
135:
136: /**
137: * Inserts the specified element into this queue if it is possible to do
138: * so immediately without violating capacity restrictions.
139: * When using a capacity-restricted queue, this method is generally
140: * preferable to {@link #add}, which can fail to insert an element only
141: * by throwing an exception.
142: *
143: * @param e the element to add
144: * @return <tt>true</tt> if the element was added to this queue, else
145: * <tt>false</tt>
146: * @throws ClassCastException if the class of the specified element
147: * prevents it from being added to this queue
148: * @throws NullPointerException if the specified element is null and
149: * this queue does not permit null elements
150: * @throws IllegalArgumentException if some property of this element
151: * prevents it from being added to this queue
152: */
153: boolean offer(Object e);
154:
155: /**
156: * Retrieves and removes the head of this queue. This method differs
157: * from {@link #poll poll} only in that it throws an exception if this
158: * queue is empty.
159: * is empty.
160: *
161: * @return the head of this queue
162: * @throws NoSuchElementException if this queue is empty
163: */
164: Object remove();
165:
166: /**
167: * Retrieves and removes the head of this queue,
168: * or returns <tt>null</tt> if this queue is empty.
169: *
170: * @return the head of this queue, or <tt>null</tt> if this queue is empty
171: */
172: Object poll();
173:
174: /**
175: * Retrieves, but does not remove, the head of this queue. This method
176: * differs from {@link #peek peek} only in that it throws an exception
177: * if this queue is empty.
178: *
179: * @return the head of this queue
180: * @throws NoSuchElementException if this queue is empty
181: */
182: Object element();
183:
184: /**
185: * Retrieves, but does not remove, the head of this queue,
186: * or returns <tt>null</tt> if this queue is empty.
187: *
188: * @return the head of this queue, or <tt>null</tt> if this queue is empty
189: */
190: Object peek();
191: }
|