Release Notes for iPlanet™ Message Queue for Java™ (iMQ)

Version 2.0

Updated June 5, 2001




These release notes contain important information available at the time of the Version 2.0 release of iPlanet Message Queue for Java™ (iMQ). New features and enhancements, known limitations and problems, technical notes, and other information are addressed here. Read this document before you begin using iMQ.

An electronic version of the most up-to-date version of these release notes can be found at the iPlanet documentation web site: http://docs.iplanet.com/docs/manuals/. Check the web site after installing your software and then periodically thereafter to view the most up-to-date release notes.

These release notes contain the following sections:




Java Message Service (JMS) Compliance

iMQ is designed to be compliant with the Java Message Service (JMS) 1.0.2 specification. Because an official Compatibility Test Suite (CTS) for JMS has not yet been released, we are unable to provide verification of JMS 1.0.2 compliance.

Known bugs related to JMS compliance, and their workarounds, are listed in the "Known Bugs" section of this document.




iMQ Documentation Updates

The following documents have been updated from those distributed and installed with the iMQ product. The revisions to the installed documents, discussed below, can be found in updated documents at the iPlanet documentation web site: http://docs.iplanet.com/docs/manuals/.

Installation Guide

The iMQ Installation Guide incorrectly lists several supported products and operating systems:

Operating System

Table 4-1, "Hardware and Software Requirements for Windows," incorrectly lists the following supported operating system: Windows NT 4.0 Service Pack 4.

The correct version is: Windows NT 4.0 Service Pack 5 and 6.

Java Development Kits

Table 1-1, "iMQ 2.0 Product Support Matrix," incorrectly lists the following supported Java Development Kits for iMQ client applications:

The correct platforms are:

Administrator's Guide

The iMQ Administrator's Guide has been revised as follows.

Administration Console Tutorial

A tutorial describing how to use the iMQ Administration Console has been added to the iMQ Administrator's Guide. The Administration Console is a graphical user interface application used to remotely administer an iMQ messaging system, including managing brokers, iMQ administered objects, and messaging applications. The Administration Console combines the capabilities of two command line utilities (JMQ Command and JMQ Object Manager).

HTTP Servlet Setup

The class name of the HTTP Servlet in Step 4 of the "Configuring the Tunnel Servlet" section of Appendix B is given as:

com.sun.messging.jmq.transport.httptunnel.servlet.HTTPTunnelServlet

The correct class name is (note lower case characters):

com.sun.messging.jmq.transport.httptunnel.servlet.HttpTunnelServlet

Miscellaneous property Name Corrections

The names of a number of broker instance configuration properties have been corrected.

Developer's Guide

The iMQ Developer's Guide has been revised to fix a few typographical errors.

Example Applications README

A new version of the Example Applications README file is now available. The README describes the various example applications and how to use them. The new, corrected version replaces the README file installed in the following directory: JMQ_HOME/examples/jms

License File

In the License file that shipped with the iMQ product, Item 3A under "Supplemental Terms and Conditions" incorrectly lists jmq.jar twice.

The correct listing is:

<JMQ_HOME>/lib/jms.jar

<JMQ_HOME>/lib/jmq.jar




What's New in iMQ Version 2.0

For descriptions of these and other new features, see the iMQ Migration Guide.




Known Limitations




Known Bugs

This section contains a listing of the more important bugs known at the time of the iMQ 2.0 release.

For a list of current bugs, their status and workarounds, Java (TM) Developer Connection (TM) members should see the Bug Parade page on the Java Developer Connection web site. Please check that page before you report a new bug. Although not all iMQ bugs are listed here, it is a good starting place if you want to know whether a problem has been reported.

The relevant page is:

http://developer.java.sun.com/developer/index.html



Note

Java Developer Connection membership is free but does require registration for access. Details on how to become a Java Developer Connection member are provided on Sun's "For Developers" web page.



To report a new bug or submit a feature request, send mail to imq-feedback@sun.com.



Table 1    Bug Descriptions 

Bug Number

Details


4407510
 

The jmqcmd and jmqadmin utilities do not currently display temporary destinations in a broker. This makes it impossible for an administrator to monitor or manage these destinations.

