JMX Support

A new API has been added for configuring and monitoring Message Queue brokers in conformance with the Java Management Extensions (JMX) specification. Using this API, you can configure and monitor broker functions programmatically from within a Message Queue client application. In earlier versions of Message Queue, these functions were accessible only from the command line or the Administration Console.

The API consists of a set of JMX Managed Beans (MBeans) for managing the following Message Queue–related resources:

• Message brokers

• Connection services

• Connections

• Destinations

• Message producers

• Message consumers

• Transactions

• Broker clusters

• Logging

• The Java Virtual Machine (JVM)

These MBeans provide attributes and operations for synchronously polling and manipulating the state of the underlying resources, as well as notifications that allow a client application to listen for and respond asynchronously to state changes as they occur. Using the JMX API, client applications can perform configuration and monitoring tasks like the following:

• Set a broker's port number

• Set a broker's maximum message size

• Pause a connection service

• Set the maximum number of threads for a connection service

• Get the current number of connections on a service

• Destroy a connection

• Create a destination

• Destroy a destination

• Enable or disable auto-creation of destinations

• Purge all messages from a destination

• Get the cumulative number of messages received by a destination since the broker was started

• Get the current state (running or paused) of a queue

• Get the current number of message producers for a topic

• Purge all messages from a durable subscriber

• Get the current JVM heap size

For an introduction to the JMX API and for complete reference information, see the Sun Java System Message Queue 4.1 Developer’s Guide for JMX Clients.

Broker Support: JMX-Related Properties

Several new broker properties have been added to support the JMX API (see Table 1–3). None of these properties can be set from the command line with the Message Queue Command utility (imqcmd). Instead, they can either be set with the -D option of the Broker utility (imqbrokerd) or edited by hand in the broker's instance configuration file (config.properties). In addition, some of these properties (imq.jmx.rmiregistry.start, imq.jmx.rmiregistry.use, imq.jmx.rmiregistry.port) can be set with the new Broker utility options described in Table 1–4. The table lists each option, specifies its type, and describes its use.

   /jndi/rmi://brokerHost:rmiPort
      /brokerHost/brokerPort/connectorName

   /stub/rmiStub

The imq.jmx.connector.list property defines a set of named JMX connectors to be created at broker startup; imq.jmx.connector.activelist specifies which of these are to be activated. Each named connector then has its own set of properties:

By default, two JMX connectors are created, named jmxrmi and ssljmxrmi; the first is configured not to use SSL encryption (imq.jmx.connector.jmxrmi.useSSL = false, the second to use it (imq.jmx.connector.ssljmxrmi.useSSL = true). By default, only the jmxrmi connector is activated at broker startup; see SSL Support for JMX Clients for information on how to activate the ssljmxrmi connector for secure communications.

For convenience, new options (Table 1–4) are also added to the command-line Broker utility (imqbrokerd) to control the usage, startup, and port for the RMI registry. The use and effects of these options are the same as those of the equivalent broker properties, as described in Table 1–3. The table lists each option, specifies its equivalent broker property, and describes its use.

A new subcommand (Table 1–5) is added to the command-line Command utility (imqcmd) for listing the JMX service URLs of JMX connectors created and started at broker startup. This information is needed by JMX clients that do not use the Message Queue convenience class AdminConnectionFactory to obtain their JMX connectors, and can also be used for managing or monitoring Message Queue via a generic JMX browser such as the Java Monitoring and Management Console (jconsole).

SSL Support for JMX Clients

As mentioned above, a Message Queue message broker is configured by default for insecure communication using the preconfigured JMX connector jmxrmi. Applications wishing to use the Secure Socket Layer (SSL) for secure communication must activate the alternate, secure JMX connector, ssljmxrmi. This requires the following steps:

1. Obtain and install a signed certificate in the same way as for the ssljms, ssladmin, or cluster connection service, as described in the Message Queue Administration Guide.

2. Install the root certification authority certificate in the trust store if necessary.

3. Add the ssljmxrmi connector to the list of JMX connectors to be activated at broker startup:

   imq.jmx.connector.activelist=jmxrmi,ssljmxrmi

4. Start the broker with the Message Queue Broker utility (imqbrokerd), either passing it the key-store password in a password file or typing it from the command line when prompted.

5. By default, the ssljmxrmi connector (or any other SSL-based connector) is configured to validate all broker SSL certificates presented to it. To avoid this validation (for instance, when using self-signed certificates during software testing), set the broker property imq.jmx.connector.ssljmxrmi.brokerHostTrusted to true.

On the client side, the administrator connection factory (AdminConnectionFactory) must be configured with a URL specifying ssljmxrmi as the preferred connector:

AdminConnectionFactory  acf = new AdminConnectionFactory();
acf.setProperty(AdminConnectionConfiguration.imqAddress, "mq://myhost:7676/ssljmxrmi");

If needed, use the system properties javax.net.ssl.trustStore and javax.net.ssl.trustStorePassword to point the JMX client to the trust store.