4.2. The Breakdown of Agent Plug-in Configuration
rhq-plugin.xml inside the META-INF/ directory).
- A plug-in component file that contains all of the code for the plug-in functionality
- A
*Discovery.javafile that configures the discovery process for the resources defined in the plug-in - A
*EventPoller.javathat defines the events that can be collected by the resource
rhq-plugin.xml plug-in descriptor.
4.2.1. Schema Files
rhq-configuration.xsd file to define the basic configuration options available.
rhq-plugin.xsd file, which extends the rhq-configuration.xsd schema and adds additional elements specifically for resource-related plug-ins.
rhq-configuration.xsd file provides schema which is available for all JBoss ON plug-ins. The rhq-configuration.xsd file is in source/modules/core/client-api/src/main/resources.
rhq-configuration schema relate to setting configuration values for a plug-in, like <simple-property> and <map-property>.
Table 4.1. rhq-configuration.xsd Schema Elements
| Element | Description |
|---|---|
| configuration-property | For adding a configuration attribute to a plug-in for user-defined settings. |
| simple-property | For setting a default configuration value. |
| option | For setting whether a property's values come from an enumerated list (false) or can be anything defined by the user (true). |
rhq-configuration.xsd file also defines the most common flags that can be used for the plug-in descriptor, including the required name and optional displayName attributes.
Table 4.2. rhq-configuration.xsd Schema Attributes
| Attribute | Description |
|---|---|
| name | Required. Gives a unique name for the plug-in. |
| displayName | Gives the name to use for the plug-in in the GUI. If this isn't given, then the name value is used. |
| description | Gives a short description of the plug-in. |
rhq-plugin.xsd provides all of the schema elements specifically for agent plug-ins. The rhq-plugin.xsd file is in the source/modules/core/client-api/src/main/resources directory.
rhq-plugin.xsd file are listed in Table 4.3, “rhq-plugin.xsd Schema Elements”.
Table 4.3. rhq-plugin.xsd Schema Elements
| Element | Description |
|---|---|
| plugin | Contains the root element for the plug-in descriptor. |
| depends | Identifies any other plug-ins which this plug-in requires or extends. |
| platforms, servers, services | Identifies the type for a resource defined within the agent plug-in. <platforms> are top-level elements, but <servers> and <services> are added as children of platforms or other server and service resources. |
| metric |
An element within a platform, server, or service which defines metrics which can be collected for that resource type.
Child elements and attributes for this resource element are listed in the
rhq-plugin.xsd file.
Values that form part of a larger data structure, such as an array of values, need to be deconstructed into individual values before they can be monitored.
|
| event | An element within a platform, server, or service which defines whether that resource supports events. There are no other configuration properties with events; the events themselves are culled from the resource's log files. |
| bundle-target |
Configures whether and how bundles can be deployed to a resource.
Child elements and attributes for this resource element are listed in the
rhq-plugin.xsd file.
|
| drift-definition |
Configures whether and how drift monitoring can be performed for a resource.
Child elements and attributes for this resource element are listed in the
rhq-plugin.xsd file.
|
| resource-configuration |
Defines a configuration property for a resource type.
Child elements and attributes for this resource element are listed in the
rhq-plugin.xsd file.
|
| operation |
Defines an operation that can be performed on that resource type.
Child elements and attributes for this resource element are listed in the
rhq-plugin.xsd file.
|
| content |
Configures what types of packages can be uploaded or deployed on a resource type.
Child elements and attributes for this resource element are listed in the
rhq-plugin.xsd file.
|
rhq-plugin.xsd contain flags that are used within the root element of the plug-in descriptor. These add additional management attributes for controlling the release and updates of agent plug-ins.
Table 4.4. rhq-plugin.xsd Schema Attributes
| Attribute | Description |
|---|---|
| package | For setting the plug-in package name. |
| version | For setting the version of the plug-in. This must be in an OSGi-compatible format. |
| ampsVersion | For the agent plug-in system version that this plug-in requires. This must be in an OSGi-compatible format. |
| pluginLifecycleListener | For the listener which initializes and shuts down the plug-in. |
| discovery | Sets whether a resource type is detected by discovery scans. This flag may not be necessary for child resources that will be discovered by the parent resource. |
rhq-plugin.xsd file. Each one is described by the text in the <xs:annotation> tags for the item.
4.2.2. Descriptor and Configuration
- The names of the resource types (servers and services) supported by the plug-in
- Any configuration settings that the agent's plug-in components use to connect to the resource
- Any metrics (measurement definitions) to use to monitor the resource; this depends on the type of data issued by the resource itself.
- A set of operations that can be invoked on the resource. This is commonly start and stop operations, but it can include application-specific operations or other actions, like running a script.
- Resource configuration values that can be edited in the actual configuration of the resource.The plug-in configuration tells the components how to connect to the resource. The resource configuration, on the other hand, are settings in the resource itself that can be edited externally.
- Any child resources that are part of the resource hierarchy. For example, a JBoss server has data source services running within them, so the data source services are defined in the JBoss server resource plug-in, as a child resource of the JBoss server.
4.2.2.1. Resource Type, Metadata, and Plug-in Configuration
<plugin name="JMX"
displayName="Generic JMX"
package="org.rhq.plugins.jmx"
description="Supports management of JMX MBean Servers via various remoting systems."
ampsVersion="2.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="urn:xmlns:rhq-plugin"
xmlns:c="urn:xmlns:rhq-configuration">nameanddisplayNamegive the internal and GUI name of the plug-in.ampsVersiongives the version number of the plug-in itself.packagegives the name of the classes used by the components in the plug-in.
<server name="JMX Server" discovery="JMXDiscoveryComponent" class="JMXServerComponent"
description="Generic JMX Server"
supportsManualAdd="true" createDeletePolicy="neither">discoveryidentifies the discovery component used to identify the resource type.classidentifies the plug-in component which contains the actual code of the plug-in.
supportsManualAddallows resources to be added to the inventory by administrators.createDeletePolicysets whether children can be added or removed manually from inventory.
<plugin-configuration>
<c:list-property name="Servers">
<c:map-property name="OneServer">
<c:simple-property name="host"/>
<c:simple-property name="port">
<c:integer-constraint
minimum="0"
maximum="65535"/>
</c:simple-property>
<c:simple-property name="protocol">
<c:property-options>
<c:option value="http" default="true"/>
<c:option value="https"/>
</c:property-options>
</c:simple-property>
</c:map-property>
</c:list-property>
</plugin-configuration>- <simple-property>, which defines a one key-value pair
- <map-property>, which defines multiple key-value pairs related to a single entity, following the
java.util.Mapconcept - <list-property>, which contains a list of properties
<c:template name="JDK 5" description="Connect to JDK 5">
<c:simple-property name="type" default="org.mc4j.ems.connection.support.metadata.J2SE5ConnectionTypeDescriptor"/>
<c:simple-property name="connectorAddress" default="service:jmx:rmi:///jndi/rmi://localhost:8999/jmxrmi"/>
</c:template>4.2.2.2. Discovery and Process Scans
discovery attribute which identifies the discovery Java file for the resource plug-in. (If there are multiple resources defined in the plug-in, then there will be multiple discovery components.)
/**
* Discovery class
*/
public class testDiscovery implements ResourceDiscoveryComponent
,ManualAddFacet
{
private final Log log = LogFactory.getLog(this.getClass());
/**
* Do the manual add of this one resource
*/
public DiscoveredResourceDetails discoverResource(Configuration pluginConfiguration, ResourceDiscoveryContext context) throws InvalidPluginConfigurationException {
// TODO implement this
DiscoveredResourceDetails detail = null; // new DiscoveredResourceDetails(
// context.getResourceType(), // ResourceType
// );
return detail;
}
} public DiscoveredResourceDetails discoverResource(Configuration pluginConfig,
ResourceDiscoveryContext discoveryContext)
throws InvalidPluginConfigurationException {
// TODO: Connect to the remote JVM to verify the user-specified conn props are valid, and if connecting
// fails, throw an exception.
String resourceKey = pluginConfig.getSimpleValue(CONNECTOR_ADDRESS_CONFIG_PROPERTY, null);
String connectionType = pluginConfig.getSimpleValue(CONNECTION_TYPE, null);
// TODO (ips, 09/04/09): We should connect to the remote JVM in order to obtain its version.
String version = null;
DiscoveredResourceDetails resourceDetails = new DiscoveredResourceDetails(discoveryContext.getResourceType(),
resourceKey, "Java VM", version, connectionType + " [" + resourceKey + "]", pluginConfig, null);
return resourceDetails;
} name and query. name identifies the specific scan method. query is the attribute that does something. The query is a string written in Process Info Query Language (PIQL). This value is used to search for the process.
process|attribute|match=value,arg|attribute|match=value
jsmith 2035 0.0 -1.5 724712 30616 p7 S+ 9:49PM 0:01.61java-Dprogram.name=run.sh -Xms128m -Xmx512m -Dsun.rmi.dgc.client.gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000 -Djboss.platform.mbeanserver -Djava.endorsed.dirs=/devel/jboss-4.0.5.GA/lib/endorsed -classpath /devel/jboss-4.0.5.GA/bin/run.jar:/lib/tools.jarorg.jboss.Main-c minimal
process|attribute|match=value,arg|attribute|match=value | | |____ |_ |____ |______ | | | | | | | | | | | | | | | | | | | | | | | | process|basename|match=^java.*,arg|org.jboss.Main|match=.*
process|attribute|match=value
process|pidfile|match=/etc/product/lock.pid
rhq-plugin.xml descriptor file, then the discovery component must be written to implement the scan and process results.
Example 4.1. Process Scan Method in the Discovery Component
List<ProcessScanResult< autoDiscoveryResults =
context.getAutoDiscoveredProcesses();
for (ProcessScanResult result : autoDiscoveryResults) {
ProcessInfo procInfo = result.getProcessInfo();
....
// as before
DiscoveredResourceDetails detail =
new DiscoveredResourceDetails(
resourceType, key, name, null,
description, childConfig, procInfo
);
result.add(detail);
} <metric displayName="Bytes Sent"
description="Shows the rate that data bytes are sent by the Web service."
property="Bytes Sent/sec"
defaultOn="true"
displayType="summary"
measurementType="trendsup"
units="bytes"/>propertyidentifies the resource monitoring property.measurementTypesets the data type being collected.unitssets the units of the thing being monitored.
public class testComponent implements ResourceComponent , MeasurementFacet , OperationFacet
public void getValues(MeasurementReport report, Set<MeasurementScheduleRequest> metrics) throws Exception {
String propertyBase = "\\Web Service(_Total)\\";
Pdh pdh = new Pdh();
for (MeasurementScheduleRequest request : metrics) {
double value = pdh.getRawValue(propertyBase + request.getName());
report.addData(new MeasurementDataNumeric(request, value));
}
}4.2.2.3. Events
<event name="errorLogEntry" description="an entry in the error log file"/>
EventPoller component. This can be in the larger plug-in Java component, but it is usually broken into a separate *EventPoller.java component. The way to implement event polling depends on the resource and the nature of its logging. One of the simplest ways is to call the EventPoller(), then define the event type and set how the event is polled.
public PerfTestEventPoller(ResourceContext resourceContext) {
this.resourceContext = resourceContext;
}
public String getEventType() {
return PERFTEST_EVENT_TYPE;
}
public Set<Event> poll() {
int count = Integer.parseInt(System.getProperty(SYSPROP_EVENTS_COUNT, "1"));
String severityString = System.getProperty(SYSPROP_EVENTS_SEVERITY, EventSeverity.INFO.name());
EventSeverity severity = EventSeverity.valueOf(severityString);
Set<Event> events = new HashSet<Event>(count);
for (int i = 0; i < count; i++) {
Event event = new Event(PERFTEST_EVENT_TYPE, "source.loc", System.currentTimeMillis(), severity, "event #"
+ i);
events.add(event);
}
return events;
}4.2.2.4. Resource Configuration
<resource-configuration>
<c:group name="Attributes">
<c:simple-property
name="appBase"
required="true"
readOnly="true"
description="The Application Base directory for this virtual host." />
<c:simple-property
name="autoDeploy"
type="boolean"
description="Does this host deploy new applications dropped in appBase at runtime?" />
<c:simple-property
name="deployOnStartup"
type="boolean"
description="Does this host deploy applications in appBase at startup?" />
<c:simple-property
name="deployXML"
displayName="Deploy XML"
type="boolean"
description="deploy Context XML config files?" />
<c:simple-property
name="unpackWARs"
displayName="Unpack WARs"
type="boolean"
description="Does this Host automatically unpack deployed WAR files?" />
<c:simple-property
name="aliases"
required="false"
type="longString"
description="Aliases assigned to the Host. When editing, each alias must be on a new line. Aliases are automatically lowercased." />
</c:group>
</resource-configuration> public Configuration loadResourceConfiguration() {
Configuration configuration = super.loadResourceConfiguration();
try {
resetConfig(CONFIG_ALIASES, configuration);
} catch (Exception e) {
log.error("Failed to reset role property value", e);
}
return configuration;
} public void updateResourceConfiguration(ConfigurationUpdateReport report) {
Configuration reportConfiguration = report.getConfiguration();
// reserve the new alias settings
PropertySimple newAliases = reportConfiguration.getSimple(CONFIG_ALIASES);
// get the current alias settings
resetConfig(CONFIG_ALIASES, reportConfiguration);
PropertySimple currentAliases = reportConfiguration.getSimple(CONFIG_ALIASES);
// remove the aliases config from the report so they are ignored by the mbean config processing
reportConfiguration.remove(CONFIG_ALIASES);
// perform standard processing on remaining config
super.updateResourceConfiguration(report);
// add back the aliases config so the report is complete
reportConfiguration.put(newAliases);
// if the mbean update failed, return now
if (ConfigurationUpdateStatus.SUCCESS != report.getStatus()) {
return;
}
// try updating the alias settings
try {
consolidateSettings(newAliases, currentAliases, "addAlias", "removeAlias", "alias");
} catch (Exception e) {
newAliases.setErrorMessage(ThrowableUtil.getStackAsString(e));
report.setErrorMessage("Failed setting resource configuration - see property error messages for details");
log.info("Failure setting Tomcat VHost aliases configuration value", e);
}
// If all went well, persist the changes to the Tomcat server.xml
try {
storeConfig();
} catch (Exception e) {
report
.setErrorMessage("Failed to persist configuration change. Changes will not survive Tomcat restart unless a successful Store Configuration operation is performed.");
}
}4.2.3. Lifecycle Listeners
org.rhq.core.pluginapi.plugin.PluginLifecycleListener class allocates global resources needed by plug-in components and cleans up those resources.
pluginLifecycleListener attribute in the top-level <plugin> element.
<plugin name="Apache" displayName="Apache HTTP Server" description="Management of Apache web servers" package="org.rhq.plugins.apache" pluginLifecycleListener="ApachePluginLifecycleListener" ...
4.2.4. Plug-in Dependencies: Defining Relationships Between Plug-ins
- Required dependencies are set using the <depends> element. Just using <depends> means that the required plug-in must be loaded or the other plug-in will fail to load. Adding the
useClassesattribute makes the classes and JAR files for the parent plug-in available to the child plug-in. - An injection plug-in dependency means that a root-level resource runs inside another resource type, and that parent resource is defined as a parent plug-in. This essentially adds a new child to an existing resource type.
- An embedded plug-in dependency means that a new parent resource type is added for an existing child. This can allow the child to be extended to share the new parent's classloader (depending on both plug-ins' configuration) or simply expand discovery.
4.2.4.1. Required Plug-in Dependencies
useClasses attribute. The useClasses option can be set for only one required dependency in a single plug-in descriptor. If no <depends> element has a useClasses attribute, the last <depends> element specified in the plug-in descriptor, by default, has its useClasses attribute to true.
4.2.4.2. Embedded Plug-in Dependencies
sourcePlugin and sourceType attributes on the resource elements. When a plug-in source is specified, the server or service is copied from the source resource type, which means it has the same metadata as the source, with the exception that the embedded server or service can override the discovery and resource classes and, potentially, have a different name.
4.2.4.3. Injection Plug-in Dependencies
<runs-inside> <parent-resource-type name="JMX Server" plugin="JMX" /> <parent-resource-type name="JBoss Server" plugin="JBoss AS" /> </runs-inside>
4.2.5. Class Sharing Between Plug-ins
Figure 4.1. Agent Components, Together

