Chapter 13. Running scripts and tasks on Data Grid Server

Add tasks and scripts to Data Grid Server deployments for remote execution from the Command Line Interface (CLI) and Hot Rod or REST clients. You can implement tasks as custom Java classes or define scripts in languages such as JavaScript.

13.1. Adding tasks to Data Grid Server deployments

Add your custom server task classes to Data Grid Server.

Prerequisites

  • Stop Data Grid Server if it is running.

    Data Grid Server does not support runtime deployment of custom classes.

Procedure

  1. Add a META-INF/services/org.infinispan.tasks.ServerTask file that contains the fully qualified names of server tasks, for example: 

    example.HelloTask
  2. Package your server task implementation in a JAR file.
  3. Copy the JAR file to the $RHDG_HOME/server/lib directory of your Data Grid Server installation.
  4. Add your classes to the deserialization allow list in your Data Grid configuration. Alternatively set the allow list using system properties.

Reference

13.1.1. Data Grid Server tasks

Data Grid Server tasks are classes that extend the org.infinispan.tasks.ServerTask interface and generally include the following method calls:

setTaskContext()
Allows access to execution context information including task parameters, cache references on which tasks are executed, and so on. In most cases, implementations store this information locally and use it when tasks are actually executed. When using SHARED instantiation mode, the task should use a ThreadLocal to store the TaskContext for concurrent invocations.
getName()
Returns unique names for tasks. Clients invoke tasks with these names.
getExecutionMode()

Returns the execution mode for tasks.

  • TaskExecutionMode.ONE_NODE only the node that handles the request executes the script. Although scripts can still invoke clustered operations. This is the default.
  • TaskExecutionMode.ALL_NODES Data Grid uses clustered executors to run scripts across nodes. For example, server tasks that invoke stream processing need to be executed on a single node because stream processing is distributed to all nodes.
getInstantiationMode()

Returns the instantiation mode for tasks.

  • TaskInstantiationMode.SHARED creates a single instance that is reused for every task execution on the same server. This is the default.
  • TaskInstantiationMode.ISOLATED creates a new instance for every invocation.
call()
Computes a result. This method is defined in the java.util.concurrent.Callable interface and is invoked with server tasks.
Important

Server task implementations must adhere to service loader pattern requirements. For example, implementations must have a zero-argument constructors.

The following HelloTask class implementation provides an example task that has one parameter. It also illustrates the use of a ThreadLocal to store the TaskContext for concurrent invocations. 

package example;

import org.infinispan.tasks.ServerTask;
import org.infinispan.tasks.TaskContext;

public class HelloTask implements ServerTask<String> {

   private static final ThreadLocal<TaskContext> taskContext = new ThreadLocal<>();

   @Override
   public void setTaskContext(TaskContext ctx) {
      taskContext.set(ctx);
   }

   @Override
   public String call() throws Exception {
      TaskContext ctx = taskContext.get();
      String name = (String) ctx.getParameters().get().get("name");
      return "Hello " + name;
   }

   @Override
   public String getName() {
      return "hello-task";
   }

}

Reference

13.2. Adding scripts to Data Grid Server deployments

Use the command line interface to add scripts to Data Grid Server.

Prerequisites

Data Grid Server stores scripts in the ___script_cache cache. If you enable cache authorization, users must have CREATE permissions to add to ___script_cache.

Assign users the deployer role at minimum if you use default authorization settings.

Procedure

  1. Define scripts as required.

    For example, create a file named multiplication.js that runs on a single Data Grid server, has two parameters, and uses JavaScript to multiply a given value: 

    // mode=local,language=javascript
multiplicand * multiplier
  2. Create a CLI connection to Data Grid.

  3. Use the task command to upload scripts, as in the following example: 

    task upload --file=multiplication.js multiplication

  4. Verify that your scripts are available. 

    ls tasks
multiplication

13.2.1. Data Grid Server scripts

Data Grid Server scripting is based on the javax.script API and is compatible with any JVM-based ScriptEngine implementation.

