Scripts

Scripts allow AggreGate Server administrators and privileged users to execute custom pure-Java code within a Java Virtual Machine (JVM) that runs AggreGate Server. Every script is executed inside server core and has access to all in-memory objects and structures of the server. Thus, scripts are very powerful tool that provide an ability for a full real-time control of the server.

Scripts are executed in server JVM and their permissions are not restricted in any way. Thereby a single unintentional error in a script, or some malicious code, may cause the server to function improperly, hang, get 100% CPU time, corrupt its database or even corrupt data on the machine running it. By default, only the default administrator may modify and execute scripts. Give only trusted users permissions to execute scripts.

To let another user execute scripts, set his permission level in Scripts context to Admin. This will allow the user to execute all scripts in this context.

To allow execution of a single script, set the user's permission level in that Script context to Admin.

Scripts are written in Java. Every script is a single Java class that must implement a Script interface:

public Object execute(ScriptExecutionEnvironment environment, Object... parameters) throws ScriptException;

This interface declares a single execute() method that is called by AggreGate Server when script is executed. There are two ways to launch a script:

•	Automatic execution on AggreGate Server startup. The script is executed by the server automatically during startup if the Launch Automatically Upon Server Startup flag is enabled in stript properties.

The script may return some data in the form of Java Object. This object is converted to a Data Table to be returned by the execute function of the Script context. If script returns an instance of DataTable class, this Data Table is returned by the execute function unchanged. Otherwise a single-cell table is created and script output is stored in the cell of this table. If class of object returned by the script is not supported by the Data Tables engine, this object is converted to String by calling Object.toString(). If script returns NULL, a single-cell table with nullable string field is returned by the execute function.

Every script has access to an object implementing ScriptExecutionEnvironment interface that is passed as an argument to execute() method. Here is what ScriptExecutionEnvironment interface look like:

Instance of ScriptExecutionEnvironment provides access to an object implementing CallerController interface (it is obtained by calling getCallerController() method). This object incorporates permissions of a user that initiated script execution. CallerController object is passed as an argument to most of context-related operations (Get Context, Get/Set Variable, Call Function, Add/Remove Event Listener etc.)

When a script is launched automatically during server startup, its execution environment contains a system CallerController that suppresses all permission checking.

When a new script is created, its text is not empty. It contains an auto-generated stub of a class implementing Script interface with an empty execute() method. Here is the default script text:

public Object execute(ScriptExecutionEnvironment environment) throws ScriptException

Note, that %ScriptClassNamePattern% will be replaced by an auto-generated Java class name during compilation. Do not change this part of the script to avoid compilation problems.

After you've put some meaningful code inside the body of execute() method, you may try to execute a script. Note, that script is re-compiled by Java compiler upon every execution. Any compilation errors are reported to the user. See description of Execute action for more information.

Two contexts are used to administer the scripts: One is the general Scripts context, which serves as a container. The other is the Script context, which holds information for one particular script.

ls_scripts