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

Destinations

This section describes the MBeans used for managing destinations:

The destination configuration MBean configures a destination.
The destination monitor MBean monitors a destination.
The destination manager configuration MBean manages destination configuration MBeans.
The destination manager monitor MBean manages destination monitor MBeans.

The following subsections describe each of these MBeans in detail.

Destination Configuration

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

Object Name

The destination configuration MBean has an object name of the following form:

com.sun.messaging.jms.server:type=Destination,subtype=Config,desttype=destinationType,name=destinationName

where destinationType is one of the destination types shown in Table 2–33 and destinationName is the name of the destination. For example:

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

The utility class MQObjectName provides a static method, createDestinationConfig, for constructing object names of this form.

Attributes

The destination configuration MBean has the attributes shown in Table 2–32. The names of these attributes are defined as static constants in the utility class DestinationAttributes.

Table 2–32 Destination Configuration Attributes


Name	Type	Settable?	Description
`Name`	`String`	No	Destination name
`Type`	`String`	No	Destination type See Table 2–33 for possible values.
`MaxNumMsgs`	`Long`	Yes	Maximum number of unconsumed messages A value of `-1` denotes an unlimited number of messages.
`MaxBytesPerMsg`	`Long`	Yes	Maximum size, in bytes, of any single message Rejection of a persistent message is reported to the producing client with an exception; no notice is sent for nonpersistent messages. A value of `-1` denotes an unlimited message size.
`MaxTotalMsgBytes`	`Long`	Yes	Maximum total memory, in bytes, for unconsumed messages
`LimitBehavior`	`String`	Yes	Broker behavior when memory-limit threshold reached See Table 2–34 for possible values. If the value is `REMOVE_OLDEST` or `REMOVE_LOW_PRIORITY` and the `UseDMQ` attribute is `true`, excess messages are moved to the dead message queue.
`MaxNumProducers`	`Integer`	Yes	Maximum number of associated message producers When this limit is reached, no new producers can be created. A value of `-1` denotes an unlimited number of producers.
`MaxNumActiveConsumers`	`Integer`	Yes	(Queue destinations only) Maximum number of associated active message consumers in load-balanced delivery A value of `-1` denotes an unlimited number of consumers.
`MaxNumBackupConsumers`	`Integer`	Yes	(Queue destinations only) Maximum number of associated backup message consumers in load-balanced delivery A value of `-1` denotes an unlimited number of consumers.
`ConsumerFlowLimit`	`Long`	Yes	Maximum number of messages delivered to consumer in a single batch In load-balanced queue delivery, this is the initial number of queued messages routed to active consumers before load balancing begins. A destination consumer can override this limit by specifying a lower value on a connection. A value of `-1` denotes an unlimited number of consumers.
`LocalOnly`	`Boolean`	No	Local delivery only? This property applies only to destinations in broker clusters, and cannot be changed once the destination has been created. If `true`, the destination is not replicated on other brokers and is limited to delivering messages only to local consumers (those connected to the broker on which the destination is created).
`LocalDeliveryPreferred`	`Boolean`	Yes	(Queue destinations only) Local delivery preferred? This property applies only to load-balanced delivery in broker clusters. If `true`, messages will be delivered to remote consumers only if there are no associated consumers on the local broker. The destination must not be restricted to local-only delivery (`LocalOnly` must be `false`).
`UseDMQ`	`Boolean`	Yes	Send dead messages to dead message queue? If `false`, dead messages will simply be discarded.

Table 2–33 shows the possible values for the Type attribute. These values are defined as static constants in the utility class DestinationType.

Table 2–33 Destination Configuration Type Values


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

Table 2–34 shows the possible values for the LimitBehavior attribute. These values are defined as static constants in the utility class DestinationLimitBehavior.

Table 2–34 Destination Limit Behaviors


Value	Utility Constant	Meaning
`FLOW_CONTROL`	`DestinationLimitBehavior.FLOW_CONTROL`	Slow down producers
`REMOVE_OLDEST`	`DestinationLimitBehavior.REMOVE_OLDEST`	Throw out oldest messages
`REMOVE_LOW_PRIORITY`	`DestinationLimitBehavior.REMOVE_LOW_PRIORITY`	Throw out lowest-priority messages according to age; no notice to producing client
`REJECT_NEWEST`	`DestinationLimitBehavior.REJECT_NEWEST`	Reject newest messages; notify producing client with an exception only if message is persistent

