org.jaitools.jiffle
Class Jiffle

java.lang.Object
  extended by org.jaitools.jiffle.Jiffle

public class Jiffle
extends java.lang.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 = "images { dest=write; } dest = x() + y() * width();" ;

 Jiffle jiffle = new Jiffle();
 jiffle.setScript(script);
 jifle.compile();

 // Now we get the runtime object from the compiled Jiffle object
 JiffleDirectRuntime runtime = jiffle.getRuntimeInstance();

 // Create an image to hold the results of the script
 final int width = 10;
 WritableRenderedImage destImg = ImageUtils.createConstantImage(width, width, 0.0d);
 
 // Associate this image with the variable name used in the script
 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 org.jaitools.demo.jiffle package in the JAI-tools demo module.

Implementation note

The Jiffle compiler is actually a Jiffle to Java translator. When a client requests a runtime object, the script is translated into Java source for a runtime class. This source code is then passed to an embedded Janino compiler which produces the runtime object.

Since:
0.1
Version:
$Id: Jiffle.java 1653 2011-06-16 10:23:02Z 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.
 
Field Summary
static java.util.logging.Logger LOGGER
           
 
Constructor Summary
Jiffle()
          Creates a new instance.
Jiffle(java.io.File scriptFile, java.util.Map<java.lang.String,Jiffle.ImageRole> params)
          Creates a new instance by compiling the script read from scriptFile.
Jiffle(java.lang.String script, java.util.Map<java.lang.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.
 java.util.Map<java.lang.String,Jiffle.ImageRole> getImageParams()
          Gets the current image parameters.
 java.lang.String getName()
          Gets the name assigned to this object.
 JiffleDirectRuntime getRuntimeInstance()
          Creates an instance of the default runtime class.
<T extends JiffleRuntime>
T
getRuntimeInstance(java.lang.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.
 java.lang.String getRuntimeSource(boolean scriptInDocs)
          Gets a copy of the Java source for the runtime class.
 java.lang.String getRuntimeSource(Jiffle.RuntimeModel model, boolean scriptInDocs)
          Gets a copy of the Java source for the runtime class.
 java.lang.String getScript()
          Gets the Jiffle script.
 boolean isCompiled()
          Tests whether the script has been compiled successfully.
 void setImageParams(java.util.Map<java.lang.String,Jiffle.ImageRole> params)
          Sets the image parameters.
 void setName(java.lang.String name)
          Replaces the default name set for this object with a user-supplied name.
 void setScript(java.io.File scriptFile)
          Sets the script.
 void setScript(java.lang.String script)
          Sets the script.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

LOGGER

public static final java.util.logging.Logger LOGGER
Constructor Detail

Jiffle

public Jiffle()
Creates a new instance.


Jiffle

public Jiffle(java.lang.String script,
              java.util.Map<java.lang.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 - on compilation errors

Jiffle

public Jiffle(java.io.File scriptFile,
              java.util.Map<java.lang.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 - on compilation errors
Method Detail

setScript

public final void setScript(java.lang.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 empty or null

setScript

public final void setScript(java.io.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 - if the script is empty or null

getScript

public java.lang.String getScript()
Gets the Jiffle script.

Returns:
the script or an empty String if none has been set

setImageParams

public final void setImageParams(java.util.Map<java.lang.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 java.util.Map<java.lang.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(java.lang.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 java.lang.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 - on compilation errors

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:

The Jiffle object must be compiled before calling this method.

Returns:
the runtime object
Throws:
JiffleException - if the script has not been compiled or if errors occur in creating the runtime instance

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 script has not been compiled or if errors occur in creating the runtime instance

getRuntimeInstance

public <T extends JiffleRuntime> T getRuntimeInstance(java.lang.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 script has not been compiled or if errors occur in creating the runtime instance

getRuntimeSource

public java.lang.String getRuntimeSource(boolean scriptInDocs)
                                  throws JiffleException
Gets a copy of the Java source for the runtime class. The script must have been compiled before calling this method.

Parameters:
scriptInDocs - whether to include the original Jiffle script in the class javadocs
Returns:
source for the runtime class
Throws:
JiffleException - if the script has not been compiled or if errors occur in creating the runtime source code

getRuntimeSource

public java.lang.String getRuntimeSource(Jiffle.RuntimeModel model,
                                         boolean scriptInDocs)
                                  throws JiffleException
Gets a copy of the Java source for the runtime class. The script must have been compiled before calling this method.

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 - if the script has not been compiled or if errors occur in creating the runtime source code


Copyright © 2011. All Rights Reserved.