Chapter 36. Scripting

JBoss Data Grid includes a method of storing scripts on servers, allowing remote clients to execute scripts locally with the JDK’s javax.script.ScriptEngines. By default the JDK comes with Nashorn, capable of running JavaScript; however, this may be extended to run any JVM language that offers their own ScriptEngine.

Scripts are stored in a special, protected cache entitled ___script_cache. As this is a protected cache only loopback requests or connections with authorization enabled will be allowed to access the cache.

The following requirements must be met to connect to the ___script_cache remotely:

A script may be added to the ___script_cache by putting the script into the cache itself with the name of the script as the key, and the content of the script as the value. If the name of the script contains a filename extension, such as sample.js , then the extension will determine the engine used to execute the script. This behavior may be overridden by specifying metadata inside the script itself.

As the contents of the script should be stored in the value of the ___script_cache this may either be loaded from a pre-existing file, or manually entered. The following examples demonstrate both of these options:

private static final String SCRIPT_CACHE = "___script_cache";
private RemoteCache<String, String> scriptingCache;
[...]
    scriptingCache = cacheManager.getCache(SCRIPT_CACHE);
[...]

    private void loadScript(String filename) throws IOException{
        StringBuilder sb = new StringBuilder();
        BufferedReader reader = new BufferedReader(new FileReader(filename));
        for (String line = reader.readLine(); line != null; line = reader.readLine()) {
            sb.append(line);
            sb.append("\n");
        }
        System.out.println(sb.toString());
        scriptingCache.put(filename,sb.toString());
    }

RemoteCache<String, String> scriptCache = cacheManager.getCache("___script_cache");
scriptCache.put("multiplication.js",
  "// mode=local,language=javascript\n" +
  "// parameters=[multiplicand,multiplier]" +
  "multiplicand * multiplier\n"

Metadata may be stored in the script to provide additional information to the server on how the script is executed. This metadata is contained in a specially formatted comment on the first lines of the script.

Properties are defined as key=value pairs separated by commas, with the comment styles, such as //, ;;, or \#, depending on the scripting language in use. This information may be split over multiple lines if necessary, and single or double quotes may be used to delimit the values.

The following is an example of a valid metadata comment:

// name=test, language=javascript
// mode=local, parameters=[a,b,c]

As the execution mode is a characteristic of the script there is no additional configuration required on the client to invoke scripts in different modes.

The script engine exposes several internal objects as pre-defined bindings when the script is executed. These are:

In addition to the standard bindings, a script may have a set of named parameters passed in which also appear as bindings. Parameters are passed in as a map of name, value pairs where the name is a string, and the value is any value understood by the marshaller in use.

Consider the following script which takes two parameters, multiplicand and multiplier:

// mode=local,language=javascript
// parameters=[multiplicand,multiplier]
multiplicand * multiplier

As the last operation is an evaluation its result will be returned to the script invoker. Passing in values changes depending on how the script is executed, and will be covered under each execution method.

If authorization is disabled on the server then anyone may execute scripts once they have been installed. Otherwise, only users with EXEC permissions will be allowed to run previously installed scripts.

Scripts may be executed in Hot Rod by calling execute(scriptName, parameters) on the cache where the script should be executed. In this case the scriptName corresponds with the name of the script stored in the ___script_cache, and parameters is a Map<String,Object> of named parameters.

The following example demonstrates executing the above multiplication.js script through Hot Rod:

RemoteCache<String, Integer> cache = cacheManager.getCache();
// Create the parameters for script execution
Map<String, Object> params = new HashMap<>();
params.put("multiplicand", 10);
params.put("multiplier", 20);
// Run the script on the server, passing in the parameters
Object result = cache.execute("multiplication.js", params);

The following examples demonstrate various tasks to assist in the reader’s understanding of the scripting syntax, and to get ideas on what tasks may be suitable for scripts in each environment.

// mode:distributed,language=javascript
cacheManager.getAddress().toString();

// mode=local,language=javascript
var Function = Java.type("java.util.function.Function")
var Collectors = Java.type("java.util.stream.Collectors")
var Arrays = Java.type("org.infinispan.scripting.utils.JSArrays")
cache
    .entrySet().stream()
    .map(function(e) e.getValue())
    .map(function(v) v.toLowerCase())
    .map(function(v) v.split(/[\W]+/))
    .flatMap(function(f) Arrays.stream(f))
    .collect(Collectors.groupingBy(Function.identity(), Collectors.counting()));

There are no issues using streams in clusters with other modes.