Connecting to the MBean Server

As defined in the JMX Specification, client applications obtain MBeans through an MBean server, accessed by means of a JMX connector. Message Queue message brokers use the standard JMX-compliant MBean server and JMX connector provided with the Java Development Kit (JDK) 1.5, which use remote method invocation (RMI) as the infrastructure for communicating between client and server. Once you have a JMX connector, you can use it to obtain an MBean server connection with which to access the attributes, operations, and notifications of individual MBeans.

For convenience, Message Queue provides an administration connection factory (class AdminConnectionFactory), similar in spirit to the familiar Message Queue connection factory, for creating JMX connectors with a minimum of effort. It is also possible to dispense with this convenience class and obtain a JMX connector using standard JMX classes instead. The following sections illustrate these two techniques. While Message Queue client applications are free to use either method, the first is simpler and is recommended.

Obtaining a JMX Connector from an Administration Connection Factory

The Message Queue convenience class AdminConnectionFactory (defined in package com.sun.messaging) encapsulates a predefined set of configuration properties and hides the details involved in creating a JMX connector. Example 2–1 shows the most straightforward use, creating a connector at the default port 7676 on host localhost, with the user name and password both set to the default value of admin. After creating the connector, its getMBeanServerConnection method is called to obtain a server connection for interacting with Message Queue MBeans.

Example 2–1 Obtaining a JMX Connector from an Administration Connection Factory

import javax.management.remote.*;
import com.sun.messaging.AdminConnectionFactory;


//  Create administration connection factory for default host and port (localhost:7676)
    AdminConnectionFactory  acf = new AdminConnectionFactory();
    
//  Get JMX connector using default user name (admin) and password (admin)
    JMXConnector  jmxc = acf.createConnection();
    
//  Get MBean server connection
    MBeanServerConnection  mbsc = jmxc.getMBeanServerConnection();

Example 2–2 shows how to reconfigure an administration connection factory's properties to nondefault values. Instead of using the default broker address (localhost:7676), the code shown here uses the connection factory's setProperty method to reconfigure it to connect to a broker at port 9898 on host otherhost. (The names of the connection factory's configuration properties are defined as static constants in the Message Queue utility class AdminConnectionConfiguration, defined in package com.sun.messaging.) The arguments to the factory's createConnection method are then used to supply a user name and password other than the defaults.

Example 2–2 Configuring an Administration Connection Factory

import javax.management.remote.*;
import com.sun.messaging.AdminConnectionFactory;


//  Create administration connection factory
    AdminConnectionFactory  acf = new AdminConnectionFactory();
    
//  Configure for specific broker address
    acf.setProperty(AdminConnectionConfiguration.imqAddress, "otherhost:9898");
    
//  Get JMX connector, supplying user name and password
    JMXConnector  jmxc = acf.createConnection("AliBaba", "sesame");
    
//  Get MBean server connection
    MBeanServerConnection  mbsc = jmxc.getMBeanServerConnection();

Obtaining a JMX Connector Without Using an Administration Connection Factory

The generic (non–Message Queue) way of obtaining a JMX connector, as described in the JMX Specification, is by invoking the static connect method of the standard JMX class JMXConnectorFactory (see Example 2–3). Client applications may choose to use this method instead of an administration connection factory in order to avoid dependency on Message Queue–specific classes.

Example 2–3 Obtaining a JMX Connector Without Using an Administration Connection Factory

import java.util.HashMap;
import javax.management.remote.*;


//  Provide credentials required by server for user authentication
    HashMap   environment = new HashMap();
    String[]  credentials = new String[] {"AliBaba", "sesame"};
    environment.put (JMXConnector.CREDENTIALS, credentials);
    
//  Create JMXServiceURL of JMX Connector (must be known in advance)
    JMXServiceURL  url 
        = new JMXServiceURL("service:jmx:rmi:///jndi/rmi://localhost:9999/server");
    
//  Get JMX connector
    JMXConnector  jmxc = JMXConnectorFactory.connect(url, environment);
    
//  Get MBean server connection
    MBeanServerConnection  mbsc = jmxc.getMBeanServerConnection();

The JMXConnectorFactory.connect method accepts two parameters:

• A JMX service URL identifying the JMX connector server from which to obtain a connector

• An optional environment parameter specifying attributes of the connections to be made

The service URL is a string whose syntax is described in the next section; the environment parameter is a hash map mapping attribute names to their corresponding values. In particular, the CREDENTIALS attribute specifies the authentication credentials (user name and password) to be used in establishing a connection. The hash-map key for this attribute is defined as a static constant, CREDENTIALS, in the JMXConnector interface; the corresponding value is a 2–element string array containing the user name at index 0 and the password at index 1.

JMX Service URLs

For Message Queue applications (which always use the RMI protocol for JMX connections), the JMX service URL has the following syntax:

service:jmx:rmi://[host[:port]][urlPath]

Although host and port may be included, they are ignored by the RMI protocol. If urlPath is specified, it gives the Java Naming and Directory Interface (JNDI) location of an RMI stub (typically a location within an RMI registry) in the form

/jndi/jndiName

For example, the URL

service:jmx:rmi://myhost/jndi/rmi://myhost:1099/myhost/myjmxconnector

specifies an RMI stub at the location

rmi://myhost:1099/myhost/myjmxconnector

which is an RMI registry running at location myhost/myjmxconnector on port 1099 of host myhost.

Alternatively, if urlPath is omitted from the service URL, the JMX connector server will generate a client URL containing the actual RMI stub embedded within it in encoded and serialized form. For example, the service URL

service:jmx:rmi://localhost

will generate a client URL of the form

service:jmx:rmi://localhost/stub/rmiStub

where rmiStub is an encoded and serialized representation of the RMI stub itself.