This section describes some problems that can occur when you develop JMS client applications that use the publish/subscribe domain. It discusses problems that are specific to the publish/subscribe domain. Refer to Handling errors and Solving problems for more general troubleshooting guidance.
It is important that JMS client applications surrender all external resources when they terminate. To do this, call the close() method on all objects that can be closed once they are no longer required. For the publish/subscribe domain, these objects are:
The WebSphere MQ classes for Java Message Service implementation eases this task by using a cascading close. With this process, a call to close on a TopicConnection results in calls to close on each of the TopicSessions it created. This in turn results in calls to close on all TopicSubscribers and TopicPublishers the sessions created.
To ensure the proper release of external resources, call connection.close() for each of the connections that an application creates.
There are some circumstances where this close procedure might not complete. These include:
In these circumstances, the close() is not called, and external resources remain open on the terminated application's behalf. The main consequences of this are:
Additionally, if the broker resides on a queue manager other than the application's local queue manager, correct operation of WebSphere MQ JMS depends on the communication channels between the two queue managers. If these channels fail for any reason, problems such as the above can occur until the channels restart. When diagnosing problems relating to channels, be careful not to lose WebSphere MQ JMS control messages on the transmission queue.
To avoid the problems associated with non-graceful closure of subscriber objects, WebSphere MQ JMS includes a subscriber cleanup utility that attempts to detect any earlier WebSphere MQ JMS publish/subscribe problems that could have resulted from other applications. This utility runs transparently in the background and should not affect other WebSphere MQ JMS operations. If a large number of problems are detected against a given queue manager, you might see some performance degradation while resources are cleaned up.
The exact behavior of the utility depends on the subscription store in use:
If all the TopicConnections on a given queue manager close, when the next TopicConnection initializes for that queue manager, the utility runs again.
The cleanup utility uses information found on the SYSTEM.JMS.ADMIN.QUEUE and SYSTEM.JMS.PS.STATUS.QUEUE to detect previously failed subscribers. If any are found, it cleans up associated resources by deregistering the subscriber from the broker, and cleaning up any unconsumed messages or temporary queues associated with the subscription.
The cleanup utility uses information found on the SYSTEM.JMS.REPORT.QUEUE (typically responses from the publish/subscribe broker) to remove unconsumed messages and temporary queues associated with a failed subscriber. It can be a few seconds after the subscriber fails before the cleanup routine can remove the messages and queues.
Two properties on the TopicConnectionFactory control behavior of this cleanup thread: CLEANUP and CLEANUPINT. CLEANUPINT determines how often (in milliseconds) cleanup is executed against any given queue manager. CLEANUP takes one of four possible values:
The cleanup thread tries to remove unconsumed subscription messages or temporary queues for failed subscriptions. This mode of cleanup does not interfere with the operation of other JMS applications.
This mode of cleanup can interfere with the operation of JMS applications running with later versions of WebSphere MQ JMS. If multiple JMS applications are using the same queue manager, but using different versions of WebSphere MQ JMS, only clients using the most recent version of WebSphere MQ JMS must use this option.
This option can be useful if the application is distant from the queue manager, and especially if it only publishes rather than subscribes. However, one application must clean up the queue manager to deal with any unconsumed messages. This can be a JMS application with CLEANUP(SAFE) or CLEANUP(STRONG), or the manual cleanup utility described in Manual cleanup.
This property can be set on the Java command-line using the -D option, to NONE, SAFE, or STRONG. Any other value causes an exception. If not set, the property defaults to SAFE.
This allows easy JVM-wide change to the cleanup level without updating every TopicConnectionFactory used by the system. This is useful for applications or application servers that use multiple TopicConnectionFactory objects.
Where multiple TopicConnections exist within a JVM against the same queue manager, but with differing values for CLEANUP and CLEANUPINT, the following rules are used to determine behavior:
If you use the broker-based subscription store, you can operate cleanup manually from the command-line. The syntax for bindings attach is:
Cleanup [-m <qmgr>] [-r <interval>] [SAFE | STRONG | FORCE | NONDUR] [-t]
or, for client attach:
Cleanup -client [-m <qmgr>] -host <hostname> [-port <port>] [-channel <channel>] [-r <interval>] [SAFE | STRONG | FORCE | NONDUR] [-t]
Where:
This is a dangerous option that can leave an inconsistent state between the queue manager and the broker. It cannot be run while any WebSphere MQ JMS publish/subscribe application is running against the queue manager; doing so causes the cleanup utility to abort.
After clearing the SYSTEM.JMS.REPORT.QUEUE, it attempts to remove any remaining unconsumed messages sent to non-durable subscribers. If the queue manager's command server is running on any queue beginning SYSTEM.JMS.ND.*, messages are cleared and the queue itself might be deleted. Otherwise, only SYSTEM.JMS.ND.SUBSCRIBER.QUEUE and SYSTEM.JMS.ND.CC.SUBSCRIBER.QUEUE are cleared of messages.
You can use a programming interface to the cleanup routines for use with SUBSTORE(BROKER), through the class com.ibm.mq.jms.Cleanup. Instances of this class have getter/setter methods for each of the connection properties; and also for the cleanup level and interval.
It exposes two methods:
This class allows complete customization of publish/subscribe Cleanup, but it is intended for use by system administration programs rather than application programs.
For more details, refer to Cleanup.
The WebSphere MQ JMS implementation uses report messages from the broker to confirm registration and deregistration commands. These reports are normally consumed by the WebSphere MQ classes for Java Message Service implementation, but under some error conditions, they might remain on the queue. These messages are sent to the SYSTEM.JMS.REPORT.QUEUE queue on the local queue manager.
A Java(TM) application, PSReportDump, is supplied with WebSphere MQ classes for Java Message Service, which dumps the contents of this queue in plain text format. The information can then be analyzed, either by you, or by IBM(R) support staff. You can also use the application to clear the queue of messages after a problem is diagnosed or fixed.
The compiled form of the tool is installed in the <MQ_JAVA_INSTALL_PATH>/bin directory. To invoke the tool, change to this directory, then use the following command:
java -Djava.library.path=library_path PSReportDump [-m queueManager] [-clear]where library_path is the path to the WebSphere MQ Java libraries
(see The WebSphere MQ Java libraries), and:
Output is sent to the screen, or you can redirect it to a file.
If a large number of JMS clients connect directly to a broker running on Windows, and the connections happen almost simultaneously, a java.net.BindException address in use exception might be thrown in response to a TopicConnection call. You can try to avoid this by catching the exception and retrying, or by pacing the connections.
Notices |
Downloads |
Library |
Support |
Feedback
![]() ![]() |
csqzaw1372 |