UnboundID Server SDK

Ping Identity
UnboundID Server SDK Documentation
Getting Started with the UnboundID Server SDK

Building and Deploying Java-Based Extensions

Extension Packaging Overview

A set of extension implementations written using the UnboundID Server SDK along with metadata, dependent library jars, and any custom configuration files are packaged up for install in an extension bundle. An extension bundle is just a directory that is optionally zip archived and contains a special file structure, required jar file manifest attributes, and metadata files. Each extension bundle is identified by a unique ID generated from the bundle's vendor ID and a unique bundle name. All extension bundles are installed into their own root directory named by its ID in the extensions directory below the server root. Extensions bundles are easily installed, updated, and managed using the manage-extension tool.

During the installation process, the tool will use the information provided in the manifest attributes of the extension jar file to verify that the bundle is compatible with the server and that it is not already installed. The extension jar file as well as the docs, lib, and config sub-directories of each extension bundle are copied to their own directory under extensions directory in the server instance root. A manifest file will be generated to inventory all files in the bundle so any modifications may be detected when the extension is updated.

During the update process, existing contents from the installed extension bundle will be replaced by the contents in the updated extension bundle. When done, new contents in the updated extension bundle but not present in the installed extension bundle are then copied. A file-directives.properties file may be used to customize exactly what files to replace and what to do if it was modified since the they were installed. It could also delete, ignore, or back up files if needed. A new manifest file will be generated to inventory the contents of the new bundle.

Using the Provided Build Mechanism

The UnboundID Server SDK provides a mechanism that can be used to easily build and package Java-based extension bundles. It is recommended that this build mechanism be used for extension bundles to be deployed into production environments because it provides a significant number of features to help make the extension more supportable and compatible with the manage-extension tool, including:

In order to build and package one or more extensions into an extension bundle using the provided build mechanism, use the following process:

  1. Create or copy the extension source files into the src directory, creating an appropriate directory hierarchy for the Java packages used for the extensions. Ensure a nullary constructor is available in all extension classes.

  2. If the extensions have any dependencies on third-party libraries (other than the UnboundID Server SDK or UnboundID LDAP SDK for Java, which will automatically be included in the build classpath), then the jar files for those libraries should be copied into the lib directory.

  3. Edit the extension.properties file to set values for the properties used to specify the name, version, and vendor information for the extension bundle. The vendor ID attribute should be unique for the individual or group that supports the extensions and should use the Java package naming convention. The name attribute should uniquely identify this extension bundle for the vendor.

  4. Place any custom configuration files needed by the extensions in the config directory. It is also recommended to also place a copy of each configuration file named with a version number in the config/update directory. They could be used as a baseline after an update so the user of the extension may easily identify their customizations for a particular deployment.

  5. Review the config/update/file-directives.properties file to ensure the manage-extension tool will correctly update the files needed by the extension during an update install. Care should be taken to not replace any custom configuration files that were modified after the install.

  6. Invoke the "build.sh" shell script (or build.bat batch file on Windows systems) with no arguments to build and package the extensions.

After the build process has completed, the jar file containing the packaged extension bundle and the corresponding documentation will be below the build directory, in a subdirectory whose name contains the vendor ID, name, and version number for the extension. A zip archive with the same name will also be created.

If you do want to use the provided build environment to compile and package your extension bundle, then you may want to check the entire build environment into a version control system along with your source code. In that case, simply develop your extensions in the src directory. You will probably want to configure the version control system to ignore the build directory, since it will contain dynamically-generated files.

Using an Alternate Build Environment

If you would rather create your own build environment than use the one provided with the server SDK, then all that is really required is to have the unboundid‑server‑sdk.jar and unboundid‑ldapsdk‑ce.jar jar files in your classpath.

If you do use a separate build environment, then it is still recommended that you use the provided build environment as described above to create the extension jar file to include in the bundle. This will ensure that all of the appropriate manifest attributes are in place, and will provide the additional benefit of generating javadoc and other extension-specific documentation.

If you consider it absolutely necessary to package an extension bundle for deployment in your own build environment, then the resulting directory must have the following file structure:

When packaging a zip archive of the extension bundle, the bundle directory must be included as a base directory in the archive.

The extension jar files must contain a manifest with the following attributes:

It is also strongly recommended that you package the source code for the extension in the jar file along with the compiled classes to make it easier to support the extension if problems arise in the future and the source code is needed to help in troubleshooting the problem.

Installing Extension Bundles

After your extension has been built and packaged into an extension bundle, then you may install it for use in the server:

  1. Install the extension bundle with the --install option of the manage-extension tool. For example:

    bin/manage-extension --install extensionBundle.zip

  2. Use the dsconfig tool or the web-based administration console in order to create configuration objects for your extension as needed. Use the "third-party" type for the extension, and supply the fully-qualified name of the Java class providing the logic for your extension as the value of the extension‑class property. If your extension requires any arguments, then specify them as values to the extension‑argument property. Each argument should be provided as a separate property value in the form "name=value".

Updating Extension Bundles

If you will be installing an updated version of an existing extension rather than a new extension, then the process is similar:

  1. If the new version of the extension requires a set of arguments that is incompatible with the previously deployed version, then use the dsconfig tool or the administration console to disable any existing instances of the extension. This is not necessary if the current set of arguments for the extension will be compatible with the new version.

  2. Update the extension bundle with the --update option of the manage-extension tool. For example:

    bin/manage-extension --update extensionBundle.zip

  3. If you had previously disabled the configuration objects for the existing versions of your extensions, then make any necessary configuration changes (e.g., by updating the set of extension arguments as necessary), and then re-enable the extensions.

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. Update the extension bundle with the manage-extension tool 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.

Un-installing Extension Bundles

To completely remove an extension bundle and all included extensions:

  1. Use the dsconfig tool or the web-based administration console to disable or remove the configuration objects for the extensions from the bundle to uninstall.

  2. Stop the server.

  3. Delete the extension bundle directory under extensions directory in the server instance root. The extension bundle directory is named by the unique ID of each extension bundle, which is generated from the bundle's vendor ID and a unique bundle name.

  4. Start the server and look for warnings related to any extension classes that are not found. These classes were probably included in the bundle that was just un-installed. These configuration objects will need to be disabled or removed.

Customizing the Installation Process

There may be times where custom code needs to run during certain stages of the installation/update process to perform extra validation checks or to perform migrations of custom configuration files. The manage-extension tool's behavior is extensible by including implementations of Manage Extension Plugins in the extension bundle. Multiple plugins may be included and they will be invoked in the order listed by the extension jar's manifest attribute.