jaitools.jiffle.runtime
Class JiffleExecutor

java.lang.Object
  jaitools.jiffle.runtime.JiffleExecutor

public class JiffleExecutor
extends 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:

1.1

Version:

$Id: JiffleExecutor.java 1527 2011-03-08 05:54:23Z 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, TimeUnit unit) Requests that the executor shutdown after completing any tasks already submitted.
void	shutdownNow() Attempts to shutdown the executor immediately.
int	submit(Jiffle jiffle, Map<String,RenderedImage> images, JiffleProgressListener progressListener) Submits an Jiffle 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(Jiffle jiffle,
                  Map<String,RenderedImage> images,
                  JiffleProgressListener progressListener)
           throws JiffleExecutorException

Submits an Jiffle object for execution. If the script is not already compiled the executor will compile it. 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:

jiffle - a properly compiled Jiffle object

images - source and destination images as a Map with keys being image variable names as used in the Jiffle script and image parameters

progressListener - an optional progress listener (may be null)

Returns:

the job ID that can be used to query progress

Throws:

JiffleExecutorException - if the Jiffle object was not compiled correctly

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,
                               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.