Message Queue MBeans

The JMX architecture is based on the notion of a managed bean, or MBean, a Java object conforming to the management interface defined in the JMX Specification. This management interface consists of the following:

• Attributes holding data values representing static or dynamic properties of the underlying resource

• Operations that can be invoked to perform actions on the underlying resource

• Notifications informing the client application of state changes or other significant events affecting the underlying resource

Message Queue 's JMX functionality is exposed through MBeans associated with various Message Queue resources. These MBeans are of two kinds: resource MBeans and manager MBeans. The attributes, operations, and notifications available for each type of MBean are described in detail in Chapter 2, Message Queue MBean Reference.

Resource MBeans

Resource MBeans are associated with individual Message Queue resources of the following types:

• Message brokers

• Connection services

• Connections

• Destinations

• Broker clusters

• Logging

• The Java Virtual Machine (JVM)

Configuration and monitoring functions are implemented by separate MBeans. Each managed resource is associated with a configuration MBean for setting the resource's configuration and a monitor MBean for gathering (typically transient) information about its runtime state. For instance, there is a destination configuration MBean for configuring a destination and a destination monitor MBean for obtaining runtime information about it. In general, each instance of a managed resource has its own pair of MBeans: thus there is a separate destination configuration MBean and destination monitor MBean for each individual destination. (In the case of the Java Virtual Machine, there is only a JVM monitor MBean with no corresponding configuration MBean.)

Configuration MBeans are used to perform such tasks as 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

• Purge all messages from a destination

• Set the level of logging information to be written to an output channel

Monitor MBeans are used to obtain runtime information such as the following:

• The current number of connections on a service

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

• The current state (running or paused) of a queue destination

• The current number of message producers for a topic destination

• The host name and port number of a cluster's master broker

• The current JVM heap size

Manager MBeans

In addition to the resource MBeans associated with individual resources, there are also manager MBeans for managing some whole categories of resources. These manager MBeans also come in pairs—one for configuration and one for monitoring—for the following resource categories:

• Connection services

• Connections

• Destinations

• Message producers

• Message consumers

• Transactions

Unlike individual resource MBeans, a broker has only one pair of manager MBeans for each whole category of resources: for instance, a single destination manager configuration MBean and a single destination manager monitor MBean. For some categories (connection services, connections, destinations), the manager MBeans exist in addition to the ones for individual resources, and are used to manage the collection of resource MBeans within the category or to perform global tasks that are beyond the scope of individual resource MBeans. Thus, for instance, there is a connection manager configuration MBean and a connection manager monitor MBean in addition to the connection configuration and connection monitor MBeans associated with individual connections. Manager MBeans of this type are used to perform tasks such as the following:

• Get the object names of the service monitor MBeans for all available connection services

• Get the total number of current connections

• Destroy a connection

• Create or destroy a destination

• Enable or disable auto-creation of destinations

• Pause message delivery for all destinations

In other cases (message producers, message consumers, transactions), there are no MBeans associated with individual resources and all of the resources in the category are managed through the manager MBeans themselves. The manager MBeans for these categories can be used for such tasks as the following:

• Get the destination name associated with a message producer

• Purge all messages from a durable subscriber

• Commit or roll back a transaction

Object Names

Each individual MBean is designated by an object name belonging to the JMX class ObjectName, which encapsulates a string identifying the MBean. For Message Queue MBeans, the encapsulated name string has the following syntax:

com.sun.messaging.jms.server:property=value[,property=value]*

Table 1–1 shows the possible properties.

Table 1–1 Object Name Properties

Property	Description	Values
type	MBean type	See Table 1–2.
subtype	MBean subtype	See Table 1–3.
desttype	Destination type  Applies only to MBeans of the following types:   Destination configuration Destination monitor	See Table 1–4.
name	Resource name  Applies only to MBeans of the following types:   Service configuration Service monitor Destination configuration Destination monitor	For service configuration and service monitor MBeans, see Table 1–5. For destination configuration and destination monitor MBeans, the destination name.   Examples: myTopic temporary_destination://queue/129.145.180.99/63008/1
id	Resource identifier  Applies only to MBeans of the following types:   Connection configuration Connection monitor	Example: 7853717387765338368

