Source Code Cross Referenced for BlockingQueue.java in  » Rule-Engine » drolls-Rule-Engine » org » drools » util » concurrent » locks » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Java Source Code / Java Documentation
1. 6.0 JDK Core
2. 6.0 JDK Modules
3. 6.0 JDK Modules com.sun
4. 6.0 JDK Modules com.sun.java
5. 6.0 JDK Modules sun
6. 6.0 JDK Platform
7. Ajax
8. Apache Harmony Java SE
9. Aspect oriented
10. Authentication Authorization
11. Blogger System
12. Build
13. Byte Code
14. Cache
15. Chart
16. Chat
17. Code Analyzer
18. Collaboration
19. Content Management System
20. Database Client
21. Database DBMS
22. Database JDBC Connection Pool
23. Database ORM
24. Development
25. EJB Server geronimo
26. EJB Server GlassFish
27. EJB Server JBoss 4.2.1
28. EJB Server resin 3.1.5
29. ERP CRM Financial
30. ESB
31. Forum
32. GIS
33. Graphic Library
34. Groupware
35. HTML Parser
36. IDE
37. IDE Eclipse
38. IDE Netbeans
39. Installer
40. Internationalization Localization
41. Inversion of Control
42. Issue Tracking
43. J2EE
44. JBoss
45. JMS
46. JMX
47. Library
48. Mail Clients
49. Net
50. Parser
51. PDF
52. Portal
53. Profiler
54. Project Management
55. Report
56. RSS RDF
57. Rule Engine
58. Science
59. Scripting
60. Search Engine
61. Security
62. Sevlet Container
63. Source Control
64. Swing Library
65. Template Engine
66. Test Coverage
67. Testing
68. UML
69. Web Crawler
70. Web Framework
71. Web Mail
72. Web Server
73. Web Services
74. Web Services apache cxf 2.0.1
75. Web Services AXIS2
76. Wiki Engine
77. Workflow Engines
78. XML
79. XML UI
Java
Java Tutorial
Java Open Source
Jar File Download
Java Articles
Java Products
Java by API
Photoshop Tutorials
Maya Tutorials
Flash Tutorials
3ds-Max Tutorials
Illustrator Tutorials
GIMP Tutorials
C# / C Sharp
C# / CSharp Tutorial
C# / CSharp Open Source
ASP.Net
ASP.NET Tutorial
JavaScript DHTML
JavaScript Tutorial
JavaScript Reference
HTML / CSS
HTML CSS Reference
C / ANSI-C
C Tutorial
C++
C++ Tutorial
Ruby
PHP
Python
Python Tutorial
Python Open Source
SQL Server / T-SQL
SQL Server / T-SQL Tutorial
Oracle PL / SQL
Oracle PL/SQL Tutorial
PostgreSQL
SQL / MySQL
MySQL Tutorial
VB.Net
VB.Net Tutorial
Flash / Flex / ActionScript
VBA / Excel / Access / Word
XML
XML Tutorial
Microsoft Office PowerPoint 2007 Tutorial
Microsoft Office Excel 2007 Tutorial
Microsoft Office Word 2007 Tutorial
Java Source Code / Java Documentation » Rule Engine » drolls Rule Engine » org.drools.util.concurrent.locks 
Source Cross Referenced  Class Diagram Java Document (Java Doc) 


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 {@link edu.emory.mathcs.backport.java.util.Queue} that additionally supports operations
013:         * that wait for the queue to become non-empty when retrieving an
014:         * element, and wait for space to become available in the queue when
015:         * storing an element.
016:         *
017:         * <p><tt>BlockingQueue</tt> methods come in four forms, with different ways
018:         * of handling operations that cannot be satisfied immediately, but may be
019:         * satisfied at some point in the future:
020:         * one throws an exception, the second returns a special value (either
021:         * <tt>null</tt> or <tt>false</tt>, depending on the operation), the third
022:         * blocks the current thread indefinitely until the operation can succeed,
023:         * and the fourth blocks for only a given maximum time limit before giving
024:         * up.  These methods are summarized in the following table:
025:         *
026:         * <p>
027:         * <table BORDER CELLPADDING=3 CELLSPACING=1>
028:         *  <tr>
029:         *    <td></td>
030:         *    <td ALIGN=CENTER><em>Throws exception</em></td>
031:         *    <td ALIGN=CENTER><em>Special value</em></td>
032:         *    <td ALIGN=CENTER><em>Blocks</em></td>
033:         *    <td ALIGN=CENTER><em>Times out</em></td>
034:         *  </tr>
035:         *  <tr>
036:         *    <td><b>Insert</b></td>
037:         *    <td>{@link #add add(e)}</td>
038:         *    <td>{@link #offer offer(e)}</td>
039:         *    <td>{@link #put put(e)}</td>
040:         *    <td>{@link #offer(Object, long, TimeUnit) offer(e, time, unit)}</td>
041:         *  </tr>
042:         *  <tr>
043:         *    <td><b>Remove</b></td>
044:         *    <td>{@link #remove remove()}</td>
045:         *    <td>{@link #poll poll()}</td>
046:         *    <td>{@link #take take()}</td>
047:         *    <td>{@link #poll(long, TimeUnit) poll(time, unit)}</td>
048:         *  </tr>
049:         *  <tr>
050:         *    <td><b>Examine</b></td>
051:         *    <td>{@link #element element()}</td>
052:         *    <td>{@link #peek peek()}</td>
053:         *    <td><em>not applicable</em></td>
054:         *    <td><em>not applicable</em></td>
055:         *  </tr>
056:         * </table>
057:         *
058:         * <p>A <tt>BlockingQueue</tt> does not accept <tt>null</tt> elements.
059:         * Implementations throw <tt>NullPointerException</tt> on attempts
060:         * to <tt>add</tt>, <tt>put</tt> or <tt>offer</tt> a <tt>null</tt>.  A
061:         * <tt>null</tt> is used as a sentinel value to indicate failure of
062:         * <tt>poll</tt> operations.
063:         *
064:         * <p>A <tt>BlockingQueue</tt> may be capacity bounded. At any given
065:         * time it may have a <tt>remainingCapacity</tt> beyond which no
066:         * additional elements can be <tt>put</tt> without blocking.
067:         * A <tt>BlockingQueue</tt> without any intrinsic capacity constraints always
068:         * reports a remaining capacity of <tt>Integer.MAX_VALUE</tt>.
069:         *
070:         * <p> <tt>BlockingQueue</tt> implementations are designed to be used
071:         * primarily for producer-consumer queues, but additionally support
072:         * the {@link java.util.Collection} interface.  So, for example, it is
073:         * possible to remove an arbitrary element from a queue using
074:         * <tt>remove(x)</tt>. However, such operations are in general
075:         * <em>not</em> performed very efficiently, and are intended for only
076:         * occasional use, such as when a queued message is cancelled.
077:         *
078:         * <p> <tt>BlockingQueue</tt> implementations are thread-safe.  All
079:         * queuing methods achieve their effects atomically using internal
080:         * locks or other forms of concurrency control. However, the
081:         * <em>bulk</em> Collection operations <tt>addAll</tt>,
082:         * <tt>containsAll</tt>, <tt>retainAll</tt> and <tt>removeAll</tt> are
083:         * <em>not</em> necessarily performed atomically unless specified
084:         * otherwise in an implementation. So it is possible, for example, for
085:         * <tt>addAll(c)</tt> to fail (throwing an exception) after adding
086:         * only some of the elements in <tt>c</tt>.
087:         *
088:         * <p>A <tt>BlockingQueue</tt> does <em>not</em> intrinsically support
089:         * any kind of &quot;close&quot; or &quot;shutdown&quot; operation to
090:         * indicate that no more items will be added.  The needs and usage of
091:         * such features tend to be implementation-dependent. For example, a
092:         * common tactic is for producers to insert special
093:         * <em>end-of-stream</em> or <em>poison</em> objects, that are
094:         * interpreted accordingly when taken by consumers.
095:         *
096:         * <p>
097:         * Usage example, based on a typical producer-consumer scenario.
098:         * Note that a <tt>BlockingQueue</tt> can safely be used with multiple
099:         * producers and multiple consumers.
100:         * <pre>
101:         * class Producer implements Runnable {
102:         *   private final BlockingQueue queue;
103:         *   Producer(BlockingQueue q) { queue = q; }
104:         *   public void run() {
105:         *     try {
106:         *       while (true) { queue.put(produce()); }
107:         *     } catch (InterruptedException ex) { ... handle ...}
108:         *   }
109:         *   Object produce() { ... }
110:         * }
111:         *
112:         * class Consumer implements Runnable {
113:         *   private final BlockingQueue queue;
114:         *   Consumer(BlockingQueue q) { queue = q; }
115:         *   public void run() {
116:         *     try {
117:         *       while (true) { consume(queue.take()); }
118:         *     } catch (InterruptedException ex) { ... handle ...}
119:         *   }
120:         *   void consume(Object x) { ... }
121:         * }
122:         *
123:         * class Setup {
124:         *   void main() {
125:         *     BlockingQueue q = new SomeQueueImplementation();
126:         *     Producer p = new Producer(q);
127:         *     Consumer c1 = new Consumer(q);
128:         *     Consumer c2 = new Consumer(q);
129:         *     new Thread(p).start();
130:         *     new Thread(c1).start();
131:         *     new Thread(c2).start();
132:         *   }
133:         * }
134:         * </pre>
135:         *
136:         * <p>Memory consistency effects: As with other concurrent
137:         * collections, actions in a thread prior to placing an object into a
138:         * {@code BlockingQueue}
139:         * <a href="package-summary.html#MemoryVisibility"><i>happen-before</i></a>
140:         * actions subsequent to the access or removal of that element from
141:         * the {@code BlockingQueue} in another thread.
142:         *
143:         * <p>This interface is a member of the
144:         * <a href="{@docRoot}/../technotes/guides/collections/index.html">
145:         * Java Collections Framework</a>.
146:         *
147:         * @since 1.5
148:         * @author Doug Lea
149:         */
150:        public interface BlockingQueue extends Queue {
151:            /**
152:             * Inserts the specified element into this queue if it is possible to do
153:             * so immediately without violating capacity restrictions, returning
154:             * <tt>true</tt> upon success and throwing an
155:             * <tt>IllegalStateException</tt> if no space is currently available.
156:             * When using a capacity-restricted queue, it is generally preferable to
157:             * use {@link #offer(Object) offer}.
158:             *
159:             * @param e the element to add
160:             * @return <tt>true</tt> (as specified by {@link java.util.Collection#add})
161:             * @throws IllegalStateException if the element cannot be added at this
162:             *         time due to capacity restrictions
163:             * @throws ClassCastException if the class of the specified element
164:             *         prevents it from being added to this queue
165:             * @throws NullPointerException if the specified element is null
166:             * @throws IllegalArgumentException if some property of the specified
167:             *         element prevents it from being added to this queue
168:             */
169:            boolean add(Object e);
170:
171:            /**
172:             * Inserts the specified element into this queue if it is possible to do
173:             * so immediately without violating capacity restrictions, returning
174:             * <tt>true</tt> upon success and <tt>false</tt> if no space is currently
175:             * available.  When using a capacity-restricted queue, this method is
176:             * generally preferable to {@link #add}, which can fail to insert an
177:             * element only by throwing an exception.
178:             *
179:             * @param e the element to add
180:             * @return <tt>true</tt> if the element was added to this queue, else
181:             *         <tt>false</tt>
182:             * @throws ClassCastException if the class of the specified element
183:             *         prevents it from being added to this queue
184:             * @throws NullPointerException if the specified element is null
185:             * @throws IllegalArgumentException if some property of the specified
186:             *         element prevents it from being added to this queue
187:             */
188:            boolean offer(Object e);
189:
190:            /**
191:             * Inserts the specified element into this queue, waiting if necessary
192:             * for space to become available.
193:             *
194:             * @param e the element to add
195:             * @throws InterruptedException if interrupted while waiting
196:             * @throws ClassCastException if the class of the specified element
197:             *         prevents it from being added to this queue
198:             * @throws NullPointerException if the specified element is null
199:             * @throws IllegalArgumentException if some property of the specified
200:             *         element prevents it from being added to this queue
201:             */
202:            void put(Object e) throws InterruptedException;
203:
204:            /**
205:             * Inserts the specified element into this queue, waiting up to the
206:             * specified wait time if necessary for space to become available.
207:             *
208:             * @param e the element to add
209:             * @param timeout how long to wait before giving up, in units of
210:             *        <tt>unit</tt>
211:             * @param unit a <tt>TimeUnit</tt> determining how to interpret the
212:             *        <tt>timeout</tt> parameter
213:             * @return <tt>true</tt> if successful, or <tt>false</tt> if
214:             *         the specified waiting time elapses before space is available
215:             * @throws InterruptedException if interrupted while waiting
216:             * @throws ClassCastException if the class of the specified element
217:             *         prevents it from being added to this queue
218:             * @throws NullPointerException if the specified element is null
219:             * @throws IllegalArgumentException if some property of the specified
220:             *         element prevents it from being added to this queue
221:             */
222:            boolean offer(Object e, long timeout, TimeUnit unit)
223:                    throws InterruptedException;
224:
225:            /**
226:             * Retrieves and removes the head of this queue, waiting if necessary
227:             * until an element becomes available.
228:             *
229:             * @return the head of this queue
230:             * @throws InterruptedException if interrupted while waiting
231:             */
232:            Object take() throws InterruptedException;
233:
234:            /**
235:             * Retrieves and removes the head of this queue, waiting up to the
236:             * specified wait time if necessary for an element to become available.
237:             *
238:             * @param timeout how long to wait before giving up, in units of
239:             *        <tt>unit</tt>
240:             * @param unit a <tt>TimeUnit</tt> determining how to interpret the
241:             *        <tt>timeout</tt> parameter
242:             * @return the head of this queue, or <tt>null</tt> if the
243:             *         specified waiting time elapses before an element is available
244:             * @throws InterruptedException if interrupted while waiting
245:             */
246:            Object poll(long timeout, TimeUnit unit)
247:                    throws InterruptedException;
248:
249:            /**
250:             * Returns the number of additional elements that this queue can ideally
251:             * (in the absence of memory or resource constraints) accept without
252:             * blocking, or <tt>Integer.MAX_VALUE</tt> if there is no intrinsic
253:             * limit.
254:             *
255:             * <p>Note that you <em>cannot</em> always tell if an attempt to insert
256:             * an element will succeed by inspecting <tt>remainingCapacity</tt>
257:             * because it may be the case that another thread is about to
258:             * insert or remove an element.
259:             *
260:             * @return the remaining capacity
261:             */
262:            int remainingCapacity();
263:
264:            /**
265:             * Removes a single instance of the specified element from this queue,
266:             * if it is present.  More formally, removes an element <tt>e</tt> such
267:             * that <tt>o.equals(e)</tt>, if this queue contains one or more such
268:             * elements.
269:             * Returns <tt>true</tt> if this queue contained the specified element
270:             * (or equivalently, if this queue changed as a result of the call).
271:             *
272:             * @param o element to be removed from this queue, if present
273:             * @return <tt>true</tt> if this queue changed as a result of the call
274:             * @throws ClassCastException if the class of the specified element
275:             *         is incompatible with this queue (optional)
276:             * @throws NullPointerException if the specified element is null (optional)
277:             */
278:            boolean remove(Object o);
279:
280:            /**
281:             * Returns <tt>true</tt> if this queue contains the specified element.
282:             * More formally, returns <tt>true</tt> if and only if this queue contains
283:             * at least one element <tt>e</tt> such that <tt>o.equals(e)</tt>.
284:             *
285:             * @param o object to be checked for containment in this queue
286:             * @return <tt>true</tt> if this queue contains the specified element
287:             * @throws ClassCastException if the class of the specified element
288:             *         is incompatible with this queue (optional)
289:             * @throws NullPointerException if the specified element is null (optional)
290:             */
291:            public boolean contains(Object o);
292:
293:            /**
294:             * Removes all available elements from this queue and adds them
295:             * to the given collection.  This operation may be more
296:             * efficient than repeatedly polling this queue.  A failure
297:             * encountered while attempting to add elements to
298:             * collection <tt>c</tt> may result in elements being in neither,
299:             * either or both collections when the associated exception is
300:             * thrown.  Attempts to drain a queue to itself result in
301:             * <tt>IllegalArgumentException</tt>. Further, the behavior of
302:             * this operation is undefined if the specified collection is
303:             * modified while the operation is in progress.
304:             *
305:             * @param c the collection to transfer elements into
306:             * @return the number of elements transferred
307:             * @throws UnsupportedOperationException if addition of elements
308:             *         is not supported by the specified collection
309:             * @throws ClassCastException if the class of an element of this queue
310:             *         prevents it from being added to the specified collection
311:             * @throws NullPointerException if the specified collection is null
312:             * @throws IllegalArgumentException if the specified collection is this
313:             *         queue, or some property of an element of this queue prevents
314:             *         it from being added to the specified collection
315:             */
316:            int drainTo(Collection c);
317:
318:            /**
319:             * Removes at most the given number of available elements from
320:             * this queue and adds them to the given collection.  A failure
321:             * encountered while attempting to add elements to
322:             * collection <tt>c</tt> may result in elements being in neither,
323:             * either or both collections when the associated exception is
324:             * thrown.  Attempts to drain a queue to itself result in
325:             * <tt>IllegalArgumentException</tt>. Further, the behavior of
326:             * this operation is undefined if the specified collection is
327:             * modified while the operation is in progress.
328:             *
329:             * @param c the collection to transfer elements into
330:             * @param maxElements the maximum number of elements to transfer
331:             * @return the number of elements transferred
332:             * @throws UnsupportedOperationException if addition of elements
333:             *         is not supported by the specified collection
334:             * @throws ClassCastException if the class of an element of this queue
335:             *         prevents it from being added to the specified collection
336:             * @throws NullPointerException if the specified collection is null
337:             * @throws IllegalArgumentException if the specified collection is this
338:             *         queue, or some property of an element of this queue prevents
339:             *         it from being added to the specified collection
340:             */
341:            int drainTo(Collection c, int maxElements);
342:        }
www.java2java.com | Contact Us
Copyright 2009 - 12 Demo Source and Support. All rights reserved.
All other trademarks are property of their respective owners.