Temporary destinations are explicitly created and destroyed (using the JMS API) by client applications that need a destination at which to receive replies to messages sent to other clients. Even though these destinations are maintained by the broker only for the duration of the connection for which they are created, they (like ' normal' destinations) do consume resources.

Workaround: None. The problem will be resolved in a future release. 

4428745
 

A client connecting to a broker over HTTP may not receive notification that the broker has been shutdown if that shutdown happens while the web server is down.

The HTTP servlet maintains connections to the broker across webserver restarts. This prevents a client from realizing that the broker has shutdown until after both the webserver and the broker have been restarted.

Workaround: You should make sure the broker is restarted promptly if there are HTTP clients. You can also set the client's ConnectionFactory property JMQAckTimeout to a non-zero to limit the timeout value when using HTTP tunneling; this will help in situations when the HTTP client waits for replies from the broker. 

442971
 

The broker cannot handle large numbers of consumers with selectors.

The broker internally creates a separate selector parser object for each message consumer with a selector. The space consumed by these objects causes the broker to run out of memory. For example, with the default out of box configuration, a broker can support approximately 2000 consumers with selectors.

Creating large number of consumers without selectors is quite safe.

Workaround: Increase the java heap size (JVM -Xmx argument) for the broker's VM. This can be done using the -vmargs command line argument at broker startup time. If the broker is installed as a Windows NT service, use the jmqsvcadmin command to remove and reinstall the service with the correct -vmargs argument.

Note that increasing the heap size beyond the physical memory size is not very useful and, due to excessive paging, can degrade the system performance drastically. 

4430938
 

You cannot use the Administration Console to add an object with a lookup name that already exists.

The Administration Console does not currently allow you to add an administered object to an object store, using a lookup name that is already in use. This prevents administrators from replacing administered objects that exist in the object store.

Workaround:

  • Enter a lookup name that does not already exist, or

  • Delete the existing administered object; then add the new one, or

  • Use the command line utility jmqobjmgr to add the object.

 

4430941
 

Neither the Administration Console nor the jmqobjmgr utility lists objects of unknown type.

An object store is used to store iMQ administered objects. It is accessed using the Java Naming and Directory Interface (JNDI).You can use this API or interface to store any kind of object (not just iMQ administered objects). Additionally, LDAP Directory Servers generally allow you to store various types of objects. It is possible for an object store to contain a variety of objects—some of which are not relevant to iMQ.

The iMQ administration tools (jmqobjmgr and the Administration Console) currently only list or display objects that are recognizable to iMQ 2.0 (i.e. the iMQ administered objects). This may prevent administrators from realizing that there are other objects located in the object store. This will cause an error if you attempt to add a new object to the object store and that object has a lookup name that is already used by an unlisted object.

The administration tools provided with the LDAP server should provide a means to view all the objects in the object store.

Workaround: none; the problem will be resolved in a future release. 

443138
 

Message selection does not work properly if the selector string contains string literals that contain Japanese or other multi-byte characters. For example,

String selector = "<propertyname> = '\u033e\u033f'";

and a String property <propertyname> is set on the message:

msg.setStringProperty("<propertyname>", "\u033e\u033f");

Workaround: When specifying the selector string at the time a receiver or subscriber is created, replace the unicode escape notation "\u" with the notation "\\u", as shown in the example below:

String selector = "<propertyname> = '\\u033e\\u033f'"; 

4431924
 

Multiple modal dialogs may cause a deadlock.

Multiple modal dialogs may be visible in the Administration Console: some dialogs are displayed as a result of user actions; others are displayed when a broker connection is lost. When multiple modal dialogs appear, the Administration Console is locked and you cannot dismiss any of the dialogs.

Workaround: Close the top-most dialog using the window manager controls: the window close button (X) at the upper right corner on Windows or the Close window manager menu item on Solaris. 

4440100
 

The Administration Console does not handle request timeouts gracefully.

The Administration Console (jmqadmin) manages iMQ brokers by sending administrative messages and waits for status reply messages back from the broker. These status reply messages are used to determine whether the administration task requested was performed successfully.

Sometimes, these status reply messages may take longer than usual to arrive at the Administration Console. This may be because the broker is busy or because of a slow connection. When a status reply message is not detected after a certain period of time, the Administration Console times out and displays a dialog containing the text: Timed out waiting for status message from the broker. Will continue waiting for status.