Operations

The destination configuration MBean supports the operations shown in Table 2–35. The names of these operations are defined as static constants in the utility class DestinationOperations.

Table 2–35 Destination Configuration Operations


Name	Parameters	Return Type	Description
`pause`	`pauseType` (`String`)	None	Pause message delivery See Table 2–36 for possible values of `pauseType`.
`pause`	None	None	Pause all message delivery Equivalent to `pause(DestinationPauseType.ALL)`.
`resume`	None	None	Resume message delivery
`purge`	None	None	Purge all messages
`compact`	None	None	(File-based persistence only) Compact persistent data store Note – Only a paused destination can be compacted.

Table 2–36 shows the possible values for the pause operation's pauseType parameter. These values are defined as static constants in the utility class DestinationPauseType.

Table 2–36 Destination Pause Types


Value	Utility Constant	Meaning
`PRODUCERS`	`DestinationPauseType.PRODUCERS`	Pause delivery from associated message producers
`CONSUMERS`	`DestinationPauseType.CONSUMERS`	Pause delivery to associated message consumers
`ALL`	`DestinationPauseType.ALL`	Pause all message delivery

Notification

The destination configuration MBean supports the notification shown in Table 2–37.

Table 2–37 Destination Configuration Notification


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

Destination Monitor

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

Object Name

The destination monitor MBean has an object name of the following form:

com.sun.messaging.jms.server:type=Destination,subtype=Monitor,desttype=destinationType,name=destinationName

where destinationType is one of the destination types shown in Table 2–39 and destinationName is the name of the destination. For example:

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

The utility class MQObjectName provides a static method, createDestinationMonitor, for constructing object names of this form.

Attributes

The destination monitor MBean has the attributes shown in Table 2–38. The names of these attributes are defined as static constants in the utility class DestinationAttributes.

Table 2–38 Destination Monitor Attributes


