JMS Resource Adapter Property Reference

20 JMS Resource Adapter Property Reference

This chapter describes the configuration properties of the Message Queue JMS Resource Adapter (JMS RA), which enables you to integrate Message Queue with any Java EE application server by means of the standard Java EE connector architecture (JCA). When plugged into an application server, the Resource Adapter allows applications deployed in that application server to use Message Queue to send and receive JMS messages.

The Message Queue JMS Resource Adapter exposes its configuration properties through three JavaBean components:

The ResourceAdapter JavaBean (ResourceAdapter JavaBean) affects the behavior of the Resource Adapter as a whole.
The ManagedConnectionFactory JavaBean (ManagedConnectionFactory JavaBean) affects connections created by the Resource Adapter for use by message-driven beans (MDBs).
The ActivationSpec JavaBean (ActivationSpec JavaBean) affects message endpoints that represent MDBs in their interactions with the messaging system.

To set property values for these entities, you use the tools provided by your application server for configuration and deployment of the Resource Adapter and for deployment of MDBs.

This chapter lists and describes the configuration properties of the Message Queue JMS Resource Adapter. It contains the following sections:

About Shared Topic Subscriptions for Clustered Containers
ResourceAdapter JavaBean
ManagedConnectionFactory JavaBean
ActivationSpec JavaBean

About Shared Topic Subscriptions for Clustered Containers

The Message Queue JMS Resource Adapter provides a special feature called shared subscriptions for containers that support clustering, such as GlassFish Server. This feature enables clustered containers to share the load of processing messages for topic subscriptions across the instances of a cluster.

When this feature is enabled, the following behaviors apply:

Attempts by multiple connections to use the same client id do not result in an exception, provided that the connections are from different instances in the cluster.
Two or more subscriptions on the same topic with the same client id and (if the subscription is durable) the same durable subscription name are considered "shared"; that is, they are treated as a single subscription, with each message being sent to only one of the participating subscriptions.

The sharing of subscriptions relies on client id being set, not only for durable subscriptions (which always require client id) but for non-durable subscriptions (which do not normally require client id). If the subscription is being created by the resource adapter for use by a message-driven bean (MDB), and client id is not set, then the resource adapter will set the client id to the name of the MDB. However if the subscription is being created programmatically using the JMS API, and client id is not set, then an exception will be thrown.

Note that, in the EJB or web container, applications that create a connection using a connection factory are not permitted to set client id on the newly created connection, but must set it on the connection factory instead. This restriction is imposed by the EJB specification, though it applies to web components as well. There is no such restrictions in the application client container.

Disabling Shared Subscriptions

By default, the shared subscriptions feature is enabled. In some applications that use non-durable subscriptions, however, the shared behavior is not desired. In such cases, disable the shared subscriptions feature by setting the useSharedSubscriptionInClusteredContainer property to false on either the ActivationSpec or ManagedConnectionFactory, as appropriate:

For an MDB, set the ActivationSpec property useSharedSubscriptionInClusteredContainer to false. Do this in exactly the same way as with other ActivationSpec properties, using annotations in the MDB itself or in the deployment descriptor ejb-jar.xml or glassfish-ejb-jar.xml. Alternatively, if the glassfish-ejb-jar.xml deployment descriptor specifies a connection factory using the <mdb-connection-factory> element, then the property can be configured on the connection factory instead, as described in the next item.
For GlassFish applications creating a non-durable subscription using the JMS API rather than using an MDB, set the connection factory property useSharedSubscriptionInClusteredContainer to false using the GlassFish Administration Console, the GlassFish asadmin command or the resource descriptor glassfish-resources.xml.

Only set useSharedSubscriptionInClusteredContainer to false for non-durable subscriptions.

Consumer Flow Control When Shared Subscriptions Are Used

When shared subscriptions are being used, then consumer flow control operates slightly differently than is described in Client Runtime Message Flow Adjustments.

