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.Iterator;
010: import java.util.Collection;
011: import java.util.NoSuchElementException;
012:
013: /**
014: * This class provides skeletal implementations of some {@link Queue}
015: * operations. The implementations in this class are appropriate when
016: * the base implementation does <em>not</em> allow <tt>null</tt>
017: * elements. Methods {@link #add add}, {@link #remove remove}, and
018: * {@link #element element} are based on {@link #offer offer}, {@link
019: * #poll poll}, and {@link #peek peek}, respectively but throw
020: * exceptions instead of indicating failure via <tt>false</tt> or
021: * <tt>null</tt> returns.
022: *
023: * <p> A <tt>Queue</tt> implementation that extends this class must
024: * minimally define a method {@link Queue#offer} which does not permit
025: * insertion of <tt>null</tt> elements, along with methods {@link
026: * Queue#peek}, {@link Queue#poll}, {@link Collection#size}, and a
027: * {@link Collection#iterator} supporting {@link
028: * Iterator#remove}. Typically, additional methods will be overridden
029: * as well. If these requirements cannot be met, consider instead
030: * subclassing {@link AbstractCollection}.
031: *
032: * <p>This class is a member of the
033: * <a href="{@docRoot}/../technotes/guides/collections/index.html">
034: * Java Collections Framework</a>.
035: *
036: * @since 1.5
037: * @author Doug Lea
038: */
039: public abstract class AbstractQueue extends AbstractCollection
040: implements Queue {
041:
042: /**
043: * Constructor for use by subclasses.
044: */
045: protected AbstractQueue() {
046: }
047:
048: /**
049: * Inserts the specified element into this queue if it is possible to do so
050: * immediately without violating capacity restrictions, returning
051: * <tt>true</tt> upon success and throwing an <tt>IllegalStateException</tt>
052: * if no space is currently available.
053: *
054: * <p>This implementation returns <tt>true</tt> if <tt>offer</tt> succeeds,
055: * else throws an <tt>IllegalStateException</tt>.
056: *
057: * @param e the element to add
058: * @return <tt>true</tt> (as specified by {@link Collection#add})
059: * @throws IllegalStateException if the element cannot be added at this
060: * time due to capacity restrictions
061: * @throws ClassCastException if the class of the specified element
062: * prevents it from being added to this queue
063: * @throws NullPointerException if the specified element is null and
064: * this queue does not permit null elements
065: * @throws IllegalArgumentException if some property of this element
066: * prevents it from being added to this queue
067: */
068: public boolean add(Object e) {
069: if (offer(e))
070: return true;
071: else
072: throw new IllegalStateException("Queue full");
073: }
074:
075: /**
076: * Retrieves and removes the head of this queue. This method differs
077: * from {@link #poll poll} only in that it throws an exception if this
078: * queue is empty.
079: *
080: * <p>This implementation returns the result of <tt>poll</tt>
081: * unless the queue is empty.
082: *
083: * @return the head of this queue
084: * @throws NoSuchElementException if this queue is empty
085: */
086: public Object remove() {
087: Object x = poll();
088: if (x != null)
089: return x;
090: else
091: throw new NoSuchElementException();
092: }
093:
094: /**
095: * Retrieves, but does not remove, the head of this queue. This method
096: * differs from {@link #peek peek} only in that it throws an exception if
097: * this queue is empty.
098: *
099: * <p>This implementation returns the result of <tt>peek</tt>
100: * unless the queue is empty.
101: *
102: * @return the head of this queue
103: * @throws NoSuchElementException if this queue is empty
104: */
105: public Object element() {
106: Object x = peek();
107: if (x != null)
108: return x;
109: else
110: throw new NoSuchElementException();
111: }
112:
113: /**
114: * Removes all of the elements from this queue.
115: * The queue will be empty after this call returns.
116: *
117: * <p>This implementation repeatedly invokes {@link #poll poll} until it
118: * returns <tt>null</tt>.
119: */
120: public void clear() {
121: while (poll() != null)
122: ;
123: }
124:
125: /**
126: * Adds all of the elements in the specified collection to this
127: * queue. Attempts to addAll of a queue to itself result in
128: * <tt>IllegalArgumentException</tt>. Further, the behavior of
129: * this operation is undefined if the specified collection is
130: * modified while the operation is in progress.
131: *
132: * <p>This implementation iterates over the specified collection,
133: * and adds each element returned by the iterator to this
134: * queue, in turn. A runtime exception encountered while
135: * trying to add an element (including, in particular, a
136: * <tt>null</tt> element) may result in only some of the elements
137: * having been successfully added when the associated exception is
138: * thrown.
139: *
140: * @param c collection containing elements to be added to this queue
141: * @return <tt>true</tt> if this queue changed as a result of the call
142: * @throws ClassCastException if the class of an element of the specified
143: * collection prevents it from being added to this queue
144: * @throws NullPointerException if the specified collection contains a
145: * null element and this queue does not permit null elements,
146: * or if the specified collection is null
147: * @throws IllegalArgumentException if some property of an element of the
148: * specified collection prevents it from being added to this
149: * queue, or if the specified collection is this queue
150: * @throws IllegalStateException if not all the elements can be added at
151: * this time due to insertion restrictions
152: * @see #add(Object)
153: */
154: public boolean addAll(Collection c) {
155: if (c == null)
156: throw new NullPointerException();
157: if (c == this )
158: throw new IllegalArgumentException();
159: boolean modified = false;
160: Iterator e = c.iterator();
161: while (e.hasNext()) {
162: if (add(e.next()))
163: modified = true;
164: }
165: return modified;
166: }
167:
168: }
|