2.2. Understanding the Red Hat JBoss A-MQ Configuration Model

Abstract

The broker configuration is comprised of an XML template file that provides the framework for how a broker instance is configured, a default OSGi persistent identifier, and one or more OSGi persistent identifiers created by the OSGi Admin service. The container uses the template file to seed the configuration into the broker's runtime. The properties stored in the OSGi persistent identifiers replace any property placeholders left in the template. This allows the OSGi Admin service to update the broker's configuration on the fly.

Overview

One of the weaknesses of the Apache ActiveMQ configuration model is that any changes require a broker restart. Red Hat JBoss A-MQ addresses this weakness by capitalizing on the OSGi Admin service. The container combines both the Apache ActiveMQ XML configuration and OSGi persistent identifier(PID) properties to manage a broker instances runtime configuration.
In JBoss A-MQ your Apache ActiveMQ XML configuration file becomes a configuration template. It can contain property placeholders for any settings that may need to be set on the fly. It can also be used as a baseline for configuring a group of brokers and the placeholders represent settings that need to be modified for individual brokers.
As shown in Figure 2.1, “Red Hat JBoss A-MQ Configuration System”, the configuration template is combined with the OSGi PID properties. While the broker is running the OSGi Admin service monitors the appropriate PIDs for changes. When it detects a change, the admin service will automatically change the broker's runtime configuration.

Figure 2.1. Red Hat JBoss A-MQ Configuration System

Configuration templates

The JBoss A-MQ configuration template is an XML file that is based on the Apache ActiveMQ configuration file. The main differences between an Apache ActiveMQ and a JBoss A-MQ configuration template are:
  • configuration templates use property placeholders for settings that will be controlled via the OSGi Admin service
  • configuration templates do not configure the broker's name
  • configuration templates do not configure the location of the data directory
  • configuration templates do not configure transport connectors
  • configuration templates do not configure network connectors
  • configuration templates do not control if a broker is a master or a slave node
  • configuration templates can be used as a baseline for multiple brokers on the same machine
The networking properties and role in a master/slave group are specified by the broker's PID and do not need to appear in the template. The broker's name and data directory are replaced in the template with property placeholders. Property placeholders can also be substituted for any attribute value or element value in the XML configuration. This allows the OSGi Admin system populate them from the broker's PID.
Property placeholders are specified using the syntax ${propName} and are resolved by matching properties in the broker's PID. In order to use property placeholder the configuration template must include the bean definition shown in Example 2.1, “Adding Property Placeholder Support to Red Hat JBoss A-MQ Configuration”.

Example 2.1. Adding Property Placeholder Support to Red Hat JBoss A-MQ Configuration

<!-- Allows us to use system properties and fabric as variables in this configuration file -->
<bean class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer">
  <property name="properties">
    <bean class="io.fabric8.mq.fabric.ConfigurationProperties"/>
  </property>      
</bean>

<broker ... >
  ...
</broker>
The configuration template shown in Example 2.2, “Configuration with Property Placeholders” uses three property placeholders that allow you to modify the base configuration using fabric properties.

Example 2.2. Configuration with Property Placeholders

<broker xmlns="http://activemq.apache.org/schema/core"
        brokerName="${broker-name}"
        dataDirectory="${data}"
        persistent="${persists}"
        start="false">
  ...
  <persistenceAdapter>
    <jdbcPersistenceAdapter dataDirectory="${data}/derby"
                            dataSource="#derby-ds" />
  </persistenceAdapter>

</broker>

OSGi PIDs

Persistent identifiers are described in chapter 104, [Configuration Admin Service Specification], of the [OSGi Compendium Services Specification]. It is a unique key used by the OSGi framework's admin service to associate configuration properties with active services. The PIDs for a JBoss A-MQ instance have the prefix io.fabric8.mq.fabric.server.
Every PID has a physical representation as a file of name value pairs. For standalone brokers the files are located in the etc/ folder and use the .cfg extension and are updated using the config shell. For broker's in a fabric the files are stored in the Fabric Ensemble and are edited using the fabric shell's profile management commands.