Scripts allow LinkServer administrators and privileged users to execute custom pure-Java code within a Java Virtual Machine (JVM) that runs LinkServer. 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 interface Script
{
public Object execute(ScriptExecutionEnvironment environment) throws ScriptException;
}
This interface declares a single execute() method that is called by LinkServer when script is executed. There are two ways to launch a script:
| • | Automatic execution on LinkServer 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:
public interface ScriptExecutionEnvironment
{
public abstract CallerController getCallerController();
}
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 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:
import com.tibbo.aggregate.common.datatable.*;
import com.tibbo.linkserver.script.*;
public class users_admin_scripts_test implements Script
{
public Object execute(ScriptExecutionEnvironment environment) throws ScriptException
{
}
}
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.
|
Example: changing IP address of a hardware Device Server.
import com.tibbo.aggregate.common.context.*; import com.tibbo.aggregate.common.datatable.*; import com.tibbo.linkserver.*; import com.tibbo.linkserver.script.*;
public class users_admin_scripts_test implements Script { public Object execute(ScriptExecutionEnvironment environment) throws ScriptException { try { // Getting context of a Device Server Context con = LinkServer.getContextManager().get("users.admin.deviceservers.c1", environment.getCallerController());
if (con == null) { throw new ScriptException("Device Server not available"); }
// Getting IP address variable DataTable val = con.getVariable("IP_setting", environment.getCallerController()); // Changing IP address val.rec().setValue("IP_setting", "192.168.1.235"); // Writing new value of variable con.setVariable("IP_setting", environment.getCallerController(), val); // Rebooting Device Server con.callFunction("reboot", environment.getCallerController()); return null; } catch (ScriptException ex) { throw ex; } catch (Exception ex) { throw new ScriptException(ex); } } }
|
|
Every user has his own set of scripts. |
Administering Scripts
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. |
|
Using Scripts In Expressions
It is possible to call a script from an expression by inserting a reference to the execute function of the Script context. Function parameters specified in the reference will be passed to the script. The Execute Script function returns a value that may be referred from the other parts of expression.
|
Example. Here is the expression referring calculator script and passing some input to it:
{users.admin.scripts.calculator:execute("123", "456", "789")}
The script will receive three strings "123", "456" and "789" as an input (see specifying context function input parameters in the reference for details). It may convert these strings to numbers, perform necessary calculations on them and return the result. |
Every script is characterized by several properties:
Field Description |
Field Name |
Script Name. Name of the script context, required to refer to this script from other parts of the system. It should satisfy the context naming conventions, and cannot be changed once the alert is created. |
name |
Script Description. Textual description of the script. This is also a description of the Script context. |
description |
Script Text. Script source in Java programming language. |
text |
Launch Automatically Upon Server Startup. Flag that forces server to launch script during startup. |
autorun |
These properties may be accessed through the childInfo variable.