mvn org.rhq:agent-plugin-gen [-Ddescriptor-file=/path/to/rhq-plugin.xml] [-DoutputDir=/path/to/the/new/plugin/project]
As of today, to develop an RHQ agent plugin with Maven one has to use the standard JAR packaging and declare many different Maven plugins executions (like Dependency Plugin or ANT Plugin) to implement things like:
copying dependencies somewhere in the build directory
deploying the agent plugin to a development container
setting up integration tests with a standalone plugin container
It would be nice to have a custom Maven packaging for agent plugins and a set of mojos to get (at least) the same things done with only a few lines of configuration.
A prototype is on Github: https://github.com/tsegismont/rhq-agent-plugin-plugin
With Maven, one way to describe a custom packaging is to create and share an assembly descriptor, as described in the Maven documentation. But this is less powerful than a "native" custom Maven packaging which can take control of the build lifecycle (custom phases).
A mojo is the implementation of a Maven goal see Introduction to Maven 2.0 Plugin Development.
The packaging mojo takes care of the plugin archive creation. Like the war mojo does, the rhq-agent-plugin mojo should be able to determine the dependencies of scope RUNTIME required by the agent plugin and automatically add them under the lib/ directory of the archive.
In the prototype, the main project artifact is the plugin archive. This means that what you will find in Maven repositories is the plugin archive embedding its dependencies, not a simple JAR of the plugin classes. It's possible in the future to add a parameter to attach a JAR of classes (with classifier) to the list of project artifacts.
Note that the prototype make uses of the Maven Archiver utility. This will allow the RHQ team to conform with the JBoss.org standard for manifest file entries.
The prototype has a mojo which can deploy the built archive to a local development container. It is not activated (bound to a phase) by default.
It would be nice to be able to deploy the plugin archive to a remote RHQ server (needs to add plugin deployment feature to the REST API).
It's possible to create a mojo which does not require an existing project. We could use this feature to generate a skeleton project. One would type:
mvn org.rhq:agent-plugin-gen [-Ddescriptor-file=/path/to/rhq-plugin.xml] [-DoutputDir=/path/to/the/new/plugin/project]
And would get a Maven project generated with a pre-configured POM and skeleton component and discovery classes.
The code of the plugin-gen helper might be reused here.
The agent plugin descriptor schema allows to add help sections as html. There is a plugin documentation generator tool which can be reused / repackaged in this plugin.
This would not be activated by default.
There is a plugin validator tool which can be reused / repackaged in this plugin.
This would not be activated by default.
This mojo would prepare in the build directory a standalone plugin container for integration tests. The platform plugin and the Sigar libraries would be there.
Most of the plugins maintained by the RHQ team use this standalone container technique. We might still prefer to favor the usage of the Arquillian Integration For Agent Plugins in the future.
Here is an example project POM (see comments):
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.mycompany.rhq.agent.plugins</groupId>
<artifactId>my-custom-plugin</artifactId>
<version>1.0-SNAPSHOT</version>
<!-- This project has the custom plugin packaging -->
<packaging>rhq-agent-plugin</packaging>
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
</properties>
<dependencies>
<!-- Dependencies provided by the plugin container -->
<dependency>
<groupId>org.rhq</groupId>
<artifactId>rhq-core-domain</artifactId>
<version>4.6.0</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>org.rhq</groupId>
<artifactId>rhq-core-plugin-api</artifactId>
<version>4.6.0</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>org.rhq</groupId>
<artifactId>rhq-core-native-system</artifactId>
<version>4.6.0</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>commons-logging</groupId>
<artifactId>commons-logging</artifactId>
<version>1.1.1</version>
<scope>provided</scope>
</dependency>
<!-- Dependencies required by my plugin -->
<!-- All dependencies under RUNTIME scope will be included in the plugin archive -->
<dependency>
<groupId>commons-httpclient</groupId>
<artifactId>commons-httpclient</artifactId>
<version>3.1</version>
<exclusions>
<exclusion>
<groupId>commons-logging</groupId>
<artifactId>commons-logging</artifactId>
</exclusion>
<exclusion>
<groupId>commons-codec</groupId>
<artifactId>commons-codec</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>commons-codec</groupId>
<artifactId>commons-codec</artifactId>
<version>1.3</version>
</dependency>
<!-- Some test dependencies -->
<dependency>
<groupId>org.rhq</groupId>
<artifactId>rhq-core-plugin-container</artifactId>
<version>4.6.0</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.rhq</groupId>
<artifactId>test-utils</artifactId>
<version>4.6.0</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.rhq</groupId>
<artifactId>rhq-core-plugin-container</artifactId>
<version>4.6.0</version>
<type>test-jar</type>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<plugins>
<!-- This is to get the Maven version available as a property -->
<!-- It will be used to customize the archive manifest file -->
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>build-helper-maven-plugin</artifactId>
<executions>
<execution>
<phase>initialize</phase>
<goals>
<goal>maven-version</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.rhq.maven.plugins</groupId>
<artifactId>rhq-agent-plugin-plugin</artifactId>
<version>0.1-SNAPSHOT</version>
<!-- Tell Maven that this plugin will extend the standard lifecycle and packaging -->
<!-- Without this the build fails to recognize the custom packaging -->
<extensions>true</extensions>
<configuration>
<!-- Here comes the project manifest customization -->
<archive>
<manifest>
<addDefaultSpecificationEntries>true</addDefaultSpecificationEntries>
<addDefaultImplementationEntries>true</addDefaultImplementationEntries>
</manifest>
<manifestEntries>
<Maven-Version>${maven.version}</Maven-Version>
<Java-Version>${java.version}</Java-Version>
<Java-Vendor>${java.vendor}</Java-Vendor>
<Os-Name>${os.name}</Os-Name>
<Os-Arch>${os.arch}</Os-Arch>
<Os-Version>${os.version}</Os-Version>
<Build-Number>${buildNumber}</Build-Number>
<Build-Time>${buildTime}</Build-Time>
</manifestEntries>
</archive>
</configuration>
<executions>
<!-- Here we configure the execution of optional mojos -->
<execution>
<id>deploy-to-dev-container</id>
<goals>
<goal>rhq-agent-plugin-deploy</goal>
</goals>
<phase>package</phase>
<configuration>
<deployDirectory>/path/to/dev/container/deploy/dir</deployDirectory>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>
Maven archetypes have very limited features: they only allow to template the creation of a project, as explained in the Introduction to Archetypes.
Still they are very easy to create: you setup a model project and then ask Maven to create an archetype from this model
We might prepare an archetype for:
a standard agent plugin
a plugin depending on the JMX plugin
Both would generate a project with pre-configured custom packaging and pre-configured plugin mojos executions.