Sun Java System Message Queue 4.3 Developer's Guide for JMX Clients

Broker Clusters

This section describes the MBeans used for managing broker clusters:

The cluster configuration MBean configures a broker's cluster-related properties.
The cluster monitor MBean monitors the brokers in a cluster.

The following subsections describe each of these MBeans in detail.

Cluster Configuration

The cluster configuration MBean is used for configuring a broker's cluster-related properties. There is one such MBean for each broker.

Object Name

The cluster configuration MBean has the following object name:

com.sun.messaging.jms.server:type=Cluster,subtype=Config

A string representing this object name is defined as a static constant CLUSTER_CONFIG_MBEAN_NAME in the utility class MQObjectName.

Attributes

The cluster configuration MBean has the attributes shown in Table 3–74. The names of these attributes are defined as static constants in the utility class ClusterAttributes.

Table 3–74 Cluster Configuration Attributes


Name	Type	Settable?	Description
`HighlyAvailable`	`Boolean`	No	High-availability (HA) cluster?
`ClusterID` [HA clusters only]	`String`	No	Cluster identifier Must be a unique alphanumeric string of no more than `n` - 13 characters, where `n` is the maximum table name length allowed by the database. No two running clusters may have the same cluster identifier. This string is appended to the names of all database tables in the cluster’s shared persistent store. Note – For brokers belonging to an HA cluster, this attribute is used in database table names in place of `BrokerID` (see Table 3–1).
`ConfigFileURL` [Conventional clusters only]	`String`	Yes	URL of cluster configuration file
`LocalBrokerInfo`	`CompositeData`	No	Descriptive information about local broker The value returned is a JMX `CompositeData` object describing the broker; see Table 3–76 for lookup keys used with this object.
`MasterBrokerInfo`	`CompositeData`	No	Descriptive information about master broker The value returned is a JMX `CompositeData` object describing the master broker; see Table 3–76 for lookup keys used with this object.

Operations

The cluster configuration MBean supports the operations shown in Table 3–75. The names of these operations are defined as static constants in the utility class ClusterOperations.

Table 3–75 Cluster Configuration Operations


Name	Parameters	Result Type	Description
`getBrokerAddresses`	None	`String[]`	Addresses of brokers in cluster Each address specifies the host name and Port Mapper port number of a broker in the cluster, in the form `hostName:portNumber`. Example: `host1:3000` For conventional clusters, the list includes all brokers specified by the broker property `imq.cluster.brokerlist`. For HA clusters, it includes all active and inactive brokers in the cluster table stored in the HA database.
`getBrokerIDs` [HA clusters only]	None	`String[]`	Broker identifiers of brokers in cluster The list includes all active and inactive brokers in the cluster table stored in the HA database.
`getBrokerInfoByAddress`	`brokerAddress` (`String`)	`CompositeData`	Descriptive information about broker The desired broker is designated by its host name and Port Mapper port number (`brokerAddress`), in the form `hostName:portNumber`. The value returned is a JMX `CompositeData` object describing the broker; see Table 3–76 for lookup keys used with this object.
`getBrokerInfoByID`	`brokerID` (`String`)	`CompositeData`	Descriptive information about broker The desired broker is designated by its broker identifier (`brokerID`). The value returned is a JMX `CompositeData` object describing the broker; see Table 3–76 for lookup keys used with this object. For conventional clusters, the operation returns `null`.
`getBrokerInfo`	None	`CompositeData[]`	Descriptive information about all brokers in cluster The value returned is an array of JMX `CompositeData` objects describing the brokers; see Table 3–76 for lookup keys used with these objects. For conventional clusters, the array includes all brokers specified by the broker property `imq.cluster.brokerlist`. For HA clusters, it includes all active and inactive brokers in the cluster table stored in the HA database.
`reload` [Conventional clusters only]	None	None	Reload cluster configuration file

The LocalBrokerInfo and MasterBrokerInfo attributes and the getBrokerInfoByAddress, getBrokerInfoByID, and getBrokerInfo operations return objects implementing the JMX interface CompositeData, which maps lookup keys to associated data values. The keys shown in Table 3–76 are defined as static constants in the utility class BrokerClusterInfo for use with these objects.