Table 1–2 shows the possible values for the object name's type property.

Table 1–2 Message Queue MBean Types

Value	Description
Broker	Broker resource MBean
Service	Connection service resource MBean
ServiceManager	Connection service manager MBean
Connection	Connection resource MBean
ConnectionManager	Connection manager MBean
Destination	Destination resource MBean
DestinationManager	Destination manager MBean
ProducerManager	Message producer manager MBean
ConsumerManager	Message consumer manager MBean
TransactionManager	Transaction manager MBean
Cluster	Broker cluster resource MBean
Log	Logging resource MBean
JVM	JVM resource MBean

Table 1–3 shows the possible values for the object name's subtype property.

Table 1–3 Message Queue MBean Subtypes

Value	Description
Config	Configuration MBean
Monitor	Monitor MBean

For destination configuration and destination monitor MBeans, the object name's desttype property specifies whether the destination is a point-to-point queue or a publish/subscribe topic. Table 1–4 shows the possible values, which are defined for convenience as static constants in the utility class DestinationType.

Table 1–4 Destination Types

Value	Utility Constant	Meaning
q	DestinationType.QUEUE	Queue (point-to-point) destination
t	DestinationType.TOPIC	Topic (publish/subscribe) destination

For service configuration and service monitor MBeans, the object name's name property identifies the connection service with which the MBean is associated. Table 1–5 shows the possible values.

Table 1–5 Connection Service Names

Service Name	Service Type	Protocol Type
jms	Normal	TCP
ssljms	Normal	TLS (SSL-based security)
httpjms	Normal	HTTP
httpsjms	Normal	HTTPS (SSL-based security)
admin	Admin	TCP
ssladmin	Admin	TLS (SSL-based security)

The following are some example object names:

• Broker configuration MBean:

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

• Service manager monitor MBean:

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

• Connection configuration MBean:

  com.sun.messaging.jms.server:type=Connection,subtype=Config,id=7853717387765338368
  

• Destination monitor MBean for a queue named Dest:

  com.sun.messaging.jms.server:type=Destination,subtype=Monitor,desttype=t,name="Dest"
  

The object names for each type of Message Queue MBean are given in the relevant sections of Chapter 2, Message Queue MBean Reference. All such names are either defined as static constants or returned by static methods in the utility class MQObjectName (see Table 1–6). For instance, the constant

MQObjectName.BROKER_CONFIG_MBEAN_NAME

is defined as a string representing the object name for a broker configuration MBean, and the method call

MQObjectName.createDestinationMonitor(DestinationType.TOPIC, "Dest");

returns the destination monitor MBean object name shown above. Note that, whereas methods such as createDestinationMonitor return an actual object name (that is, an object of class ObjectName) that can be assigned directly to a variable of that type

ObjectName  destMonitorName
    = MQObjectName.createDestinationMonitor(DestinationType.TOPIC, "Dest");

constants like BROKER_CONFIG_MBEAN_NAME instead represent an ordinary string (class String) that must then be converted into the corresponding object name itself:

ObjectName  brokerConfigName = new ObjectName(MQObjectName.BROKER_CONFIG_MBEAN_NAME);

Table 1–6 Utility Constants and Methods for Object Names

