Oracle GlassFish Message Queue 4.4.2 Developer's Guide for JMX Clients

Destinations

This section describes the MBeans used for managing destinations:

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.

MaxNumActiveConsumers [Queue destinations only]

Integer

Yes 

Maximum number of associated active message consumers in load-balanced delivery 

A value of -1 denotes an unlimited number of consumers.

MaxNumBackupConsumers

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).

LocalDeliveryPreferred

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. 

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 

compact [File-based persistence only]

None 

None 

Compact persistent data store 


Note –

Only a paused destination can be compacted.


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?  

ConnectionID [Temporary destinations only]

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.

NumBackupConsumers [Queue destinations only]

Integer

No 

Current number of associated backup message consumers 

PeakNumBackupConsumers

Integer

No 

Peak number of associated backup message consumers since broker started 

AvgNumBackupConsumers

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 

DiskReserved [File-based persistence only]

Long

No 

Amount of disk space, in bytes, reserved for destination 

DiskUsed

Long

No 

Amount of disk space, in bytes, currently in use by destination 

DiskUtilizationRatio

Integer

No 

Ratio of disk space currently in use to disk space reserved for destination 

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 

getConnection [Temporary destinations only]

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.  

getBackupConsumerIDs [Queue destinations only]

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. 

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.

AutoCreateQueueMaxNumActiveConsumers [Auto-created queue destinations only]

Integer

Yes 

Maximum total number of active message consumers in load-balanced delivery 

A value of -1 denotes an unlimited number of consumers.

AutoCreateQueueMaxNumBackupConsumers

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.

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 

compact [File-based persistence only]

None 

None 

Compact all destinations 


Note –

Only paused destinations can be compacted.


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.