Chapter 7. Remotely Executing Server-Side Tasks
Define and add tasks to Data Grid servers that you can invoke from the Data Grid command line interface, REST API, or from Hot Rod clients.
You can implement tasks as custom Java classes or define scripts in languages such as JavaScript.
7.1. Creating Server Tasks
Create custom task implementations and add them to Data Grid servers.
7.1.1. 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.
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. -
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.
-
call()
-
Computes a result. This method is defined in the
java.util.concurrent.Callable
interface and is invoked with server tasks.
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:
package example; import org.infinispan.tasks.ServerTask; import org.infinispan.tasks.TaskContext; public class HelloTask implements ServerTask<String> { private TaskContext ctx; @Override public void setTaskContext(TaskContext ctx) { this.ctx = ctx; } @Override public String call() throws Exception { String name = (String) ctx.getParameters().get().get("name"); return "Hello " + name; } @Override public String getName() { return "hello-task"; } }
7.1.2. Deploying Server Tasks to Data Grid Servers
Add your custom server task classes to Data Grid servers.
Prerequisites
Stop any running Data Grid servers. Data Grid does not support runtime deployment of custom classes.
Procedure
- Package your server task implementation in a JAR file.
Add a
META-INF/services/org.infinispan.tasks.ServerTask
file that contains the fully qualified names of server tasks, for example:example.HelloTask
-
Copy the JAR file to the
$RHDG_HOME/server/lib
directory of your Data Grid server. - Add your classes to the deserialization whitelist in your Data Grid configuration. Alternatively set the whitelist using system properties.
7.2. Creating Server Scripts
Create custom scripts and add them to Data Grid servers.
7.2.1. Server Scripts
Data Grid server scripting is based on the javax.script
API and is compatible with any JVM-based ScriptEngine implementation.
Hello World Script Example
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}"
.
7.2.1.1. Script Metadata
Metadata provides additional information about scripts that Data Grid servers use 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 7.1. Metadata Properties
Property | Description |
---|---|
| Defines the exection mode and has the following values:
|
| Specifies the ScriptEngine that executes the script. |
| Specifies filename extensions as an alternative method to set the ScriptEngine. |
| Specifies roles that users must have to execute scripts. |
| Specifies an array of valid parameter names for this script. Invocations which specify parameters not included in this list cause exceptions. |
| 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 |
7.2.1.2. Script Bindings
Data Grid exposes internal objects as bindings for script execution.
Binding | Description |
---|---|
| Specifies the cache against which the script is run. |
| Specifies the marshaller to use for serializing data to the cache. |
|
Specifies the |
| Specifies the instance of the script manager that runs the script. You can use this binding to run other scripts from a script. |
7.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.
7.2.2. Adding Scripts to Data Grid Servers
Use the command line interface to add scripts to Data Grid servers.
Prerequisites
Data Grid servers store scripts in the ___script_cache
cache. If you enable cache authorization, users must have the ___script_manager
role to access ___script_cache
.
Procedure
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
Open a CLI connection to Data Grid and use the
task
command to upload your scripts as in the following example:[//containers/default]> task upload --file=multiplication.js multiplication
Verify that your scripts are available.
[//containers/default]> ls tasks multiplication
7.2.3. 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
7.3. Running Server-Side Tasks and Scripts
Execute tasks and custom scripts on Data Grid servers.
7.3.1. Running Tasks and Scripts
Use the command line interface to run tasks and scripts on Data Grid servers.
Prerequisites
- Open a CLI connection to Data Grid.
Procedure
Use the task
command to run tasks and scripts on Data Grid servers, as in the following examples:
Execute a script named
multipler.js
and specify two parameters:[//containers/default]> task exec multipler.js -Pmultiplicand=10 -Pmultiplier=20 200.0
Execute a task named
@@cache@names
to retrieve a list of all available caches://containers/default]> task exec @@cache@names ["___protobuf_metadata","mycache","___script_cache"]
7.3.2. Programmatically Running Scripts
Call the execute()
method to run scripts with the Hot Rod RemoteCache
interface, as in the following example:
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);
Reference
7.3.3. Programmatically Running Tasks
Call the execute()
method to run tasks with the Hot Rod RemoteCache
interface, as in the following example:
// 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);
Reference