Universal Messaging 10.3 | Developer Guide | Enterprise APIs | Enterprise Developer's Guide for Java | Provider for JMS | Resource Adapter for JMS
 
Resource Adapter for JMS
For Red Hat JBoss EAP and IBM WebSphere Application Server, the Universal Messaging installation contains a product-specific generic resource adapter for JMS. For details of the supported releases of these third party products, refer to the System Requirements for Software AG Products document on the Software AG documentation web site.
The following description uses the term UMRA to refer to this Universal Messaging-specific adapter. UMRA is based on the Generic Resource Adapter for JMS.
The UMRA adapter is a .rar file that can be deployed and configured using the standard administration tools of your chosen application server. The necessary deployment and configuration steps vary from application server to application server, so refer to the documentation of your application server for the steps involved in this process.
The UMRA .rar file is located in <InstallDir>/UniversalMessaging/j2ee/umra.rar and contains the modified genericra.jar, the nJMS.jar and nClient.jar. A README.txt is included and outlines the changes made to the resource adapter. The ra.xml descriptor file is located in the META-INF directory.
Configurable Properties of UMRA
The Generic Resource Adapter for JMS offers a set of properties that you can configure according to your requirements. UMRA supports a subset of these properties, as listed in the following table.
Parameter
Description
Universal Messaging recommendation
Default
connectionFactoryJndiName
The name of the JMS connection factory.
The name of the JMS connection factory.
ConnectionValidation
If true, the application server will register an error listener with the JMS connection and invalidate the connection if the error is communicated by Universal Messaging.
This will render the connection unusable from the application server perspective and will prevent the native Universal Messaging reconnection mechanism from recovering such connections.
So in general, it is recommended to set this parameter to false.
false
DeliveryType
For inbound delivery there are 2 modes: "Asynchronous" and "Synchronous". If the value is left empty, this assumes "Asynchronous" delivery. Synchronous delivery spawns several threads (according to the maxPoolSize property, see below), which are several consumers if the destination is not a Topic destinationType, and blocks each one waiting to consume messages within the thread. This can lead to warnings in some application servers that some threads are stuck. With asynchronous delivery the messages are retrieved serially by Universal Messaging in threads owned by the Universal Messaging client, but then they are dispatched for concurrent processing to the MDBs (message driven bean). The acknowedgement is serial again (a limitation in the implementation).
Purely depending on the requirements. If there are many MDBs it's most probably better to have "Asynchronous" delivery.
destinationJndiName
The JNDI name of the destination.
The JNDI name of the destination.
destinationType
Can be javax.jms.Destination, javax.jms.Queue or javax.jms.Topic
Place the proper type of the destination.
javax.jms.Destination
endpointReleaseTimeout
The time to wait for the message driven beans (MDBs) already processing messages to complete.
Larger values mean that, when stopping (undeploying) the application, it may take longer to wait until all MDBs are done.
Use the default value: 180.
180
JndiProperties
The properties to pass to the JNDI context, e.g. "java.naming.factory.initial=com.pcbsys.nirvana.nSpace.NirvanaContextFactory, java.naming.provider.url="nsp://localhost:26000", java.naming.security.authentication=simple"
Set the appropriate properties to connect to Universal Messaging.
maxPoolSize
The MDB thread pool size for an asynchronous consumer, i.e., the maximum number of messages that can be processed in parallel by MDBs for this consumer.
For a synchronous consumer, if not 'SERIAL' deliveryConcurrencyMode and not Topic destinationType, this is the number of threads to block waiting for a message.
Set depending on the load. For high load with heavy MDB processing it could be beneficial to have a higher number here (take into account the capabilities of the hardware and whether MDB is CPU bound, I/O bound, etc.)
8
maxWaitTime
The maximum time to wait to obtain an MDB from the pool in order to process the message.
If MDBs are taking their time processing the messages or we have huge redelivery interval, the incoming message might need to wait until a resource is free to process it.
Set depending on the requirements.
300
messageSelector
The message selector for the subscription.
Set depending on the requirements.
Password
ProviderIntegrationMode
Should be JNDI or ClassName
Set to "JNDI".
reconnectAttempts
Number of times to try to reconnect if Universal Messaging indicates a connection problem via the JMS Connection listener.
If this is 0, the reconnection will be accomplished by the Universal Messaging native reconnection mechanism, which is recommended approach.
0
reconnectInterval
Reconnection interval in seconds.
See the above item.
0
subscriptionDurability
"Durable" or "Non-Durable" topic subscription
Set depending on the requirements.
Non-Durable
subscriptionName
The name of the durable subscription, if any.
Set depending on the requirements
useProxyMessages
This should be set to "true" if the application code needs to use the java.jms.Message#setJMSReplyTo method - otherwise the call will fail with an exception. The default is "false".
Set depending on the requirements.
false
Unsupported and partially supported properties
In addition to the supported properties listed in the table above, the General Resource Adapter for JMS offers some additional properties that UMRA recognizes but does not support, or supports only partially. These properties are listed in the following table.
Parameter
Description
Universal Messaging recommendation
ackTimeOut
Applicable when HUMode is true.
Don't use this property, UMRA will assign a default value.
applicationName
Used if "monitoring" is enabled and will provide JMX monitoring. This is the name of the resource pool (e.g. Server session pool - free and busy resources, wait time etc. to monitor.).
Not supported in Universal Messaging.
batchSize
Doesn't seem to be used in the code.
Don't use this property, UMRA will assign a default value.
CommonSetterMethodName
Applicable when the provider integration mode is ClassName.
Don't use this property, UMRA will assign a default value. UMRA integration mode is JNDI.
ConnectionFactoryClassName
Applicable when the provider integration mode is ClassName.
Don't use this property, UMRA will assign a default value. UMRA integration mode is JNDI.
ConnectionFactoryProperties
Applicable when the provider integration mode is ClassName.
Don't use this property, UMRA will assign a default value. UMRA integration mode is JNDI.
deadMessageConnectionFactoryProperties
Applicable when the provider integration mode is ClassName.
Don't use this property, UMRA will assign a default value. UMRA integration mode is JNDI.
deadMessageDestinationClassName
Applicable when the provider integration mode is ClassName.
Don't use this property, UMRA will assign a default value. UMRA integration mode is JNDI.
deadMessageDestinationJndiName
Applicable when the provider integration mode is ClassName.
Don't use this property, UMRA will assign a default value. UMRA integration mode is JNDI.
deadMessageDestinationProperties
Applicable when the provider integration mode is ClassName.
Don't use this property, UMRA will assign a default value. UMRA integration mode is JNDI.
deadMessageConnectionFactoryJndiName
JNDI name of the JMS connection factory to place dead messages.
Not supported in Universal Messaging.
deadMessageDestinationType
javax.jms.Destination, javax.jms.Queue or javax.jms.Topic
Not supported in Universal Messaging.
deliveryConcurrencyMode
Applicable for synchronous delivery. Value is empty or 'SERIAL'. SERIAL means only one thread devoted to message consumption and processing.
Not supported in Universal Messaging.
destinationProperties
Applicable when the provider integration mode is ClassName.
Don't use this property, UMRA will assign a default value. UMRA integration mode is JNDI.
HUAMode
HUA stands for "hold until ack".
Use the default value. Should be "false" given that scenario in which this is "true" is not well understood.
instanceCount
The number of instances on which UMRA is deployed (value > 1 is applicable only if "loadBalancingRequired" is true). It also can be part of generated JMS clientId if "ClientId" parameter is set.
Load balancing is not supported in Universal Messaging.
loadBalancingRequired
This will provide a kind of load balancing by adding an artificial or provided filter to apply on the message by Universal Messaging.
Set "false". Load balancing is not supported with Universal Messaging.
MDBDeploymentRetryAttempt
Doesn't seem to be used.
Don't use this property, UMRA will assign a default value.
MDBDeploymentRetryInterval
Doesn't seem to be used.
Don't use this property, UMRA will assign a default value.
monitoring
Enable JMX monitoring for the resource pool. Related to "ApplicationName" parameter.
Not supported with Universal Messaging.
Password
QueueClassName
Applicable when the provider integration mode is ClassName.
Don't use this property, UMRA will assign a default value. UMRA integration mode is JNDI.
QueueConnectionFactoryClassName
Applicable when the provider integration mode is ClassName.
Don't use this property, UMRA will assign a default value. UMRA integration mode is JNDI.
redeliveryAttempts
Applicable in the presence of XA support. This takes effect when a message driven bean (MDB) throws an exception. The redelivery happen purely within the UMRA client, no session recovery, rollbacks whatsoever used.
Not applicable, UMRA doesn't support XA.
redeliveryInterval
Applicable in the presence of XA support. This takes effect when an MDB throws an exception. The redelivery happen purely within the UMRA client; no session recovery, rollbacks whatsoever is used.
Not applicable, UMRA doesn't support XA.
RMPolicy
Applies to XA Support. When RMPolicy is set to "OnePerPhysicalConnection", the XAResource wrapper implementation's isSameRM in the Generic JMS RA would check if both the XAResources use the same physical connection, before delegating to the wrapped objects.
Don't use this property, UMRA will assign a default value. UMRA doesn't support XA.
sendBadMessagesToDMD
If messages are to be sent to a dead message destination (DMD) when there is a problem during the consumption.
Not supported with Universal Messaging.
shareClientid
When we use load balancing, this indicates if all the deployments should use the same JMS Client ID.
Not supported with Universal Messaging.
TopicClassName
Applicable when the provider integration mode is ClassName.
Don't use this property, UMRA will assign a default value. UMRA integration mode is JNDI.
TopicConnectionFactoryClassName
Applicable when the provider integration mode is ClassName.
Don't use this property, UMRA will assign a default value. UMRA integration mode is JNDI.
UnifiedDestinationClassName
Applicable when the provider integration mode is ClassName.
Don't use this property, UMRA will assign a default value. UMRA integration mode is JNDI.
UseFirstXAForRedelivery
Applicable for XA transactions, covers some corner case, looks there is a problem when set to "true".
Don't use this property, UMRA will assign a default value.
XAConnectionFactoryClassName
Applicable when the provider integration mode is ClassName.
Don't use this property, UMRA will assign a default value. UMRA integration mode is JNDI.
XAQueueConnectionFactoryClassName
Applicable when the provider integration mode is ClassName.
Don't use this property, UMRA will assign a default value. UMRA integration mode is JNDI.
XATopicConnectionFactoryClassName
Applicable when the provider integration mode is ClassName.
Don't use this property, UMRA will assign a default value. UMRA integration mode is JNDI.
Other sources of information
Software AG occasionally publishes information about the configuration process for UMRA in the Wiki of the Technical Community at http://techcommunity.softwareag.com/pwiki. Note that the material on the Wiki is not part of the official product documentation and is not necessarily up to date with the latest version of the product, but nevertheless you might find the information useful.