With a normal topic subscription, the maximum number of messages that can be held pending for any single subscriber, waiting to be consumed, is defined by the broker property imq.autocreate.topic.consumerFlowLimit for auto-created topics, or the destination property consumerFlowLimit for administratively-created topics. Both properties have a default value of 1000. This can be overridden on a per-connection basis by setting the connection factory property imqConsumerFlowLimit to a lower value than that defined for the topic.

When the subscription is shared, however, different logic applies. In this case, the limit is defined by the broker property imq.autocreate.topic.sharedConsumerFlowLimit for auto-created topics or the broker property imq.admincreate.topic.sharedConsumerFlowLimit for all administratively-created topics. It is not possible to set this limit on individual administratively-created topics. Both properties have a default value of 5. This can be overridden on a per-connection basis by setting the connection factory property imqConsumerFlowLimit to a lower value than that defined for the topic. Note that, as with all connection factory properties, this is specified using the options property of the managed connection factory.

ResourceAdapter JavaBean

The ResourceAdapter configuration configures the default JMS Resource Adapter behavior. Table 20-1 lists and describes the properties with which you can configure this JavaBean.

Table 20-1 Resource Adapter Properties

Property Type Default Value Description

Property	Type	Default Value	Description
`connectionURL`^Foot 1	String	`mq://localhost:7676/jms`	Message service address for connecting to the Message Queue service
`brokerInstanceName`	String	`imqbroker`	Name of broker instance
`brokerPort`	Integer	`7676`	Port number for connecting to broker
`brokerBindAddress`	String	Null	Address to which broker binds on host machine If null, the broker will bind to all addresses on the host machine.
`userName`^Foot 2	String	`guest`	Default user name for connecting to Message Queue service
`password`^Footref 2	String	`guest`	Default password for connecting to Message Queue service
`addressListBehavior`	String	`PRIORITY`	Order in which to attempt connection to Message Queue service: `PRIORITY`: Order specified in address list `RANDOM`: Random order Note: Reconnection attempts after a connection failure start with the broker whose connection failed and proceed sequentially through the address list, regardless of the value set for this property.
`addressListIterations`	Integer	`1`	Number of times to iterate through address list attempting to establish or reestablish a connection
`reconnectEnabled`	Boolean	`false`	Attempt to reestablish a lost connection?
`reconnectAttempts`	Integer	`6`	Number of times to attempt reconnection to each address in address list before moving on to next
`reconnectInterval`	Long integer	`30000`	Interval, in milliseconds, between reconnection attempts
`brokerEnableHA`	Boolean	`false`	Enable high availability?
`clusterID`	String	None	Cluster identifier If specified, only brokers with the same cluster identifier can be clustered together. In the event of broker failure, client connections will fail over only to brokers with the same cluster identifier as the original broker. If not specified, client connections can fail over to any other broker with an unspecified cluster identifier. For standalone brokers (those not belonging to a cluster), this property is ignored. The identifier may contain only alphabetic letters (`A`-`Z`, `a`-`z`), numeric digits (`0`-`9`), and the underscore character (`_`).
`brokerID`	String	None	Broker identifier For brokers using a JDBC-based persistent data store, this string is appended to the names of all database tables to make them unique in the case where more than one broker instance is using the same database. For brokers using a file-based data store, this property is ignored. In an enhanced cluster, each broker must have a unique broker identifier. The identifier may contain only alphabetic letters (`A`-`Z`, `a`-`z`), numeric digits (`0`-`9`), and the underscore character (`_`).

`connectionURL`^Foot 1

String

mq://localhost:7676/jms

Message service address for connecting to the Message Queue service

brokerInstanceName

String

imqbroker

Name of broker instance

brokerPort

Integer

7676

Port number for connecting to broker

brokerBindAddress

String

Null

Address to which broker binds on host machine

If null, the broker will bind to all addresses on the host machine.

`userName`^Foot 2

String

guest

Default user name for connecting to Message Queue service

`password`^Footref 2

String

guest

Default password for connecting to Message Queue service

addressListBehavior

String

PRIORITY

Order in which to attempt connection to Message Queue service:

PRIORITY: Order specified in address list
RANDOM: Random order

Note: Reconnection attempts after a connection failure start with the broker whose connection failed and proceed sequentially through the address list, regardless of the value set for this property.

