UnboundID Server SDK

Building and Deploying Java-Based Extensions

Using the Provided Build Mechanism

The UnboundID Server SDK provides a mechanism that can be used to easily build and package Java-based extensions. It is recommended that this build mechanism be used for extensions to be deployed into production environments because it provides a significant number of features to help make the extension more supportable, 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 can be used to help provide support for the extension. 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 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 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.
   
   
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. If multiple extensions are to be built and packaged into the same jar file, then the property values should be for the collective set of extensions rather than any individual extension.
   
   
4. 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 and the corresponding documentation will be below the build directory, in a subdirectory whose name contains the name and version number for the extension.

If you do want to use the provided build environment to compile and package your extensions, 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 jar file to actually deploy in the server. 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 extensions for deployment in your own build environment, then the resulting 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-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.

Deploying Java-Based Extensions

After your extension has been built and packaged into a jar file, then you may deploy it for use in the server using the following process:

1. Stop the server.
   
   
2. Copy the jar file containing the packaged extension or set of extensions into the lib/extensions directory below the server root.
   
   
3. If your extension depends on any libraries other than the UnboundID Server SDK or UnboundID LDAP SDK for Java, then copy the jar files for those libraries into the lib/extensions directory as well.
   
   
4. Start the server.
   
   
5. 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".
   
   

If you will be deploying 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. Stop the server.
   
   
3. Remove the jar file for the old version of the extension, along with any other jar files for additional third-party libraries used by your extension, from the lib/extensions directory. Then copy the new jar file for your updated extension, as well as the jar files for any dependent libraries, into the lib/extensions directory. It is recommended that you delete all existing versions of those jar files (or back them up into a different directory that will not be in the server classpath) rather than merely overwriting them to avoid the potential for having multiple versions of the jar files in the classpath at the same time (e.g., if the names of the new jar files are slightly different than the names of the previous files), which can cause erratic and/or incorrect behavior, or may even prevent the server from starting.
   
   
4. Start the server.
   
   
5. 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. Replace the extension 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.