Configuring the resource adapter for inbound communication

To configure inbound communication, define the properties of one or more ActivationSpec objects.

The properties of an ActivationSpec object determine how a message drive bean (MDB) receives JMS messages from an IBM® MQ queue. The transactional behavior of the MDB is defined in its deployment descriptor.

An ActivationSpec object has two sets of properties:
  • Properties that are used to create a JMS connection to an IBM MQ queue manager
  • Properties that are used to create a JMS connection consumer that delivers messages asynchronously as they arrive on a specified queue

The way in which you define the properties of an ActivationSpec object depends on the administration interfaces provided by your application server.

New ActivationSpec properties in JMS 2.0

The JMS 2.0 specification introduced two new ActivationSpec properties. The connectionFactoryLookup and destinationLookup properties can be provided with a JNDI name of an administered object to be used in preference to the other ActivationSpec properties.

For example, assume that a connection factory is defined in JNDI and the JNDI name of that object is specified in the connectionFactoryLookup property for an activation specification. All the properties of the connection factory that are defined in JNDI are used in preference to the properties in Table 1.
If a destination is defined in JNDI and the JNDI name is set in the ActivationSpec's destinationLookup property then the values of that are used in preference to the values in Table 2. For more information about how these two properties are used, see ActivationSpec connectionFactoryLookup and destinationLookup properties.

Properties used to create a JMS connection to an IBM MQ queue manager

All of the properties in Table 1 are optional.
Table 1. Properties of an ActivationSpec object that are used to create a JMS connection
Name of property Type Valid values (default value in bold) Description
applicationName String
  • The invoking class name, if it is available, adjusted to be no longer than 28 characters. If it is not available, the string WebSphere MQ Client for Java is used.
The name by which an application is registered with the queue manager. This application name is shown by the DISPLAY CONN MQSC/PCF command (where the field is called APPLTAG ) or in the IBM MQ Explorer Application Connections display (where the field is called App name ).
brokerCCDurSubQueue 1 String
  • SYSTEM.JMS.D.CC.SUBSCRIBER.QUEUE
  • A queue name
The name of the queue from which a connection consumer receives durable subscription messages
brokerCCSubQueue 1 String
  • SYSTEM.JMS.ND.CC.SUBSCRIBER.QUEUE
  • A queue name
The name of the queue from which a connection consumer receives nondurable subscription messages
brokerControlQueue 1 String
  • SYSTEM.BROKER.CONTROL.QUEUE
  • A queue name
The name of the broker control queue
brokerQueueManager 1 String
  • "" (empty string)
  • A queue manager name
The name of the queue manager on which the broker is running
brokerSubQueue 1 String
  • SYSTEM.JMS.ND.SUBSCRIBER.QUEUE
  • A queue name
The name of the queue from which a nondurable message consumer receives messages
brokerVersion 1 String
  • unspecified - After the broker is migrated from V6 to V7, set this property so that RFH2 headers are no longer used. After migration, this property is no longer relevant.
  • V1 - To use an IBM MQ publish/subscribe broker.This value is the default value if TRANSPORT is set to BIND or CLIENT.
  • V2 - To use a broker of IBM Integration Bus in native mode. This value is the default value if TRANSPORT is set to DIRECT or DIRECTHTTP.
The version of the broker being used
ccdtURL String
  • null
  • A uniform resource locator (URL)
A URL that identifies the name and location of the file containing the client channel definition table (CCDT) and specifies how the file can be accessed
CCSID String
  • 819
  • A coded character set identifier supported by the Java virtual machine (JVM)
The coded character set identifier for a connection
channel String
  • SYSTEM.DEF.SVRCONN
  • The name of an MQI channel
The name of the MQI channel to use
cleanupInterval 1 int
  • 3 600 000
  • A positive integer
The interval, in milliseconds, between background runs of the publish/subscribe cleanup utility
cleanupLevel 1 String
  • SAFE
  • NONE
  • STRONG
  • FORCE
  • NONDUR
The cleanup level for a broker-based subscription store
clientID String
  • null
  • A client identifier