classLoader="instance" on the resource type and make sure the resource type's discovery component implements the ClassLoaderFacet so it tells the plug-in container where any additional connection classes can be found for the specific version of the specific resource being managed.
classLoader option set to shared. This means that Z1.server resources share their classloaders with their parent resources, and that classloader may be a resource classloader or a plug-in classloader. Every Z1.server resource uses the same classloader.
Example 4.2. classLoader for Plug-in Z
<plug-in name="Z">
<depends plugin="A" />
<server name="Z1.server" classLoader="shared">
<runs-inside>
<parent-resource-type name="B1.server" plugin="B"/>
<parent-resource-type name="C1.server" plugin="C"/>
</runs-inside>
</server>
<server name="Z2.server" sourcePlugin="D" sourceType="D1" classLoader="instance">
</server>
<server name="Z3.server" classLoader="instance">
</server>
</plugin>classLoader option to instance means that each resource uses its own resource plug-in. However, for Z2.server, the Z2.server plug-in is extended by embedding the values for Plug-in D, so Z2.server resources share their classloaders with their parent plug-in.
classLoader option is set to instance and it has no injected or embedded dependencies. When the classLoader option is set to instance, the ResourceDiscoveryComponent implementation can optionally define a ClassLoaderFacet with a method (getAdditionalClasspathUrls) that returns a List<URL> pointing to additional JARs that should be placed in the resource's classloader. When the plug-in container needs to create a classloader for a resource, it checks if the resource's discovery component implements this facet, and, if so, it gets the additional classpath URLs and adds them to the resource classloader when it creates it.
classLoader attribute value and its parent's classLoader attribute value.
| Resource ClassLoader | Parent ClassLoader | ClassLoader Description |
|---|---|---|
| shared | shared | The useClasses value must be set to true so that the resource can access both its classes and the parent classes. |
| instance | shared | The resource primarily needs its own classes, but it may be beneficial for useclasses to be set to true to so that the child can use parent classes. |
| shared | instance | The resource uses only its own classloader. |
| instance | instance | The resource uses only its own classloader. |

Where did the comment section go?
Red Hat's documentation publication system recently went through an upgrade to enable speedier, more mobile-friendly content. We decided to re-evaluate our commenting platform to ensure that it meets your expectations and serves as an optimal feedback mechanism. During this redesign, we invite your input on providing feedback on Red Hat documentation via the discussion platform.