Configuring the resource adapter for outbound communication

To configure outbound communication, define the properties of a ConnectionFactory object and an administered destination object.

Example of using outbound communication

When using outbound communication, an application running in an application server starts a connection to a queue manager, and then sends messages to its queues and receives messages from its queues in a synchronous manner. For example, the following servlet method, doGet(), uses outbound communication:


protected void doGet(HttpServletRequest request, HttpServletResponse response)
     throws ServletException, IOException {

...

// Look up ConnectionFactory and Queue objects from the JNDI namespace

     InitialContext ic = new InitialContext();
     ConnectionFactory cf = (javax.jms.ConnectionFactory) ic.lookup("myCF");
     Queue q = (javax.jms.Queue) ic.lookup("myQueue");

// Create and start a connection

     Connection c = cf.createConnection();
     c.start();

// Create a session and message producer

     Session s = c.createSession(false, Session.AUTO_ACKNOWLEDGE);
     MessageProducer pr = s.createProducer(q);

// Create and send a message

     Message m = s.createTextMessage("Hello, World!");
     pr.send(m);

// Create a message consumer and receive the message just sent

     MessageConsumer co = s.createConsumer(q);
     Message mr = co.receive(5000);

// Close the connection

      c.close();
}

When the servlet receives an HTTP GET request, it retrieves a ConnectionFactory object and a Queue object from the JNDI namespace, and uses the objects to send a message to an IBM® MQ queue. The servlet then receives the message that it has sent.

Resources needed for outbound communication

To configure outbound communication, define JCA resources in the following categories:

The properties of a ConnectionFactory object, which the application server uses to create a JMS ConnectionFactory object.
The properties of an administered destination object, which the application server uses to create a JMS Queue object or JMS Topic object.

The way you define these properties depends on the administration interfaces provided by your application server. ConnectionFactory, Queue, and Topic objects created by the application server are bound into a JNDI namespace from where they can be retrieved by an application.

Typically, you define one ConnectionFactory object for each queue manager that applications might need to connect to. You define one Queue object for each queue that applications might need to access in the point-to-point domain. And you define one Topic object for each topic that applications might want to publish or subscribe to. A ConnectionFactory object can be domain independent. Alternatively, it can be domain-specific, a QueueConnectionFactory object for the point-to-point domain or a TopicConnectionFactory object for the publish/subscribe domain.

Properties of a ConnectionFactory object

Table 1 lists the properties of a ConnectionFactory object.