Name	Type	Settable?	Description
`Name`	`String`	No	Destination name
`Type`	`String`	No	Destination type See Table 2–39 for possible values.
`CreatedByAdmin`	`Boolean`	No	Administrator-created destination?
`Temporary`	`Boolean`	No	Temporary destination?
`ConnectionID`	`String`	No	(Temporary destinations only) Connection identifier
`State`	`Integer`	No	Current state See Table 2–40 for possible values.
`StateLabel`	`String`	No	String representation of current state: Useful for displaying the state in human-readable form, such as in the Java Monitoring and Management Console (`jconsole`). See Table 2–40 for possible values.
`NumProducers`	`Integer`	No	Current number of associated message producers
`NumConsumers`	`Integer`	No	Current number of associated message consumers For queue destinations, this attribute includes both active and backup consumers. For topic destinations, it includes both nondurable and (active and inactive) durable subscribers and is equivalent to `NumActiveConsumers`.
`PeakNumConsumers`	`Integer`	No	Peak number of associated message consumers since broker started For queue destinations, this attribute includes both active and backup consumers. For topic destinations, it includes both nondurable and (active and inactive) durable subscribers and is equivalent to `PeakNumActiveConsumers`.
`AvgNumConsumers`	`Integer`	No	Average number of associated message consumers since broker started For queue destinations, this attribute includes both active and backup consumers. For topic destinations, it includes both nondurable and (active and inactive) durable subscribers and is equivalent to `AvgNumActiveConsumers`.
`NumActiveConsumers`	`Integer`	No	Current number of associated active message consumers For topic destinations, this attribute includes both nondurable and (active and inactive) durable subscribers and is equivalent to `NumConsumers`.
`PeakNumActiveConsumers`	`Integer`	No	Peak number of associated active message consumers since broker started For topic destinations, this attribute includes both nondurable and (active and inactive) durable subscribers and is equivalent to `PeakNumConsumers`.
`AvgNumActiveConsumers`	`Integer`	No	Average number of associated active message consumers since broker started For topic destinations, this attribute includes both nondurable and (active and inactive) durable subscribers and is equivalent to `AvgNumConsumers`.
`NumBackupConsumers`	`Integer`	No	(Queue destinations only) Current number of associated backup message consumers
`PeakNumBackupConsumers`	`Integer`	No	(Queue destinations only) Peak number of associated backup message consumers since broker started
`AvgNumBackupConsumers`	`Integer`	No	(Queue destinations only) Average number of associated backup message consumers since broker started
`NumMsgs`	`Long`	No	Current number of messages stored in memory and persistent store Does not include messages held in transactions.
`NumMsgsPendingAcks`	`Long`	No	Current number of messages being held in memory and persistent store pending acknowledgment
`NumMsgsHeldInTransaction`	`Long`	No	Current number of messages being held in memory and persistent store in uncommitted transactions
`PeakNumMsgs`	`Long`	No	Peak number of messages stored in memory and persistent store since broker started
`AvgNumMsgs`	`Long`	No	Average number of messages stored in memory and persistent store since broker started
`NumMsgsIn`	`Long`	No	Cumulative number of messages received since broker started
`NumMsgsOut`	`Long`	No	Cumulative number of messages sent since broker started
`MsgBytesIn`	`Long`	No	Cumulative size in bytes of messages received since broker started
`MsgBytesOut`	`Long`	No	Cumulative size in bytes of messages sent since broker started
`PeakMsgBytes`	`Long`	No	Size in bytes of largest single message received since broker started
`TotalMsgBytes`	`Long`	No	Current total size in bytes of messages stored in memory and persistent store Does not include messages held in transactions.
`TotalMsgBytesHeldInTransaction`	`Long`	No	Current total size in bytes of messages being held in memory and persistent store in uncommitted transactions
`PeakTotalMsgBytes`	`Long`	No	Peak total size in bytes of messages stored in memory and persistent store since broker started
`AvgTotalMsgBytes`	`Long`	No	Average total size in bytes of messages stored in memory and persistent store since broker started
`DiskReserved`	`Long`	No	(File-based persistence only) Amount of disk space, in bytes, reserved for destination
`DiskUsed`	`Long`	No	(File-based persistence only) Amount of disk space, in bytes, currently in use by destination
`DiskUtilizationRatio`	`Integer`	No	(File-based persistence only) Ratio of disk space currently in use to disk space reserved for destination

Table 2–39 shows the possible values for the Type attribute. These values are defined as static constants in the utility class DestinationType.

Table 2–39 Destination Monitor Type Values


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

Table 2–40 shows the possible values for the State and StateLabel attributes. These values are defined as static constants in the utility class DestinationState.

Table 2–40 Destination State Values


Value	Utility Constant	String Representation	Meaning
`0`	`DestinationState.RUNNING`	`RUNNING`	Destination running
`1`	`DestinationState.CONSUMERS_PAUSED`	`CONSUMERS_PAUSED`	Message consumers paused
`2`	`DestinationState.PRODUCERS_PAUSED`	`PRODUCERS_PAUSED`	Message producers paused
`3`	`DestinationState.PAUSED`	`PAUSED`	Destination paused
`-1`	`DestinationState.UNKNOWN`	`UNKNOWN`	Destination state unknown

Operations

The destination monitor MBean supports the operations shown in Table 2–41. The names of these operations are defined as static constants in the utility class DestinationOperations.

Table 2–41 Destination Monitor Operations


Name	Parameters	Return Type	Description
`getConnection`	None	`ObjectName`	(Temporary destinations only) Object name of connection monitor MBean for connection
`getProducerIDs`	None	`String[]`	Producer identifiers of all current associated message producers
`getConsumerIDs`	None	`String[]`	Consumer identifiers of all current associated message consumers For queue destinations, this operation returns both active and backup consumers. For topic destinations, it returns both nondurable and (active and inactive) durable subscribers.
`getActiveConsumerIDs`	None	`String[]`	Consumer identifiers of all current associated active message consumers For topic destinations, this operation returns both nondurable and (active and inactive) durable subscribers.
`getBackupConsumerIDs`	None	`String[]`	(Queue destinations only) Consumer identifiers of all current associated backup message consumers