MBean Type	Utility Constant or Method
Broker configuration	MQObjectName.BROKER_CONFIG_MBEAN_NAME
Broker monitor	MQObjectName.BROKER_MONITOR_MBEAN_NAME
Service configuration	MQObjectName.createServiceConfig
Service monitor	MQObjectName.createServiceMonitor
Service manager configuration	MQObjectName.SERVICE_MANAGER_CONFIG_MBEAN_NAME
Service manager monitor	MQObjectName.SERVICE_MANAGER_MONITOR_MBEAN_NAME
Connection configuration	MQObjectName.createConnectionConfig
Connection monitor	MQObjectName.createConnectionMonitor
Connection manager configuration	MQObjectName.CONNECTION_MANAGER_CONFIG_MBEAN_NAME
Connection manager monitor	MQObjectName.CONNECTION_MANAGER_MONITOR_MBEAN_NAME
Destination configuration	MQObjectName.createDestinationConfig
Destination monitor	MQObjectName.createDestinationMonitor
Destination manager configuration	MQObjectName.DESTINATION_MANAGER_CONFIG_MBEAN_NAME
Destination manager monitor	MQObjectName.DESTINATION_MANAGER_MONITOR_MBEAN_NAME
Producer manager configuration	MQObjectName.PRODUCER_MANAGER_CONFIG_MBEAN_NAME
Producer manager monitor	MQObjectName.PRODUCER_MANAGER_MONITOR_MBEAN_NAME
Consumer manager configuration	MQObjectName.CONSUMER_MANAGER_CONFIG_MBEAN_NAME
Consumer manager monitor	MQObjectName.CONSUMER_MANAGER_MONITOR_MBEAN_NAME
Transaction manager configuration	MQObjectName.TRANSACTION_MANAGER_CONFIG_MBEAN_NAME
Transaction manager monitor	MQObjectName.TRANSACTION_MANAGER_MONITOR_MBEAN_NAME
Cluster configuration	MQObjectName.CLUSTER_CONFIG_MBEAN_NAME
Cluster monitor	MQObjectName.CLUSTER_MONITOR_MBEAN_NAME
Log configuration	MQObjectName.LOG_CONFIG_MBEAN_NAME
Log monitor	MQObjectName.LOG_MONITOR_MBEAN_NAME
JVM monitor	MQObjectName.JVM_MONITOR_MBEAN_NAME

Utility Classes

The package com.sun.messaging.jms.management.server in the Message Queue JMX interface contains a collection of utility classes defining useful static constants and methods for use with Message Queue MBeans. Table 1–7 lists these utility classes; see the relevant sections of Chapter 2, Message Queue MBean Reference and the Message Queue JMX JavaDoc documentation for further details.

Table 1–7 Message Queue JMX Utility Classes

Class	Description
MQObjectName	Constants and methods for Message Queue MBean object names
MQNotification	Superclass for all Message Queue JMX notifications
BrokerAttributes	Names of broker attributes
BrokerOperations	Names of broker operations
BrokerNotification	Constants and methods related to broker notifications
BrokerState	Constants related to broker state
ServiceAttributes	Names of connection service attributes
ServiceOperations	Names of connection service operations
ServiceNotification	Constants and methods related to connection service notifications
ServiceState	Constants related to connection service state
ConnectionAttributes	Names of connection attributes
ConnectionOperations	Names of connection operations
ConnectionNotification	Constants and methods related to connection notifications
DestinationAttributes	Names of destination attributes
DestinationOperations	Names of destination operations
DestinationNotification	Constants and methods related to destination notifications
DestinationType	Names of destination types
DestinationState	Constants related to destination state
DestinationLimitBehavior	Names of destination limit behaviors
DestinationPauseType	Constants related to destination pause type
ProducerAttributes	Names of message producer attributes
ProducerOperations	Names of message producer operations
ProducerInfo	Field names in composite data object for message producers
ConsumerAttributes	Names of message consumer attributes
ConsumerOperations	Names of message consumer operations
ConsumerInfo	Field names in composite data object for message consumers
TransactionAttributes	Names of transaction attributes
TransactionOperations	Names of transaction operations
TransactionNotification	Constants and methods related to transaction notifications
TransactionInfo	Field names in composite data object for transactions
TransactionState	Constants related to transaction state
ClusterAttributes	Names of broker cluster attributes
ClusterOperations	Names of broker cluster operations
ClusterNotification	Constants and methods related to broker cluster notifications
BrokerClusterInfo	Field names in composite data object for broker clusters
LogAttributes	Names of logging attributes
LogNotification	Constants and methods related to logging notifications
LogLevel	Names of logging levels
JVMAttributes	Names of Java Virtual Machine (JVM) attributes