Supporting a script language

The library support by default the Groovy, Javascript, Python and Ruby (by JRuby) scripting languages. It is however possible to support other languages.

Overview

To support a new scripting language, you must extend the two following classes:

• AbstractScriptWrapper to parse scripts
• AbstractScriptException to handle exceptions encountered during the script execution

The ScriptWrapper

You can extend the following methods:

• Specify the script extension to get the extension of script files
• Specify the default imports to get the default import declarations in the script. Normally you will need to import the Java interface and the Script context class in your scripting language
• Specify the default declaration to get the class declaration (extending the Java interface) of your script
• Specify the default content to get the default content to add to your script
• Specify the end declaration to add the end of the script class declaration
• Specify the parsing of the script object to parse the script file
• Specify the creation of the script object to compile the script and get the associated object, when you have the script String content
• ScriptWrapper.getScriptException(Throwable) to get the script runtime exception knowing a Throwable

The script extension

The ScriptWrapper.getScriptExtension() method allows to get the extension of script files. For example, it returns "groovy" for Groovy scripts, and "rb" for Ruby scripts.

This is used only in the ScriptExceptionListener interface.

The default imports

The AbstractScriptWrapper.getDefaultImports() method allows to get the default import declarations in the script. Normally you will need to import the Java interface and the Script context class in your scripting language.

For example, for Groovy we will have by default:

      import org.scripthelper.context.ScriptContext;
      import org.scripthelper.context.DefaultScriptContext;
      import <the_script_interface_classpath>;

The default declaration

The AbstractScriptWrapper.getDefaultDeclaration() method allows to get the class declaration (extending the Java interface) of your script.

For example, for Groovy we will have:

      class GroovyClass implements + className {
        <context_class_path> context;

Where <context_class_path> is the classpath of the Script context class, and className is whatever name you want to use to create your Groovy class.

The default content

The AbstractScriptWrapper.getDefaultContent() method allows to get the default content to add to your script. You usually only need to add the method to set the Script context.

For example, for Groovy we will have:

      public void init(ScriptContext ctx) {
        context = <context_class_path>ctx;
      }

Where <context_class_path> is the classpath of the Script context class.

Parsing the script object

The AbstractScriptWrapper.parseScript(ScriptSource, ScriptContent) method allows to parse the script file.

You usually would want to separate the import declarations to separate them from the rest of the script.

Creating the script object

The AbstractScriptWrapper.createScriptObject() method allows to compile the script and get the associated object, when you have the script String content after parsing.

For example, we have in Groovy:

      protected Object createScriptObject() throws Exception {
        // compile the script with the InvokeDynamic optimization
        CompilerConfiguration config = new CompilerConfiguration();
        Map<String, Boolean> optim = config.getOptimizationOptions();
        config.setTargetBytecode(CompilerConfiguration.JDK8);
        optim.put("indy", Boolean.TRUE);
        GroovyClassLoader groovyLoader = new GroovyClassLoader(getClassLoader(), config);
        Class<?> groovyClass = groovyLoader.parseClass(scriptContent);

        GroovyObject groovyObject = (GroovyObject) groovyClass.newInstance();
        return groovyObject;
      }

The end declaration

The AbstractScriptWrapper.getEnd() method allows to add the end of the script class declaration.

For example it is simply a "}" in Groovy, or "end" in Ruby.

The ScriptException

The only method you need to implement is the AbstractScriptException.populateStackTrace(boolean) method which will recreate a Stack trace.