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:

• It will automatically generate documentation for the extensions, including usage information for available arguments and potentially including example argument sets.
  
  
• It will automatically build API documentation (i.e., javadoc) for the extensions.
  
  
• It will include a number of attributes in the jar file manifest that are required by the manage-extension tool. Some of the information included is the build time, extension name and version, contact information for the individual or group that will support the extension, and the version of the UnboundID Server SDK used to build the extension.
  
  
• It will assemble all custom and metadata files into the file structure required by the manage-extension tool. It also contains default metadata files that are easily customizable if needed.
  
  
• It provides an option to include the source code for the extension along with the compiled classes in the resulting jar file. This helps ensure that the source is not lost and that the specific version of the source used for the compiled extension is available.
  
  

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:

• Extension jar – The jar file containing the extension implementation classes. It must contain the attributes in the manifest file as described below.
• lib – This directory should contain all dependency jars needed by the extension classes.
• docs – Any documentation for the extensions, including Javadoc. This could be automatically generated using the provided build mechanism.
• config – This directory should contain all custom configuration files needed by the extension.
• config/update – A baseline copy of all configuration files designed for user customization.
• config/update/file-directives.properties – The properties file that instructs the manage-extension tool on what to do with the installed extension files during an update install. For example, to replace a installed file config/config.cfg in the bundle with the updated version unless it is modified, include the following line in the properties file:
  
  config/config.cfg=IGNORE_IF_MODIFIED
  
  Please refer to default file included with the provided build mechanism for a complete list of possible directives.

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

• Implementation-Title – The name of the extension or set of extensions contained in the archive. This should contain only ASCII alphabetic letters, numeric digits, the period, and the dash characters, and it must begin with a letter.
  
  
• Implementation-Version – The version string for the extension. This should contain only ASCII alphabetic letters, numeric digits, the period, and the dash characters, and it must begin with a number or letter.
  
  
• Implementation-Vendor – The name of the company or organization that created the extension.
  
  
• Implementation-Vendor-Id – The unique ID of the name of the company or organization that created the extension. It should use a notation similar to that of Java package names.
  
  
• Implementation-URL – The URL of the website for the company or organization that created the extension.
  
  
• Extension-Support-Contact – Information that may be used to contact the individual or group of people responsible for supporting the extension (e.g., an e-mail address or telephone number).
  
  
• UnboundID-Server-SDK-Version – The numeric version for the UnboundID Server SDK jar file used to build the extension. It should be in the form "MAJOR.MINOR.POINT.PATCH" (e.g., if the major version is 1, the minor version is 2, the point version is 3, and the patch version is 4, then the numeric version string should be "1.2.3.4"). See the com.unboundid.directory.sdk.common.types.Version class for the Server SDK version number, or invoke the command "java ‑jar unboundid‑server‑sdk.jar".
  
  

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.