Connections are not created directly, but are built using a connection factory. ConnectionFactory objects can be stored in a JNDI namespace, insulating the JMS application from provider specific information. For information about how to create and store ConnectionFactory objects, see Using the WebSphere MQ JMS administration tool.
To retrieve a ConnectionFactory object from a JNDI namespace, you must first set up an initial context as shown in the following code:
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 );
In this code:
For more details about using a JNDI namespace, see Sun's JNDI documentation.
environment.put(Context.REFERRAL, "throw");
After an initial context is obtained, you can retrieve a ConnectionFactory object from the JNDI namespace by using the lookup() method. The following code retrieves a ConnectionFactory object named CF from an LDAP based namespace:
ConnectionFactory factory; factory = (ConnectionFactory)ctx.lookup("cn=CF");
If a JNDI namespace is not available, it is possible to create a ConnectionFactory object at runtime. However, using this method reduces the portability of a JMS application because the application must then include references to WebSphere MQ specific classes.
The following code creates a ConnectionFactory object with all the default settings:
factory = new com.ibm.mq.jms.MQConnectionFactory();
The default transport type is bindings. You can change the transport type for a connection factory by using the setTransportType() method. Here are some examples:
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
For information about transport types in each of the specific messaging domains, see Choosing client or bindings transport, for the point-to-point domain, and TopicConnectionFactory administered objects, for the publish/subscribe domain.
Note that you cannot use the point-to-point style of messaging if the transport type is direct. If an application uses Connection and Session objects that are created from a ConnectionFactory object whose transport type is direct, the application can perform only publish/subscribe operations.
A ConnectionFactory object has the same properties as those of a QueueConnectionFactory object and a TopicConnectionFactory object combined. However, certain combinations of property settings are not valid for a ConnectionFactory object. See Properties for more details.
You can use the createConnection() method on a ConnectionFactory object to create a Connection object, as shown in the following example:
Connection connection; connection = factory.createConnection();
Both QueueConnectionFactory and TopicConnectionFactory inherit the createConnection() method from ConnectionFactory. You can therefore use createConnection() to create a domain specific object, as shown in the following code:
QueueConnectionFactory QCF; Connection connection; connection = QCF.createConnection();
This code creates a QueueConnection object. An application can now perform a domain independent operation on this object, or an operation that is applicable only to the point-to-point domain. If the application attempts to perform an operation that is applicable only to the publish/subscribe domain, an IllegalStateException is thrown with the message MQJMS1112: JMS 1.1 Invalid operation for a domain specific object. This is because the connection was created from a domain specific connection factory.
The JMS specification states that a connection is created in the stopped state. Until the connection starts, a message consumer that is associated with the connection cannot receive any messages. To start the connection, issue the following command:
connection.start();
As an alternative to creating a client connection channel definition by setting certain properties of a ConnectionFactory object, a WebSphere MQ JMS client application can use client connection channel definitions that are stored in a client channel definition table. These definitions are created by WebSphere MQ Script (MQSC) commands or WebSphere MQ Programmable Command Format (PCF) commands. When the application creates a Connection object, the WebSphere MQ JMS client searches the client channel definition table for a suitable client connection channel definition, and uses the channel definition to start an MQI channel. For more information about client channel definition tables and how to construct one, see WebSphere MQ Clients.
To use a client channel definition table, the CCDTURL property of a ConnectionFactory object must be set to a URL object. The URL object encapsulates a uniform resource locator (URL) that identifies the name and location of the file containing the client channel definition table and specifies how the file can be accessed. You can set the CCDTURL property by using the WebSphere MQ JMS administration tool, or an application can set the property by creating a URL object and calling the setCCDTURL() method of the ConnectionFactory object.
For example, if the file ccdt1.tab contains a client channel definition table and is stored on the same system on which the application is running, the application can set the CCDTURL property in the following way:
java.net.URL chanTab1 = new URL("file:///home/admdata/ccdt1.tab"); factory.setCCDTURL(chanTab1);
As another example, suppose the file ccdt2.tab contains a client channel definition table and is stored on a system that is different to the one on which the application is running. If the file can be accessed using the FTP protocol, the application can set the CCDTURL property in the following way:
java.net.URL chanTab2 = new URL("ftp://ftp.server/admdata/ccdt2.tab"); factory.setCCDTURL(chanTab2);
In addition to setting the CCDTURL property of the ConnectionFactory object, the QMANAGER property of the same object must be set to one of the following values:
These are the same values that can be used for the QMgrName parameter on an MQCONN call issued by a client application that is using Message Queue Interface (MQI). For more information about the meaning of these values therefore, see the WebSphere MQ Application Programming Reference and WebSphere MQ Clients. You can set the QMANAGER property by using the WebSphere MQ JMS administration tool, or an application can set the property by calling the setQueueManager() method of the ConnectionFactory object.
If an application then creates a Connection object from the ConnectionFactory object, the WebSphere MQ JMS client accesses the client channel definition table identified by the CCDTURL property, uses the QMANAGER property to search the table for a suitable client connection channel definition, and then uses the channel definition to start an MQI channel to a queue manager. The way that the WebSphere MQ JMS client uses the QMANAGER property to search the client channel definition table is also as described in the WebSphere MQ Application Programming Reference and WebSphere MQ Clients. If your application uses connection pooling, see also Controlling the default connection pool.
Note that the CCDTURL and CHANNEL properties of a ConnectionFactory object cannot both be set when the application calls the createConnection() method. If both properties are set, the method throws an exception. The WebSphere MQ JMS administration tool actually prevents you from setting both properties. The CCDTURL or CHANNEL property is considered to be set if its value is anything other than null, an empty string, or a string containing all blank characters.
When the WebSphere MQ JMS client finds a suitable client connection channel definition in the client channel definition table, it uses only the information extracted from the table to start an MQI channel. Any channel related properties of the ConnectionFactory object are ignored.
In particular, note the following points if you are using Secure Sockets Layer (SSL):
For more information about using SSL with a client channel definition table, see WebSphere MQ Clients.
Note also the following points if you are using channel exits:
The use of channel exits written in a language other than Java is also supported. For information about how to specify the SCYEXIT, SENDEXIT, and RCVEXIT parameters on the DEFINE CHANNEL command for channel exits written in another language, see the WebSphere MQ Script (MQSC) Command Reference.
When a WebSphere MQ JMS application attempts to connect to a WebSphere MQ queue manager in client mode, a firewall might allow only those connections that originate from specified ports or a range of ports. In this situation, you can use the LOCALADDRESS property of a ConnectionFactory, QueueConnectionFactory, or TopicConnectionFactory object to specify a port, or a range of ports, that the application can bind to.
You can set the LOCALADDRESS property by using the WebSphere MQ JMS administration tool, or by calling the setLocalAddress() method in a JMS application. Here is an example of setting the property from within an application:
mqConnectionFactory.setLocalAddress("9.20.0.1(2000,3000)");
When the application connects to a queue manager subsequently, the application binds to a local IP address and port number in the range 9.20.0.1(2000) to 9.20.0.1(3000).
In a system with more than one network interface, you can also use the LOCALADDRESS property to specify which network interface must be used for a connection.
For a direct connection to a broker, the LOCALADDRESS property is relevant only when multicast is used. In this case, you can use the property to specify which local network interface must be used for a connection, but the value of the property must not contain a port number, or a range of port numbers.
Connection errors might occur if you restrict the range of ports. If an error occurs, a JMSException is thrown with an embedded MQException that contains the WebSphere MQ reason code MQRC_Q_MGR_NOT_AVAILABLE and the following message:
Socket connection attempt refused due to LOCAL_ADDRESS_PROPERTY restrictions
An error might occur if all the ports in the specified range are in use, or if the specified IP address, host name, or port number is not valid (a negative port number, for example).
Because the WebSphere MQ JMS client might create connections other than those required by an application, always consider specifying a range of ports. In general, every session created by an application requires one port and the WebSphere MQ JMS client might require three or four additional ports. If a connection error does occur, increase the range of ports.
Connection pooling, which is used by default in WebSphere MQ JMS, might have an effect on the speed at which ports can be reused. As a result, a connection error might occur while ports are being freed.
Compressing the data that flows on a WebSphere MQ channel can improve the performance of the channel and reduce network traffic. Using function supplied with WebSphere MQ, you can compress the data that flows on message channels and MQI channels and, on either type of channel, you can compress header data and message data independently of each other. By default, no data is compressed on a channel. For a full description of channel compression, including how it is implemented in WebSphere MQ, see WebSphere MQ Intercommunication, for message channels, and WebSphere MQ Clients, for MQI channels.
A WebSphere MQ JMS application specifies the techniques that can be used for compressing header or message data on a connection by creating a java.util.Collection object. Each compression technique is an Integer object in the collection, and the order in which the application adds the compression techniques to the collection is the order in which the compression techniques are negotiated with the queue manager when the application creates the connection. The application can then pass the collection to a ConnectionFactory object by calling the setHdrCompList() method, for header data, or the setMsgCompList() method, for message data. When the application is ready, it can create the connection.
The following code fragments illustrate the approach just described. The first code fragment shows you how to implement header data compression:
Collection headerComp = new Vector(); headerComp.add(new Integer(JMSC.MQJMS_COMPHDR_SYSTEM)); . . . ((MQConnectionFactory) cf).setHdrCompList(headerComp); . . . connection = cf.createConnection();
The second code fragment shows you how to implement message data compression:
Collection msgComp = new Vector(); msgComp.add(new Integer(JMSC.MQJMS_COMPMSG_RLE)); msgComp.add(new Integer(JMSC.MQJMS_COMPMSG_ZLIB_HIGH)); . . . ((MQConnectionFactory) cf).setMsgCompList(msgComp); . . . connection = cf.createConnection();
In the second example, the compression techniques are negotiated in the order RLE, then ZLIB_HIGH, when the connection is created. The compression technique that is selected cannot be changed during the lifetime of the Connection object. Note that, to use compression on a connection, the setHdrCompList() and the setMsgCompList() methods must be called before creating the Connection object.
For more information about specifying compression techniques, and about which compression techniques are available, see MQConnectionFactory and JMSC.
Notices |
Downloads |
Library |
Support |
Feedback
![]() ![]() |
csqzaw1374 |