README.md

JShell scripting engine

The JShell was introduced with Java 9 and was designed to be used for interactive execution of code snippets in Java.

The jshell-scriptengine library is a Java 11 wrapper around the JShell API that executes an entire script and handles the binding of variables.

jshell-scriptengine is a good alternative to the usual javascript commonly used, especially if the users that will end up writing the scripts are already experienced Java programmers or can use the leverage that a Java framework can provide.

Using a scripting engine is a powerful choice if your project needs to execute code that can be easily changed outside of the development cycle and when already deployed.

Typical use cases are:

• directory in your deployed application containing scripts for customizable business logic
• editor in your application to edit (and persist) scripts

If you believe that Java as a scripting language does not exactly fit your needs, consider the sibling project spel-scriptengine (Spring Expression Language Scripting Engine).

Using JShell scripting engine in your projects

To use the JShell scripting you can either download the newest version of the .jar file from the published releases on Github or use the following dependency to Maven Central in your build script (please verify the version number to be the newest release):

Use JShell scripting engine in Maven build

<dependency>
  <groupId>ch.obermuhlner</groupId>
  <artifactId>jshell-scriptengine</artifactId>
  <version>1.1.0</version>
</dependency>

Use JShell scripting engine in Gradle build

repositories {
  mavenCentral()
}

dependencies {
  compile 'ch.obermuhlner:jshell-scriptengine:1.1.0'
}

Simple usage

The following code snippet shows a simple usage of the JShell script engine:

try {
    ScriptEngineManager manager = new ScriptEngineManager();
    ScriptEngine engine = manager.getEngineByName("jshell");

    String script = "" +
            "System.out.println(\"Input A: \" + inputA);" +
            "System.out.println(\"Input B: \" + inputB);" +
            "var output = inputA + inputB;" +
            "1000 + output;";

    engine.put("inputA", 2);
    engine.put("inputB", 3);

    Object result = engine.eval(script);
    System.out.println("Result: " + result);

    Object output = engine.get("output");
    System.out.println("Output Variable: " + output);

} catch (ScriptException e) {
    e.printStackTrace();
}

The console output of this snippet shows that the bindings for input and output variables are working correctly. The return value of the JShell script is the value of the last statement 1000 + output.

Input A: 2
Input B: 3
Result: 1005
Output Variable: 5

Access to classes

The JShell script is executed in the same Thread as the caller and has therefore access to the same classes.

Assume your project has the following class:

package ch.obermuhlner.scriptengine.example;

public class Person {
    public String name;
    public int birthYear;

    @Override
    public String toString() {
        return "Person{name=" + name + ", birthYear=" + birthYear + "}";
    }
}

In this case you can run a JShell script that uses this class Person:

try {
    ScriptEngineManager manager = new ScriptEngineManager();
    ScriptEngine engine = manager.getEngineByName("jshell");

    String script = "" +
            "import ch.obermuhlner.scriptengine.example.Person;" +
            "var person = new Person();" +
            "person.name = \"Eric\";" +
            "person.birthYear = 1967;";

    Object result = engine.eval(script);
    System.out.println("Result: " + result);

    Object person = engine.get("person");
    System.out.println("Person Variable: " + person);

} catch (ScriptException e) {
    e.printStackTrace();
}

The console output of this snippet shows that the variable person created inside the JShell script is now available in the calling Java:

Result: 1967
Person Variable: Person{name=Eric, birthYear=1967}

Error handling

try {
    ScriptEngineManager manager = new ScriptEngineManager();
    ScriptEngine engine = manager.getEngineByName("jshell");

    String script = "" +
            "System.out.println(unknown);" +
            "var message = \"Should never reach this point\"";

    Object result = engine.eval(script);
    System.out.println("Result: " + result);
} catch (ScriptException e) {
    e.printStackTrace();
}

The console output of this snippet shows that the variable unknown cannot be found:

javax.script.ScriptException: cannot find symbol
  symbol:   variable unknown
  location: class 
System.out.println(unknown);
	at ch.obermuhlner.scriptengine.jshell.JShellScriptEngine.evaluateScript(JShellScriptEngine.java:216)
	at ch.obermuhlner.scriptengine.jshell.JShellScriptEngine.eval(JShellScriptEngine.java:98)
	at ch.obermuhlner.scriptengine.jshell.JShellScriptEngine.eval(JShellScriptEngine.java:84)
	at ch.obermuhlner.scriptengine.jshell.JShellScriptEngine.eval(JShellScriptEngine.java:74)
	at ch.obermuhlner.scriptengine.example.ScriptEngineExample.runErrorExample(ScriptEngineExample.java:84)
	at ch.obermuhlner.scriptengine.example.ScriptEngineExample.main(ScriptEngineExample.java:14)

Compiling

The JShellScriptEngine implements the Compilable interface.

You can compile a script into a CompiledScript and execute it multiple times with different bindings.

try {
    ScriptEngineManager manager = new ScriptEngineManager();
    ScriptEngine engine = manager.getEngineByName("jshell");
    Compilable compiler = (Compilable) engine;

    CompiledScript compiledScript = compiler.compile("var output = alpha + beta");

    {
        Bindings bindings = engine.createBindings();
        bindings.put("alpha", 2);
        bindings.put("beta", 3);

        Object result = compiledScript.eval(bindings);
        Integer output = (Integer) bindings.get("output");
        System.out.println("Result (Integer): " + result);
        System.out.println("Output (Integer): " + output);
    }

    {
        Bindings bindings = engine.createBindings();
        bindings.put("alpha", "aaa");
        bindings.put("beta", "bbb");

        Object result = compiledScript.eval(bindings);
        String output = (String) bindings.get("output");
        System.out.println("Result (String): " + result);
        System.out.println("Output (String): " + output);
    }
} catch (ScriptException e) {
    e.printStackTrace();
}

The console output shows that the same compiled script was able to run with different bindings, which where even of different runtime types.

Result (Integer): 5
Output (Integer): 5
Result (String): aaabbb
Output (String): aaabbb

Separating the compilation from the evaluation is more efficient if you need to evaluate the same script multiple times.

Here the execution times in milliseconds for:

• Multi Eval
  • many calls to JShellScriptEngine.eval(String) (essentially compile and evaluate every time)
• Compile + Multi Eval
  • single call to JShellScriptEngine.compile(String)
  • many calls to JShellCompiledScript.eval(Bindings)