Physical Destination Property Reference

Physical Destination Properties

Table 18-1 lists the configuration properties for physical destinations. These properties can be set when creating or updating a physical destination. For auto-created destinations, you set default values in the broker’s instance configuration file (see Table 17-3).

Table 18-1 Physical Destination Properties

Property Type Default Value Description

Property	Type	Default Value	Description
`maxNumMsgs`^Foot 1	Integer	`-1`	Maximum number of unconsumed messages A value of `-1` denotes an unlimited number of messages. For the dead message queue, the default value is `1000`. Note: When flow control is in effect (`limitBehavior` = `FLOW_CONTROL`), it is possible for the specified message limit to be exceeded because the broker cannot react quickly enough to stop the flow of incoming messages. In such cases, the value specified for `maxNumMsgs` serves as merely a hint for the broker rather than a strictly enforced limit. However, if the number of unconsumed messages would exceed `imq.system.max_count`, the broker generates a `ResourceAllocationException` indicating that the destination is full and rejecting new messages.
`maxBytesPerMsg`	String	`-1`	Maximum size, in bytes, of any single message Rejection of a persistent message is reported to the producing client with an exception; no notification is sent for nonpersistent messages.
+	+	+	The value may be expressed in bytes, kilobytes, or megabytes, using the following suffixes: `b`: Bytes `k`: Kilobytes (1024 bytes) `m`: Megabytes (1024 × 1024 = 1,048,576 bytes)
+	+	+	An unsuffixed value is expressed in bytes; a value of `-1` denotes an unlimited message size.
+	+	+	Examples: `1600`: 1600 bytes `1600b`: 1600 bytes `16k`: 16 kilobytes (= 16,384 bytes) `16m`: 16 megabytes (= 16,777,216 bytes) `-1`: No limit
`maxTotalMsgBytes`^Footref 1	String	`-1`	Maximum total memory, in bytes, for unconsumed messages The syntax is the same as for `maxBytesPerMsg` (see above). For the dead message queue, the default value is `10m`.
`limitBehavior`	String	`REJECT_NEWEST`	Broker behavior when memory-limit threshold reached: `FLOW_CONTROL`: Slow down producers `REMOVE_OLDEST`: Throw out oldest messages `REMOVE_LOW_PRIORITY`: Throw out lowest-priority messages according to age; no notification to producing client `REJECT_NEWEST`: Reject newest messages; notify producing client with an exception only if message is persistent When `FLOW_CONTROL` is specified, it is still possible for the number of messages to exceed `imq.system.max_count`. In this situation, the broker generates a `ResourceAllocationException` indicating that the destination is full and rejecting new messages.
+	+	+	If the value is `REMOVE_OLDEST` or `REMOVE_LOW_PRIORITY` and the `useDMQ` property is `true`, excess messages are moved to the dead message queue. For the dead message queue itself, the default limit behavior is `REMOVE_OLDEST` and cannot be set to `FLOW_CONTROL`.
`maxNumProducers`^Foot 2	Integer	`100`	Maximum number of message producers for destination When this limit is reached, no new producers can be created. A value of `-1` denotes an unlimited number of producers.
`maxNumActiveConsumers`^Foot 3	Integer	`-1`	Maximum number of active message consumers in load-balanced delivery from queue destination A value of `-1` denotes an unlimited number of consumers. This property used mostly in cases where message order is important and you want to provide backup consumers in case the principal consumer of a queue fails. If message order is not important, then you would simply use multiple consumers to provide for scalability and availability.
`maxNumBackupConsumers`^Footref 3	Integer	`0`	Maximum number of backup message consumers in load-balanced delivery from queue destination A value of `-1` denotes an unlimited number of consumers.
`consumerFlowLimit`	Integer	`1000`	Maximum number of messages delivered to a consumer in a single batch In load-balanced queue delivery, this is the initial number of queued messages routed to an active consumer before load balancing begins. The client runtime can override this limit by specifying a lower value on the connection factory object. A value of `0` or `-1` denotes an unlimited number of messages. Not used when the JMS resource adapter, jmsra, is used to consume messages in a GlassFish Server cluster.
`isLocalOnly`^Footref 2	Boolean	`false`	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`^Footref 2 ^,^Footref 3	Boolean	`false`	Local delivery preferred? This property applies only to load-balanced queue delivery in broker clusters. If `true`, messages will be delivered to remote consumers only if there are no consumers on the local broker; the destination must not be restricted to local-only delivery (`isLocalOnly` must be `false`).
`useDMQ`^Footref 2	Boolean	`true`	Send dead messages to dead message queue? If `false`, dead messages will simply be discarded.
`validateXMLSchemaEnabled` ^Foot 4	Boolean	`false`	XML schema validation is enabled? When XML validation is enabled, the Message Queue client runtime will attempt to validate an XML message against the specified XSDs (or against the DTD, if no XSD is specified) before sending it to the broker. If the specified schema cannot be located or the message cannot be validated, the message is not sent, and an exception is thrown. Client applications using this feature should use JRE 1.5 or above. If set to `false` or not set, then XML schema validation is not enabled for the destination.
`XMLSchemaURIList`^Footref 4	String	null	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. if an XSD is changed, as a result of changing application requirements, all client applications producing XML messages based on the changed XSD must reconnect to the broker.
`reloadXMLSchemaOnFailure`^Footref 4	Boolean	`false`	Reload XML schema on failure enabled? If set to `true` and XML validation fails, then the Message Queue client runtime will attempt to reload the XSD before attempting again to validate a message. The client runtime will throw an exception if the validation fails using the reloaded SXD. If set to false or not set, then the schema is not reloaded if validation fails.

`maxNumMsgs`^Foot 1

Integer

-1

Maximum number of unconsumed messages

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

For the dead message queue, the default value is 1000.

Note: When flow control is in effect (limitBehavior = FLOW_CONTROL), it is possible for the specified message limit to be exceeded because the broker cannot react quickly enough to stop the flow of incoming messages. In such cases, the value specified for maxNumMsgs serves as merely a hint for the broker rather than a strictly enforced limit. However, if the number of unconsumed messages would exceed imq.system.max_count, the broker generates a ResourceAllocationException indicating that the destination is full and rejecting new messages.

maxBytesPerMsg

String

-1

Maximum size, in bytes, of any single message

Rejection of a persistent message is reported to the producing client with an exception; no notification is sent for nonpersistent messages.

The value may be expressed in bytes, kilobytes, or megabytes, using the following suffixes:

b: Bytes
k: Kilobytes (1024 bytes)
m: Megabytes (1024 × 1024 = 1,048,576 bytes)

An unsuffixed value is expressed in bytes; a value of -1 denotes an unlimited message size.

Examples:

1600: 1600 bytes
1600b: 1600 bytes
16k: 16 kilobytes (= 16,384 bytes)
16m: 16 megabytes (= 16,777,216 bytes)
-1: No limit

`maxTotalMsgBytes`^Footref 1

String

-1

Maximum total memory, in bytes, for unconsumed messages

The syntax is the same as for maxBytesPerMsg (see above).

For the dead message queue, the default value is 10m.

limitBehavior

String

REJECT_NEWEST

Broker behavior when memory-limit threshold reached:

FLOW_CONTROL: Slow down producers
REMOVE_OLDEST: Throw out oldest messages
REMOVE_LOW_PRIORITY: Throw out lowest-priority messages according to age; no notification to producing client
REJECT_NEWEST: Reject newest messages; notify producing client with an exception only if message is persistent

When FLOW_CONTROL is specified, it is still possible for the number of messages to exceed imq.system.max_count. In this situation, the broker generates a ResourceAllocationException indicating that the destination is full and rejecting new messages.

If the value is REMOVE_OLDEST or REMOVE_LOW_PRIORITY and the useDMQ property is true, excess messages are moved to the dead message queue. For the dead message queue itself, the default limit behavior is REMOVE_OLDEST and cannot be set to FLOW_CONTROL.

`maxNumProducers`^Foot 2

Integer

100

Maximum number of message producers for destination

When this limit is reached, no new producers can be created. A value of -1 denotes an unlimited number of producers.

`maxNumActiveConsumers`^Foot 3

Integer

-1

Maximum number of active message consumers in load-balanced delivery from queue destination

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

This property used mostly in cases where message order is important and you want to provide backup consumers in case the principal consumer of a queue fails. If message order is not important, then you would simply use multiple consumers to provide for scalability and availability.

`maxNumBackupConsumers`^Footref 3

Integer

0

Maximum number of backup message consumers in load-balanced delivery from queue destination

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

consumerFlowLimit

Integer

1000

Maximum number of messages delivered to a consumer in a single batch

In load-balanced queue delivery, this is the initial number of queued messages routed to an active consumer before load balancing begins.

The client runtime can override this limit by specifying a lower value on the connection factory object.

A value of 0 or -1 denotes an unlimited number of messages.

Not used when the JMS resource adapter, jmsra, is used to consume messages in a GlassFish Server cluster.

`isLocalOnly`^Footref 2

Boolean

false

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`^Footref 2 ^,^Footref 3