The client identifier for a connection
cloneSupport String
  • DISABLED - Only one instance of a durable topic subscriber can run at a time.
  • ENABLED - Two or more instances of the same durable topic subscriber can run simultaneously, but each instance must run in a separate Java virtual machine (JVM).
Whether two or more instances of the same durable topic subscriber can run simultaneously
connectionFactoryLookup String
  • null
  • The JNDI name for a ConnectionFactory object
 If this property is set, the ActivationSpec looks up a JMS ConnectionFactory object with the specified JNDI name in the JNDI namespace of the application server, and then uses the properties of that object to create a JMS connection to an IBM MQ queue manager, with one exception. The only property of the ActivationSpec that will be used when creating the JMS connection is the clientID. For more information, see ActivationSpec connectionFactoryLookup and destinationLookup properties.
connectionNameList String
  • localhost(1414)
  • A string composed of items separated by commas where each item takes the format: 
    
 HOSTNAME(PORT)
    where HOSTNAME is either a DNS name or an IP address.

A list of TCP/IP connection names used for inbound communications.

When specified, connectionNameList supersedes the hostname and port properties.

This property is used to reconnect to multi-instance queue managers.

connectionNameList is similar in form to localAddress, but must not be confused with it. localAddress specifies the characteristics of the local communications, whereas connectionNameList specifies how to reach a remote queue manager.

failIfQuiesce Boolean
  • true
  • false
Whether calls to certain methods fail if the queue manager is in a quiescing state
headerCompression String
  • NONE
  • SYSTEM - RLE message header compression is performed
A list of the techniques that can be used for compressing header data on a connection
hostName String
  • localhost
  • A host name
  • An IP address
The host name or IP address of the system on which the queue manager resides.

The hostname and port properties are superseded by the connectionNameList property when it is specified.

localAddress String
  • null
  • A string in the format: 
    
[ host_name ][(low_port [, high_port ])]
    where host_name is a host name or IP address, low_port and high_port are TCP port numbers, and brackets denote an optional component
For a connection to a queue manager, this property specifies either or both of the following things:
  • The local network interface to be used
  • The local port, or range of local ports, to be used

localAddress is similar in form to connectionNameList, but must not be confused with it. localAddress specifies the characteristics of the local communications, whereas connectionNameList specifies how to reach a remote queue manager.

messageCompression String
  • NONE
  • A list of one or more of the following values separated by blank characters:
    • RLE
    • ZLIBFAST
    • ZLIBHIGH
 A list of the techniques that can be used for compressing message data on a connection
messageRetention 1 Boolean
  • true - Unwanted messages remain on the input queue
  • false - Unwanted messages are dealt with according to their disposition options
Whether the connection consumer keeps unwanted messages on the input queue
messageSelection 1 String
  • CLIENT
  • BROKER
Determines whether message selection is done by IBM MQ classes for JMS or by the broker. Message selection by the broker is not supported when brokerVersion has the value 1.
password String
  • null
  • A password
The default password to use when creating a connection to the queue manager
pollingInterval 1 int
  • 5000
  • Any positive integer
If each message listener within a session has no suitable message on its queue, this value is the maximum interval, in milliseconds, that elapses before each message listener tries again to get a message from its queue. If it frequently happens that no suitable message is available for any of the message listeners in a session, consider increasing the value of this property. This property is relevant only if TRANSPORT has the value BIND or CLIENT.
port int
  • 1414
  • A TCP port number
The port on which the queue manager listens.

The hostname and port properties are superseded by the connectionNameList property when it is specified.

providerVersion string
  • unspecified
  • A string in one of the following formats
    • V.R.M.F
    • V.R.M
    • V.R
    • V
    where V, R, M, and F are integer values greater than or equal to zero.
The version, release, modification level and fix pack of the queue manager to which the MDB intends to connect.
queueManager String
  • "" (empty string)
  • A queue manager name
The name of the queue manager to connect to
receiveExit 3 String
  • null
  • A string comprising one or more items separated by commas, where each item is the fully qualified name of a class that implements the IBM MQ classes for Java interface, MQReceiveExit
