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 a WebSphere® MQ queue. The transactional behavior of the MDB is defined in its deployment descriptor.
- Properties that are used to create a JMS connection to a WebSphere MQ queue manager
- Properties that are used to create a JMS connection consumer that delivers messages asynchronously as they arrive on a specified queue
Name of property | Type | Valid values (default value in bold) | Description |
---|---|---|---|
applicationName | String |
|
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® WebSphere MQ Explorer Application Connections display (where the field is called App name). |
brokerCCDurSubQueue 1 | String |
|
The name of the queue from which a connection consumer receives durable subscription messages |
brokerCCSubQueue 1 | String |
|
The name of the queue from which a connection consumer receives nondurable subscription messages |
brokerControlQueue 1 | String |
|
The name of the broker control queue |
brokerQueueManager 1 | String |
|
The name of the queue manager on which the broker is running |
brokerSubQueue1 | String |
|
The name of the queue from which a nondurable message consumer receives messages |
brokerVersion1 | String |
|
The version of the broker being used |
ccdtURL | String |
|
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 |
|
The coded character set identifier for a connection |
channel | String |
|
The name of the MQI channel to use |
cleanupInterval 1 | int |
|
The interval, in milliseconds, between background runs of the publish/subscribe cleanup utility |
cleanupLevel1 | String |
|
The cleanup level for a broker-based subscription store |
clientID | String |
|
The client identifier for a connection |
cloneSupport | String |
|
Whether two or more instances of the same durable topic subscriber can run simultaneously |
connectionNameList | String |
|
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 |
|
Whether calls to certain methods fail if the queue manager is in a quiescing state |
headerCompression | String |
|
A list of the techniques that can be used for compressing header data on a connection |
hostName | String |
|
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 |
|
For a connection to a queue manager, this property
specifies either or both of the following things:
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 |
|
A list of the techniques that can be used for compressing message data on a connection |
messageRetention1 | Boolean |
|
Whether the connection consumer keeps unwanted messages on the input queue |
messageSelection 1 | String |
|
Determines whether message selection is done by WebSphere MQ classes for JMS or by the broker. Message selection by the broker is not supported when brokerVersion has the value 1. |
password | String |
|
The default password to use when creating a connection to the queue manager |
pollingInterval1 | int |
|
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 |
|
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 |
|
The version, release, modification level and fix pack of the queue manager to which the MDB intends to connect. |
queueManager | String |
|
The name of the queue manager to connect to |
receiveExit 3 | String |
|
Identifies a channel receive exit program, or a sequence of receive exit programs to be run in succession |
receiveExitInit | String |
|
The user data that is passed to channel receive exit programs when they are called |
rescanInterval1 | int |
|
When a message consumer in the point-to-point domain uses a
message selector to select which messages it wants to receive, WebSphere MQ classes for JMS searches
the WebSphere MQ queue for suitable messages
in the sequence determined by the MsgDeliverySequence attribute
of the queue. When WebSphere MQ classes for
JMS finds a suitable message and delivers it to the consumer, WebSphere MQ classes for JMS resumes the
search for the next suitable message from its current position in
the queue. WebSphere 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, WebSphere MQ
classes for JMS returns to the beginning of the queue to continue
its search, and a new time interval commences. |
securityExit 3 | String |
|
Identifies a channel security exit program |
securityExitInit | String |
|
The user data that is passed to a channel security exit program when it is called |
sendExit 3 | String |
|
Identifies a channel send exit program, or a sequence of send exit programs to be run in succession |
sendExitInit | String |
|
The user data that is passed to channel send exit programs when they are called |
shareConvAllowed | Boolean |
|
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 |
sparseSubscriptions1 | Boolean |
|
Controls the message retrieval policy of a TopicSubscriber object |
sslCertStores | String |
|
The Lightweight Directory Access Protocol (LDAP) servers that hold certificate revocation lists (CRLs) for use on an SSL connection |
sslCipherSuite | String |
|
The CipherSuite to use for an SSL connection |
sslFipsRequired 2 | Boolean |
|
Whether an SSL connection must use a CipherSuite that is supported by the IBM Java JSSE FIPS provider (IBMJSSEFIPS) |
sslPeerName | String |
|
For an SSL connection, a template that is used to check the distinguished name in the digital certificate provided by the queue manager |
sslResetCount | int |
|
The total number bytes sent and received by an SSL connection before the secret keys used by SSL 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. |
statusRefreshInterval1 | int |
|
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 |
|
Determines where WebSphere MQ classes for JMS stores persistent data about active subscriptions |
transportType | String |
|
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 then the resource adapter tries to make a client mode connection. |
username | String |
|
The default user name to use when creating a connection to a queue manager |
wildcardFormat | String |
|
Which version of wildcard syntax is to be used |
- This property can be used with Version 7.0 of WebSphere MQ classes for JMS. It does not affect an application connected to a Version 7.0 queue manager unless the providerVersion property is set to a version number less than 7.
- For important information about using the sslFipsRequired property, see Limitations of the IBM WebSphere MQ resource adapter.
- For information on how to configure the resource adapter so that it can locate an exit, see Configuring IBM WebSphere MQ classes for JMS to use channel exits.
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. |
destinationType | String |
|
The type of destination, a queue, or a topic |
maxMessages | int |
|
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 |
|
The maximum number of server sessions in the server session pool used by the connection consumer |
messageSelector | String |
|
A message selector expression specifying which messages are to be delivered |
nonASFTimeout | int |
|
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 only when the application is running on WebSphere Application Server version 7 or later. |
nonASFRollbackEnabled | Boolean |
|
Whether message delivery is within a WebSphere MQ syncpoint if the MDB is non-transacted. Ignored if the MDB is transacted or if nonASFTimeout is set to 0. |
poolTimeout | int |
|
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 |
|
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 |
|
What happens to messages in the internal read ahead buffer when the MDB is stopped by the administrator. |
receiveCCSID | int |
|
Destination property that sets the target CCSID
for queue manager message conversion. The value is ignored unless receiveConversion is
set to QMGR |
receiveConversion | String |
|
Destination property that determines whether data conversion is going to be performed by the queue manager. |
startTimeout | int |
|
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 |
|
Whether a durable or nondurable subscription is used to deliver messages to an MDB subscribing to the topic |
subscriptionName | String |
|
The name of the durable subscription |
useJNDI | Boolean |
|
Determines how the value of the property called destination is interpreted |
The ActivationSpec properties called destination and destinationType must be defined explicitly. All the other properties are optional.
An ActivationSpec object can have conflicting properties. For example, you can specify SSL 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.
- 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.
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 Installation of the WebSphere 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.
Inbound poison message handling in the Resource Adapter
In some circumstances, a message delivered to an MDB might be rolled back onto a WebSphere 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 WebSphere MQ so that WebSphere 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 WebSphere MQ classes for JMS.