Table 3–76 Lookup Keys for Cluster Configuration Information


Key	Value Type	Description
`Address`	`String`	Broker address, in the form `hostName:portNumber` Example: `host1:3000`
`ID` [HA clusters only]	`String`	Broker identifier

Notification

The cluster configuration MBean supports the notification shown in Table 3–77.

Table 3–77 Cluster Configuration Notification


Name	Description
`jmx.attribute.change`	Attribute value changed

Cluster Monitor

The cluster monitor MBean is used for monitoring the brokers in a cluster. There is one such MBean for each broker.

Object Name

The cluster monitor MBean has the following object name:

com.sun.messaging.jms.server:type=Cluster,subtype=Monitor

A string representing this object name is defined as a static constant CLUSTER_MONITOR_MBEAN_NAME in the utility class MQObjectName.

Attributes

The cluster monitor MBean has the attributes shown in Table 3–78. The names of these attributes are defined as static constants in the utility class ClusterAttributes.

Table 3–78 Cluster Monitor Attributes


Name	Type	Settable?	Description
`HighlyAvailable`	`Boolean`	No	High-availability (HA) cluster?
`ClusterID` [HA clusters only]	`String`	No	Cluster identifier Must be a unique alphanumeric string of no more than `n` - 13 characters, where `n` is the maximum table name length allowed by the database. No two running clusters may have the same cluster identifier. This string is appended to the names of all database tables in the cluster’s shared persistent store. Note – For brokers belonging to an HA cluster, this attribute is used in database table names in place of `BrokerID` (see Table 3–4).
`ConfigFileURL` [Conventional clusters only]	`String`	Yes	URL of cluster configuration file
`LocalBrokerInfo`	`CompositeData`	No	Descriptive information about local broker The value returned is a JMX `CompositeData` object describing the broker; see Table 3–80 for lookup keys used with this object.
`MasterBrokerInfo`	`CompositeData`	No	Descriptive information about master broker The value returned is a JMX `CompositeData` object describing the master broker; see Table 3–80 for lookup keys used with this object.

Operations

The cluster monitor MBean supports the operations shown in Table 3–79. The names of these operations are defined as static constants in the utility class ClusterOperations.

Table 3–79 Cluster Monitor Operations


Name	Parameters	Result Type	Description
`getBrokerAddresses`	None	`String[]`	Addresses of brokers in cluster Each address specifies the host name and Port Mapper port number of a broker in the cluster, in the form `hostName:portNumber`. Example: `host1:3000` For conventional clusters, the list includes all brokers specified by the broker property `imq.cluster.brokerlist`. For HA clusters, it includes all active and inactive brokers in the cluster table stored in the HA database.
`getBrokerIDs` [HA clusters only]	None	`String[]`	Broker identifiers of brokers in cluster The list includes all active and inactive brokers in the cluster table stored in the HA database.
`getBrokerInfoByAddress`	`brokerAddress` (`String`)	`CompositeData`	Descriptive information about broker The desired broker is designated by its host name and Port Mapper port number (`brokerAddress`), in the form `hostName:portNumber`. The value returned is a JMX `CompositeData` object describing the broker; seeTable 3–80 for lookup keys used with this object.
`getBrokerInfoByID`	`brokerID` (`String`)	`CompositeData`	Descriptive information about broker The desired broker is designated by its broker identifier (`brokerID`). The value returned is a JMX `CompositeData` object describing the broker; seeTable 3–80 for lookup keys used with this object. For conventional clusters, the operation returns `null`.
`getBrokerInfo`	None	`CompositeData[]`	Descriptive information about all brokers in cluster The value returned is an array of JMX `CompositeData` objects describing the brokers; see Table 3–80 for lookup keys used with these objects. For conventional clusters, the array includes all brokers specified by the broker property `imq.cluster.brokerlist`. For HA clusters, it includes all active and inactive brokers in the cluster table stored in the HA database.

The LocalBrokerInfo and MasterBrokerInfo attributes and the getBrokerInfoByAddress, getBrokerInfoByID, and getBrokerInfo operations return objects implementing the JMX interface CompositeData, which maps lookup keys to associated data values. The keys shown in Table 3–80 are defined as static constants in the utility class BrokerClusterInfo for use with these objects.

