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
It will automatically build API documentation (i.e., javadoc) for the
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:
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
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.
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
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.
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.
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‑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.
Extension jar – The jar file containing the extension
implementation classes. It must contain the attributes in the manifest file as
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:
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 "18.104.22.168"). 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:
Install the extension bundle with the --install option of the
manage-extension tool. For example:
bin/manage-extension --install extensionBundle.zip
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:
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.
Update the extension bundle with the --update option of the
manage-extension tool. For example:
bin/manage-extension --update extensionBundle.zip
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:
Stop the server.
Update the extension bundle with the manage-extension tool as detailed
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.
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:
Use the dsconfig tool or the web-based administration console to disable
or remove the configuration objects for the extensions from the bundle to
Stop the server.
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.
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.