Table 1. Properties of a ConnectionFactory object
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 ).
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.
brokerPubQueue ¹	String	SYSTEM.BROKER.DEFAULT.STREAM A queue name	The name of the queue where published messages are sent (the stream 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. See BROKERSUBQ property for more information.
brokerVersion ¹	String	unspecified - After the broker has been 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 ¹	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.
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.
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 outbound communications. 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: 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.
messageSelection ¹	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 ¹	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 application intends to connect.
pubAckInterval ¹	int	25 A positive integer	The number of messages published by a publisher before IBM MQ classes for JMS requests an acknowledgment from the broker.
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 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 ¹	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³	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.
sendCheckCount	int	0 Any positive integer	The number of send calls to allow between checking for asynchronous put errors, within a single non-transacted JMS session.
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 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 ¹	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 an SSL connection.
sslCipherSuite	String	null The name of a CipherSuite	The CipherSuite to use for an SSL connection.
sslFipsRequired ²	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 - 999 999 999	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 destination object use sockets obtained from this implementation of the SSLSocketFactory interface.
statusRefreshInterval ¹	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 SUBSTORE has the value QUEUE.
subscriptionStore ¹	String	BROKER MIGRATE QUEUE	Determines where IBM MQ classes for JMS stores persistent data about active subscriptions.
targetClientMatching	Boolean	true false	Whether a reply message, sent to the queue identified by the JMSReplyTo header field of an incoming message, has an MQRFH2 header only if the incoming message has an MQRFH2 header. You can also configure this property for an activation specification. For more information, see Configuring the targetClientMatching property for an activation specification.
temporaryModel	String	SYSTEM.DEFAULT.MODEL.QUEUE SYSTEM.JMS.TEMPQ.MODEL Any string	The name of the model queue from which JMS temporary queues are created. Use SYSTEM.DEFAULT.MODEL.QUEUE if both of the following are true: Your application uses a temporary queue that will accept non-persistent messages. Only one application will create a temporary queue on the queue manager that the ConnectionFactory points to at a time. Note that SYSTEM.DEFAULT.MODEL.QUEUE can only be opened by one application at a time. Use SYSTEM.JMS.TEMPQ.MODEL. in the following situations: When your application uses a temporary queue that will accept persistent messages. If multiple applications can connect to the queue manager that the ConnectionFactory points to and those applications need to create temporary queues at the same time. Define a new model queue with the DEFPSIST attribute set to YES, and the DEFSOPT attribute set to SHARED in the following situation: When your application uses a temporary queue that will accept non-persistent messages, and multiple applications will connect to the queue manager that the ConnectionFactory points to, and those applications need to create temporary queues at the same time. When the new model queue is created, set the temporaryModel property to the name of the new model queue.
tempQPrefix	String	"" (empty string) A prefix that can be used to form the name of an IBM MQ dynamic queue. The rules for forming the prefix are the same as the rules for forming the contents of the `DynamicQName` field in an IBM MQ object descriptor, structure MQOD, but the last non-blank character must be an asterisk (). If the value of the property is the empty string, IBM MQ classes for JMS uses the value AMQ. when creating a dynamic queue.	The prefix that is used to form the name of an IBM MQ dynamic queue.
tempTopicPrefix	String	Any non-null string consisting only of valid characters for an IBM MQ topic string	When creating temporary topics, JMS generates a topic string of the form "TEMP/`TEMPTOPICPREFIX`/`unique_id`", or if this property is left with the default value, just "TEMP/`unique_id`". Specifying a non-empty TEMPTOPICPREFIX allows specific model queues to be defined for creating the managed queues for subscribers to temporary topics created under this connection.
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. 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	int	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:

This property can be used with Version 7.0 of IBM MQ classes for JMS but 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 MQ resource adapter.
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.

The following example shows a typical set of properties of a ConnectionFactory object:


channel:        SYSTEM.DEF.SVRCONN
hostName:       192.168.0.42
port:           1414
queueManager:   ExampleQM
transportType:  CLIENT

Properties of an administered destination object

The application server uses the properties of an administered destination object to create a JMS Queue object or JMS Topic object.

Table 2 lists the properties that are common to a Queue object and a Topic object.

Table 2. Properties that are common to a Queue object and a Topic object
Name of property	Type	Valid values (default value in bold)	Description
CCSID	String	1208 A coded character set identifier supported by the Java virtual machine (JVM)	The coded character set identifier for the destination.
encoding	String	NATIVE A string of three characters: The first character specifies the representation of binary integers: N denotes normal encoding. R denotes reverse encoding. The second character specifies the representation of packed decimal integers: N denotes normal encoding. R denotes reverse encoding. The third character specifies the representation of floating point numbers: N denotes standard IEEE encoding. R denotes reverse IEEE encoding. 3 denotes zSeries encoding. NATIVE is equivalent to the string NNN.	The representation of binary integers, packed decimal integers, and floating point numbers for the destination.
expiry	String	APP - The expiry time of a message is determined by the message producer. UNLIM - A message never expires. 0 - A message never expires. A positive integer representing the expiry time of a message in milliseconds.	The expiry time of a message sent to the destination.
failIfQuiesce	String	true false	Whether an attempt to access the destination fails if the queue manager is in a quiescing state.
messageBodyStyle	String	UNSPECIFIED JMS MQ	You can set the messageBodyStyle property on JMS queues and topics: UNSPECIFIED(default) When sending, IBM MQ classes for JMS generate and include an MQRFH2 header, depending on the value of WMQ_TARGET_CLIENT. When receiving, IBM MQ classes for JMS set the JMS message properties according to values in the MQRFH2, if present. MQRFH2 is not presented as part of the JMS message body. JMS When sending, IBM MQ classes for JMS automatically generates an MQRFH2 header and includes the header in the IBM MQ message. When receiving, IBM MQ classes for JMS set the JMS message properties according to values in the MQRFH2, if present. MQRFH2 is not presented as part of the JMS message body. MQ When sending, IBM MQ classes for JMS do not generate an MQRFH2. When receiving, IBM MQ classes for JMS present the MQRFH2 as part of the JMS message body.
persistence	String	APP - The persistence of a message is determined by the message producer. QDEF - The persistence of a message is determined by the `DefPersistence` attribute of the IBM MQ queue. PERS - A message is persistent. NON - A message is nonpersistent. HIGH - The persistence of a message is determined by the `NonPersistentMessageClass` attribute of the IBM MQ queue according to the explanation in JMS persistent messages.	The persistence of a message sent to the destination.
priority	String	APP - The priority of a message is determined by the message producer. QDEF - The priority of a message is determined by the `DefPriority` attribute of the IBM MQ queue. An integer in the range 0, lowest priority, to 9, highest priority.	The priority of a message sent to the destination.
putAsyncAllowed	String	QUEUE - Determine whether asynchronous puts are allowed by referring to the queue definition. TOPIC - Determine whether asynchronous puts are allowed by referring to the topic definition. DESTINATION - Determine whether asynchronous puts are allowed by referring to the queue or topic definition. DISABLED - Asynchronous puts are not allowed. ENABLED - Asynchronous puts are allowed.	Whether message producers are allowed to use asynchronous puts to send messages to this destination.
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 message consumers and queue browsers are allowed to use read ahead to get nonpersistent messages from the destination into an internal buffer before receiving them.
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.
targetClient	String	JMS - The target of a message is a JMS application. MQ - The target of a message is a non-JMS IBM MQ application.	Whether the target of a message sent to the destination is a JMS application. A message with a target that is a JMS application contains an MQRFH2 header.

Table 3 lists the properties that are specific to a Queue object.

Table 3. Properties that are specific to a Queue object
Name of property	Type	Valid values (default value in bold)	Description
baseQueueManagerName	String	"" (empty string) A queue manager name	The name of the queue manager that owns the underlying IBM MQ queue.
baseQueueName	String	"" (empty string) A queue name	The name of the underlying IBM MQ queue.

Table 4 lists the properties that are specific to a Topic object.

Table 4. Properties that are specific to a Topic object
Name of property	Type	Valid values (default value in bold)	Description
baseTopicName	String	"" (empty string) A topic name	The name of the underlying topic.
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.
brokerDurSubQueue ¹	String	SYSTEM.JMS.D.SUBSCRIBER.QUEUE A queue name	The name of the queue from which a durable topic subscriber receives messages. See the BROKEDURRSUBQ property in the IBM MQ Explorer documentation for more information.
brokerPubQueue ¹	String	Not set A queue name	The name of the queue where published messages are sent (the stream queue). The value of this property overrides the value of the brokerPubQueue property of the ConnectionFactory object. However, if you do not set the value of this property, the value of the brokerPubQueue property of the ConnectionFactory object is used instead.
brokerPubQueueManager ¹	String	"" (empty string) A queue manager name	The name of the queue manager that owns the queue where messages published on the topic are sent.
brokerVersion ¹	String	Not set 1 2	The version of the broker being used. The value of this property overrides the value of the brokerVersion property of the ConnectionFactory object. However, if you do not set the value of this property, the value of the brokerVersion property of the ConnectionFactory object is used instead.

Note:

This property can be used with Version 7.0 of IBM MQ classes for JMS but does not affect an application connected to a Version 7.0 queue manager unless the providerVersion property of the ConnectionFactory object is set to a version number less than 7.

The following example shows a set of properties of a Queue object:


expiry:               UNLIM
persistence:          QDEF
baseQueueManagerName: ExampleQM
baseQueueName:        SYSTEM.JMS.TEMPQ.MODEL

The following example shows a set of properties of a Topic object:


expiry:               UNLIM
persistence:          NON
baseTopicName:        myTestTopic