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