Unfortunately, after you dismiss the above dialog, the Administration Console will be in an inconsistent state. The console window does not repaint properly and an exception is displayed. This problem will be addressed in a future release.

Workaround:

  • Use jmqcmd instead of the Administration Console to perform broker administration tasks that take a long time to complete.

  • Quit the Administration Console and then restart it.

 

4440533
 

The port number property does not apply to the httpjms service. Using the Administration Console or the jmqcmd utility to change the port number for this service will not have any effect.

When iMQ client applications communicate with the broker using HTTP protocol instead of direct TCP connections, they communicate with the broker via a web server (rather than directly using a connection service). Because of this, changing the port number property of the httpjms service does not have any effect.

You can use the Administration Console or the jmqcmd utility to configure connection services on the broker. These include a statically assigned port number for a service, the minimum threads, and the maximum threads allocated for the service. Although all properties are shown to be configurable for all services, the one exception is described above.

Workaround: not applicable. 

4449354
 

In extremely rare cases, calling the methods Connection.stop, Connection.start, and Connection.close at the same time as calling the methods Session.recover and Session.rollback (in separate threads) may result in an unexpected message redelivery order.

Workaround: make sure your calls to the Connection... and Session... methods specified above are serialized either by using the same thread or by using synchronization. 

4450020
 

If there are no properties set on the message when it is sent and the consumer uses selectors, the message is not delivered regardless of whether the selector evaluates to true or false. Note that JMS header fields are not included in the set of message properties.

For example, setting JMSPriority and consuming with a selector of the form "MyPropertyName IS NULL" should result in the message being received if MyPropertyName was not part of the message properties. However, since there are no properties set on the message, the message is not delivered.

Workaround: If the consumer uses selectors, make sure that the sent messages always set a property. Use a bogus property is needed; for example, Message.setIntProperty("Dummy",0);  

4450573
 

Online help causes the Administration Console to hang on Windows platforms.

When the online help is invoked from a dialog in the Administration Console, it may hang. You will not be able to scroll down in the help window or even to dismiss the help dialog. This problem occurs only on the Windows platform and only when the online help is invoked from a dialog, for example, the Add Object Store dialog. The online help invoked from the Help > Overview menu item does not have this problem.

Workaround: To dismiss the hung help dialog, hit the Cancel button on the original Administration Console dialog from where the help was invoked; this dialog should not be hung. This should dismiss both dialogs.

Because the online help is useless now when invoked from the dialog, use the Help > Overview menu item to launch help, and then navigate to the relevant help information from there. 

4451831
 

Invoking a dialog more than once using the Administration Console on the Linux platform causes a hang.

After attempting to call a dialog more than once, the dialog does not appear and the console is hung. The dialog is actually present on the Linux desktop--but in an iconified state. You should be able to locate the iconified dialog in the GNOME panel at the bottom of the screen. Clicking on it should show the previously hidden dialog.

This is due to a problem in JRE version 1.3. This problem will be addressed in the next version of the JRE.

Workaround: Locate the iconified dialog in the GNOME panel at the bottom of the screen. Click on it to show the previously hidden dialog. 




Functionality Marked as Optional in JMS 1.0.2

The JMS 1.0.2 specification indicates certain items that are optional-- each JMS provider (vendor) chooses whether or not to implement them. The iMQ product handling of each of these optional items is indicated below:



Table 2    Optional JMS 1.0.2 Functionality 

Section in JMS Specification

Description and iMQ Handling

3.4.3
JMSMessageID 

"Since message ID's take some effort to create and increase a message's size, some JMS providers may be able to optimize message overhead if they are given a hint that message ID is not used by an application. JMS Message Producer provides a hint to disable message ID."

iMQ implementation: Product does not disable Message ID generation (any setDisableMessageID() call in MessageProducer is ignored). All messages will contain a valid MessageID value. 

3.4.12
Overriding Message Header Fields 

"JMS does not define specifically how an administrator overrides these header field values. A JMS provider is not required to support this administrative option."

iMQ implementation: The iMQ product does not support the administrative override of the values in message header fields. 

3.5.9
JMS Defined Properties 

"JMS Reserves the 'JMSX' Property name prefix for JMS defined properties."

"Unless noted otherwise, support for these properties is optional."

