3.2. Writing Agent Plug-ins Using a Template

The RHQ source files includes a plug-in generator. The generator goes through a series of questions that cover most of the common configuration options for agent plug-ins, such as whether monitoring is enabled and whether there is a required JMX dependency. The generator creates the basic files including the pom.xml file, rhq-plugin.xml descriptor, and all of the associated Java files for the project. The agent plug-in can then be written and built on that template framework.
  1. It is possible to build the plug-in generator from source; the files are in the rhqInstallDir/modules/helpers/pluginGen/ directory. Alternatively, the latest version can be downloaded from http://rhq-project.org/display/RHQ/Plugins+-+Plugin+Generator.
  2. Launch the generator.
    java -jar rhq-pluginGen-version_#-jar-with-dependencies.jar
  3. Answer the questions prompted in the generator. The first pass defines the root element for the plug-in descriptor; subsequent series configure children within the plug-in. The prompts are described in Table 3.1, “Plug-in Generator Questions”.

    Table 3.1. Plug-in Generator Questions

    Prompt Parameter Description
    The plugin root category PLATFORM(P), SERVER(S), SERVICE(I) Sets the resource type of the root element in the plug-in. The value here corresponds to the <platform>, <server>, and <service>.
    Name Gives the name of the plug-in. This corresponds to the <plugin name="name" value.
    PackagePrefix Sets the name of the classes used by the plug-in. This corresponds to the package attribute in the <plugin element of the descriptor.
    This option is only given for the first plug-in element.
    FileSystemRoot
    Gives an absolute path to the location where the plug-in project directory should be created.
    This option is only given for the first plug-in element.
    ComponentClass Gives the name of the plug-in component Java file to create. This file is created with all of the required imported classes defined, based on the other functionality enabled in the generator.
    DiscoveryClass Gives the name of the discovery component Java file to create. This file is created with all of the resource discovery classes imported.
    If it should support Events Sets whether the plug-in will allow event (log) collection. If so, this options creates an <events> element in the descriptor and a corresponding *EventPoller.java file.
    Description
    ParentType Creates a parent plug-in type (<runs-inside>) element in the descriptor.
    This option is only given for the first plug-in element.
    If it should support Monitoring Sets whether the plug-in will allow monitoring. If so, this options creates a <metric> element in the descriptor.
    If it should support Operations Sets whether the plug-in will allow monitoring. If so, this options creates an <operation> element in the descriptor.
    If it should support Singleton Sets whether the plug-in is a singleton. If yes, it adds the singleton=true attribute to the resource element.
    If it should support ResourceConfiguration Sets whether this resource type has configuration properties that can be managed through the JBoss ON GUI. This corresponds to the <resource-configuration> properties in the descriptor.
    If it should support SupportFacet
    If it should support CreateChildren Sets whether children can be discovered and added to the resource inventory.
    If it should support UsesExternalJarsInPlugin Asks whether external (non-JBoss ON) JAR files are required by the plug-in. These files and classes must be imported by manually editing the plug-in files.
    If it should support DeleteChildren Sets whether children can be deleted from the resource inventory.
    If it should support ManualAddOfResourceType Sets whether children resources can be manually added to the resource's inventory.
    If it should support UsePluginLifecycleListenerApi Sets whether this plug-in will use the listener API.
    This option is only given for the first plug-in element.
    If it should support DependsOnJmxPlugin Sets whether this plug-in requires the JMX plug-in.
    This option is only given for the first plug-in element.
    RhqVersion Gives the version of the JBoss ON server and agent that this is used with.
    This option is only given for the first plug-in element.
    Do you want to add a child to testServer? Prompts whether to add a child element to the plug-in.

  4. The second part of the generator prompts for any children elements to be added within the plug-in. These will commonly be services contained within the plug-in. These have the same series of questions as in step 3.
    The generator continues prompting for children until you enter N to complete the setup.
  5. The generator creates the Maven product for the agent plug-in in the specified directory with the standard directory layout. It also creates templates for all of the required plug-in files:
    • The project pom.xml file
    • The rhq-plugin.xml descriptor file
    • nameComponent.java files for the plug-in and any children
    • nameDiscoveryComponent.java files for the the discovery component for the plug-in and any children
    • nameEventPoller.java files for any element which supports events
  6. Edit the generated files to finish out the plug-in.
  7. Build an agent plug-in.
    1. Go to the top directory for the agent plug-in project.
    2. Run the Maven build command:
      mvn install
      This command builds the plug-in into a JAR file which can be uploaded to the JBoss ON server to deploy to the agents. The JAR file is named pluginName-version.jar and is located in a target/ directory.