Basic usage

The API will consider a Script as a class implementing a Java interface. You will then be able to use the script as you would use this interface in Java code.

Use case

Suppose that you want to allow users to implement as they want an interface, for example (for the sake of the example), you might want to allow users to provide their own scripted implementation to compute a value, such as:

   public interface Script {
     public int computeResult(int value);
   }

API concepts

The basic usage of the API is based on one concept only:

• The ScriptWrapper is a wrapper around a script implementing an interface

The ScriptWrapper is a wrapper around a script seen as implementing an interface. A ScriptWrapper must be a subclass of the ScriptWrapper of the scripting language you want to use:

• The GroovyScriptWrapper for Groovy scripts
• The RubyScriptWrapper for Ruby scripts
• The JSScriptWrapper for Javascript scripts
• The PythonScriptWrapper for Python scripts

The code you must implement is very simple. For example with Groovy:

   ScriptWrapper<Script> wrapper = new GroovyScriptWrapper<Script>() {
   };

with Script being the interface you want to implement in the scripting language.

Getting the script proxy

In the basic usage, you will get a script proxy from the wrapper with ScriptWrapper.getScript(). The proxy you will get implements your Script interface, and you will be able yo use it exactly as any implementation of this interface.

   ScriptWrapper<Script> wrapper = new GroovyScriptWrapper<Script>() {
   };
   Script Script = wrapper.getScript();

And install the script:

   File file = new File(<our script file>);
   wrapper.installScript(file);

and:

   int value = script.computeResult(10);

Note that the ScriptWrapper.getScript() method will return a non null and valid result even before the script is installed because the proxy object is a wrapper around the effective script object.

Coding the script

In our example,we could for example code the following groovy script:

   public int computeResult(int value) {
     return value * 10;
   }

You don't need to specify that this groovy script implements the Script interface. The framework will take care of that.

Using a new Script

You don't need to create a new ScriptWrapper if you want to change to script you use. Just call again the ScriptWrapper.installScript(File) method. For example this will work:

   ScriptWrapper<Script> wrapper = new GroovyScriptWrapper<Script>() {
   };
   Script Script = wrapper.getScript();

   File file = new File(<our first script file>);
   wrapper.installScript(file);
   int value = script.execute(10);

   file = new File(<our second script file>);
   value = script.execute(10);

Script logger

The ScriptLogger is an interface which logs informations and errors during the script execution. The logger is accessible by the logger field.

It is possible to set a custom logger by ScriptWrapper.setScriptLogger(ScriptLogger).

Exceptions handling

By default exceptions encountered in the script will be rethrown as ScriptException. These exceptions may be encountered in several cases:

• While trying to compile to script when calling the ScriptWrapper.installScript(File) method
• While running the script method

It is possible to log exceptions rather than throw them to the caller by:

   wrapper.logExceptions(true);

Script context

It is possible to use a global context in scripts. Note that it is not necessary to do anything to set the context for scripts, the framework will do it "under the hood".

The context is available through the context field in your script. For example:

   public void apply() {
      context.echo("Hello World");
   }

Script logger

It is possible to use a global logger.

The logger is available through the logger field in your script. For example:

   public void apply() {
      logger.append("Hello World");
   }

Script helper

It is possible to use a script helper in scripts. A script helper allows to define helper methods associated with your application. Note that these methods can also be defined in the script context, but it is clearer to define a specific class for them.

It there is a script helper, it is available through the helper field in your script. For example:

   public void apply() {
      helper.doSomeComputation();
   }

Script additional helpers

It is also possible to add additional helper classes which may be used in the script.

This can be interesting if you have existing classes in you project which you want to make available in your script without refactoring them to convert them to a single script helper.

Adding default imports

By default scripts will have the following default imports:

• The script interface classpath
• The Script context classpath

It is possible to add custom default imports to the scripts in the ScriptWrapper interface.

Combining wrappers

A ScriptWrapper only allows your script to implement one interface.

A ScriptWrapperCombiner allows the script to implement one interface among several. The combiner will get the most appropriate one for your script.

Debugging scripts

The framework allows to debug scripts. Note that for the moment, only Groovy scripts can be used in the debugger.