Notifications

The destination monitor MBean supports the notifications shown in Table 2–42. These notifications are instances of the Message Queue JMX class DestinationNotification, and their names are defined as static constants in that class.

Table 2–42 Destination Monitor Notifications


Name	Utility Constant	Description
`mq.destination.pause`	`DestinationNotification.DESTINATION_PAUSE`	Destination paused
`mq.destination.resume`	`DestinationNotification.DESTINATION_RESUME`	Destination resumed
`mq.destination.compact`	`DestinationNotification.DESTINATION_COMPACT`	Destination compacted
`mq.destination.purge`	`DestinationNotification.DESTINATION_PURGE`	Destination purged

Table 2–43 shows the methods defined in class DestinationNotification for obtaining details about a destination monitor notification.

Table 2–43 Data Retrieval Methods for Destination Monitor Notifications


Method	Return Type	Description
`getDestinationName`	`String`	Destination name
`getDestinationType`	`String`	Destination type See Table 2–39 for possible values.
`getCreatedByAdmin`	`Boolean`	Administrator-created destination?
`getPauseType`	`String`	Pause type See Table 2–36 for possible values.

Destination Manager Configuration

Each broker has a single destination manager configuration MBean, used for managing all of the broker's destination configuration MBeans.

Object Name

The destination manager configuration MBean has the following object name:

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

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

Attributes

The destination manager configuration MBean has the attributes shown in Table 2–44. The names of these attributes are defined as static constants in the utility class DestinationAttributes.

Table 2–44 Destination Manager Configuration Attributes


Name	Type	Settable?	Description
`AutoCreateQueues`	`Boolean`	Yes	Allow auto-creation of queue destinations?
`AutoCreateTopics`	`Boolean`	Yes	Allow auto-creation of topic destinations?
`NumDestinations`	`Integer`	No	Current total number of destinations
`MaxNumMsgs`	`Long`	Yes	Maximum total number of unconsumed messages A value of `-1` denotes an unlimited number of messages.
`MaxBytesPerMsg`	`Long`	Yes	Maximum size, in bytes,of any single message A value of `-1` denotes an unlimited message size.
`MaxTotalMsgBytes`	`Long`	Yes	Maximum total memory, in bytes, for unconsumed messages A value of `-1` denotes an unlimited number of bytes.
`AutoCreateQueueMaxNumActiveConsumers`	`Integer`	Yes	(Auto-created queue destinations only) Maximum total number of active message consumers in load-balanced delivery A value of `-1` denotes an unlimited number of consumers.
`AutoCreateQueueMaxNumBackupConsumers`	`Integer`	Yes	(Auto-created queue destinations only) Maximum total number of backup message consumers in load-balanced delivery A value of `-1` denotes an unlimited number of consumers.
`DMQTruncateBody`	`Boolean`	Yes	Remove message body before storing in dead message queue? If `true`, only the message header and property data will be saved.
`LogDeadMsgs`	`Boolean`	Yes	Log information about dead messages? If `true`, the following events will be logged: A destination is full, having reached its maximum size or message count. The broker discards a message for a reason other than an administrative command or delivery acknowledgment. The broker moves a message to the dead message queue.

Operations

The destination manager configuration MBean supports the operations shown in Table 2–45. The names of these operations are defined as static constants in the utility class DestinationOperations.

Table 2–45 Destination Manager Configuration Operations


Name	Parameters	Return Type	Description
`getDestinations`	None	`ObjectName[]`	Object names of destination configuration MBeans for all current destinations
`create`	`destinationType` (`String`) `destinationName` (`String`) `destinationAttributes` (`AttributeList`)	None	Create destination with specified type, name, and attributes The `destinationType` and `destinationName` parameters are required, but `destinationAttributes` may be `null`. See Table 2–46 for possible values of `destinationType`. The `destinationAttributes` list may include any of the attributes listed in Table 2–32 except `Name` and `Type`. The names of these attributes are defined as static constants in the utility class `DestinationAttributes`.
`create`	`destinationType` (`String`) `destinationName` (`String`)	None	Create destination with specified type and name Equivalent to `create(destinationType, destinationName, null)`. See Table 2–46 for possible values of `destinationType`.
`destroy`	`destinationType` (`String`) `destinationName` (`String`)	None	Destroy destination See Table 2–46 for possible values of `destinationType`.
`pause`	`pauseType` (`String`)	None	Pause message delivery for all destinations See Table 2–47 for possible values of `pauseType`.
`pause`	None	None	Pause all message delivery for all destinations Equivalent to `pause(DestinationPauseType.ALL)`.
`resume`	None	None	Resume message delivery for all destinations
`compact`	None	None	(File-based persistence only) Compact all destinations Note – Only paused destinations can be compacted.