iMQ implementation: The JMSX properties defined by the JMS 1.0.2 specification are supported in the iMQ product. 

3.5.10
Provider-specific Properties 

"JMS reserves the 'JMS_<vendor_name>' property name prefix for provider-specific properties."

iMQ implementation: The purpose of the provider-specific properties is to provide special features needed to support JMS use with provider-native clients. They should not be used for JMS to JMS messaging."

iMQ 2.0 does not use provider-specific properties. 

4.4.8
Distributed Transactions 

"JMS does not require that a provider support distributed transactions."

iMQ implementation: Distributed transactions are not supported in this release of the iMQ product. 

4.4.9
Multiple Sessions 

"For PTP <point-to-point distribution model>, JMS does not specify the semantics of concurrent QueueReceivers for the same queue; however, JMS does not prohibit a provider from supporting this." See section 5.8 of the JMS specification for more information.

iMQ implementation: The iMQ implementation supports three queue delivery policies: Failover, Round Robin, and Single (default). For more information, refer to the iMQ Administrator's Guide.

The Single queue delivery policy is equivalent to the JMQ 1.1 behavior. 




Technical Notes

Increasing File Descriptors to Improve Performance

The speed of storing messages in the default file-based persistence is affected by the number of file descriptors available for use by the file store. A large number of descriptors will allow the system to process large numbers of persistent messages faster.

To improve performance for performance testing or deployment, administrators should increase the maximum number of file descriptors available for an application and then increase the size of the shared file descriptor pool by updating the value of the property:

jmq.broker.file.message.fdpool.limit

Securing Persistent Data

The iMQ broker uses a persistent store that can contain, among other information, message files that are being temporarily stored. Since these messages might contain proprietary information, it is recommended that the data store be secured against unauthorized access.

An iMQ broker can use either the built-in or plugged-in persistence.

Built-in Persistent Store

A broker using built-in persistence writes persistent data to a flat file data store located at:

JMQ_VARHOME/stores/brokerName/filestore/

where brokerName is a name identifying the broker instance.

The brokerName/filestore/ directory is created when the broker instance is started for the first time. The procedure for securing this directory depends on the operating system on which the broker is running.

Solaris and Linux.

The permissions on the JMQ_VARHOME/stores/brokerName/filestore/ directory depend on the umask of the user that started the broker instance. Hence, permission to start a broker instance and to read its persistent files can be restricted by appropriately setting the umask. Alternatively, an administrator (superuser) can secure persistent data by setting the permissions on the JMQ_VARHOME/stores directory to 700.

Windows NT.

The permissions on the JMQ_VARHOME/stores/brokerName/filestore/ directory can be set only if you are using the NTFS file system (and not the FAT file system). To change permissions, log in as the user that started the broker instance (or as Administrator), select the JMQ_VARHOME/stores/brokerName/ directory in the NT Explorer, and open the properties dialog for the folder. If you are using an NTFS file system, there will be a Security tab at the top of the dialog. Open the Permissions dialog and check the Replace Permissions on Subdirectories and Replace Permissions on Existing Files. Set the permissions appropriately.

Plugged-in Persistent Store

A broker using plugged-in persistence writes persistent data to a JDBC-compliant database.

For a database managed by a database server (for example, an Oracle database), it is recommended that you create a user name and password to access the iMQ database tables (tables whose names start with "JMQ"). If the database does not allow individual tables to be protected, create a dedicated database to be used only by iMQ brokers. See the database vendor for documentation on how to create user name/password access.

