Specify a range of ports for client connections in IBM MQ classes for JMS

Use the LOCALADDRESS property to specify a range of ports that the application can bind to.

When an IBM MQ classes for JMS application attempts to connect to an IBM 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, we 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.

We can set the LOCALADDRESS property by using the IBM 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("192.0.2.0(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 192.0.2.0(2000) to 192.0.2.0(3000).

In a system with more than one network interface, we can also use the LOCALADDRESS property to specify which network interface must be used for a connection.

For a real-time connection to a broker, the LOCALADDRESS property is relevant only when multicast is used. In this case, we 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 IBM 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 IBM MQ classes for JMS 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 IBM MQ classes for JMS 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 IBM MQ classes for 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.

Parent topic: Accessing IBM MQ features from an IBM MQ classes for JMS application