RHQ plugins - platform services

There was recently a question on the Jopr devel mailinglist, that Ian Springer answered - I've taken his answers to write this post, as this is of general interest to plugin writers.

Bruno asks:
I have written a plugin which defines a single service like so:

<plugin ...>
  <service
      name="Interdomain Service"
      ...
      supportsManualAdd="true">
  </service>
</plugin>

But during auto-discovery, the resource discovery component does not get called. It only gets called, if I define the Interdomain Service to be a server. What am I missing here?

Lets first have a look at the resource hierarchy within RHQ:

So for <server>s that are standalone within a <plugin> tag, it is obvious that the parent is the <platform>, while <service> can have both other ResourceCategory as parent.

This means that you have to define the service's parent type(s), so RHQ knows where to stick it in the type hierarchy once it's discovered. There are a few ways to do this, depending on your needs.

If it's a platform service (i.e. a service whose parent is the platform
itself), you'd do something like:

<service name="Interdomain Service" ...>
  <runs-inside>
    <parent-resource-type name="Windows"  plugin="Platforms"/>
    <parent-resource-type name="Linux"    plugin="Platforms"/>
    <parent-resource-type name="Solaris"  plugin="Platforms"/>
    <parent-resource-type name="HP-UX"    plugin="Platforms"/>
    <parent-resource-type name="AIX"      plugin="Platforms"/>
    <parent-resource-type name="FreeBSD"  plugin="Platforms"/>
    <parent-resource-type name="Mac OS X" plugin="Platforms"/>
    <parent-resource-type name="Java" plugin="Platforms"/> <!-- any OS that RHQ doesn't have native (i.e. SIGAR) support for -->
  </runs-inside>
      ...
</service>

(If your service will only run on certain OS'es, you could remove the
unsupported platform types from the list of parent types).

Or you could do something similar to say it can be the child of multiple
server or service types, e.g.:

<service name="Interdomain Service" ...>       
  <runs-inside>
    <parent-resource-type name="JMX Server" plugin="JMX"/>
    <parent-resource-type name="JBossAS Server" plugin="JBossAS"/>
    <parent-resource-type name="JBossAS Server" plugin="JBossAS5"/>
  </runs-inside>
      ...
</service>

Finally, if you want it to be a child of a single server or service type
defined in the same plugin, just nest it inside the parent server or
service element, e.g.:

<server name="CoolServer">
   <service name="Interdomain Service" ...>
      ...
   </service>
   ...
</server>

The reason it works if you change it to a server, rather
than a service, is because, when parsing the plugin descriptor, if RHQ
encounters a server element at the top level with no runs-inside types
defined, it assumes the server is a platform server (a server who has
all the platform types as its parents). So:

<server name="Interdomain Service" ...>
    ...
</server>

is essentially equivalent to:

<server name="Interdomain Service" ...>
  <runs-inside>
    <parent-resource-type name="Windows"  plugin="Platforms"/>
    <parent-resource-type name="Linux"    plugin="Platforms"/>
    ...
    <parent-resource-type name="Mac OS X" plugin="Platforms"/>
    <parent-resource-type name="Java" plugin="Platforms"/> <!-- any OS that RHQ doesn't have native (i.e. SIGAR) support for -->
  </runs-inside>
      ...
</server>

Most of the time when writing a plugin you will probably start with a server at the top level of your plugin, so it will just work.