Identifies a channel receive exit program, or a sequence of receive exit programs to be run in succession
receiveExitInit String
  • null
  • A string comprising one or more items of user data separated by commas
The user data that is passed to channel receive exit programs when they are called
rescanInterval 1 int
  • 5000
  • Any positive integer
When a message consumer in the point-to-point domain uses a message selector to select which messages it wants to receive, IBM MQ classes for JMS searches the IBM MQ queue for suitable messages in the sequence determined by the MsgDeliverySequence attribute of the queue. When IBM MQ classes for JMS finds a suitable message and delivers it to the consumer, IBM MQ classes for JMS resumes the search for the next suitable message from its current position in the queue. IBM MQ classes for JMS continues to search the queue in this way until it reaches the end of the queue, or until the interval of time in milliseconds, as determined by the value of this property, has expired. In each case, IBM MQ classes for JMS returns to the beginning of the queue to continue its search, and a new time interval commences.
securityExit 3 String
  • null
  • The fully qualified name of a class that implements the IBM MQ classes for Java interface, MQSecurityExit
Identifies a channel security exit program
securityExitInit String
  • null
  • A string of user data
The user data that is passed to a channel security exit program when it is called
sendExit 3 String
  • null
  • A string comprising one or more items separated by commas, where each item is the fully qualified name of a class that implements the IBM MQ classes for Java interface, MQSendExit
Identifies a channel send exit program, or a sequence of send exit programs to be run in succession
sendExitInit String
  • null
  • A string comprising one or more items of user data separated by commas
The user data that is passed to channel send exit programs when they are called
shareConvAllowed Boolean
  • NO - A client connection cannot share its socket.
  • YES - A client connection can share its socket.
Whether a client connection can share its socket with other top-level JMS connections from the same process to the same queue manager, if the channel definitions match
sparseSubscriptions 1 Boolean
  • false - Subscriptions receive frequent matching messages.
  • true - Subscriptions receive infrequent matching messages. This value requires that the subscription queue can be opened for browse.
Controls the message retrieval policy of a TopicSubscriber object
sslCertStores String
  • null
  • A string of one or more LDAP URLs separated by blanks. Each LDAP URL has the format: 
    
ldap://host_name [: port ]
    where host_name is a host name or IP address, port is a TCP port number, and brackets denote an optional component.
The Lightweight Directory Access Protocol (LDAP) servers that hold certificate revocation lists (CRLs) for use on a TLS connection
sslCipherSuite String
  • null
  • The name of a CipherSuite
The CipherSuite to use for a TLS connection
sslFipsRequired 2 Boolean
  • false
  • true
Whether a TLS connection must use a CipherSuite that is supported by the IBM Java JSSE FIPS provider (IBMJSSEFIPS)
sslPeerName String
  • null
  • A template for distinguished names
For a TLS connection, a template that is used to check the distinguished name in the digital certificate provided by the queue manager
sslResetCount int
  • 0
  • An integer in the range 0 - 999 999 999
The total number bytes sent and received by a TLS connection before the secret keys used by TLS are renegotiated
sslSocketFactory String A string representing the fully qualified class name of a class providing an implementation of the javax.net.ssl.SSLSocketFactory interface. Optionally including an argument to be passed to the constructor method, enclosed in parentheses. Any connections established in the scope of the administered object use sockets obtained from this implementation of the SSLSocketFactory interface.
statusRefreshInterval 1 int
  • 60000
  • Any positive integer
The interval, in milliseconds, between refreshes of the long running transaction that detects when a subscriber loses its connection to the queue manager. This property is relevant only if subscriptionStore has the value QUEUE.
subscriptionStore 1 String
  • BROKER
  • MIGRATE
  • QUEUE
Determines where IBM MQ classes for JMS stores persistent data about active subscriptions
transportType String
  • CLIENT
  • BINDINGS
  • BINDINGS_THEN_CLIENT
Whether a connection to a queue manager uses client mode or bindings mode. If the value BINDINGS_THEN_CLIENT is specified, the resource adapter first tries to make a connection in bindings mode. If this connection attempt fails the resource adapter then tries to make a client mode connection.

