How to write an alert sender plugin for RHQ/Jopr (Part 1)

Now that RHQ 1.4.0-B01 is out, it is time to show you how you can easily write your own alert notification mechanism and plug it into RHQ (see also "RHQ and the future of alerts").

As an example we'll use a sender that will use a http-POST request to a remote host where the body of the request will contain the alert message (like the one you know from the existing email-sender).

But before we do this, I'll show you the bits involved, so that the source code is easier to understand.

In order to write the plugin you need two things at least:

• plugin descriptor


• a sender class

Sometimes you also want to implement a component class (more later).

So lets have a look at them in turn:

Plugin descriptor

The structure of the plugin descriptor, rhq-serverplugin.xml, looks like this:

It follows the schema definition in rhq-serverplugin-alert.xsd.
Elements in it are the following.

• alert-plugin: This is the parent element for the whole descriptor. It contains the following attributes, which are all taken from the general server plugin descriptor:
  
  
  
  • name: name of the plugin
  
  
  • displayName: name of the plugin as it shows up in the UI
  
  
  • package: the package of the plugin. Is used to determine the fully qualified class name if it contains no package. Within RHQ, there is a naming convention of Alert:medium for this
  
  
  • description: A description of the plugin as it shows up in the list of plugins
  
  
  • version: the version of the plugin.
  
  
  
  

The first few child elements come from the general server-plugin descriptor and apply to all server side plugins.

• help: general information about the plugin, that also shows up in the list of plugins


• plugin-component: class name of a class that gets loaded on plugin start and stays there as a "singleton" until unload. See below.


• scheduled-jobs: this is a configuration that allows you to have your plugin code be run at regular intervals; it is probably less of interest for alert senders


• plugin-configuration: properties listed here will end up in the system-wide preferences system UI and serve to do general configuration of the plugin (like e.g. the name of a remote host where alert notifications should be sent to)

The next batch of elements is specific to the alert-plugins:

• short-name: the short name of the sender. This is used e.g. in UI drop downs to select the sender


• plugin-class: the name of the class that implements the abstract AlertSender class to build the actual sender.


• alert-configuration: specific properties on a per AlertDefinition basis. This can e.g. be the list of email addresses the alert notification should be sent to.


• custom-ui: this element is not yet active and is supposed to help building a custom UI if the UI via alert-configuration is not powerful enough.

The sender class

All senders need to extend the class org.rhq.enterprise.server.plugin.pc.alert.AlertSender which looks a little like this:

public abstract class AlertSender {
 
    /** Configuration from the global per plugin type preferences */
    protected Configuration preferences;
 
    /** Configuration from the per alert definition parameters */
    protected Configuration alertParameters;
 
    /** Global component holding persistent resources */
    protected T pluginComponent;
 
    /** Do the work */
    public abstract SenderResult send(Alert alert) ;
}

The method of interest is send(Alert) where you get the data for this specific alert passed in. You need to implement it.

The preferences or the alert definition specific properties are injected by the RHQ server, as well as the plugin component, so that you can just get your properties that you set up in the deployment descriptor via calls like this:

   String hostname = preferences.getSimpleValue("hostName","localhost");

assuming that you have the following in the plugin descriptor:

....
  <serverplugin:plugin-configuration>
    <c:simple-property name="hostName" />
  </serverplugin:plugin-configuration>
...

Component class (optional)

The component class is a class that implements the interface org.rhq.enterprise.server.plugin.pc.ServerPluginComponent. It can be used to e.g start up a connection to a remote host within the start() method and tear it down when stop() is called. You need to expect that start() and stop() can get calles multiple times during the life of a plugin.

The interface has two more methods: initialize() and shutdown() - those are called directly after loading and before unloading an alert sender. The idea here could e.g. to load an external library and unload it at plugin unload.

The component class is a "singleton" in the lifecycle of a server plugin and stays present while the plugin is loaded. It is optional for alert Plugins - if it is present, it will be injected into AlertSender.pluginComponent.

Plugin structure

The alert sender is created in the standard Maven-2 directory structure. Java sources go into src/main/java/, while the plugin descriptor goes into src/main/resources/META-INF/rhq-serverplugin.xml:

Round up

Ok, that's it for now. You have seen what is involved in writing an alert sender plugin for RHQ and Jopr (versions 1.4.0.B01 and up).

As always give me and us feedback - e.g. via Irc at #rhq on freenode.

Continue with part 2...