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 TDI server and configuration instances provide a method for TDI 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 the scripts. Calls to these Hooks are synchronized to avoid potential multi-threading issues.
Upon startup, Tivoli Directory Integrator 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 TDI Server Hook functions are prefixed with "TDI_"., and these are executed at various points during operation.
All Tivoli Directory Integrator 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 TDI_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 Tivoli Directory Integrator components:
Function Name | Called by (source) | User Parameter and Expected Value |
---|---|---|
TDI_ALStarted | Config Instance | Called when an AssemblyLine is started.
user = The AssemblyLine that started return value ignored |
TDI_ALStopped | Config Instance | Called when an AssemblyLine stopped.
user = The AssemblyLine that stopped return value ignored |
TDI_ConfigStarted | Server | Called when a Config instance started.
user = The configuration instance return value ignored |
TDI_ConfigStopped | Server | Called after a Config instanced stopped.
user = The configuration instance return value ignored |
TDI_Shutdown | Server/Config Instance | Called immediately before the TDI server is
terminating the JVM (for example, System.exit()).
user = Exit status (integer) return value ignored |
Access to TDI 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 Tivoli Directory Integrator 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:
Parent topic: Scripting in an AssemblyLine