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

Brokers

This section describes the MBeans used for managing brokers:

The following subsections describe each of these MBeans in detail.

Broker Configuration

The broker configuration MBean is used for configuring a broker. There is one such MBean for each broker.

Object Name

The broker configuration MBean has the following object name:

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

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

Attributes

The broker configuration MBean has the attributes shown in Table 3–1. The names of these attributes are defined as static constants in the utility class BrokerAttributes.

Table 3–1 Broker Configuration Attributes

Name 

Type 

Settable? 

Description 

BrokerID

String

No 

Broker 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 brokers may have the same broker identifier.

For brokers using a JDBC-based persistent data store, this string is appended to the names of all database tables to make them unique in the case where more than one broker instance is using the same database. If a database is not used as the persistent data store, the value of this attribute is null.


Note –

For high-availability brokers, database table names use the ClusterID attribute (see Table 3–74) instead.


Version

String

No 

Broker version 

InstanceName

String

No 

Broker instance name 

Example:

    imqbroker


Port

Integer

Yes 

Port number of Port Mapper 

Operations

The broker configuration MBean supports the operations shown in Table 3–2. The names of these operations are defined as static constants in the utility class BrokerOperations.

Table 3–2 Broker Configuration Operations

Name 

Parameters 

Result Type 

Description 

shutdown

nofailover (Boolean)

time (Long)

None 

Shut down broker 

If nofailover is false or null, another broker will attempt to take over for this broker when it shuts down; this applies only to brokers in a high-availability (HA) cluster. If nofailover is true, no such takeover attempt will occur.

The time parameter specifies the interval, in seconds, before the broker actually shuts down; for immediate shutdown, specify 0 or null.

shutdown

None 

None 

Shut down broker immediately 

If the broker is part of a high-availability (HA) cluster, another broker will attempt to take over for it.

Equivalent to shutdown(Boolean.FALSE, new Long(0)).

restart

None 

None 

Restart broker 

quiesce

None 

None 

Quiesce broker 

The broker will refuse any new connections; existing connections will continue to be served.  

unquiesce

None 

None 

Unquiesce broker 

The broker will again accept new connections.  

takeover [HA clusters only]

brokerID (String)

None 

Initiate takeover from specified broker 

The desired broker is designated by its broker identifier (brokerID).

getProperty

propertyName (String)

String

Get value of configuration property 

The desired property is designated by its name (propertyName)

resetMetrics

None 

None 

Reset metrics 

Resets to zero all metrics in monitor MBeans that track cumulative, peak, or average counts. The following attributes are affected:  

     

Service monitor

    NumConnectionsOpened


    NumConnectionsRejected


    NumMsgsIn


    NumMsgsOut


    MsgBytesIn


    MsgBytesOut


    NumPktsIn


    NumPktsOut


    PktBytesIn


    PktBytesOut


     

Service manager monitor

    NumMsgsIn


    NumMsgsOut


    MsgBytesIn


    MsgBytesOut


    NumPktsIn


    NumPktsOut


    PktBytesIn


    PktBytesOut


     

Connection manager monitor

    NumConnectionsOpened


    NumConnectionsRejected


     

Destination monitor

    PeakNumConsumers


    AvgNumConsumers


    PeakNumActiveConsumers


    AvgNumActiveConsumers


    PeakNumBackupConsumers


    AvgNumBackupConsumers


    PeakNumMsgs


    AvgNumMsgs


    NumMsgsIn


    NumMsgsOut


    MsgBytesIn


    MsgBytesOut


    PeakMsgBytes


    PeakTotalMsgBytes


    AvgTotalMsgBytes


     

Transaction manager monitor

    NumTransactionsCommitted


    NumTransactionsRollback


Notification

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

Table 3–3 Broker Configuration Notification

Name 

Description 

jmx.attribute.change

Attribute value changed 

Broker Monitor

The broker monitor MBean is used for monitoring a broker. There is one such MBean for each broker.

Object Name

The broker monitor MBean has the following object name:

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

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

Attributes

The broker monitor MBean has the attributes shown in Table 3–4. The names of these attributes are defined as static constants in the utility class BrokerAttributes.

Table 3–4 Broker Monitor Attributes

Name 

Type 

Settable? 

Description 

BrokerID

String

No 

Broker 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 brokers may have the same broker identifier.

For brokers using a JDBC-based persistent data store, this string is appended to the names of all database tables to make them unique in the case where more than one broker instance is using the same database. If a database is not used as the persistent data store, the value of this attribute is null.


Note –

For high-availability brokers, database table names use the ClusterID attribute (see Table 3–78) instead.


Version

String

No 

Broker version 

InstanceName

String

No 

Broker instance name 

Port

Integer

No 

Port number of Port Mapper 

ResourceState

String

No 

Current broker resource state:  

    green: < 80% memory utilization


    yellow: 80–90% memory utilization


    orange: 90–98% memory utilization


    red: > 98% memory utilization



Note –

The threshold values shown are the default thresholds for triggering the various states; these can be changed by setting the broker configuration properties

    imq.green.threshold


    imq.yellow.threshold


    imq.orange.threshold


    imq.red.threshold



Embedded

Boolean

No 

Is broker embedded (started from within another process)? 

Notifications

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

Table 3–5 Broker Monitor Notifications

Name 

Utility Constant 

Description 

mq.broker.shutdown.start

BrokerNotification.BROKER_SHUTDOWN_START

Broker has begun shutting down 

mq.broker.quiesce.start

BrokerNotification.BROKER_QUIESCE_START

Broker has begun quiescing 

mq.broker.quiesce.complete

BrokerNotification.BROKER_QUIESCE_COMPLETE

Broker has finished quiescing 

mq.broker.takeover.start [HA clusters only]

BrokerNotification.BROKER_TAKEOVER_START

Broker has begun taking over persistent data store from another broker 

mq.broker.takeover.complete

BrokerNotification.BROKER_TAKEOVER_COMPLETE

Broker has finished taking over persistent data store from another broker 

mq.broker.takeover.fail

BrokerNotification.BROKER_TAKEOVER_FAIL

Attempted takeover has failed 

mq.broker.resource.state.change

BrokerNotification.BROKER_RESOURCE_STATE_CHANGE

Broker’s resource state has changed 

mq.cluster.broker.join

ClusterNotification.CLUSTER_BROKER_JOIN

Broker has joined a cluster 

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

Table 3–6 Data Retrieval Methods for Broker Monitor Notifications

Method 

Result Type 

Description 

getBrokerID

String

Broker identifier

getBrokerAddress

String

Broker address, in the form hostName:portNumber

Example:

    host1:3000


getFailedBrokerID [HA clusters only]

String

Broker identifier of broker being taken over

getOldResourceState

String

Broker’s previous resource state:  

    green: < 80% memory utilization


    yellow: 80–90% memory utilization


    orange: 90–98% memory utilization


    red: > 98% memory utilization



Note –

The threshold values shown are the default thresholds for triggering the various states; these can be changed by setting the broker configuration properties

    imq.green.threshold


    imq.yellow.threshold


    imq.orange.threshold


    imq.red.threshold



getNewResourceState

String

Broker’s new resource state (see getOldResourceState, above, for possible values)

getHeapMemoryUsage

MemoryUsage

Broker’s current heap memory usage 

The value returned is an object of class MemoryUsage (defined in the package java.lang.management).