Connections are not created directly, but are built using a connection factory. Factory objects can be stored in a JNDI namespace, insulating the JMS application from provider-specific information. Details of how to create and store factory objects are in Using the WebSphere MQ JMS administration tool.
If you do not have a JNDI namespace available, see Creating factories at runtime.
To retrieve an object from a JNDI namespace, set up an initial context, as shown in this fragment taken from the IVTRun sample file:
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:
For more details about JNDI usage, see Sun's JNDI documentation.
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");
The createQueueConnection() method on the factory object is used to create a Connection, as shown in the following code:
QueueConnection connection; connection = factory.createQueueConnection();
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(R) 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(TM) bindings to connect to the default queue manager on the local machine. The set methods described in MQConnectionFactory can be used to customize the factory with WebSphere MQ specific information.
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 MQTopicConnectionFactory for more details. Note that certain combinations of property settings are not valid for TopicConnectionFactory objects. See Properties for more details.
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();
WebSphere MQ JMS can communicate with WebSphere MQ using either client or bindings transport. (However, client transport is not supported on z/OS.) If you use the Java bindings, the JMS application and the WebSphere MQ queue manager must be located on the same machine. If you use the client, the queue manager can be on a different machine from the application.
The contents of the connection factory object determine which transport to use. Using the WebSphere MQ JMS administration tool describes how to define a factory object for use with client or bindings transport.
The following code fragment illustrates how you can define the transport within an application:
String HOSTNAME = "machine1"; String QMGRNAME = "machine1.QM1"; 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);
When used in client mode, WebSphere MQ JMS does not access information stored in a qm.ini file, or the equivalent information stored in the Windows Registry. Entries in a qm.ini file, such as the KeepAlive entry, are therefore ignored.
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 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 an application. Here is an example of setting the property from within an application:
mqQueueConnectionFactory.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.
Notices |
Downloads |
Library |
Support |
Feedback
![]() ![]() |
csqzaw1364 |