Server Hooks

Server Hooks allow you to write JavaScript code to respond to events and errors that occur at the server level. Unlike AssemblyLine and component Hooks, Server Hooks are stored in separate script files. These files are kept in the serverhooks folder in the current solution directory and must contain specifically named script functions. The Security Directory Integrator server and configuration instances provide a method for SDI components to invoke custom Server-level Hooks. A Server Hook is a function name that is defined in a script file. Function implementations are provided by simply dropping script files in the "serverhooks" directory of the solution directory.

In addition to these Hooks being called by the Server when specific events occur, they can also be invoked from your scripts. Calls to these Hooks are synchronized to avoid potential multi-threading issues.

Upon startup, SDI loads and executes all user scripts in the serverhooks subdirectory. Scripts may or may not contain function declarations. A script that has no function declarations is executed once at startup before any configuration instances are started. Code that defines standard SDI Server Hook functions are prefixed with "SDI_"., and these are executed at various points during operation. All SDI Server Hook functions have the following JavaScript signature:

/**
 	 * @param NameOfFunction The configuration instance invoking the function
	 * @param source The component invoking the function
	 * @param user Arbitrary parameter information from the source
	 */
	function SDI_functionName(Name_of_function, source, user) {
	}

The "NameOfFunction" and "source" parameters always provide access to the Config Instance and calling component, respectively. The "user" parameter is used for different purposes in the various Hook functions. The following standard function names are invoked by various SDI components:

Function Name	Called by (source)	User Parameter and Expected Value
SDI_ALStarted	Config Instance	Called when an AssemblyLine is started. user = The AssemblyLine that started return value ignored
SDI_ALStopped	Config Instance	Called when an AssemblyLine stopped. user = The AssemblyLine that stopped return value ignored
SDI_ConfigStarted	Server	Called when a Config instance started. user = The configuration instance return value ignored
SDI_ConfigStopped	Server	Called after a Config instanced stopped. user = The configuration instance return value ignored
SDI_Shutdown	Server/Config Instance	Called immediately before the SDI server is terminating the JVM (for example, System.exit()). user = Exit status (integer) return value ignored

Access to SDI Server Hook functions is provided through the main.invokeServerHook() method. This function is synchronized to prevent more than one thread executing a Hook at a time. All calls are invoked synchronously so the caller will wait for the function to return. As a result, care should be taken not to spend too much time in a server Hook.

As mentioned previously, scripts are defined and made available by creating files in the "serverhooks" subdirectory of the solution directory. Scripts that contain sensitive information should be encrypted with the Server-API before adding it to the directory. The serverapi/cryptoutils tool is available for encrypting script files. Note that SDI automatically tries to decrypt files with extension .jse, hence encrypted files should preferably have that extension.

Furthermore, the files in the serverhooks directory are loaded and executed after first sorting the file names using case-sensitive sort with the standard collating sequence for the platform. All files in the top-level directory are loaded before files in any subdirectories are processed. Some examples Server Hook use are:

• A custom object that you always want loaded in SDI for use for our own scripting could be instantiated from a JavaScript snippet hooked into the server Hook on SDI startup. This gives you more control than simply referring to the class under the Java Libraries folder in the Config Browser.
• One or more custom ALs that you start creates an audit log for these events or propagates these events to other systems using some transport (SNMP, HTTP, JMS, and so forth).
• A corporate security policy you implement that is invoked every time a Config is loaded or AL started.

• Calling Server Hooks from script
  

Parent topic:

Scripting in an AssemblyLine