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:
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.
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
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 |
||
---|---|---|---|---|---|
String |
Inherited from ResourceAdapter JavaBean (see Table 20–1) |
List of message service addresses for connecting to Message Queue service |
|||
String |
guest |
User name for connecting to Message Queue service |
|||
String |
guest |
Password for connecting to Message Queue service |
|||
String |
None |
Client identifier for connections to Message Queue service |
|||
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. |
|||
Integer |
1 |
Number of times to iterate through address list attempting to establish or reestablish a connection |
|||
Boolean |
false | ||||
Integer |
6 |
Number of times to attempt reconnection to each address in address list before moving on to next |
|||
Long integer |
30000 |
Interval, in milliseconds, between reconnection attempts |
|||
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:
If value contains a comma or an equals sign, precede the symbol with a backslash (\) or enclose the entire value in quotes; for example:
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. |
|||
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. |
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. |
||
String |
None |
Type of destination specified by destination property: javax.jms.Queue: Queue destination javax.jms.Topic: Topic destination |
|||
String |
None |
Message selector for filtering messages delivered to consumer |
|||
String |
None |
Name for durable subscriptions This property must be set if subscriptionDurability is set to Durable. |
|||
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. |
|||
String |
None |
Client ID for connections to Message Queue service This property must be set if subscriptionDurability is set to Durable. |
|||
String |
Auto-acknowledge |
Acknowledgment mode: Auto-acknowledge: Auto-acknowledge mode Dups-ok-acknowledge: Dups-OK-acknowledge mode |
|||
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. |
|||
Integer |
6 |
Number of times to redeliver a message when MDB throws an exception during message delivery |
|||
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. |
|||
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:
If value contains a comma or an equals sign, precede the symbol with a backslash (\) or enclose the entire value in quotes; for example:
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. |
|||
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. |