jaitools.jiffle
Class Jiffle

java.lang.Object
  jaitools.jiffle.Jiffle

public class Jiffle
extends Object

Compiles scripts and generates Java sources and executable bytecode for runtime classes.

Example of use:

 // A script to write sequential values to image pixels
 String script = "init { n = 0; } dest = n++ ;" ;

 // We tell Jiffle about variable names that represent images
 // (in this case, only "dest") via a Map of parameters
 Map<String, Jiffle.ImageRole> imageParams = CollectionFactory.map();
 imageParams.put("dest", Jiffle.ImageRole.DEST);

 // Using this constructor results in the script being compiled
 // immediately (any errors will generate JiffleExceptions)
 Jiffle jiffle = new Jiffle(script, imageParams);

 // Now get a runtime object
 JiffleDirectRuntime runtime = jiffle.getRuntimeInstance();

 // Create an image to hold the results of the script and pass it
 // to the runtime object
 final int width = 10;
 TiledImage destImg = ImageUtils.createConstantImage(width, width, 0.0d);
 runtime.setDestinationImage("dest", destImg);

 // Evaluate the script for all destination image pixels
 runtime.evaluateAll();
 

For further examples of how to create and run Jiffle scripts see the jaitools.demo.jiffle package in the JAI-tools demo module.

Implementation note

The Jiffle compiler is really a Jiffle to Java translator. When a client requests a runtime object, the script is translated and the resulting Java source is passed to an embedded Janino compiler which compiles the source to bytecode in memory.

Since:

1.0

Version:

$Id: Jiffle.java 1512 2011-03-07 02:21:45Z michael.bedward $

Author:

Michael Bedward

See Also:

JiffleBuilder, JiffleExecutor

Nested Class Summary

static class	Jiffle.ImageRole Used to specify the roles of images referenced in a Jiffle script.
static class	Jiffle.RuntimeModel Constants for runtime model.

Constructor Summary

Jiffle()
Creates a new instance.

Jiffle(File scriptFile, Map<String,Jiffle.ImageRole> params)
Creates a new instance by compiling the script read from scriptFile.

Jiffle(String script, Map<String,Jiffle.ImageRole> params)
Creates a new instance by compiling the provided script.

Method Summary

void	compile() Compiles the script into Java source for the runtime class.
Map<String,Jiffle.ImageRole>	getImageParams() Gets the current image parameters.
String	getName() Gets the name assigned to this object.
JiffleDirectRuntime	getRuntimeInstance() Creates an instance of the default runtime class.
<T extends JiffleRuntime> T	getRuntimeInstance(Class<T> baseClass) Gets the runtime object for this script.
JiffleRuntime	getRuntimeInstance(Jiffle.RuntimeModel model) Creates a runtime object based using the class specified by model.
String	getRuntimeSource(Jiffle.RuntimeModel model, boolean scriptInDocs) Gets a copy of the Java source for the runtime class.
String	getScript() Gets the Jiffle script.
boolean	isCompiled() Tests whether the script has been compiled successfully.
void	setImageParams(Map<String,Jiffle.ImageRole> params) Sets the image parameters.
void	setName(String name) Replaces the default name set for this object with a user-supplied name.
void	setScript(File scriptFile) Sets the script.
void	setScript(String script) Sets the script.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Jiffle

public Jiffle()

Creates a new instance.

Jiffle

public Jiffle(String script,
              Map<String,Jiffle.ImageRole> params)
       throws JiffleException

Creates a new instance by compiling the provided script. Using this constructor is equivalent to:

 Jiffle jiffle = new Jiffle();
 jiffle.setScript(script);
 jiffle.setImageParams(params);
 jiffle.compile();
 

Parameters:

script - Jiffle source code to compile

params - defines the names and roles of image variables referred to in the script.

Throws:

JiffleException - if there are any errors compiling the script

Jiffle

public Jiffle(File scriptFile,
              Map<String,Jiffle.ImageRole> params)
       throws JiffleException

