Maven archetype for OpenDJ plugin development

Posted 12 years ago by Nemanja Lukic

We have previously written about the plugin development for OpenDJ based on the example-plugin.zip which comes with the binary distribution. However, as OpenDJ is evolving and slowly migrating to Maven, on the initiative of the ForgeRock team 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 artifactIdproperty, 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.

Nemanja Lukic

3 Responses to “Maven archetype for OpenDJ plugin development”

  1. Laszlo says:

    Thanks, great work. I try it now.

    Here are the working command samples:

    mvn install:install-file
    -Dfile=opendj-server-plugin-archetype-1.0.0-SNAPSHOT.jar
    -DgroupId=org.forgerock.opendj
    -DartifactId=opendj-server-plugin-archetype
    -Dversion=1.0.0-SNAPSHOT
    -Dpackaging=jar -DgeneratePom=true

    mvn archetype:generate -DarchetypeCatalog=local
    -DarchetypeGroupId=org.forgerock.opendj
    -DarchetypeArtifactId=opendj-server-plugin-archetype
    -DarchetypeVersion=1.0.0-SNAPSHOT
    -DgroupId=com.example
    -DartifactId=sample-plugin
    -Dversion=1.0.0-SNAPSHOT
    -DmessageFile=sample_plugin
    -DpluginName=SamplePlugin

  2. Matt Swift says:

    Hi Nemanja,

    This is really cool. 🙂

    Even though we’re still missing the necessary support in OpenDJ required in order to generate the LDAP schema and run unit tests, I think that we should still try and get this into the OpenDJ Maven repository, what do you think?

    Cheers,

    Matt

Leave a Reply

Related articles