UnboundID Server SDK

Building and Deploying Scripted Extensions

The UnboundID Server SDK provides support for writing and deploying certain kinds of extensions using a dynamic scripting language as an alternative to compiled Java code. The primary benefit that this offers is that it is possible to deploy extensions without the need to compile or package them into jar files. It is also possible to deploy new or updated extensions without the need to restart the server (as long as those extensions do not require adding or updating any third-party libraries provided in jar files). Using a dynamic scripting language rather than compiled Java code may incur a penalty in performance, but in many cases the actual impact to server performance is minimal.

At the present time, only the Groovy language may be used for scripted extensions. Groovy provides the benefit of nearly perfect Java compatibility, although it does offer additional features and conveniences that Java by itself does not provide. When writing scripted extensions with Groovy, you may choose to either stick to only Java-compatible syntax, or use the full capabilities offered by Groovy.

You can deploy Groovy-scripted extensions as either individual script files or bundled in jar files (in which the jar files merely contain the Groovy scripts in the appropriate directory hierarchy). To deploy an extension using individual script files, the process is as follows:

1. If the extension depends on any third-party libraries (other than the UnboundID Server SDK or UnboundID LDAP SDK for Java), you must first stop the server, place the jar files for those libraries in the lib/extensions directory below the server root, and re-start the server. If the extension does not have any requirements on any third-party libraries, then this step is not required.
   
   
2. Create an appropriate directory hierarchy for any package(s) used by the script files below the lib/groovy‑scripted‑extensions directory and copy the script files into those directories as appropriate.
   
   
3. Use the dsconfig tool or the web-based administration console to create configuration objects for your extension as needed. Use the "groovy‑scripted" type for the extension, and supply the fully-qualified name of the Groovy class providing the logic for the extension in the script‑class property. If your extension requires any arguments, then specify them as values to the script‑argument property. Each argument should be provided as a separate property value in the form "name=value".
   
   

If your scripted extensions are to be deployed in a jar file, then the process is the same, except that the jar file containing the Groovy scripts should be placed directly in the lib/groovy‑scripted‑extensions directory without the need to create any subordinate directory structure. Note, however, that if you use jar files (or a mix of jar files and individual scripts), you must be careful to ensure that you do not install conflicting versions of the same scripts.

In order to deploy an updated version of an existing scripted extension, the process is as follows:

1. Use dsconfig or the administration console to disable the existing configuration objects for the scripted extension types to be updated.
   
   
2. If the extension depends on any third-party libraries and the new version of the extension requires new versions of those libraries, then you must stop the server, delete the files for the old versions of those libraries from the lib/extensions directory, copy the new versions of those libraries into that directory, and start the server. If your extension does not depend on any third-party libraries, or if you do not need to update the versions of the libraries that it does use, then this step is not required.
   
   
3. Remove the files for the existing version of the extensions (whether the individual script files or jar files containing the scripts) and deploy the updated versions of those files.
   
   
4. Use dsconfig or the administration console to re-enable the configuration objects for the updated extensions. If the updated version requires any argument changes, then you can make those argument changes in the configuration objects at this time.
   
   

A few extensions cannot be disabled. The above procedure could be followed by deleting and re-adding the extension in place of disabling it and re-enabling it. Alternatively, the offline mode of dsconfig can be used as follows:

1. Stop the server.
   
   
2. Replace the extension script file(s) or jar file(s) as detailed above.
   
   
3. Using dsconfig in offline mode, make any necessary configuration changes (e.g., by updating the set of extension arguments as necessary). Do this with care as it will bypass validation of the arguments by the extension.
   
   
4. Start the server and look for warnings related to the extension's new arguments.