addressListIterations

Integer

1

Number of times to iterate through address list attempting to establish or reestablish a connection

reconnectEnabled

Boolean

false

Attempt to reestablish a lost connection?

reconnectAttempts

Integer

6

Number of times to attempt reconnection to each address in address list before moving on to next

reconnectInterval

Long integer

30000

Interval, in milliseconds, between reconnection attempts

brokerEnableHA

Boolean

false

Enable high availability?

clusterID

String

None

Cluster identifier

If specified, only brokers with the same cluster identifier can be clustered together. In the event of broker failure, client connections will fail over only to brokers with the same cluster identifier as the original broker. If not specified, client connections can fail over to any other broker with an unspecified cluster identifier.

For standalone brokers (those not belonging to a cluster), this property is ignored.

The identifier may contain only alphabetic letters (A-Z, a-z), numeric digits (0-9), and the underscore character (_).

brokerID

String

None

Broker identifier

For brokers using a JDBC-based persistent data store, this string is appended to the names of all database tables to make them unique in the case where more than one broker instance is using the same database. For brokers using a file-based data store, this property is ignored.

In an enhanced cluster, each broker must have a unique broker identifier.

The identifier may contain only alphabetic letters (A-Z, a-z), numeric digits (0-9), and the underscore character (_).

^Footnote 1Must be specified

^Footnote 2Required

ManagedConnectionFactory JavaBean

A managed connection factory is used to create connections managed by the resource adapter. Table 20-2 shows the properties of the ManagedConnectionFactory JavaBean; if set, these properties override the corresponding properties of the ResourceAdapter JavaBean.

Table 20-2 Managed Connection Factory Properties

Property Type Default Value Description

