How We Make a Resource Configuration Manageable Today

Resource configuration is declared in the plugin descriptor, rhq-plugin.xml. The following example is a snippet from the JBoss AS plugin and lists part of the resource configuration for a datasource.

<service name="Datasource" class="DatasourceComponent"
         discovery="org.rhq.plugins.jmx.MBeanResourceDiscoveryComponent"
        createDeletePolicy="both" subCategory="Resources">
  ...
  <resource-configuration>
    <c:group name="connection" displayName="Connection Information">
      <c:simple-property name="type">
        <c:property-options>
          <c:option value="no-tx-datasource" name="No TX Datasource"/>
          <c:option value="local-tx-datasource" name="Local TX Datasource" default="true"/>
          <c:option value="xa-datasource" name="XA Datasource"/>
        </c:property-options>
      </c:simple-property>
      <c:simple-property name="jndi-name" readOnly="true" displayName="JNDI Name"
                         description="The JNDI name under which the DataSource wrapper will be bound."/>
      <c:simple-property name="driver-class"
                         description="The fully qualified name of the JDBC driver or datasource class"/>
       ...
    </c:group>
    ...
    <c:template name="Oracle Local TX" description="Local Transaction Template for Oracle">
      <c:simple-property name="type" default="local-tx-datasource"/>
      <c:simple-property name="driver-class" default="oracle.jdbc.driver.OracleDriver"/>
      <c:simple-property name="connection-url" default="jdbc:oracle:oci:@youroracle-tns-name"/>
      <c:simple-property name="exception-sorter-class-name"
                         default="org.jboss.resource.adapter.jdbc.vendor.OracleExceptionSorter"/>
      <c:simple-property name="check-valid-connection-sql" default="SELECT * FROM DUAL"/>
    </c:template>
    ...
  </resource-configuration>
</service>

Thus far we have declared what actual configuration is supported. To effect changes on the resource configuration, the ResourceComponent implementation must implement the ConfigurationFacet interface which is shown below.

interface ConfigurationFacet {
    Configuration loadResourceConfiguration() throws Exception;

    void updateResourceConfiguration(ConfigurationUpdateReport report);
}

The two methods in ConfigurationFacet provide the read/write operations that are called by the plugin container. With the <resource-configuration> declaration and an implementation of ConfigurationFacet, we have everything in place (from the plugin side) that we need to manager a resource's configuration.

Updating a Resource Configuration

When a user (from the UI) makes a configuration change, it results in a call to ConfigurationManagerLocal.updateResourceConfiguration(Subject subject, int resourceId, Configuration newConfiguration). This method does two things - persist the update request to the audit trail and send the update request to the appropriate agent. We will look at each of these two steps in greater detail.

The update request is persisted as an instance of ResourceConfigurationUpdate. ResourceConfigurationUpdate has a status attribute which can have a value of In Progress, Success, or Failure. If a there is already an update in progress, the ResourceConfigurationUpdate is given a failure status and an exception is thrown. If no update is currently in progress, we mark the ResourceConfigurationUpdate as in progress and persist it to the database.

The second step in updateResourceConfiguration() is to send the update request to the agent. AgentClient is the RHQ agent interface that is exposed to the server. AgentClient in turn provides access to agent services, namely ConfigurationAgentService in this case. ConfigurationManagerBean (the implementation of ConfigurationManagerLocal) obtains a reference to the ConfigurationAgentService and calls ConfigurationAgentService.updateResourceConfiguration(ConfigurationUpdateRequest request). There are a few things to point out about this method call:

• The request is sent as a ConfigurationUpdateRequest object

• The ConfigurationUpdateRequest object contains the entire configuration, not just a series of diffs

• The update is applied asynchronously such that when control returns back to ConfigurationManagerBean, the resource configuration update has not yet completed

ConfigurationManager is the agent service implementation of ConfigurationAgentService. ConfigurationManager is a plugin container service that forms the communication layer through which the RHQ server sends requests to plugins. ConfigurationManager looks up the ConfigurationFacet to be called, and schedules the update via a UpdateResourceConfigurationRunner object. When the update has finished, UpdateResourceConfigurationRunner calls ConfigurationServerService.completeConfigurationUpdate(ConfigurationUpdateResponse response). ConfigurationServerService resides on the RHQ server and provides an interface to the agent back into the server.

ConfigurationServerService in turn calls ConfigurationManagerLocal.completeResourceConfigurationUpdate(ConfigurationUpdateResponse response). completeResourceConfiguration() takes the status (success/failure) and configuration from the response and persists them in the audit trail (i.e., in the form of a ResourceConfigurationUpdate object). If the update was a success, the configuration is assigned to the Resource.resourceConfiguration property, making the latest, known good configuration easily accessible from the Resource object.

