Maven archetype for OpenDJ plugin development

We have previously written about the plugin development for OpenDJ based on the example-plugin.zip which comes with the binary distribution. However, as OpenDJis evolving and slowly migrating to Maven, on the initiative of the ForgeRockteam we have come up with the Maven archetype to make the plugin development easier and more developer friendly.

Maven greatly reduces the effort in the process of development, and the archetype is a step furthere in that direction. What OpenDJ plugin archetype offers is a project template with the necessary tools to focus on the implementation of the funcionality rather then wasting time and resources in managing the build framework. In other words, the plugin archetype does for you most of the tasks outlined in the article “OpenDJ plugin development based on example-plugin”. Download and installation

The archetype is currently in development and it is not available from the online repository (ForgeRock or otherwise). However, the latest version can be downloaded from: here. The downloaded JAR of the archetype has to be deployed in the local repository before you can use it. To do so, you need to execute the following:

mvn install:install-file

-Dfile=opendj-server-plugin-archetype-1.0.0-SNAPSHOT.jar

-DgroupId=org.forgerock.opendj

-DartifactId=opendj-server-plugin-archetype

-Dpackaging=jar

-Dversion=1.0.0-SNAPSHOT -DgeneratePom=true

File

is the path to the JAR file, and the rest of the parameters should be left as such.

The first step is to create a project for your plugin, let’s call it

Sample Plugin:

mvn archetype:generate

-DarchetypeCatalog=local

-DarchetypeArtifactId=opendj-server-plugin-archetype

-DarchetypeGroupId=org.forgerock.opendj

-DarchetypeVersion=1.0.0-SNAPSHOT

-DgroupId=com.example -DartifactId=sample-plugin

-Dversion=1.0.0-SNAPSHOT -DmessageFile=sample_plugin

-DpluginName=SamplePlugin

Here is the overview of the parameters:

• _archetypeCatalog=local_specifies that the archetype should be looked for in the local repository;
• _archetypeArtifactId=opendj-server-plugin-archetype_is the ID of the archetype in the catalog;
• _archetypeGroupId=org.forgerock.opendj_is the group ID of the archetype;
• _groupId=com.example_is the package to which this plugin belongs to, typically you want this for your own company;
• _artifactId=sample-plugin_is the name of the artifact, normally it is lower case name of the plugin where spaces are substituted with ‘-’ sign;
• _version=1.0-SNAPSHOT_is the version your plugin;
• messageFile=sample_plugin_is the name of the file which stores localised messages for the plugin, it should be the lower case version of the plugin name where the space is substituted with the ‘’ sign - very similar to the artifactId property;
• _pluginName=SamplePlugin_is the name of the plugin which would be used to generate the template Java class and plugin configuration in XML, it should be the camel-case version of the plugin, without spaces.

This would create a directory which corresponds with the value of

artifactId

property, in our case: sample-plugin. The directory would be provisioned with the necessary files to produce a working plugin, and the most relevant are:

pom.xml

src/main/java/com/example/messages/sample_plugin.properties

src/main/java/com/example/SamplePlugin.java

src/main/java/com/example/SamplePluginConfiguration.xml

src/main/xml

pom.xml

defines the project dependencies and all the phases of the build process. Of course, if your plugin implementation requires additional dependencies, processing and so on, you would want to edit this file accordingly.

src/main/java

directory contains the package with the Java classes that implement the functionality of the plugin. The package name corresponds to the

groupId

property, and the files to the

messageFile

and

pluginName

properties as explained above. By default, files that are generated contain the code, the configuration and the messages of the example plugin. You may choose to edit those files or simply get rid of them and use them as an example.

src/main/xml

contains XML framework for processing the plugin configuration and generating the Java code for OpenDJ management infrastructure. Normally, no modifications are required here and if you do modify something, it is very likely something would break. From this point forward, you can start modifying the sources with your own functionality.

In order to generate the plugin it is sufficient to execute:

mvn package

It would perform the necessary transformations, get the dependencies and generate the plugin JAR. The only thing it does not create is the schema file, which you have to write by hand according to the configuration of the plugin. For more details please refer to the article “

OpenDJ plugin development based on example-plugin

“.

Limitations

The archetype currently has several limitations:

• it cannot generate schema automatically;
• it cannot execute unit tests with OpenDJ testing tools.

Todo

For the future versions, it is planned to solve the issues listed in the limitations section and to add the capability to generate javadocs.

References

Discussion on OpenDJ-dev mailing list.

Maven tips and tricks for OpenDJ.

Extending OpenDJ functionality with a plugin.