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

Version 2.0, Service Pack 1

Updated August 24, 2001




These release notes contain important information available at the time of the Version 2.0, Service Pack 1 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 with the iMQ 2.0 product. The revised documents are installed with the Service Pack and also can be found in updated documents at the iPlanet documentation web site: http://docs.iplanet.com/docs/manuals/.

Installation Guides

The iMQ 2.0, Service Pack 1 product includes two installation guides: an updated iMQ Installation Guide and a special Service Pack Installation Guide, describing how to install the Service Pack. Once you have installed the iMQ 2.0 product using the iMQ Installation Guide, follow the instructions in the Service Pack Installation Guide to install the Service Pack.

Administrator's Guide

The iMQ Administrator's Guide has been revised to clarify a few conceptual points and to correct minor technical and typographical errors. Appendix B, HTTP Support, in particular, has been revised to clarify the steps needed to access a broker using HTTP connections.

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, Service Pack 1

Service Pack 1 Compared to iMQ Version 2.0

The 2.0 Service Pack 1 is 100% compatible with iMQ 2.0 in all respects. For example an iMQ 2.0 client can talk to a Service Pack 1 broker. A Service Pack 1 client can talk to a iMQ 2.0 broker. Service Pack 1 clients can use iMQ 2.0 admin objects. iMQ 2.0 and Service Pack 1 brokers can be part of the same cluster.

Service Pack 1 includes the following enhancements to iMQ 2.0:

iMQ Version 2.0 Compared to JMQ 1.1

The iMQ 2.0 product includes the following changes to JMQ 1.1:

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




Known Limitations

The limitations described below apply to both iMQ 2.0 and to the Service Pack 1 release.




Bugs Fixed in Service Pack 1

Below is a short description of the most important bugs fixed in Service Pack 1. For more details about any of these bugs they can view the complete report at the Java Developer Connection site:

http://developer.java.sun.com/developer/bugParade

Fixed Broker-related Bugs:



Table 1    Fixed Broker-related Bugs

Bug Number

Description


4429719
 

Broker cannot handle large numbers of consumers with selectors 

4423900
 

Broker should automatically swap messages if out of memory 

4431858
 

Broker generates lots of WARNINGS for Non-existent Destination after reset 

4448847
 

Broker log files should use proper EOL termination on Windows 

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 

4450862
 

Temporary destinations not marked as temporary in clustered environment 

4451545
 

Temporary dest delete not propagated to other brokers in cluster environment 

4450006
 

Broker performance degrades with 10000 destinations 

4457339
 

Cluster protocol performance improvement. 

4461531
 

Durable subscribers not destroyed when the associated topic is destroyed 

4486679
 

Linux : service becomes unresponsive if port number is changed 

4495086
 

Broker gets StreamCorruptedError under heavy connection load in a single process 

Fixed Administration-related Bugs:



Table 2    Fixed Administration-related Bugs

Bug Number

Description


4392616
 

jmqobjmgr/jmqcmd: attribute lists not sorted 

4428775
 

Administration Console (jmqadmin): refresh button should refresh what is displayed, not what's selected 

4430938
 

Administration Console (jmqadmin): cannot add an object with a lookup name that already exists 

4433991
 

version of broker should be visible from jmqadmin 

4440100
 

Administration Console (jmqadmin): does not handle request timeouts gracefully 

4432483
 

jmqcmd, jmqadmin: setting admin max threads = 0 is allowed & hangs admin 

4449789
 

Administration Console (jmqadmin): typo in online help - QueueBrokers should be QueueBrowsers 

4450573
 

Online help causes the Administration Console (jmqadmin) to hang on Windows platforms 

4454981
 

Administration Console (jmqadmin): service/destination lists are not sorted 

4458564
 

jmqusermgr: user list displayed is not sorted 

Fixed Client-related Bugs:



Table 3    Fixed Client-related Bugs

Bug Number

Description


4450222
 

JMS API: gives no warning if we do this: setJMSDeliveryMode(1) 

4454097
 

NullPointerException in client when jmqcmd is used to restart broker on Linux 

4457272
 

Client runtime size grows disproportionately large with selector consumers 

4465177
 

broker not delivering message if connection started right after createconnection 

