The UnboundID Server SDK is a set of APIs for developing extensions to the PingData server products, including PingDirectory and PingDataGovernance.
This repository provides components that can be used to develop and package UnboundID Server SDK extensions as Maven projects. The project is provided as a convenient but unsupported alternative to the Server SDK's official Ant-based build mechanisms.
The included components are:
Component | Description |
---|---|
server-sdk-archetype | Generates a Maven project for building extension bundles. |
server-sdk-docs-maven-plugin | Generates an extension bundle's HTML documentation. |
Typically, only the archetype needs to be used directly; the project that it generates will use the docs plugin automatically.
- Generate a project using the archetype
- Implement the Server SDK extension(s)
- Build the extension bundle
- Install the extension bundle
Use the archetype to generate a Maven project, providing your own values for
groupId
and artifactId
:
mvn archetype:generate -DarchetypeGroupId=com.unboundid \
-DarchetypeArtifactId=server-sdk-archetype \
-DarchetypeVersion=1.0.16 \
-DgroupId=com.example -DartifactId=my-extension \
-DinteractiveMode=false
The new project will contain an example extension class in src/main/java
.
To implement your Server SDK extension, modify or replace this class, and add
any others that you need. A single project may include multiple Server SDK
extensions, which will be packaged as a single extension bundle.
You will also need to customize the generated pom.xml
:
- Provide project metadata in the following fields:
name
description
organization
- Set the target PingData version by changing
server-sdk.version
. Examples of valid values are8.1.0.0
and8.2.0.0-EA
.
If you'd like other assets to appear in the extension bundle, place
them in a subdirectory of src/main/assembly
and configure assembly.xml
to include the subdirectory (documentation
here). Any
files that you place in src/main/assembly/config
will be automatically
copied over.
.
├── pom.xml # Extension metadata and extensions go here.
└── src
└── main
├── assembly # Custom files may be placed here; configure with assembly.xml.
│ ├── assembly.xml # Determines the contents of the extension bundle.
│ ├── config
│ │ └── update
│ │ └── file-directives.properties # Governs how files are replaced when updating.
│ └── docs
│ ├── images
│ │ ├── favicon.ico
│ │ └── vendor-name-on-white.png
│ └── ping.css
├── java
│ └── com
│ └── example
│ └── MyExampleExtension.java # Replace this with your extension.
└── resources
├── javadoc
│ └── ping-javadoc-stylesheet.css
└── velocity
├── extension.html.vm
└── index.html.vm
When you are ready to build an extension bundle, run mvn package
.
The extension bundle will be created as a zip in the target
directory.
Install the extension bundle using the manage-extension tool.
$ bin/manage-extension --install com.example.my-extension-1.0-SNAPSHOT.zip
After installing the extension bundle, you'll need to configure the PingData server to use it. The necessary configuration varies depending on the specifics of your extension.
The following notes may be useful to developers making changes to this project. If you're a user of this project (i.e., an extension developer), you can ignore this section.
If you've made changes locally that you wish to test, don't forget to install the local copy:
mvn install
When generating a project from your local archetype, you need to tell
Maven to use the local archetype catalog with the archetypeCatalog
option:
mvn archetype:generate -DarchetypeGroupId=com.unboundid \
-DarchetypeArtifactId=server-sdk-archetype \
-DarchetypeVersion=1.0.16-SNAPSHOT \
-DgroupId=com.example -DartifactId=my-extension \
-DinteractiveMode=false -DarchetypeCatalog=local
When you build the project, the Maven Replacer Plugin
will perform a substitution on a ${server-sdk-docs-maven-plugin.version}
token
in the server-sdk-archetype/pom.xml
file. This allows the server-sdk-docs-maven-plugin
version to be set correctly in the archetype POM. You should not commit this
change to server-sdk-archetype/pom.xml
. Please see the comment in project.build.plugins
for more details.
To update the Server SDK version to correspond to a new server release, you must make two changes.
The server-sdk.version
property in the parent POM
determines the Server SDK version used by the server-sdk-docs-maven-plugin
and server-sdk-archetype components. It does not affect the Server SDK
version used by projects generated from the archetype. That change should
be made to the server-sdk.version
property in the archetype POM.
This is licensed under the Apache License 2.0.