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 3-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 3-32. The names of these attributes are defined as static constants in the utility class DestinationAttributes.

Table 3-32 Destination Configuration Attributes

Name Type Settable? Description Name String No Destination name Type String No Destination type See Table 3-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 3-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. MaxNumActiveConsumers1 Integer Yes Maximum number of associated active message consumers in load-balanced delivery A value of -1 denotes an unlimited number of consumers. MaxNumBackupConsumers1 Integer Yes 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). LocalDeliveryPreferred1 Boolean Yes 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. ValidateXMLSchemaEnabled Boolean Yes XML schema validation is enabled? If set to false or not set, then XML schema validation is not enabled for the destination. XMLSchemaURIList String Yes Space separated list of XML schema document (XSD) URI strings The URIs point to the location of one or more XSDs to use for XML schema validation, if enabled. Use double quotes around this value if multiple URIs are specified. Example: “http://foo/flap.xsd http://test.com/test.xsd” If this property is not set or null and XML validation is enabled, XML validation is performed using a DTD specified in the XML document. ReloadXMLSchemaOnFailure Boolean Yes Reload XML schema on failure enabled? If set to false or not set, then the schema is not reloaded if validation fails.

¹Queue destinations only

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

Table 3-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 3-34 shows the possible values for the LimitBehavior attribute. These values are defined as static constants in the utility class DestinationLimitBehavior.

Table 3-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 3-35. The names of these operations are defined as static constants in the utility class DestinationOperations.

Table 3-35 Destination Configuration Operations

Name Parameters Result Type Description pause pauseType (String) None Pause message delivery See Table 3-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 compact1 None None Compact persistent data store Note - Only a paused destination can be compacted.

¹File-based persistence only

Table 3-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 3-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 3-37.

Table 3-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 3-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 3-38. The names of these attributes are defined as static constants in the utility class DestinationAttributes.

Table 3-38 Destination Monitor Attributes

Name Type Settable? Description Name String No Destination name Type String No Destination type See Table 3-39 for possible values. CreatedByAdmin Boolean No Administrator-created destination? Temporary Boolean No Temporary destination? ConnectionID1 String No Connection identifier State Integer No Current state See Table 3-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 3-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. NumWildcardProducers Integer No Current number of wildcard message producers associated with the destination For topic destinations only. NumWildcardConsumers Integer No Current number of wildcard message consumers associated with the destination For topic destinations only. NumWildcards Integer No Current number of wildcard message producers and wildcard message consumers associated with the destination For topic destinations only. 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. NumBackupConsumers2 Integer No Current number of associated backup message consumers PeakNumBackupConsumers2 Integer No Peak number of associated backup message consumers since broker started AvgNumBackupConsumers2 Integer No 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. NumMsgsRemote Long No Current number of messages stored in memory and persistent store that were produced to a remote broker in a cluster. This number does not include messages included 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 NextMessageID String No JMS Message ID of the next message to be delivered to any consumer 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. TotalMsgBytesRemote Long No Current total size in bytes of messages stored in memory and persistent store that were produced to a remote broker in a cluster. This value does not include messages included 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 DiskReserved3 Long No Amount of disk space, in bytes, reserved for destination DiskUsed3 Long No Amount of disk space, in bytes, currently in use by destination DiskUtilizationRatio3 Integer No Ratio of disk space currently in use to disk space reserved for destination

¹Temporary destinations only

²Queue destinations only

³File-based persistence only

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

Table 3-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 3-40 shows the possible values for the State and StateLabel attributes. These values are defined as static constants in the utility class DestinationState.

Table 3-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 3-41. The names of these operations are defined as static constants in the utility class DestinationOperations.

Table 3-41 Destination Monitor Operations

Name Parameters Result Type Description getConnection1 None ObjectName 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. getBackupConsumerIDs2 None String[] Consumer identifiers of all current associated backup message consumers getConsumerWildcards none String[] Wildcard strings used by current consumers associated with the destination For topic destinations only. getProducerWildcards none String[] Wildcard strings used by current producers associated with the destination For topic destinations only. getWildcards none String[] Wildcard strings used by current consumers and producers associated with the destination For topic destinations only. getNumWildcardConsumers wildcard-String Integer Number of current consumers associated with the destination that are using the specified wildcard string For topic destinations only. getNumWildcardProducers wildcard-String Integer Number of current producers associated with the destination that are using the specified wildcard string For topic destinations only.

¹Temporary destinations only

²Queue destinations only

Notifications

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

Table 3-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 3-43 shows the methods defined in class DestinationNotification for obtaining details about a destination monitor notification.

Table 3-43 Data Retrieval Methods for Destination Monitor Notifications

Method Result Type Description getDestinationName String Destination name getDestinationType String Destination type See Table 3-39 for possible values. getCreatedByAdmin Boolean Administrator-created destination? getPauseType String Pause type See Table 3-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 3-44. The names of these attributes are defined as static constants in the utility class DestinationAttributes.

Table 3-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. AutoCreateQueueMaxNumActiveConsumers1 Integer Yes Maximum total number of active message consumers in load-balanced delivery A value of -1 denotes an unlimited number of consumers. AutoCreateQueueMaxNumBackupConsumers1 Integer Yes 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.

¹Auto-created queue destinations only

Operations

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

Table 3-45 Destination Manager Configuration Operations

Name Parameters Result 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 3-46 for possible values of destinationType. The destinationAttributes list may include any of the attributes listed in Table 3-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 3-46 for possible values of destinationType. destroy destinationType (String) destinationName (String) None Destroy destination See Table 3-46 for possible values of destinationType. pause pauseType (String) None Pause message delivery for all destinations See Table 3-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 compact1 None None Compact all destinations Note - Only paused destinations can be compacted.

¹File-based persistence only

Table 3-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 3-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 3-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 3-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 3-48.

Table 3-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 3-49. The names of these attributes are defined as static constants in the utility class DestinationAttributes.

Table 3-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 3-50. The name of this operation is defined as a static constant in the utility class DestinationOperations.

Table 3-50 Destination Manager Monitor Operation

Name Parameters Result 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 3-51. These notifications are instances of the Message Queue JMX class DestinationNotification, and their names are defined as static constants in that class.

Table 3-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 3-52 shows the methods defined in class DestinationNotification for obtaining details about a destination manager monitor notification.

Table 3-52 Data Retrieval Methods for Destination Manager Monitor Notifications

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