Property	Type	Default Value	Description
`addressList`	String	Value of `connectionURL` property of `ResourceAdapter` JavaBean (see Table 20-1)	List of message service addresses for connecting to Message Queue service
`userName`^Foot 1	String	`guest`	User name for connecting to Message Queue service
`password`^Footref 1	String	`guest`	Password for connecting to Message Queue service
`clientID`	String	None	Client identifier for connections to Message Queue service
`addressListBehavior`	String	`PRIORITY`	Order in which to attempt connection to Message Queue service: `PRIORITY`: Order specified in address list `RANDOM`: Random order Note: Reconnection attempts after a connection failure start with the broker whose connection failed and proceed sequentially through the address list, regardless of the value set for this property.
`addressListIterations`	Integer	`1`	Number of times to iterate through address list attempting to establish or reestablish a connection
`reconnectEnabled`	Boolean	`false`	Attempt to reestablish a lost connection?
`reconnectAttempts`	Integer	`6`	Number of times to attempt reconnection to each address in address list before moving on to next
`reconnectInterval`	Long integer	`30000`	Interval, in milliseconds, between reconnection attempts
`options`^Footref 1	String	None	A list of additional connection factory properties to be used when creating connections to a Message Queue broker. When specified, the value of `options` must be a comma-separated list of connection factory properties and their values, in the form: `propertyName=value` If value contains a comma or an equals sign, precede the symbol with a backslash (`\`) or enclose the entire value in quotes; for example: `prop1=comma\,val,prop2="equals=val"` The `options` property cannot specify properties that are configured internally or that have their own setter methods, specifically: `imqReconnectEnabled`, `imqReconnectAttempts`, `imqReconnectInterval`, `imqDefaultUsername`, `imqDefaultPassword`, `imqAddressList`, `imqAddressListIterations`. Any values specified in `options` for these properties are ignored.
`useSharedSubscriptionInClusteredContainer`	Boolean	`true`	Controls whether topic subscriptions created using this ManagedConnectionFactory will be shared when running in a clustered container, as described in About Shared Topic Subscriptions for Clustered Containers. Set to `true` (the default) to share subscriptions. The `clientID` property must also be set, even if the subscription is nondurable. Set to `false` to not share subscriptions. This setting should only be used for nondurable subscriptions. The `clientID` property does not need to be set.

addressList

String

Value of connectionURL property of ResourceAdapter JavaBean (see Table 20-1)

List of message service addresses for connecting to Message Queue service

`userName`^Foot 1

String

guest

User name for connecting to Message Queue service

`password`^Footref 1

String

guest

Password for connecting to Message Queue service

clientID

String

None

Client identifier for connections to Message Queue service

addressListBehavior

String

PRIORITY

Order in which to attempt connection to Message Queue service:

PRIORITY: Order specified in address list
RANDOM: Random order

Note: Reconnection attempts after a connection failure start with the broker whose connection failed and proceed sequentially through the address list, regardless of the value set for this property.

addressListIterations

Integer

1

Number of times to iterate through address list attempting to establish or reestablish a connection

reconnectEnabled

Boolean

false

Attempt to reestablish a lost connection?

reconnectAttempts

Integer

6

Number of times to attempt reconnection to each address in address list before moving on to next

reconnectInterval

Long integer

30000

Interval, in milliseconds, between reconnection attempts

`options`^Footref 1

String

None

A list of additional connection factory properties to be used when creating connections to a Message Queue broker.

When specified, the value of options must be a comma-separated list of connection factory properties and their values, in the form:

propertyName=value

If value contains a comma or an equals sign, precede the symbol with a backslash (\) or enclose the entire value in quotes; for example:

prop1=comma\,val,prop2="equals=val"

The options property cannot specify properties that are configured internally or that have their own setter methods, specifically: imqReconnectEnabled, imqReconnectAttempts, imqReconnectInterval, imqDefaultUsername, imqDefaultPassword, imqAddressList, imqAddressListIterations. Any values specified in options for these properties are ignored.

useSharedSubscriptionInClusteredContainer

Boolean

true

Controls whether topic subscriptions created using this ManagedConnectionFactory will be shared when running in a clustered container, as described in About Shared Topic Subscriptions for Clustered Containers.

Set to true (the default) to share subscriptions. The clientID property must also be set, even if the subscription is nondurable.

Set to false to not share subscriptions. This setting should only be used for nondurable subscriptions. The clientID property does not need to be set.

^Footnote 1Optional

ActivationSpec JavaBean

Table 20-3 shows the configurable properties of the ActivationSpec JavaBean. These properties are used by the application server when instructing the Resource Adapter to activate a message endpoint and associate it with a message-driven bean.

Table 20-3 ActivationSpec Properties

Property Type Default Value Description

Property	Type	Default Value	Description
`addressList`link:#foot-optional4^,^Foot 2	String	Value of `connectionURL` property of `ResourceAdapter` JavaBean (see Table 20-1)	Message service address for connecting to Message Queue service
`userName`^Footref 1 ^,^Footref 2	String	Inherited from `ResourceAdapter` JavaBean (see Table 20-1)	User name for connecting to Message Queue service.
`password`^Footref 1 ^,^Footref 2	String	Inherited from `ResourceAdapter` JavaBean (see Table 20-1)	Password for connecting to Message Queue service.
`clientId`^Foot 3	String	None	Client ID for connections to Message Queue service This property must be set if `subscriptionDurability` is set to `Durable`.
`addressListBehavior`link:#sthref237^,^Footref 2	String	Inherited from `ResourceAdapter` JavaBean (see Table 20-1)	Order in which to attempt connection or reconnection to Message Queue service: PRIORITY: order specified in address list RANDOM: Random order
`addressListIterations`link:#sthref239^,^Footref 2	Integer	Inherited from `ResourceAdapter` JavaBean (see Table 20-1)	Number of times to iterate through addressList attempting to establish or reestablish a connection. When this limit is reached an exception will be thrown and a new connection attempt will begin, with no limit.
`reconnectAttempts`^Footref 1 ^,^Footref 2	Integer	Inherited from `ResourceAdapter` JavaBean (see Table 20-1)	Number of times to attempt connection or reconnection to each address in addressList before moving on to next.
`reconnectInterval1`link:#sthref243^,^Footref 2	Integer	Inherited from `ResourceAdapter` JavaBean (see Table 20-1)	Interval, in milliseconds, between reconnection attempts
`destination`^Footref 3	String	None	Name of destination from which to consume messages The value must be that of the `destinationName` property for a Message Queue destination administered object.
`destinationType`^Footref 3	String	None	Type of destination specified by `destination` property: `jakarta.jms.Queue`: Queue destination `jakarta.jms.Topic`: Topic destination
`messageSelector`link:#sthref247^,^Footref 3	String	None	Message selector for filtering messages delivered to consumer
`subscriptionName`^Footref 3	String	None	Name for durable subscriptions This property must be set if `subscriptionDurability` is set to `Durable`.
`subscriptionDurability`^Footref 3	String	`NonDurable`	Durability of consumer for topic destination: `Durable`: Durable consumer `NonDurable`: Nondurable consumer This property is valid only if `destinationType` is set to `jakarta.jms.Topic`, and is optional for nondurable subscriptions and required for durable ones. If set to `Durable`, the `clientID` and `subscriptionName` properties must also be set.
`acknowledgeMode`link:#sthref251^,^Footref 3	String	`Auto-acknowledge`	Acknowledgment mode: `Auto-acknowledge`: Auto-acknowledge mode `Dups-ok-acknowledge`: Dups-OK-acknowledge mode
`customAcknowledgeMode`	String	None	Acknowledgment mode for MDB message consumption Valid values are `No_acknowledge` or null. You can use no-acknowledge mode only for a nontransacted, nondurable topic subscription; if you use this setting with a transacted subscription or a durable subscription, subscription activation will fail.
`endpointExceptionRedeliveryAttempts`	Integer	`6`	Number of times to redeliver a message when MDB throws an exception during message delivery
`endpointExceptionRedeliveryInterval`	integer	500	The amount of time, in milliseconds, to wait before the next redelivery attempt.
`sendUndeliverableMsgsToDMQ`	Boolean	`true`	Place message in dead message queue when MDB throws a runtime exception and number of redelivery attempts exceeds the value of `endpointExceptionRedeliveryAttempts`? If `false`, the Message Queue broker will attempt redelivery of the message to any valid consumer, including the same MDB.
`options`^Footref 1	String	None	A list of additional connection factory properties to be used when creating connections to a Message Queue broker. When specified, the value of `options` must be a comma-separated list of connection factory properties and their values, in the form: `propertyName=value` If value contains a comma or an equals sign, precede the symbol with a backslash (`\`) or enclose the entire value in quotes; for example: `prop1=comma\,val,prop2="equals=val"` The `options` property cannot be used to specify properties that are configured internally or that have their own setter methods, specifically: `imqReconnectEnabled`, `imqReconnectAttempts`, `imqReconnectInterval`, `imqDefaultUsername`, `imqDefaultPassword`, `imqAddressList`, `imqAddressListIterations`, `imqAddressListBehavior`. Any values specified in `options` for these properties are ignored.
`useSharedSubscriptionInClusteredContainer`	Boolean	`true`	Controls whether topic subscriptions created using this ActivationSpec will be shared when running in a clustered container, as described in About Shared Topic Subscriptions for Clustered Containers. Set to `true` (the default) to share subscriptions. Set to `false` to not share subscriptions. This setting should only be used for nondurable subscriptions.

`addressList`link:#foot-optional4^,^Foot 2

String

Value of connectionURL property of ResourceAdapter JavaBean (see Table 20-1)

Message service address for connecting to Message Queue service

`userName`^Footref 1 ^,^Footref 2

String

Inherited from ResourceAdapter JavaBean (see Table 20-1)

User name for connecting to Message Queue service.

`password`^Footref 1 ^,^Footref 2

String

Inherited from ResourceAdapter JavaBean (see Table 20-1)

Password for connecting to Message Queue service.

`clientId`^Foot 3

String

None

Client ID for connections to Message Queue service

This property must be set if subscriptionDurability is set to Durable.

`addressListBehavior`link:#sthref237^,^Footref 2

String

Inherited from ResourceAdapter JavaBean (see Table 20-1)

Order in which to attempt connection or reconnection to Message Queue service:

PRIORITY: order specified in address list

RANDOM: Random order

`addressListIterations`link:#sthref239^,^Footref 2

Integer

Inherited from ResourceAdapter JavaBean (see Table 20-1)

Number of times to iterate through addressList attempting to establish or reestablish a connection.

When this limit is reached an exception will be thrown and a new connection attempt will begin, with no limit.

`reconnectAttempts`^Footref 1 ^,^Footref 2

Integer

Inherited from ResourceAdapter JavaBean (see Table 20-1)

Number of times to attempt connection or reconnection to each address in addressList before moving on to next.

`reconnectInterval1`link:#sthref243^,^Footref 2

Integer

Inherited from ResourceAdapter JavaBean (see Table 20-1)

Interval, in milliseconds, between reconnection attempts

`destination`^Footref 3

String

None

Name of destination from which to consume messages

The value must be that of the destinationName property for a Message Queue destination administered object.

`destinationType`^Footref 3

String

None

Type of destination specified by destination property:

jakarta.jms.Queue: Queue destination
jakarta.jms.Topic: Topic destination

`messageSelector`link:#sthref247^,^Footref 3

String

None

Message selector for filtering messages delivered to consumer

`subscriptionName`^Footref 3

String

None

Name for durable subscriptions

This property must be set if subscriptionDurability is set to Durable.

`subscriptionDurability`^Footref 3

String

NonDurable

Durability of consumer for topic destination:

Durable: Durable consumer
NonDurable: Nondurable consumer

This property is valid only if destinationType is set to jakarta.jms.Topic, and is optional for nondurable subscriptions and required for durable ones. If set to Durable, the clientID and subscriptionName properties must also be set.

`acknowledgeMode`link:#sthref251^,^Footref 3

String

Auto-acknowledge

Acknowledgment mode:

Auto-acknowledge: Auto-acknowledge mode
Dups-ok-acknowledge: Dups-OK-acknowledge mode

customAcknowledgeMode

String

None

Acknowledgment mode for MDB message consumption

Valid values are No_acknowledge or null.

You can use no-acknowledge mode only for a nontransacted, nondurable topic subscription; if you use this setting with a transacted subscription or a durable subscription, subscription activation will fail.

endpointExceptionRedeliveryAttempts

Integer

6

Number of times to redeliver a message when MDB throws an exception during message delivery

endpointExceptionRedeliveryInterval

integer

500

The amount of time, in milliseconds, to wait before the next redelivery attempt.

sendUndeliverableMsgsToDMQ

Boolean

true

Place message in dead message queue when MDB throws a runtime exception and number of redelivery attempts exceeds the value of endpointExceptionRedeliveryAttempts?

If false, the Message Queue broker will attempt redelivery of the message to any valid consumer, including the same MDB.

`options`^Footref 1

String

None

A list of additional connection factory properties to be used when creating connections to a Message Queue broker.

When specified, the value of options must be a comma-separated list of connection factory properties and their values, in the form:

propertyName=value

If value contains a comma or an equals sign, precede the symbol with a backslash (\) or enclose the entire value in quotes; for example:

prop1=comma\,val,prop2="equals=val"

The options property cannot be used to specify properties that are configured internally or that have their own setter methods, specifically: imqReconnectEnabled, imqReconnectAttempts, imqReconnectInterval, imqDefaultUsername, imqDefaultPassword, imqAddressList, imqAddressListIterations, imqAddressListBehavior. Any values specified in options for these properties are ignored.

useSharedSubscriptionInClusteredContainer

Boolean

true

Controls whether topic subscriptions created using this ActivationSpec will be shared when running in a clustered container, as described in About Shared Topic Subscriptions for Clustered Containers.

Set to true (the default) to share subscriptions.

Set to false to not share subscriptions. This setting should only be used for nondurable subscriptions.

^Footnote 1Optional

^Footnote 2Property specific to Message Queue JMS Resource Adapter

^Footnote 3Standard Enterprise JavaBean (EJB) and Java EE Connector Architecture (CA) property

Note that there is no reconnectEnabled property for the ActivationSpec JavaBean.