[z/OS]If an activation specification that is running on a WebSphere® Application Server for z/OS® system has been configured to use the BINDINGS_THEN_CLIENT transport mode and a previously established connection is broken, then any reconnection attempts by the activation specification first attempt to use the BINDINGS transport mode. If the BINDINGS transport mode connection attempt is unsuccessful, the activation specification subsequently attempts a CLIENT transport mode connection.
username String
  • null
  • A user name
The default user name to use when creating a connection to a queue manager
wildcardFormat String
  • CHAR- Recognizes character wildcards only, as used in broker version 1
  • TOPIC - Recognizes topic level wildcards only, as used in broker version 2
Which version of wildcard syntax is to be used
Notes:
  1. This property can be used with IBM MQ classes for JMS in IBM WebSphere MQ 7.0. It does not affect an application connected to an IBM WebSphere MQ 7.0 queue manager unless the providerVersion property is set to a version number less than 7.
  2. For important information about using the sslFipsRequired property, see Limitations of the IBM MQ resource adapter.
  3. For information on how to configure the resource adapter so that it can locate an exit, see Configuring IBM MQ classes for JMS to use channel exits.

Properties used to create a JMS connection consumer

Note: The destination and destinationType must be defined explicitly. All the other properties in Table 2 are optional.
Table 2. Properties of an ActivationSpec object that are used to create a JMS connection consumer
Name of property Type Valid values (default value in bold) Description
destination String A destination name The destination from which to receive messages. The useJNDI property determines how the value of this property is interpreted.
destinationLookup String
  • null
  • The JNDI name for a Destination object
 If this property is set, the ActivationSpec looks up a JMS Destination object with the specified JNDI name in the JNDI namespace of the application server, and then uses the properties of that object to create a JMS connection consumer, in preference to the other properties specified on the ActivationSpec. For more information, see ActivationSpec connectionFactoryLookup and destinationLookup properties.
destinationType String
  • javax.jms.Queue
  • javax.jms.Topic
The type of destination, a queue, or a topic
maxMessages int
  • 1
  • A positive integer
The maximum number of messages that can be assigned to a server session at one time. If the activation spec is delivering messages to an MDB in an XA transaction, a value of 1 is used regardless of the setting of this property.
maxPoolDepth int
  • 10
  • A positive integer
The maximum number of server sessions in the server session pool used by the connection consumer
messageSelector String
  • null
  • An SQL92 message selector expression
A message selector expression specifying which messages are to be delivered
nonASFTimeout int
  • 0
  • A positive integer
A positive value indicates that non-ASF delivery is used. The value is the time, in milliseconds, that a get request waits for messages that might not have yet arrived (a get with wait call). The default value, 0, indicates that ASF delivery is used.
This parameter is valid if:
  • The application is running on WebSphere Application Server 7.0 or later.
  • The application is running in WebSphere Application Server Liberty using the appropriate level of wmqJmsClient feature. For more information, see Liberty and the IBM MQ resource adapter.
nonASFRollbackEnabled Boolean
  • false - The message is consumed even if the MDB fails
  • true - Failure within the MDB causes the message to roll back to the queue.
Whether message delivery is within an IBM MQ syncpoint if the MDB is non-transacted. Ignored if the MDB is transacted or if nonASFTimeout is set to 0.
poolTimeout int
  • 300000
  • A positive integer
The time, in milliseconds, that an unused server session is held open in the server session pool before being closed due to inactivity
readAheadAllowed int
  • DESTINATION - Determine whether read ahead is allowed by referring to the queue or topic definition.
  • DISABLED - Read ahead is not allowed.
  • ENABLED - Read ahead is allowed.
  • QUEUE - Determine whether read ahead is allowed by referring to the queue definition.
  • TOPIC - Determine whether read ahead is allowed by referring to the topic definition.
Whether the MDB is allowed to use read ahead to get nonpersistent messages from the destination into an internal buffer before receiving them
readAheadClosePolicy int
  • ALL - All messages in the internal read ahead buffer are delivered to the MDB before it stops.
  • CURRENT - Only the current MDB invocation completes, potentially leaving messages in the internal read ahead buffer, which are then discarded.
