org.jaitools.jiffle.runtime
Class JiffleExecutor

java.lang.Object
  extended by org.jaitools.jiffle.runtime.JiffleExecutor

public class JiffleExecutor
extends java.lang.Object

A multi-threaded, event-driven executor service for Jiffle scripts. Jiffle objects can be submitted to this class to execute rather than the client working with a JiffleRuntime instance directly. This is preferable for computationally demanding tasks because the scripts run in a separate thread to the client. For multiple tasks, the executor can be set up to run all tasks concurrently in separate threads (if system resources permit), or run up to N tasks concurrently. If necessary, a task will be held in a queue while waiting for a thread. Setting N to 1 gives the option of serial execution.

The client can optionally follow progress during execution with a JiffleProgressListener. When the task is finished its status and results can be retrieved via JiffleEventListener.

Example of use:


 // assuming the executor is a class field in this example
 executor = new JiffleExecutor();

 executor.addEventListener(new JiffleEventListener() {

     public void onCompletionEvent(JiffleEvent ev) {
         myCompletionMethod(ev);
     }

     public void onFailureEvent(JiffleEvent ev) {
         myFailureMethod(ev);
     }
 });
 
Now we can build Jiffle objects and submit them to the executor as shown here:

 String script = "dest = src > 10 ? src : null;" ;

 Map<String, Jiffle.ImageRole> imageParams = CollectionFactory.map();
 imageParams.put("src", Jiffle.ImageRole.SOURCE);
 imageParams.put("dest", Jiffle.ImageRole.DEST);

 Jiffle jiffle = new Jiffle(script, imageParams);

 // Map with the source and destination images
 RenderedImage sourceImg = ...
 WritableRenderedImage destImg = ...
 Map<String, RenderedImage> images = CollectionFactory.map();
 images.put("src", sourceImg);
 images.put("dest", destImg);

 // Submit the task to the executor
 executor.submit(jiffle, images, new MyProgressListener());
 
When the script has completed the event listener will be notified and the results can be retrieved:

 private void myCompletionMethod(JiffleEvent ev) {
     // Get and display the result image
     JiffleExecutorResult result = ev.getResult();
     RenderedImage img = result.getImages().get("dest");
     ...
 }

 private void myFailureMethod(JiffleEvent ev) {
     System.out.println("Bummer...");
 }
 
Once the application has finished with th executor it should call one of the shutdown methods which terminate the task and polling threads.

Since:
0.1
Version:
$Id: JiffleExecutor.java 1653 2011-06-16 10:23:02Z michael.bedward $
Author:
Michael Bedward

Field Summary
static long DEFAULT_POLLING_INTERVAL
          The default interval for polling tasks to check for completion (20 mS)
 
Constructor Summary
JiffleExecutor()
          Creates an executor with default settings.
JiffleExecutor(int maxTasks)
          Creates an executor that can have, at most,maxTasks running concurrently, with further tasks being placed in a queue.
 
Method Summary
 void addEventListener(JiffleEventListener listener)
          Adds an event listener.
 long getPollingInterval()
          Gets the interval in milliseconds for polling task completion.
 boolean isListening(JiffleEventListener listener)
          Checks if a particular listener is registered with this executor.
 boolean removeEventListener(JiffleEventListener listener)
          Removes an event listener.
 void setPollingInterval(long millis)
          Sets the polling interval for task completion.
 void shutdown()
          Requests that the executor shutdown after completing any tasks already submitted.
 boolean shutdownAndWait(long timeOut, java.util.concurrent.TimeUnit unit)
          Requests that the executor shutdown after completing any tasks already submitted.
 void shutdownNow()
          Attempts to shutdown the executor immediately.
 int submit(JiffleDirectRuntime runtime, JiffleProgressListener progressListener)
          Submits an JiffleDirectRuntime object for execution.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_POLLING_INTERVAL

public static final long DEFAULT_POLLING_INTERVAL
The default interval for polling tasks to check for completion (20 mS)

See Also:
Constant Field Values
Constructor Detail

JiffleExecutor

public JiffleExecutor()
Creates an executor with default settings. There is no upper limit on the number of concurrent tasks. A cached thread pool will be used which recycles existing threads where possible.


JiffleExecutor

public JiffleExecutor(int maxTasks)
Creates an executor that can have, at most,maxTasks running concurrently, with further tasks being placed in a queue.

Parameters:
maxTasks - the maximum number of concurrent tasks
Method Detail

setPollingInterval

public void setPollingInterval(long millis)
Sets the polling interval for task completion. JiffleExecutor uses a separate thread to poll tasks for completion (either success or failure) at a fixed interval. The interval can only be changed prior to submitting the first task. After that, any calls to this method will result in a warning message being logged and the new value being ignored.

Parameters:
millis - interval between task polling in milliseconds; values less than 1 are ignored
See Also:
DEFAULT_POLLING_INTERVAL

getPollingInterval

public long getPollingInterval()
Gets the interval in milliseconds for polling task completion.

Returns:
polling interval

addEventListener

public void addEventListener(JiffleEventListener listener)
Adds an event listener.

Parameters:
listener - the listener
See Also:
JiffleEvent

removeEventListener

public boolean removeEventListener(JiffleEventListener listener)
Removes an event listener.

Parameters:
listener - the listener
Returns:
true if the listener was removed; false if it was not registered with this executor

isListening

public boolean isListening(JiffleEventListener listener)
Checks if a particular listener is registered with this executor.

Parameters:
listener - the listener
Returns:
true if the listener has already been added; false otherwise

submit

public int submit(JiffleDirectRuntime runtime,
                  JiffleProgressListener progressListener)
Submits an JiffleDirectRuntime object for execution. Depending on existing tasks and the number of threads available to the executor there could be a delay before the task starts. Clients can receive notification via an optional progress listener.

Parameters:
runtime - the run-time instance to execute
progressListener - an optional progress listener (may be null)
Returns:
the job ID that can be used to query progress

shutdown

public void shutdown()
Requests that the executor shutdown after completing any tasks already submitted. Control returns immediately to the client.


shutdownAndWait

public boolean shutdownAndWait(long timeOut,
                               java.util.concurrent.TimeUnit unit)
Requests that the executor shutdown after completing any tasks already submitted. Control returns to the calling thread after the executor has shutdown or the time out period has elapsed, whichever comes first.

Parameters:
timeOut - time-out period
unit - time unit
Returns:
true if the executor has shutdown; false if the time-out period elapsed or the thread was interrupted

shutdownNow

public void shutdownNow()
Attempts to shutdown the executor immediately.



Copyright © 2011. All Rights Reserved.