Hello world

The following is a simple example that runs on a single Data Grid server, has one parameter, and uses JavaScript: 

// mode=local,language=javascript,parameters=[greetee]
"Hello " + greetee

When you run the preceding script, you pass a value for the greetee parameter and Data Grid returns "Hello ${value}".

13.2.1.1. Script metadata

Metadata provides additional information about scripts that Data Grid Server uses when running scripts.

Script metadata are property=value pairs that you add to comments in the first lines of scripts, such as the following example: 

// name=test, language=javascript
// mode=local, parameters=[a,b,c]
  • Use comment styles that match the scripting language (//, ;;, #).
  • Separate property=value pairs with commas.
  • Separate values with single (') or double (") quote characters.

Table 13.1. Metadata Properties

PropertyDescription

mode

Defines the execution mode and has the following values:

local only the node that handles the request executes the script. Although scripts can still invoke clustered operations.

distributed Data Grid uses clustered executors to run scripts across nodes.

language

Specifies the ScriptEngine that executes the script.

extension

Specifies filename extensions as an alternative method to set the ScriptEngine.

role

Specifies roles that users must have to execute scripts.

parameters

Specifies an array of valid parameter names for this script. Invocations which specify parameters not included in this list cause exceptions.

datatype

Optionally sets the MediaType (MIME type) for storing data as well as parameter and return values. This property is useful for remote clients that support particular data formats only.

Currently you can set only text/plain; charset=utf-8 to use the String UTF-8 format for data.

13.2.1.2. Script bindings

Data Grid exposes internal objects as bindings for script execution.

BindingDescription

cache

Specifies the cache against which the script is run.

marshaller

Specifies the marshaller to use for serializing data to the cache.

cacheManager

Specifies the cacheManager for the cache.

scriptingManager

Specifies the instance of the script manager that runs the script. You can use this binding to run other scripts from a script.

13.2.1.3. Script parameters

Data Grid lets you pass named parameters as bindings for running scripts.

Parameters are name,value pairs, where name is a string and value is any value that the marshaller can interpret.

The following example script has two parameters, multiplicand and multiplier. The script takes the value of multiplicand and multiplies it with the value of multiplier. 

// mode=local,language=javascript
multiplicand * multiplier

When you run the preceding script, Data Grid responds with the result of the expression evaluation.

13.2.2. Programmatically Creating Scripts

Add scripts with the Hot Rod RemoteCache interface as in the following example: 

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

Reference

org.infinispan.client.hotrod.RemoteCache

13.3. Running scripts and tasks

Use the command line interface to run tasks and scripts on Data Grid Server deployments. Alternatively you can execute scripts and tasks from Hot Rod clients.

Prerequisites

  • Add scripts or tasks to Data Grid Server.

Procedure

  1. Create a CLI connection to Data Grid.

  2. Use the task command to run tasks and scripts, as in the following examples:

    • Execute a script named multiplier.js and specify two parameters: 

      task exec multiplier.js -Pmultiplicand=10 -Pmultiplier=20
200.0

    • Execute a task named @@cache@names to retrieve a list of all available caches: 

      task exec @@cache@names
["___protobuf_metadata","mycache","___script_cache"]

Programmatic execution

  • Call the execute() method to run scripts with the Hot Rod RemoteCache interface, as in the following examples:

Script execution

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

Task execution

// Add configuration for a locally running server.
ConfigurationBuilder builder = new ConfigurationBuilder();
builder.addServer().host("127.0.0.1").port(11222);

// Connect to the server.
RemoteCacheManager cacheManager = new RemoteCacheManager(builder.build());

// Retrieve the remote cache.
RemoteCache<String, String> cache = cacheManager.getCache();

// Create task parameters.
Map<String, String> parameters = new HashMap<>();
parameters.put("name", "developer");

// Run the server task.
String greet = cache.execute("hello-task", parameters);
System.out.println(greet);

Additional resources