Table 3–80 Lookup Keys for Cluster Monitor Information


Key	Value Type	Description
`Address`	`String`	Broker address, in the form `hostName:portNumber` Example: `host1:3000`
`ID` [HA clusters only]	`String`	Broker identifier
`State`	`Integer`	Current state of broker See Table 3–81 for possible values.
`StateLabel`	`String`	String representation of current broker state Useful for displaying the state in human-readable form, such as in the Java Monitoring and Management Console (`jconsole`). See Table 3–81 for possible values.
`TakeoverBrokerID`	`String`	Broker identifier of broker that has taken over this broker's persistent data store
`NumMsgs`	`Long`	Current number of messages stored in memory and persistent store
`StatusTimestamp`	`Long`	Time of last status update, in standard Java format (milliseconds since January 1, 1970, 00:00:00 UTC) Used to determine whether a broker is running. The interval at which a broker updates its status can be configured with the broker property `imq.cluster.monitor.interval`.

Table 3–81 shows the possible values returned for the lookup keys State and StateLabel. These values are defined as static constants in the utility class BrokerState.

Table 3–81 Broker State Values


Value	Utility Constant	String Representation	Meaning
`0`	`BrokerState.OPERATING`	`OPERATING`	Broker is operating
`1`	`BrokerState.TAKEOVER_STARTED`	`TAKEOVER_STARTED`	Broker has begun taking over persistent data store from another broker
`2`	`BrokerState.TAKEOVER_COMPLETE`	`TAKEOVER_COMPLETE`	Broker has finished taking over persistent data store from another broker
`3`	`BrokerState.TAKEOVER_FAILED`	`TAKEOVER_FAILED`	Attempted takeover has failed
`4`	`BrokerState.QUIESCE_STARTED`	`QUIESCE_STARTED`	Broker has begun quiescing
`5`	`BrokerState.QUIESCE_COMPLETE`	`QUIESCE_COMPLETE`	Broker has finished quiescing
`6`	`BrokerState.SHUTDOWN_STARTED`	`SHUTDOWN_STARTED`	Broker has begun shutting down
`7`	`BrokerState.BROKER_DOWN`	`BROKER_DOWN`	Broker is down
`-1`	`BrokerState.UNKNOWN`	`UNKNOWN`	Broker state unknown

Notifications

The cluster monitor MBean supports the notifications shown in Table 3–82. These notifications are instances of the Message Queue JMX classes ClusterNotification and BrokerNotification, and their names are defined as static constants in those classes.

Table 3–82 Cluster Monitor Notifications


Name	Utility Constant	Description
`mq.cluster.broker.join`	`ClusterNotification.CLUSTER_BROKER_JOIN`	A broker has joined the cluster
`mq.cluster.broker.down`	`ClusterNotification.CLUSTER_BROKER_DOWN`	A broker in the cluster has shut down or crashed
`mq.broker.takeover.start` [HA clusters only]	`BrokerNotification.BROKER_TAKEOVER_START`	A broker has begun taking over persistent data store from another broker
`mq.broker.takeover.complete`	`BrokerNotification.BROKER_TAKEOVER_COMPLETE`	A broker has finished taking over persistent data store from another broker
`mq.broker.takeover.fail`	`BrokerNotification.BROKER_TAKEOVER_FAIL`	An attempted takeover has failed

Table 3–83 shows the methods defined in class ClusterNotification for obtaining details about a cluster monitor notification. See Table 3–6 for the corresponding methods of class BrokerNotification.

Table 3–83 Data Retrieval Methods for Cluster Monitor Notifications


Method	Result Type	Description
`isHighlyAvailable`	`Boolean`	High-availability (HA) cluster?
`getClusterID`	`String`	Cluster identifier
`getBrokerID`	`String`	Broker identifier of affected broker
`getBrokerAddress`	`String`	Address of affected broker, in the form `hostName:portNumber` Example: `host1:3000`
`isMasterBroker` [Conventional clusters only]	`Boolean`	Master broker affected?