The user name and password required to open a database connection by a broker can be provided as broker configuration properties. However it is more secure to provide them as command line options when starting up the broker (see iMQ Administrator's Guide, Appendix A, "Setting Up Plugged-in Persistence").

For an embedded database that is accessed directly by the iMQ broker via the database's JDBC driver (for example, a Cloudscape database), security is usually provided by setting file permissions (as described in "Built-in Persistent Store," above) on the directory where the persistent data will be stored. To ensure that the database is readable and writable by both the broker and the jmqdbmgr utility, however, both should be run by the same user.

Clock Synchronization Recommended

It is recommended that you synchronize the clocks on all hosts interacting with the iMQ system. This is particularly important if you are using message expiration (TimeToLive). Failure to synchronize the hosts' clocks may result in TimeToLive not working as expected (messages may not be delivered).

In the Solaris operating environment, you can issue the rdate command on a local host to synchronize with remote host. (You must be superuser--that is, root--to run this command.) For example, the following command synchronizes the local host (call it Host 2) with remote host Host1:

# rdate Host1

On Linux the command is similar, but you must provide the -s option:

# rdate -s Host1

On Windows platforms, you can issue the net command with the time subcommand to synchronize your local host with a remote host. For example, the following command synchronizes the local host (call it Host 2) with remote host Host1:

net time \\Host1 /set

JAR Files for Client Applications

Building and running a JMS client application requires jndi.jar (JNDI) as well as jmq.jar and jms.jar to be in your classpath setting. The jndi.jar file is required even if you are not directly using JNDI because it is referenced through the Destination and ConnectionFactory classes. These JAR files can be found in the JMQ_HOME/lib directory.

If you are using JNDI, in addition to the above, you must also include providerutil.jar plus either fscontext.jar (if you are using the file-system context) or ldap.jar (if you are using the LDAP context).

Out of Memory Errors

If you are running a client application that deals with large messages or many small messages, it may encounter OutOfMemoryError errors. The client runtime does not have a memory leak--it just has insufficient memory to copy the messages off the network and deliver them to your client.

To eliminate these OutofMemoryError errors, increase the maximum Java heap size. You can do this by passing the appropriate command line option to the java or jre command.

On JDK1.1.X, use the -mx option. For example:

java -mx64m MyClass

On Java2 (formerly code-named "JDK 1.22"), use the -Xmx option. For example:

java -Xmx128m MyClass

In JDK1.1.X, the default maximum heap size was only 16MB. In Java2, the default was increased to 64MB. Therefore, this problem is more likely to be seen when running against JDK1.1.X than when running against Java2.

Y2K Information

For full Y2K compliance, it is necessary to run iMQ 2.0 with a Y2K-compliant JDK (or JRE) and a Y2K-compliant operating system.



JDK

Up-to-date versions of JDK 1.1.8 and Java 2 (formerly code-named "JDK 1.22") are Y2K-compliant.

Operating System

On Solaris, up-to-date versions of 2.6, Solaris 7, and Solaris 8 are Y2K-compliant.



(For other operating systems, check the operating system vendor's website for information on Y2K-compliance.)

By "up-to-date" it is meant that the JDK or operating system in question is used in conjunction with the most current Y2K-patches applicable to that version. Y2K patches for Sun products can be found at:

http://www.sun.com/y2000/

OS-Defined Connection Limitations on Clients and Brokers

On the Solaris and Linux platforms, the shell in which the client or broker is running places a soft limit on the number of file descriptors that a client can use. In the iMQ system, each connection a client makes, or each connection a broker accepts, uses one of these file descriptors. As a result, you cannot have a broker or client running with more than 256 connections on Solaris or 1024 on Linux without changing this limit. (The number is actually slightly lower than that due to a few file descriptors that are used for other purposes.)

To change this limit, see the ulimit man page. The limit needs to be changed in each shell in which a client or broker will be executing.




How to Report Problems

To report a problem, send mail to imq-feedback@sun.com.

If you have a support contract and you have problems with iMQ, contact iPlanet customer support using one of the following mechanisms:

So that we can best assist you in resolving problems, please have the following information available when you contact support:




For More Information

Discussion Forum

A discussion forum is available for iMQ customers. It provides a place for customers to exchange ideas on iMQ-related topics and share problem-solving tips and techniques.

To subscribe to the jmq-interest list, send email to listserv@java.sun.com and include a message like the following in the message body. Please supply the appropriate data for the first and last name.

subscribe jmq-interest firstname lastname

To unsubscribe to the list, send email to listserv@java.sun.com and include in the message body:

signoff jmq-interest



Note

The jmq-interest forum is meant for general iMQ issues. For specific questions about iMQ 2.0, send your questions to imq-feedback@sun.com.



iPlanet Information

Useful iPlanet information can be found at the following Internet locations:

Use of iPlanet Message Queue for Java is subject to the terms described in the license agreement accompanying it.
Copyright © 2001 Sun Microsystems, Inc. Some preexisting portions Copyright © 2000 Netscape Communications Corp. All rights reserved.

Last Updated June 05, 2001