Building a connection

 

Overview

Connections are not created directly, but are built using a connection factory. Factory objects can be stored in a JNDI namespace or created at runtime.

 

Retrieving the factory from JNDI

To retrieve an object from a JNDI namespace, set up an initial context. For example: 

import javax.jms.*;
import javax.naming.*;
import javax.naming.directory.*;
.
.
.
java.util.Hashtable environment = new java.util.Hashtable();
environment.put(Context.INITIAL_CONTEXT_FACTORY, icf);
environment.put(Context.PROVIDER_URL, url);
Context ctx = new InitialDirContext( environment );

where:

icf
defines a factory class for the initial context

url
defines a context specific URL

Some combinations of the JNDI packages and LDAP service providers can result in an LDAP error 84. To resolve the problem, insert the following line before the call to InitialDirContext. 

environment.put(Context.REFERRAL, "throw");

Once an initial context is obtained, objects are retrieved from the namespace by using the lookup() method. The following code retrieves a QueueConnectionFactory named ivtQCF from an LDAP-based namespace: 

QueueConnectionFactory factory;
factory = (QueueConnectionFactory)ctx.lookup("cn=ivtQCF");

 

Using the factory to create a connection

The createQueueConnection() method on the factory object is used to create a Connection, as shown in the following code: 

QueueConnection connection;
connection = factory.createQueueConnection();

 

Creating factories at runtime

If a JNDI namespace is not available, it is possible to create factory objects at runtime. However, using this method reduces the portability of the JMS application because it requires references to WebSphere MQ specific classes.

The following code creates a QueueConnectionFactory with all default settings: 

factory = new com.ibm.mq.jms.MQQueueConnectionFactory();

(You can omit the com.ibm.mq.jms. prefix if you import the com.ibm.mq.jms package instead.)

A connection created from the above factory uses the Java bindings to connect to the default queue manager on the local machine.

The only way to create a TopicConnectionFactory object at runtime is to construct it using the MQTopicConnectionFactory constructor. For example: 

MQTopicConnectionFactory fact = new MQTopicConnectionFactory();

This creates a default TopicConnectionFactory object with the bindings transportType and all other default settings.

It is possible to change the transportType for the TopicConnectionFactory using its setTransportType() method. For example: 

fact.setTransportType(JMSC.MQJMS_TP_BINDINGS_MQ);     // Bindings mode
fact.setTransportType(JMSC.MQJMS_TP_CLIENT_MQ_TCPIP); // Client mode
fact.setTransportType(JMSC.MQJMS_TP_DIRECT_TCPIP);    // Direct TCP/IP mode

The full JMS TopicConnectionFactory interface has been implemented. Refer to TopicConnectionFactory for more details. Note that certain combinations of property settings are not valid for TopicConnectionFactory objects. See Properties for more details.

 

Starting the connection

The JMS specification defines that connections should be created in the stopped state. Until the connection starts, MessageConsumers that are associated with the connection cannot receive any messages. To start the connection, issue the following command: 

connection.start();

Table 14. Set methods on MQQueueConnectionFactory

Method Description
setCCSID(int) Used to set the MQEnvironment.CCSID property
setChannel(String) The name of the channel for a client connection
setFailIfQuiesce(int) Defines the behavior an application exhibits when making calls (for example, send and receive) against a quiescing queue manager. The options are:

  • JMSC.MQJMS_FIQ_NO

  • JMSC.MQJMS_FIQ_YES (the default)
setHostName(String) The name of the host for a client connection
setPort(int) The port for a client connection
setQueueManager(String) The name of the queue manager
setTemporaryModel(String) The name of a model queue used to generate a temporary destination as a result of a call to QueueSession.createTemporaryQueue(). Make this the name of a temporary dynamic queue, rather than a permanent dynamic queue.
setTransportType(int) How to connect to WebSphere MQ. The options are:

  • JMSC.MQJMS_TP_BINDINGS_MQ (the default)

  • JMSC.MQJMS_TP_CLIENT_MQ_TCPIP.

  • JMSC.MQJMS_TP_DIRECT_TCPIP
JMSC is in the package com.ibm.mq.jms
setReceiveExit(String)
setSecurityExit(String)
setSendExit(String)
setReceiveExitInit(String)
setSecurityExitInit(String)
setSendExitInit(String)
 Allow the use of the send, receive, and security exits provided by the underlying WebSphere MQ Classes for Java. The set*Exit methods take the name of a class that implements the relevant exit methods. (See the WebSphere MQ product documentation for details.)

The class must implement a constructor with a single String parameter. This string provides any initialization data required by the exit, and is set to the value provided in the corresponding set*ExitInit method.

 

Client transport vs. bindings transport

WebSphere MQ JMS can communicate with WebSphere MQ using either the client or bindings transports.

  1. If bindings transports are used, the JMS application and the MQ queue manager must be located on the same machine.

  2. If client transports, the queue manager can be on a different machine from the application.

The contents of the connection factory object determine which transport to use. For example: 

String HOSTNAME = "machine1";
String QMGRNAME = "machine1.PARIS";
String CHANNEL = "SYSTEM.DEF.SVRCONN";
 
factory = new MQQueueConnectionFactory();
factory.setTransportType(JMSC.MQJMS_TP_CLIENT_MQ_TCPIP);
factory.setQueueManager(QMGRNAME);
factory.setHostName(HOSTNAME);
factory.setChannel(CHANNEL);

 

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

 

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.