What happens to messages in the internal read ahead buffer when the MDB is stopped by the administrator.
receiveCCSID int
  • 0 - Use JVM Charset.defaultCharset
  • 1208 - UTF-8
  • A supported coded character set identifier
Destination property that sets the target CCSID for queue manager message conversion. The value is ignored unless receiveConversion is set to QMGR.
receiveConversion String
  • CLIENT_MSG
  • QMGR
Destination property that determines whether data conversion is going to be performed by the queue manager.
sharedSubscription Boolean
  • False - The MDB should not open the subscription as a shared subscription.
  • True - The MDB should open the subscription as a shared subscription (with the rules that JMS 2.0 implies, see the JMS 2.0 specification at Java.net).
 Controls how an MDB is driven from a shared subscription. For more information about how to use this property, see Examples of how to define the sharedSubscription property.
startTimeout int
  • 10 000
  • A positive integer
The time, in milliseconds, within which delivery of a message to an MDB must start after the work to deliver the message has been scheduled. If this time elapses, the message is rolled back onto the queue.
subscriptionDurability String
  • NonDurable - A nondurable subscription is used to deliver messages to an MDB subscribing to the topic.
  • Durable - A durable subscription is used to deliver messages to an MDB subscribing to the topic.
Whether a durable or nondurable subscription is used to deliver messages to an MDB subscribing to the topic
subscriptionName String
  • "" (empty string)
  • A subscription name
The name of the durable subscription
useJNDI Boolean
  • false - The property called destination is interpreted as the name of an IBM MQ queue or a topic.
  • true - The property called destination is interpreted as the name of a javax.jms.Queue object or javax.jms.Topic object in the JNDI namespace of the application server.
Determines how the value of the property called destination is interpreted
Note: This property is deprecated in IBM MQ 9.0. The destinationLookup property should be used instead.

Property conflicts and dependencies

An ActivationSpec object can have conflicting properties. For example, you can specify TLS properties for a connection in bindings mode. In this case, the behavior is determined by the transport type and the messaging domain, which is either point-to-point or publish/subscribe as determined by the destinationType property. Any properties that are not applicable to the specified transport type or messaging domain are ignored.

If you define a property that requires other properties to be defined, but you do not define these other properties, the ActivationSpec object throws an InvalidPropertyException exception when its validate() method is called during the deployment of an MDB. The exception is reported to the administrator of the application server in a manner that depends on the application server. For example, if you set the subscriptionDurability property to Durable, indicating that you want use durable subscriptions, you must also define the subscriptionName property.

If the properties called ccdtURL and channel are both defined, an InvalidPropertyException exception is thrown. However, if you define the ccdtURL property only, leaving the property called channel with its default value of SYSTEM.DEF.SVRCONN, no exception is thrown, and the client channel definition table identified by the ccdtURL property is used to start a JMS connection.

ActivationSpec connectionFactoryLookup and destinationLookup properties

These two properties can be used to specify the JNDI names of ConnectionFactory and Destination objects that are used in preference to the properties of the ActivationSpec as defined in Table 1 and Table 2.
It is important to note the following points that describe how these properties work in detail.
connectionFactoryLookup
The ConnectionFactory that is looked up from JNDI is used as a source of the properties listed in Table 1. The ConnectionFactory object is not used to actually create any JMS connections, only the properties of the object are queried. These properties from the ConnectionFactory override any properties that are defined on the ActivationSpec. There is a single exception to this. If the ActivationSpec has the ClientID property set, then the value of this property overrides the value specified in the ConnectionFactory. This is because a common scenario is using a single ConnectionFactory with multiple ActivationSpecs. This simplifies administration. However, the JMS 2.0 specification states that every JMS Connection created from a ConnectionFactory should have a unique ClientID. Because of this, ActivationSpecs need to have the ability to override any value set on the ConnectionFactory. If no ClientID is set on the ActivationSpec, any value on the connection factory is used.
destinationLookup
A Destination and a UseJndi property are defined on the ActivationSpec. If the UseJndi flag is set to true, then the text specified in the destination property is considered to be a JNDI name and a destination object with that JNDI name is looked up from JNDI.