Viewing Resource Configuration History

A user can view a resource's configuration update history, including its latest configuration. Note that the latest configuration might actually be the live configuration. First, a request for the latest configuration is made by calling ConfigurationManagerLocal.getLatestResourceConfigurationUpdate(Subject, int resourceId). This method first queries the database for the latest ResourceConfigurationUpdate know by the server. Next we call a helper method to get the live configuration. This is done by calling ConfigurationAgentService.loadResourceConfiguration(int resourceId). If the live configuration differs from the one found in the last update on the server, then we persist a ResourceConfigurationUpdate with the live configuration, effectively making it the latest, known configuration on the server. As a side effect, that configuration is also assigned to the Resource.resourceConfigration property, making the latest, known configuration easily accessible from the Resource object.

After retrieving the latest configuration, ConfigurationManagerLocal.findResourceConfigurationUpdates() is called. This method is straightforward in that it just queries the database for ResourceConfigurationUpdates.

Concepts

This would add a mechanism where by a user can view and edit the raw textual content of a configuration within the RHQ configuration subsystem. To allow for the best of all worlds, this system should support being a parallel to the abstract configuration model and allow the developer to support structure, raw or both configuration models.

Domain Model Changes

Here is a UML class diagram of what the Configuration entity looks like today:

All of the attributes or properties listed after the version property are all basically different views of the same underlying data structure which holds the Property objects representing the structured configuration. The next diagram includes a new RawConfiguration class.

Things to note about the new RawConfiguration class added to the diagram

• The path property corresponds to the file system path of the configuration file

• The contents attribute is the actual file contents stored as a byte array.

• The sha256 property is read-only and is a SHA-256 sum of the contents property.

• There is a one-to-many association between Configuration and RawConfiguration. This provides the flexibility for supporting structured configuration, raw configuration, or both on a resource.

• A RawConfiguration object cannot exist without having a parent Configuration object. This will be enforced with a foreign key constraint.

Plugin Descriptor Changes

We need to add new meta data attributes that allow the resource type to declare what type of configuration it supports. Something like configurationFormat = {raw, structured, both}... Whether or not a resource supports partial validation could potentially be inferred by its implementation of this new facet interface. An example would be:

<resource-configuration configurationFormat="raw|structured|both">
</resource-configuration>

For existing plugins that will not have this new attribute declared, we will have to assume a default value of structured since that was the only one previously supported.

Plugin Model Changes

A couple different approaches have been discussed, and in the following sections we will consider each of them

List<RawConfig> translateToRaw(Configuration config) {
    Configuration config = loadRawResourceConfiguration();
    List<RawConfiguration> results = new ArrayList<RawConfiguration>();
    for (RawConfiguration nextRaw : config.getRawConfigs()) {
        // merges current data from 'config' into 'nextRaw', and returns it
        RawConfiguration updatedRaw = mergeRawConfiguration(config, nextRaw);
        results.add(updatedRaw);
    }
    return results;
}

Configuration translateToStructured(List<RawConfiguration> rawConfigs) {
    Configuration config = loadStructuredResourceConfiguration();
    for (RawConfiguration nextRaw : rawConfigs) {
        // merges current data from 'nextRaw' into 'config' in place
        mergeStructuredConfiguration(nextRaw, config);
    }
    return config;
}

void updateResourceConfiguration(ConfigurationUpdateReport report) {
    Configuration config = null;
    List<RawConfiguration> rawConfigs = null;
    if (report == ConfigurationUpdateReport.Type.STRUCTURED) {
        config = report.getStructuredConfig();
        if (rawSupported()) { // PC-level helper method
            rawConfigs = translateToRaw(config);
        }
    } else {
        rawConfigs = report.getRawConfigs();
        if (structuredSupported()) { // PC-level helper method
            config = translateToStructured(rawConfigs);
        }
    }
    if (config != null) {
        updateStructuredConfiguration(config);
    }
    if (rawConfigs != null) {
        for (RawConfiguration nextRaw : rawConfigs) {
            updateRawConfiguration(nextRaw);
        }
    }
}

interface ResourceConfigurationFacet {
    Configuration loadStructuredConfiguration();

    List<RawConfigurations> loadRawConfigurations();

    void persistStructuredConfiguration(Configuration);

    void persistRawConfiguration(RawConfig);

    void validate(Configuration);

    void validate(RawConfiguration);

    void updateEnumerations(Configuration);

    RawConfiguration mergeRawConfiguration(Configuration from, RawConfiguration to);

    void mergeStructuredConfiguration(RawConfiguration from, Configuration to);
}

Data Flow Changes

There are some complexities involved with making sure that we keep the audit trail in sync at all times. In this section, we will review the existing data flow, point out some potential concerns, and finally look at some solutions that alleviate those concerns.