Sun GlassFish Message Queue 4.4 Administration Guide

Chapter 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 Sun GlassFish Message Queue with any J2EE 1.4 application server by means of the standard J2EE 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

The Message Queue JMS Resource Adapter provides a special feature called shared subscriptions for containers that support clustering, such as Sun Java System GlassFish Enterprise 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:

A client id must be set when creating any subscription, even a nondurable subscription (which does not normally require a client id). Attempting to create a subscription without a client id throws an exception.
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 the same durable subscription name (if the subscription is durable) are considered “shared”; that is, they are treated as a single subscription, with each message being sent to only one of the participating subscriptions.

By default, the shared subscriptions feature is enabled. In some applications that use nondurable subscriptions, however, the shared behavior is not desired. In such cases, the useSharedSubscriptionInClusteredContainer property can be set to false to disable the feature.

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
`addressList` [Exactly one of these properties must be specified]	String	`mq://localhost:7676/jms`	Message service address for connecting to Message Queue service Equivalent to `connectionURL` (below).
`connectionURL`	String	`mq://localhost:7676/jms`	Message service address for connecting to the Message Queue service Equivalent to `addressList`(above).
`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` [Required]	String	`guest`	Default user name for connecting to Message Queue service
`password`	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 (`_`).

ManagedConnectionFactory JavaBean

A managed connection factory defines the connections that the Resource Adapter provides to a message-driven bean. 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

addressList

String

Inherited from ResourceAdapter JavaBean (see Table 20–1)

List of message service addresses for connecting to Message Queue service

userName [Optional]

String

guest

User name for connecting to Message Queue service

password

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

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.

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

addressList [Optional] ^, [Property specific to Message Queue JMS Resource Adapter]

String

Inherited from ResourceAdapter JavaBean

Message service address for connecting to Message Queue service

destination [Standard Enterprise JavaBean (EJB) and J2EE Connector Architecture (CA) property]

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

String

None

Type of destination specified by destination property:

javax.jms.Queue: Queue destination

javax.jms.Topic: Topic destination

messageSelector^,

String

None

Message selector for filtering messages delivered to consumer

subscriptionName

String

None

Name for durable subscriptions

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

subscriptionDurability

String

NonDurable

Durability of consumer for topic destination:

Durable: Durable consumer

NonDurable: Nondurable consumer

This property is valid only if destinationType is set to javax.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.

clientId

String

None

Client ID for connections to Message Queue service

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

acknowledgeMode^,

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

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

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