Configuration for inbound communication

 

To configure inbound communication, define the properties of one or more ActivationSpec objects. The properties of an ActivationSpec object determine how an MDB receives JMS messages from a WebSphere 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 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

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

Table 1 lists the properties of an ActivationSpec object that are used to create a JMS connection to a WebSphere MQ queue manager.

Properties of an ActivationSpec object that are used to create a JMS connection

Name of property	Type	Valid values (default value in bold)	Description
brokerCCDurSubQueue	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	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	String	SYSTEM.BROKER.CONTROL.QUEUE A queue name	The name of the broker control queue
brokerQueueManager	String	"" (empty string) A queue manager name	The name of the queue manager on which the broker is running
brokerSubQueue	String	SYSTEM.JMS.ND.SUBSCRIBER.QUEUE A queue name	The name of the queue from which a nondurable message consumer receives messages
brokerVersion	String	1 2	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 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	int	3 600 000 A positive integer	The interval, in milliseconds, between background runs of the publish/subscribe cleanup utility
cleanupLevel	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
failIfQuiesce	boolean	true false	Whether calls to certain methods fail if the queue manager is in a quiescing state
hostName	String	localhost A host name An IP address	The host name or IP address of the system on which the queue manager resides
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: The local network interface to be used The local port, or range of local ports, to be used
messageSelection	String	CLIENT BROKER	Determines whether message selection is done by WebSphere MQ JMS or by the broker. Message selection by the broker is not supported when brokerVhas the value 1.
password	String	null A password	The default password to use when creating a connection to the queue manager
port	int	1414 A TCP port number	The port on which the queue manager listens
queueManager	String	"" (empty string) A queue manager name	The name of the queue manager to connect to
receiveExit	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 WebSphere MQ base 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
securityExit	String	null The fully qualified name of a class that implements the WebSphere MQ base 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	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 WebSphere MQ base 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
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 an SSL connection
sslCipherSuite	String	null The name of a CipherSuite	The CipherSuite to use for an SSL connection
sslFipsRequired1	boolean	false true	Whether an SSL 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 an SSL 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 to 999 999 999	The total number bytes sent and received by an SSL connection before the secret keys used by SSL are renegotiated
subscriptionStore	String	MIGRATE QUEUE BROKER	Determines where WebSphere MQ JMS stores persistent data about active subscriptions
transportType	String	CLIENT BINDINGS	Whether a connection to a queue manager uses client mode or bindings mode
username	String	null A user name	The default user name to use when creating a connection to a queue manager
For important information about using the sslFipsRequired property, see Limitations of the WebSphere MQ resource adapter.

Table 2 lists the properties of an ActivationSpec object that are used to create a JMS connection consumer.

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.
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
maxPoolSize	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
poolTimeout	int	300 000 A positive integer	The period of time, in milliseconds, that an unused server session is held open in the server session pool before being closed due to inactivity
startTimeout	int	10 000 A positive integer	The period of 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 period of 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 a WebSphere 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 application server's JNDI namespace.	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, we 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, 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.

Most of the properties of an ActivationSpec object are equivalent to properties of WebSphere MQ JMS objects or parameters of WebSphere MQ JMS methods. However, three tuning properties, and one usability property, have no equivalents in WebSphere MQ 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 period of 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 make another attempt to deliver the message. A warning is written to diagnostic trace, if enabled, but this 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.

maxPoolSize

The maximum number of server sessions in the server session pool used by a connection consumer. The connection consumer uses a server session to deliver a message to an MDB. A larger pool size 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 size smaller in order to maintain the load on the application server at a manageable level. Note that 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 period of 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.

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 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 we cannot rely on a specific MDB receiving the message. Messages sent in the publish/subscribe domain are received by all eligible MDBs.

uj40080_