001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one
003: * or more contributor license agreements. See the NOTICE file
004: * distributed with this work for additional information
005: * regarding copyright ownership. The ASF licenses this file
006: * to you under the Apache License, Version 2.0 (the
007: * "License"); you may not use this file except in compliance
008: * with the License. You may obtain a copy of the License at
009: *
010: * http://www.apache.org/licenses/LICENSE-2.0
011: *
012: * Unless required by applicable law or agreed to in writing,
013: * software distributed under the License is distributed on an
014: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015: * KIND, either express or implied. See the License for the
016: * specific language governing permissions and limitations
017: * under the License.
018: */
019: /*
020: * Written by Doug Lea with assistance from members of JCP JSR-166
021: * Expert Group and released to the public domain, as explained at
022: * http://creativecommons.org/licenses/publicdomain
023: */
024: package org.apache.openjpa.lib.util.concurrent;
025:
026: import java.util.Collection;
027: import java.util.Iterator;
028: import java.util.NoSuchElementException;
029:
030: /**
031: * This class provides skeletal implementations of some {@link Queue}
032: * operations. The implementations in this class are appropriate when
033: * the base implementation does <em>not</em> allow <tt>null</tt>
034: * elements. Methods {@link #add add}, {@link #remove remove}, and
035: * {@link #element element} are based on {@link #offer offer}, {@link
036: * #poll poll}, and {@link #peek peek}, respectively but throw
037: * exceptions instead of indicating failure via <tt>false</tt> or
038: * <tt>null</tt> returns.
039: * A <tt>Queue</tt> implementation that extends this class must
040: * minimally define a method {@link Queue#offer} which does not permit
041: * insertion of <tt>null</tt> elements, along with methods {@link
042: * Queue#peek}, {@link Queue#poll}, {@link Collection#size}, and a
043: * {@link Collection#iterator} supporting {@link
044: * Iterator#remove}. Typically, additional methods will be overridden
045: * as well. If these requirements cannot be met, consider instead
046: * subclassing {@link AbstractCollection}. This class is a member of the
047: * <a href="{@docRoot}/../guide/collections/index.html">
048: * Java Collections Framework</a>.
049: *
050: * @author Doug Lea
051: * @since 1.5
052: */
053: abstract class AbstractQueue extends AbstractCollection implements
054: Queue {
055:
056: /**
057: * Constructor for use by subclasses.
058: */
059: protected AbstractQueue() {
060: }
061:
062: /**
063: * Inserts the specified element into this queue if it is possible to do so
064: * immediately without violating capacity restrictions, returning
065: * <tt>true</tt> upon success and throwing an <tt>IllegalStateException</tt>
066: * if no space is currently available.
067: * This implementation returns <tt>true</tt> if <tt>offer</tt> succeeds,
068: * else throws an <tt>IllegalStateException</tt>.
069: *
070: * @param e the element to add
071: * @return <tt>true</tt> (as specified by {@link Collection#add})
072: * @throws IllegalStateException if the element cannot be added at this
073: * time due to capacity restrictions
074: * @throws ClassCastException if the class of the specified element
075: * prevents it from being added to this queue
076: * @throws NullPointerException if the specified element is null and
077: * this queue not permit null elements
078: * @throws IllegalArgumentException if some property of this element
079: * prevents it from being added to this queue
080: */
081: public boolean add(Object e) {
082: if (offer(e))
083: return true;
084: else
085: throw new IllegalStateException("Queue full");
086: }
087:
088: /**
089: * Retrieves and removes the head of this queue. This method differs
090: * from {@link #poll poll} only in that it throws an exception if this
091: * queue is empty. This implementation returns the result of <tt>poll</tt>
092: * unless the queue is empty.
093: *
094: * @return the head of this queue
095: * @throws NoSuchElementException if this queue is empty
096: */
097: public Object remove() {
098: Object x = poll();
099: if (x != null)
100: return x;
101: else
102: throw new NoSuchElementException();
103: }
104:
105: /**
106: * Retrieves, but does not remove, the head of this queue. This method
107: * differs from {@link #peek peek} only in that it throws an exception if
108: * this queue is empty.
109: * This implementation returns the result of <tt>peek</tt>
110: * unless the queue is empty.
111: *
112: * @return the head of this queue
113: * @throws NoSuchElementException if this queue is empty
114: */
115: public Object element() {
116: Object x = peek();
117: if (x != null)
118: return x;
119: else
120: throw new NoSuchElementException();
121: }
122:
123: /**
124: * Removes all of the elements from this queue.
125: * The queue will be empty after this call returns.
126: * This implementation repeatedly invokes {@link #poll poll} until it
127: * returns <tt>null</tt>.
128: */
129: public void clear() {
130: while (poll() != null)
131: ;
132: }
133:
134: /**
135: * Adds all of the elements in the specified collection to this
136: * queue. Attempts to addAll of a queue to itself result in
137: * <tt>IllegalArgumentException</tt>. Further, the behavior of
138: * this operation is undefined if the specified collection is
139: * modified while the operation is in progress.
140: * This implementation iterates over the specified collection,
141: * and adds each element returned by the iterator to this
142: * queue, in turn. A runtime exception encountered while
143: * trying to add an element(including, in particular, a
144: * <tt>null</tt> element) may result in only some of the elements
145: * having been successfully added when the associated exception is thrown.
146: *
147: * @param c collection containing elements to be added to this queue
148: * @return <tt>true</tt> if this queue changed as a result of the call
149: * @throws ClassCastException if the class of an element of the specified
150: * collection prevents it from being added to this queue
151: * @throws NullPointerException if the specified collection contains a
152: * null element and this queue does not permit null elements,
153: * or if the specified collection is null
154: * @throws IllegalArgumentException if some property of an element of the
155: * specified collection prevents it from being added to this
156: * queue, or if the specified collection is this queue
157: * @throws IllegalStateException if not all the elements can be added at
158: * this time due to insertion restrictions
159: * @see #add(Object)
160: */
161: public boolean addAll(Collection c) {
162: if (c == null)
163: throw new NullPointerException();
164: if (c == this )
165: throw new IllegalArgumentException();
166: boolean modified = false;
167: Iterator e = c.iterator();
168: while (e.hasNext()) {
169: if (add(e.next()))
170: modified = true;
171: }
172: return modified;
173: }
174: }
|