001: // $HeadURL: https://svn.wald.intevation.org/svn/deegree/base/trunk/src/org/deegree/framework/concurrent/Executor.java $
002: /*---------------- FILE HEADER ------------------------------------------
003:
004: This file is part of deegree.
005: Copyright (C) 2001-2008 by:
006: EXSE, Department of Geography, University of Bonn
007: http://www.giub.uni-bonn.de/deegree/
008: lat/lon GmbH
009: http://www.lat-lon.de
010:
011: This library is free software; you can redistribute it and/or
012: modify it under the terms of the GNU Lesser General Public
013: License as published by the Free Software Foundation; either
014: version 2.1 of the License, or (at your option) any later version.
015:
016: This library is distributed in the hope that it will be useful,
017: but WITHOUT ANY WARRANTY; without even the implied warranty of
018: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
019: Lesser General Public License for more details.
020:
021: You should have received a copy of the GNU Lesser General Public
022: License along with this library; if not, write to the Free Software
023: Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
024:
025: Contact:
026:
027: Andreas Poth
028: lat/lon GmbH
029: Aennchenstr. 19
030: 53177 Bonn
031: Germany
032: E-Mail: poth@lat-lon.de
033:
034: Prof. Dr. Klaus Greve
035: Department of Geography
036: University of Bonn
037: Meckenheimer Allee 166
038: 53115 Bonn
039: Germany
040: E-Mail: greve@giub.uni-bonn.de
041:
042: ---------------------------------------------------------------------------*/
043: package org.deegree.framework.concurrent;
044:
045: import java.util.ArrayList;
046: import java.util.List;
047: import java.util.concurrent.Callable;
048: import java.util.concurrent.CancellationException;
049: import java.util.concurrent.ExecutionException;
050: import java.util.concurrent.ExecutorService;
051: import java.util.concurrent.Executors;
052: import java.util.concurrent.Future;
053: import java.util.concurrent.TimeUnit;
054:
055: /**
056: * The <code>Executor</code> is deegree's central place to:
057: * <ul>
058: * <li>Perform a task asynchronously (in an independent thread) optionally with a maximum execution
059: * time.</li>
060: * <li>Perform a task synchronously with a maximum execution time.</li>
061: * <li>Perform several task synchronously (but in parallel threads) with a maximum execution time.</li>
062: * </ul>
063: * <p>
064: * The <code>Executor</code> class is realized as a singleton and uses a cached thread pool
065: * internally to minimize overhead for acquiring the necessary {@link Thread} instances and to
066: * manage the number of concurrent threads.
067: * </p>
068: *
069: * @author <a href="mailto:poth@lat-lon.de">Andreas Poth</a>
070: * @author <a href="mailto:schmitz@lat-lon.de">Andreas Schmitz</a>
071: * @author <a href="mailto:bezema@lat-lon.de">Rutger Bezema</a>
072: * @author <a href="mailto:schneider@lat-lon.de">Markus Schneider</a>
073: * @author last edited by: $Author: aschmitz $
074: *
075: * @version $Revision: 9861 $, $Date: 2008-02-01 06:04:34 -0800 (Fri, 01 Feb 2008) $
076: * @see java.util.concurrent.ExecutorService
077: * @see org.deegree.framework.concurrent.ExecutionFinishedListener
078: */
079: public class Executor {
080:
081: private static Executor exec;
082:
083: private ExecutorService execService;
084:
085: /**
086: * Private constructor required for singleton pattern.
087: */
088: private Executor() {
089: this .execService = Executors.newCachedThreadPool();
090: }
091:
092: /**
093: * Returns the only instance of this class (singleton pattern).
094: *
095: * @return the only instance of this class
096: */
097: public synchronized static Executor getInstance() {
098:
099: if (exec == null) {
100: exec = new Executor();
101: }
102: return exec;
103: }
104:
105: /**
106: * Performs a task asynchronously (in an independent thread) without any time limit.
107: *
108: * @param <T>
109: * type of return value
110: * @param task
111: * task to be performed (specified in the {@link Callable#call()} method)
112: * @param finishedListener
113: * notified when the method call finishes (succesfully or abnormally), may be null
114: */
115: public <T> void performAsynchronously(Callable<T> task,
116: ExecutionFinishedListener<T> finishedListener) {
117:
118: AsyncPerformer<T> runner = new AsyncPerformer<T>(task,
119: finishedListener);
120: this .execService.execute(runner);
121: }
122:
123: /**
124: * Performs a task asynchronously (in an independent thread) with a given time limit.
125: *
126: * @param <T>
127: * type of return value
128: * @param task
129: * task to be performed (specified in the {@link Callable#call()}} method)
130: * @param finishedListener
131: * notified when the method call finishes (succesfully or abnormally), may be null
132: * @param timeout
133: * maximum time allowed for execution in milliseconds
134: */
135: public <T> void performAsynchronously(Callable<T> task,
136: ExecutionFinishedListener<T> finishedListener, long timeout) {
137:
138: AsyncPerformer<T> runner = new AsyncPerformer<T>(task,
139: finishedListener, timeout);
140: this .execService.execute(runner);
141: }
142:
143: /**
144: * Performs a task synchronously with a given timeout.
145: *
146: * @param <T>
147: * type of return value
148: * @param task
149: * tasks to be performed (specified in the {@link Callable#call()} method)
150: * @param timeout
151: * maximum time allowed for execution in milliseconds
152: * @return result value of the called method
153: * @throws CancellationException
154: * if the execution time exceeds the specified timeout / thread has been cancelled
155: * @throws InterruptedException
156: * if interrupted while waiting, in which case unfinished tasks are cancelled
157: * @throws Throwable
158: * if the tasks throws an exception itself
159: */
160: public <T> T performSynchronously(Callable<T> task, long timeout)
161: throws CancellationException, InterruptedException,
162: Throwable {
163:
164: T result;
165: List<Callable<T>> tasks = new ArrayList<Callable<T>>(1);
166: tasks.add(task);
167:
168: try {
169: List<Future<T>> futures = this .execService.invokeAll(tasks,
170: timeout, TimeUnit.MILLISECONDS);
171: Future<T> future = futures.get(0);
172: result = future.get();
173: } catch (ExecutionException e) {
174: throw (e.getCause());
175: }
176: return result;
177: }
178:
179: /**
180: * Performs several tasks synchronously in parallel threads.
181: * <p>
182: * This method does not return before all tasks are finished (successfully or abnormally). For
183: * each given {@link Callable}, an independent thread is used. For each task, an
184: * {@link ExecutionFinishedEvent} is generated and returned.
185: * @param <T> the result type of the callables
186: *
187: * @param tasks
188: * tasks to be performed (specified in the {@link Callable#call()} methods)
189: * @return ExecutionFinishedEvents for all tasks
190: * @throws InterruptedException
191: * if the current thread was interrupted while waiting
192: */
193: public <T> List<ExecutionFinishedEvent<T>> performSynchronously(
194: List<Callable<T>> tasks) throws InterruptedException {
195:
196: List<ExecutionFinishedEvent<T>> results = new ArrayList<ExecutionFinishedEvent<T>>(
197: tasks.size());
198: List<Future<T>> futures = this .execService.invokeAll(tasks);
199:
200: for (int i = 0; i < tasks.size(); i++) {
201:
202: ExecutionFinishedEvent<T> finishedEvent = null;
203: Callable<T> task = tasks.get(i);
204: Future<T> future = futures.get(i);
205:
206: try {
207: T result = future.get();
208: finishedEvent = new ExecutionFinishedEvent<T>(task,
209: result);
210: } catch (ExecutionException e) {
211: finishedEvent = new ExecutionFinishedEvent<T>(e
212: .getCause(), task);
213: } catch (CancellationException e) {
214: finishedEvent = new ExecutionFinishedEvent<T>(e, task);
215: }
216: results.add(finishedEvent);
217: }
218: return results;
219: }
220:
221: /**
222: * Performs several tasks synchronously with a given timeout in parallel threads.
223: * <p>
224: * This method does not return before all tasks are finished (successfully or abnormally). For
225: * each given {@link Callable}, an independent thread is used. For each task, an
226: * {@link ExecutionFinishedEvent} is generated and returned.
227: * @param <T> the result type of the tasks
228: *
229: * @param tasks
230: * tasks to be performed (specified in the {@link Callable#call()} methods)
231: * @param timeout
232: * maximum time allowed for execution (in milliseconds)
233: * @return ExecutionFinishedEvents for all tasks
234: * @throws InterruptedException
235: * if the current thread was interrupted while waiting
236: */
237: public <T> List<ExecutionFinishedEvent<T>> performSynchronously(
238: List<Callable<T>> tasks, long timeout)
239: throws InterruptedException {
240:
241: List<ExecutionFinishedEvent<T>> results = new ArrayList<ExecutionFinishedEvent<T>>(
242: tasks.size());
243: List<Future<T>> futures = this .execService.invokeAll(tasks,
244: timeout, TimeUnit.MILLISECONDS);
245:
246: for (int i = 0; i < tasks.size(); i++) {
247:
248: ExecutionFinishedEvent<T> finishedEvent = null;
249: Callable<T> task = tasks.get(i);
250: Future<T> future = futures.get(i);
251:
252: try {
253: T result = future.get();
254: finishedEvent = new ExecutionFinishedEvent<T>(task,
255: result);
256: } catch (ExecutionException e) {
257: finishedEvent = new ExecutionFinishedEvent<T>(e
258: .getCause(), task);
259: } catch (CancellationException e) {
260: finishedEvent = new ExecutionFinishedEvent<T>(e, task);
261: }
262: results.add(finishedEvent);
263: }
264: return results;
265: }
266:
267: // ///////////////////////////////////////////////////////////////////////////
268: // inner classes //
269: // ///////////////////////////////////////////////////////////////////////////
270:
271: /**
272: * Inner class for performing task asynchronously.
273: *
274: * @author <a href="mailto:poth@lat-lon.de">Andreas Poth</a>
275: * @author <a href="mailto:schmitz@lat-lon.de">Andreas Schmitz</a>
276: * @author <a href="mailto:bezema@lat-lon.de">Rutger Bezema</a>
277: * @author <a href="mailto:schneider@lat-lon.de">Markus Schneider</a>
278: * @author last edited by: $Author: aschmitz $
279: * @version $Revision: 9861 $
280: */
281: private class AsyncPerformer<T> implements Runnable {
282:
283: private Callable<T> task;
284:
285: private ExecutionFinishedListener<T> finishedListener;
286:
287: private long timeout = -1;
288:
289: AsyncPerformer(Callable<T> task,
290: ExecutionFinishedListener<T> finishedListener) {
291: this .task = task;
292: this .finishedListener = finishedListener;
293: }
294:
295: AsyncPerformer(Callable<T> task,
296: ExecutionFinishedListener<T> finishedListener,
297: long timeout) {
298: this .task = task;
299: this .finishedListener = finishedListener;
300: this .timeout = timeout;
301: }
302:
303: /**
304: * Performs the task using {@link Executor#performSynchronously(Callable, long)}.
305: *
306: * @see java.lang.Runnable#run()
307: */
308: public void run() {
309: ExecutionFinishedEvent<T> finishedEvent = null;
310: try {
311: T result = null;
312: if (this .timeout < 0) {
313: result = this .task.call();
314: } else {
315: result = Executor.getInstance()
316: .performSynchronously(task, timeout);
317: }
318: finishedEvent = new ExecutionFinishedEvent<T>(
319: this .task, result);
320: } catch (Throwable t) {
321: finishedEvent = new ExecutionFinishedEvent<T>(t,
322: this.task);
323: }
324: if (this.finishedListener != null) {
325: this.finishedListener.executionFinished(finishedEvent);
326: }
327: }
328: }
329:
330: }
|