The destinationLookup property behaves in exactly the same way. If it has been set, then a destination object with the JNDI name specified by the property is looked up from JNDI. This property has precedence over the useJNDI property.

The useJNDI property is deprecated at IBM MQ 9.0 as the destinationLookup property is the JMS 2.0 specification equivalent of performing the same function.

ActivationSpec properties with no equivalents in IBM MQ classes for JMS

Most of the properties of an ActivationSpec object are equivalent to properties of IBM MQ classes for JMS objects or parameters of IBM MQ classes for JMS methods. However, three tuning properties, and one usability property, have no equivalents in IBM MQ classes for JMS:
startTimeout
The time, in milliseconds, that the work manager of the application server waits for resources to become available after the resource adapter schedules a Work object to deliver a message to an MDB. If this time elapses before delivery of the message starts, the Work object times out, the message is rolled back onto the queue, and the resource adapter can then attempt to deliver the message again. A warning is written to diagnostic trace, if enabled, but does not otherwise affect the process of delivering messages. You might expect this condition to occur only at times when the application server is experiencing a very high load. If the condition occurs regularly, consider increasing the value of this property to give the work manager longer to schedule message delivery.
maxPoolDepth
The maximum number of server sessions in the server session pool used by a connection consumer. When a server session is created, it starts a conversation with a queue manager. The connection consumer uses a server session to deliver a message to an MDB. A larger pool depth allows more messages to be delivered concurrently in high volume situations, but uses more resources of the application server. If many MDBs are to be deployed, consider making the pool depth smaller in order to maintain the load on the application server at a manageable level. Each connection consumer uses its own server session pool, so that this property does not define the total number of server sessions available to all connection consumers.
poolTimeout
The time, in milliseconds, that an unused server session is held open in the server session pool before being closed due to inactivity. A transient increase in the message workload causes additional server sessions to be created in order to distribute the load but, after the message workload returns to normal, the additional server sessions remain in the pool and are not used.

Every time a server session is used, it is marked with a timestamp. Periodically a scavenger thread checks that each server session has been used within the period specified by this property. If a server session has not been used, it is closed and removed from the server session pool. A server session might not be closed immediately after the specified period has elapsed, this property represents the minimum period of inactivity before removal.

useJNDI
For a description of this property, see Table 2.

Deploying an MDB

To deploy an MDB, first define the properties of an ActivationSpec object, specifying the properties that the MDB requires. The following example is a typical set of properties that you might define explicitly: 

channel:          SYSTEM.DEF.SVRCONN
destination:      SYSTEM.DEFAULT.LOCAL.QUEUE
destinationType:  javax.jms.Queue
hostName:         192.168.0.42
messageSelector:  color='red'
port:             1414
queueManager:     ExampleQM
transportType:    CLIENT

The application server uses the properties to create an ActivationSpec object, which is then associated with an MDB. The properties of the ActivationSpec object determine how messages are delivered to the MDB. Deployment of the MDB fails if the MDB requires distributed transactions but the resource adapter does not support distributed transactions. For information about how to install the resource adapter so that distributed transactions are supported, see Installing the IBM MQ resource adapter.

If more than one MDB is receiving messages from the same destination, then a message sent in the point-to-point domain is received by only one MDB, even if other MDBs are eligible to receive the message. In particular, if two MDBs are using different message selectors, and an incoming message matches both message selectors, only one of the MDBs receives the message. The MDB chosen to receive a message is undefined, and you cannot rely on a specific MDB receiving the message. Messages sent in the publish/subscribe domain are received by all eligible MDBs.

In some circumstances, a message delivered to an MDB might be rolled back onto an IBM MQ queue. This roll back can happen, for example, if a message is delivered within a unit of work that is then rolled back. A message that is rolled back is delivered again, but a badly formatted message might repeatedly cause an MDB to fail and therefore cannot be delivered. Such a message is called a poison message. You can configure IBM MQ so that IBM MQ classes for JMS automatically transfers a poison message to another queue for further investigation or discards the message.

For details on how to handle poison messages, see Handling poison messages in IBM MQ classes for JMS.