4473928
 

JMSMessageID values don't start with the prefix 'ID:' 

4485054
 

com.sun.messaging.BasicTopic.equals() works incorrectly 

4495095
 

TopicSubscriber.getTopic() returns null for durable subscribers 




Known Bugs

This section contains a listing of the more important bugs known at the time of the iMQ 2.0, Service Pack 1 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 4    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. 

4422136
 

This is a bug in the JavaHelp system which the iMQ administration Console uses.

The bug prevents the user from dismissing a dialog using the window manager menu (e.g. the close menu item) when the JavaHelp viewer is visible. A NullPointerException is also seen.

Workaround: Dismiss the dialog using the Cancel button instead of the window manager menu. 

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. 

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. 

4431383
 

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. 

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. 

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. 

4487650
 

The wrong port number for a service may be seen after the port is updated on Linux.

The port number for a service can not be dynamically updated on Linux (because of a JDK bug). When you attempt to update the service using jmqcmd, the command will fail with the following error: [B3109]:Cannot update service port number dynamically. The change will take effect after a broker restart. However, any future queries of the service will show the future port number (which will take affect after restart) not the actual port number of the service.

Workaround: Restart the broker after changing the port number 

4487661
 

On Linux, changing the portmapper port will not immediately take affect.

A JDK bug on Linux prevents the broker from receiving immediate notification that the old socket used by the portmapper has been closed. Once a connection is attempted to the original port, the broker will received notification that the old port is closed and correctly configure the system. Until this notification is received, the new port will not respond to requests

Workaround: After changing the portmapper port, query the broker on the old port number, for example:

jmqcmd query bkr -b host:old broker port

After this query, the broker will respond on the new port. 

4488580
 

jmqcmd/jmqobjmgr: -v does not show patch information on Windows.

When the -v option is used with jmqbroker (and most of the commands/utilities in iMQ), the release and patch information is displayed. The exception to this is jmqcmd and jmqobjmgr on the Windows platform, where the patch information is not displayed.

This problem will be addressed in a future release.

Workaround: None. 

4495379
 

jmqcmd: When you create a queue and topic with the same name, only one is listed.

iMQ Command (jmqcmd) can be used to create a both a topic and a queue destination with the same name. This is done as follows:

jmqcmd create dst -n foo -t t ...

jmqcmd create dst -n foo -t q ...

A problem was introduced in Service Pack 1 in which, after doing the above, the broker destinations are listed using jmqcmd, only one of the 2 destinations is shown.

The underlying problem is not in the broker (which should have the relevant destinations properly created), but is in iMQ Command (jmqcmd). This problem will be addressed in a future release.

Workaround: Use the Administration Console (jmqadmin). 




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 5    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

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 file descriptors that are used for other purposes, such as for file-based persistence.)

To change this limit, see the ulimit man page or the instructions under "Increasing File Descriptors to Improve File-based Persistence Performance," below. The limit needs to be changed in each shell in which a client or broker will be executing.

Increasing File Descriptors to Improve File-based Persistence Performance

On the Solaris and Linux platforms, 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. (Windows does not have a file descriptor limit.) 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 to an application (in this case, the broker process) and then increase the size of the shared file descriptor pool used by the broker by updating the value of the property:

jmq.persist.file.message.fdpool.limit

The value of this property must be less than the maximum number of file descriptors available on your system.

On Solaris, for example, you can increase the file descriptor limits using the ulimit command. Processes inherit system limits from their parent (login) shell. On Solaris, there is a "hard" limit and a "soft" limit. For a non-root user, the number of file descriptors for an application cannot exceed the soft limit, which, in turn, cannot exceed the hard limit.

To check the current file descriptor limits:

Hard limit: $ ulimit -Hn

Soft limit: $ ulimit -n

To change the file descriptor limits for "root" user:

# ulimit -Hn unlimited

# ulimit -n unlimited

After this, any process created from this shell will be able to open unlimited file descriptors. So it is safe to run the jmqbroker command at this point.

To change the file descriptor limit for non-root user:

$ ulimit -Hn number1

$ ulimit -n number2

where number1 is less than 1024, and number2 is less than number1.

If 1024 is not enough, you have the following options:

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/




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 August 24, 2001