Creates a new instance by compiling the script read from scriptFile. Using this constructor is equivalent to:

 Jiffle jiffle = new Jiffle();
 jiffle.setScript(scriptFile);
 jiffle.setImageParams(params);
 jiffle.compile();
 

Parameters:

scriptFile - file containing the Jiffle script

params - defines the names and roles of image variables referred to in the script.

Throws:

JiffleException - if the file cannot be read or if there are any errors compiling the script

Method Detail

setScript

public final void setScript(String script)
                     throws JiffleException

Sets the script. Calling this method will clear any previous script and runtime objects.

Parameters:

script - a Jiffle script

Throws:

JiffleException - if the script is null or empty

setScript

public final void setScript(File scriptFile)
                     throws JiffleException

Sets the script. Calling this method will clear any previous script and runtime objects.

Parameters:

scriptFile - a file containing a Jiffle script

Throws:

JiffleException - on errors reading the script file

getScript

public String getScript()

Gets the Jiffle script.

Returns:

the script or an empty String if none has been set

setImageParams

public final void setImageParams(Map<String,Jiffle.ImageRole> params)

Sets the image parameters. These define which variables in the script refer to images and their types (source or destination).

This may be called before or after setting the script. No check is made between script and parameters until the script is compiled.

Parameters:

params - the image parameters

getImageParams

public Map<String,Jiffle.ImageRole> getImageParams()

Gets the current image parameters. The parameters are returned as an unmodifiable map.

Returns:

image parameters or an empty Map if none are set

setName

public void setName(String name)

Replaces the default name set for this object with a user-supplied name. The name is solely for use by client code. No checks are made for duplication between current instances.

Parameters:

name - the name to assign

getName

public String getName()

Gets the name assigned to this object. This will either be the default name or one assigned by the client via setName(String)

Returns:

the name

compile

public final void compile()
                   throws JiffleException

Compiles the script into Java source for the runtime class.

Throws:

JiffleException - if no script has been set or if any errors occur during compilation

isCompiled

public boolean isCompiled()

Tests whether the script has been compiled successfully.

Returns:

true if the script has been compiled; false otherwise

getRuntimeInstance

public JiffleDirectRuntime getRuntimeInstance()
                                       throws JiffleException

Creates an instance of the default runtime class.

The default runtime class implements JiffleDirectRuntime and extends an abstract base class provided by the Jiffle compiler. Objects of this class evaluate the Jiffle script and write results directly to the destination image(s). Client code can call either of the methods:

• evaluate(int x, int y)
• evaluateAll(JiffleProgressListener listener

The Jiffle object must be compiled before calling this method.

Returns:

the runtime object

Throws:

JiffleException - if the runtime object could not be created

getRuntimeInstance

public JiffleRuntime getRuntimeInstance(Jiffle.RuntimeModel model)
                                 throws JiffleException

Creates a runtime object based using the class specified by model.

The Jiffle object must be compiled before calling this method.

Parameters:

model - the Jiffle.RuntimeModel

Returns:

the runtime object

Throws:

JiffleException - if the runtime object could not be created

getRuntimeInstance

public <T extends JiffleRuntime> T getRuntimeInstance(Class<T> baseClass)
                                           throws JiffleException

Gets the runtime object for this script.

The runtime object is an instance of JiffleRuntime. By default it extends an abstract base class supplied JAI-tools: AbstractDirectRuntime when using the direct runtiem model or AbstractIndirectRuntime when using the indirect model. This method allows you to specify a custom base class. The custom class must implement either JiffleDirectRuntime or JiffleIndirectRuntime.

Type Parameters:

T - the runtime base class type

Parameters:

baseClass - the runtime base class

Returns:

the runtime object

Throws:

JiffleException - if the runtime object could not be created

getRuntimeSource

public String getRuntimeSource(Jiffle.RuntimeModel model,
                               boolean scriptInDocs)
                        throws JiffleException

Gets a copy of the Java source for the runtime class.

Parameters:

model - the Jiffle.RuntimeModel

scriptInDocs - whether to include the original Jiffle script in the class javadocs

Returns:

source for the runtime class

Throws:

JiffleException - on error creating the runtime source