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.
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.
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.
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();
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.
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.
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.