Boolean

false

Local delivery preferred?

This property applies only to load-balanced queue delivery in broker clusters. If true, messages will be delivered to remote consumers only if there are no consumers on the local broker; the destination must not be restricted to local-only delivery (isLocalOnly must be false).

`useDMQ`^Footref 2

Boolean

true

Send dead messages to dead message queue?

If false, dead messages will simply be discarded.

validateXMLSchemaEnabled

^Foot 4

Boolean

false

XML schema validation is enabled?

When XML validation is enabled, the Message Queue client runtime will attempt to validate an XML message against the specified XSDs (or against the DTD, if no XSD is specified) before sending it to the broker. If the specified schema cannot be located or the message cannot be validated, the message is not sent, and an exception is thrown. Client applications using this feature should use JRE 1.5 or above.

If set to false or not set, then XML schema validation is not enabled for the destination.

`XMLSchemaURIList`^Footref 4

String

null

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.

if an XSD is changed, as a result of changing application requirements, all client applications producing XML messages based on the changed XSD must reconnect to the broker.

`reloadXMLSchemaOnFailure`^Footref 4

Boolean

false

Reload XML schema on failure enabled?

If set to true and XML validation fails, then the Message Queue client runtime will attempt to reload the XSD before attempting again to validate a message. The client runtime will throw an exception if the validation fails using the reloaded SXD.

If set to false or not set, then the schema is not reloaded if validation fails.

^Footnote 1In a cluster environment, applies to each individual instance of a destination rather than collectively to all instances in the cluster

^Footnote 2Does not apply to dead message queue

^Footnote 3Queue destinations only

^Footnote 4This property should be set when a destination is inactive: when it has no consumers or producers and when there are no messages in the destination. Otherwise the producer must reconnect.

18 Physical Destination Property Reference

Physical Destination Properties