Compiling and Scripting

This chapter is from the book

Core Java, Volume II: Advanced Features, 13th Edition

Learn More Buy

This chapter is from the book

This chapter is from the book 

Core Java, Volume II: Advanced Features, 13th Edition

Learn More Buy

8.2. Scripting for the Java Platform

A scripting language is a language that avoids the usual edit/compile/link/run cycle by interpreting the program text at runtime. Scripting languages have a number of advantages:

• Rapid turnaround, encouraging experimentation

• Changing the behavior of a running program

• Enabling customization by program users

On the other hand, most scripting languages lack features that are beneficial for programming complex applications, such as strong typing, encapsulation, and modularity.

It is therefore tempting to combine the advantages of scripting and traditional languages. The scripting API lets you do just that for the Java platform. It enables you to invoke scripts written in JavaScript, Groovy, Ruby, and even exotic languages such as Scheme and Haskell, from a Java program. For example, the Renjin project (https://www.renjin.org) provides a Java implementation of the R programming language, which is commonly used for statistical programming, together with an “engine” of the scripting API.

When looking for a compatible implementation of your favorite language, search for JSR 223 support. (Java Specification Request 223 developed the scripting API before it was integrated into Java.)

The JMeter performance analysis tool (https://jmeter.apache.org/) is an example of a program that allows users to write scripts in any language with Java scripting support. The Maven build tool has a plugin (https://maven.apache.org/plugins/maven-scripting-plugin/index.html) for writing build steps in any language that has a Java scripting engine.

In the following sections, I'll show you how to select an engine for a particular language, how to execute scripts, and how to make use of advanced features that some scripting engines offer.

8.2.1. Getting a Scripting Engine

A scripting engine is a library that can execute scripts in a particular language. When the virtual machine starts, it discovers the available scripting engines. To enumerate them, construct a ScriptEngineManager and invoke the getEngineFactories method. You can ask each engine factory for the supported engine names, MIME types, and file extensions. Table 8.1 shows typical values.

The examples in this chapter use the Rhino scripting engine, available at https://github.com/mozilla/rhino, that implements an ancient version of JavaScript.

Table 8.1: Properties of Scripting Engine Factories

Usually, you know which engine you need, and you can simply request it by name, MIME type, or extension. For example:

var manager = new ScriptEngineManager();
ScriptEngine engine = manager.getEngineByName("rhino");

You need to provide the JAR files that implement the script engine on the classpath.

8.2.2. Script Evaluation and Bindings

Once you have an engine, you can call a script simply by invoking

Object result = engine.eval(scriptString);

If the script is stored in a file, open a Reader and call

Object result = engine.eval(reader);

You can invoke multiple scripts on the same engine. If one script defines variables, functions, or classes, most scripting engines retain the definitions for later use. For example,

engine.eval("n = 1728");
Object result = engine.eval("n + 1");

will return 1729.

Object param = factory.getParameter("THREADING");

You will often want to add variable bindings to the engine. A binding consists of a name and an associated Java object. For example, consider these statements:

engine.put("k", 1728);
Object result = engine.eval("k + 1");

The script code reads the definition of k from the bindings in the “engine scope.” This is particularly important because most scripting languages can access Java objects, often with a syntax that is simpler than the Java syntax. For example,

engine.put("d", LocalDate.now());
Object result = engine.eval("d.month"); // calls getMonth

Conversely, you can retrieve variables that were bound by scripting statements:

engine.eval("n = 1728");
Object result = engine.get("n");

In addition to the engine scope, there is also a global scope. Any bindings that you add to the ScriptEngineManager are visible to all engines.

Instead of adding bindings to the engine or global scope, you can collect them in an object of type Bindings and pass it to the eval method:

Bindings scope = engine.createBindings();
scope.put("d", LocalDate.now());
engine.eval(scriptString, scope);

This is useful if a set of bindings should not persist for future calls to the eval method.

8.2.3. Redirecting Input and Output

You can redirect the standard input and output of a script by calling the setReader and setWriter methods of the script context. For example,

var writer = new StringWriter();
engine.getContext().setWriter(new PrintWriter(writer, true));

Any output written with the JavaScript print or println functions is sent to writer.

The setReader and setWriter methods only affect the scripting engine’s standard input and output sources. For example, if you execute the JavaScript code

println("Hello");
java.lang.System.out.println("World");

only the first output is redirected.

The Rhino engine does not have the notion of a standard input source. Calling setReader has no effect.

8.2.4. Calling Scripting Functions and Methods

With some script engines, you can invoke a scripting language function directly in your Java code, without having to evaluate a script code snippet that makes the call. This is useful if you allow users to implement a service in a scripting language of their choice, so that you can call it from Java.

The script engines that offer this functionality implement the Invocable interface. In particular, the Rhino engine implements Invocable.

To call a function, call the invokeFunction method with the function name, followed by the function arguments:

// Define greet function in JavaScript
engine.eval("function greet(how, whom) { return how + ', ' + whom + '!' }");

// Call the function with arguments "Hello", "World"
result = ((Invocable) engine).invokeFunction("greet", "Hello", "World");

If the scripting language is object-oriented, call invokeMethod:

// Define Greeter class in JavaScript
engine.eval("""
function Greeter(how) { this.how = how }
Greeter.prototype.welcome = 
   function (whom) { return this.how + ', ' + whom + '!' }
""");

// Construct an instance
Object yo = engine.eval("new Greeter('Yo')");

// Call the welcome method on the instance
result = ((Invocable) engine).invokeMethod(yo, "World");

You can go a step further and ask the scripting engine to implement a Java interface. Then you can call scripting functions and methods with the Java method call syntax.

The details depend on the scripting engine, but typically you need to supply a function for each method of the interface. For example, consider a Java interface

public interface Greeter
{
   String welcome(String whom);
}

If you define a global function with the same name in Rhino, you can call it through this interface:

// Define welcome function in JavaScript
engine.eval("function welcome(whom) { return 'Hello, ' + whom + '!' }");

// Get a Java object and call a Java method
Greeter g = ((Invocable) engine).getInterface(Greeter.class);
result = g.welcome("World");

In an object-oriented scripting language, you can access a script class through a matching Java interface. For example, here is how to call an object of the JavaScript Greeter class with Java syntax:

Greeter g = ((Invocable) engine).getInterface(yo, Greeter.class);
result = g.welcome("World");

In summary, the Invocable interface is useful if you want to call scripting code from Java without worrying about the scripting language syntax.

8.2.5. Compiling a Script

Some scripting engines can compile scripting code into an intermediate form for efficient execution. Those engines implement the Compilable interface. The following example shows how to compile and evaluate code contained in a script file:

if (engine instanceof Compilable compilableEngine) {
   Reader reader = Files.newBufferedReader(path);
   CompiledScript script = compilableEngine.compile(reader);
   script.eval();
}

Of course, it only makes sense to compile a script if you need to execute it repeatedly.

8.2.6. An Example: Script Sheets

Have a look at the program in Listing 8.2 that executes a sheet in the same format as the example in Section 8.1.6. However, this time, the code is in a scripting language, and it is evaluated when the program runs.

The classpath must contain a scripting engine. Start the program like this:

java -classpath .:engineDir/\* ScriptTest engineName sheetFile

For example,

java -classpath .:rhino/\* script.ScriptTest rhino script/sheet

Listing 8.2 script/ScriptTest.java

 1 package script;
 2 
 3 import java.io.*;
 4 import java.nio.file.*;
 5 import javax.script.*;
 6 
 7 /**
 8  * @version 1.1 2023-08-17
 9  * @author Cay Horstmann
10  * 
11 
12 Download Rhino and the Rhino engine JAR from 
13 https://mvnrepository.com/artifact/org.mozilla/rhino
14 https://mvnrepository.com/artifact/org.mozilla/rhino-engine
15 Place in a directory rhino
16 
17 javac script/ScriptTest.java
18 java --classpath .:rhino/\* script.ScriptTest rhino script/sheet
19 
20  */
21 public class ScriptTest
22 {
23    public static void main(String[] args) throws ScriptException, IOException
24    {
25       var manager = new ScriptEngineManager();
26       String language;
27       if (args.length == 0) 
28       {
29          System.out.println("Available factories: ");
30          for (ScriptEngineFactory factory : manager.getEngineFactories())
31             System.out.println(factory.getEngineName());
32          return;
33       }
34       else language = args[0];
35 
36       ScriptEngine engine = manager.getEngineByName(language);               
37       if (engine == null)
38       {
39          System.err.println("No engine for " + language);
40          System.exit(1);
41       }
42 
43       String sheetName = args[1];
44       boolean verbatim = false;
45       var verbatimCode = new StringBuilder(); 
46       for (String line : Files.readAllLines(Path.of(sheetName)))
47       {
48          if (line.equals("```")) {
49             verbatim = !verbatim;
50             if (!verbatim)
51             {
52                engine.eval(verbatimCode.toString());
53                verbatimCode.delete(0, verbatimCode.length());
54             }
55          }
56          else if (verbatim) verbatimCode.append(line).append("\n");
57          else
58          {
59             String[] fragments = line.split("`");
60             for (int i = 0; i < fragments.length; i++)
61             {
62                System.out.print(i % 2 == 0 ? fragments[i] : engine.eval(fragments[i]));
63             }
64             System.out.println();
65          }
66       }      
67    }
68 }