Table 2–46 shows the possible values for the create and destroy operations' destinationType parameters. These values are defined as static constants in the utility class DestinationType.

Table 2–46 Destination Manager Configuration Type Values


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

Table 2–47 shows the possible values for the pause operation's pauseType parameter. These values are defined as static constants in the utility class DestinationPauseType.

Table 2–47 Destination Manager Pause Types


Value	Utility Constant	Meaning
`PRODUCERS`	`DestinationPauseType.PRODUCERS`	Pause delivery from associated message producers
`CONSUMERS`	`DestinationPauseType.CONSUMERS`	Pause delivery to associated message consumers
`ALL`	`DestinationPauseType.ALL`	Pause all delivery

Notification

The destination manager configuration MBean supports the notification shown in Table 2–48.

Table 2–48 Destination Manager Configuration Notification


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

Destination Manager Monitor

Each broker has a single destination manager monitor MBean, used for managing all of the broker's destination monitor MBeans.

Object Name

The destination manager monitor MBean has the following object name:

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

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

Attributes

The destination manager monitor MBean has the attributes shown in Table 2–49. The names of these attributes are defined as static constants in the utility class DestinationAttributes.

Table 2–49 Destination Manager Monitor Attributes


Name	Type	Settable?	Description
`NumDestinations`	`Integer`	No	Current total number of destinations
`NumMsgs`	`Long`	No	Current total number of messages stored in memory and persistent store for all destinations Does not include messages held in transactions.
`TotalMsgBytes`	`Long`	No	Current total size in bytes of messages stored in memory and persistent store for all destinations Does not include messages held in transactions.
`NumMsgsInDMQ`	`Long`	No	Current number of messages stored in memory and persistent store for dead message queue
`TotalMsgBytesInDMQ`	`Long`	No	Current total size in bytes of messages stored in memory and persistent store for dead message queue

Operation

The destination manager monitor MBean supports the operation shown in Table 2–50. The name of this operation is defined as a static constant in the utility class DestinationOperations.

Table 2–50 Destination Manager Monitor Operation


Name	Parameters	Return Type	Description
`getDestinations`	None	`ObjectName[]`	Object names of destination monitor MBeans for all current destinations

Notifications

The destination manager monitor MBean supports the notifications shown in Table 2–51. These notifications are instances of the Message Queue JMX class DestinationNotification, and their names are defined as static constants in that class.

Table 2–51 Destination Manager Monitor Notifications


Name	Utility Constant	Description
`mq.destination.create`	`DestinationNotification.DESTINATION_CREATE`	Destination created
`mq.destination.destroy`	`DestinationNotification.DESTINATION_DESTROY`	Destination destroyed
`mq.destination.pause`	`DestinationNotification.DESTINATION_PAUSE`	Destination paused
`mq.destination.resume`	`DestinationNotification.DESTINATION_RESUME`	Destination resumed
`mq.destination.compact`	`DestinationNotification.DESTINATION_COMPACT`	Destination compacted
`mq.destination.purge`	`DestinationNotification.DESTINATION_PURGE`	Destination purged

Table 2–52 shows the methods defined in class DestinationNotification for obtaining details about a destination manager monitor notification.

Table 2–52 Data Retrieval Methods for Destination Manager Monitor Notifications


Method	Return Type	Description
`getDestinationName`	`String`	Destination name
`getDestinationType`	`String`	Destination type See Table 2–46 for possible values.
`getCreatedByAdmin`	`Boolean`	Administrator-created destination?
`getPauseType`	`String`	Pause type See Table 2–47 for possible values.