Chapter 1 Sun Java System Message Queue 3.7 UR1 Release Notes for Microsoft Windows

These release notes contain important information available at the time of release of Sun Java™ System Message Queue 3.7 UR1 (“Message Queue”). New features and enhancements, known issues and limitations, and other information are addressed here. Read this document before you begin using Message Queue.

The most up-to-date version of these release notes can be found at the Sun documentation web site at http://docs.sun.com. Check the web site prior to installing and setting up your software and then periodically thereafter to view the most up-to-date release notes and product documentation.

These release notes contain the following sections:

• About Message Queue 3.7 UR1

• Bugs Fixed in This Release

• Important Information

• Known Issues and Limitations

• Redistributable Files

• Accessibility Features for People With Disabilities

• How to Report Problems and Provide Feedback

• Sun Welcomes Your Comments

• Additional Sun Resources

Third-party URLs are referenced in this document and provide additional, related information.

Sun is not responsible for the availability of third-party web sites mentioned in this document. Sun does not endorse and is not responsible or liable for any content, advertising, products, or other materials that are available on or through such sites or resources. Sun will not be responsible or liable for any actual or alleged damage or loss caused by or in connection with the use of or reliance on any such content, goods, or services that are available on or through such sites or resources.

About Message Queue 3.7 UR1

Sun Java System Message Queue is a full-featured message service that provides reliable, asynchronous messaging conformant to the Java Messaging Specification (JMS) 1.1. In addition, Message Queue provides features that go beyond the JMS specification to meet the needs of large-scale enterprise deployments.

Message Queue 3.7 UR1 is a maintenance release to Message Queue 3.6. It includes bug fixes and a small number of minor enhancements. This section includes the following information:

• What’s New in This Release

• Hardware and Software Requirements

What’s New in This Release

The following sections describe the new features in Message Queue 3.7 UR1:

• Combining Platform and Enterprise Features in One Edition

• Interface Changes to the C-API and C Client Runtime

• Persistent Store Format Changes

Combining Platform and Enterprise Features in One Edition

For streamlined product delivery, the Platform and Enterprise Edition of Sun Java Message Queue have been combined into a single edition beginning with Message Queue 3.7 UR1. This strategy effectively removes the feature restrictions in the stand-alone distribution and should simplify your experience with this product.

Combining editions also aligns Message Queue better with Solaris Enterprise System and provides a perpetual broad-based right to use Enterprise Edition features, with no support, maintenance, or indemnity. As with previous releases, several licensing options are available for support and maintenance services. Message Queue will continue to be packaged with Java Enterprise System and the Application Platform Suite. Please check the online store at http://www.sun.com or consult your sales representative to find an option that best suits your needs. The next table describes the upgrade paths to the new single edition of Message Queue.

Table 1–1 Upgrade Paths for Message Queue 3.7 UR1

Prior Edition	Upgrade Path	Comments
Platform Edition	Sun Java System Message Queue 3.7 UR1	All features are now available to these customers. Without license purchase, no support options are available.
Enterprise Edition	Sun Java System Message Queue 3.7 UR1	No feature changes. A range of licensing and support options are available.
Platform Edition support contracts	Upgrade to Enterprise Edition support contract	Existing support contracts for prior releases of Platform Edition will continue to be renewed. No new Platform Edition contracts will be issued for prior Platform Edition releases.
Enterprise Edition support contracts	No change.	Existing contracts will continue to be renewed. New contracts will be issued.

The following table describes the changes in delivery sources for various Message Queue products.

Table 1–2 Changes in Delivery Sources for Message Queue Products

Product	Prior Delivery Source	New Delivery Source	Comments
Message Queue	Not applicable	Sun Download Center product page	Standalone download. Community support only. No support contracts available.
Message Queue Platform Edition	Sun Download Center through the Message Queue product page	No longer available	Pages will all point to a single edition of Message Queue
Message Queue Enterprise Edition trial (through Platform Edition)	Sun Download Center through the Message Queue product page	Trial license no longer needed	No longer needed
Message Queue Enterprise Edition 90 day Trial (through Java Enterprise System download or DVD)	Java Enterprise System Download Center, prior to version 3 GA (March 2006)	Solaris Enterprise System Download Center	Solaris Enterprise System license. No support options available without product license.
Message Queue Enterprise Edition via SunStore, DVD, individual license, Java Enterprise System license, Suite license, delivered via Java Enterprise System	Java Enterprise System or Suite Download Center, media	Solaris Enterprise System or Suite Download Center, media fulfillment	No change.

Interface Changes to the C-API and C Client Runtime

• New function: MQGetDestinationName()

  MQGetDestinationName (const MQDestinationHandle destinationHandle, MQString * destinationName);

  Use this function to get the name of a destination. The returned destinationName is a copy that the caller is responsible for freeing by calling the MQFreeString() function.

  Parameters

  destinationHandle

  A handle to the destination whose name you want to know.

  destinationName

  The output parameter for the name.

  This function is useful when using the reply-to pattern. You can use the MQGetMessageReplyTo function to obtain a handle to the destination where the message should be sent. You can then use the MQGetDestinationName to get the name of that destination. Having obtained the destination name, you can process messages based on the name.

• New enumerated value: MQ_MESSAGE

  The new MQMessageType, MQ_MESSAGE, enables C clients to exchange JMS messages of type Message with other Message Queue clients that are using both C and Java:

  typedef enum _MQMessageType {MQ_TEXT_MESSAGE = 0, MQ_BYTES_MESSAGE = 1, MQ_MESSAGE = 3, MQ_UNSUPPORTED_MESSAGE = 2} MQMessageType;

  The MQ_MESSAGE type identifies messages that have a header and properties but no message body. You use the MQCreateMessage() function to create a message of this type.

• A new connection property, MQ_UPDATE_RELEASE_PROPERTY, that specifies the update release version for the installed version of Message Queue. Use the MQGetMetaData() function to obtain version information.

Persistent Store Format Changes

Two changes to Message Queue's persistent store format improve performance. One change is to the file store, the other change is to the JDBC store.

• Transaction information in the file store - The format of transaction state information stored in the Message Queue file-based persistent store has been changed to reduce disk I/O and improve the performance of JMS transactions.

• Oracle JDBC Store - In previous versions of Message Queue, the store schema used with Oracle used the LONG RAW data type to store message data. In Oracle 8, Oracle introduced the BLOB data types and deprecated the LONG RAW type. Message Queue 3.7 UR1 switches to the BLOB data type to improve performance and supportability.

Because these changes affect store compatibility, the store version has been changed from 350 to 370. Message Queue 3.7 UR1 supports automatic conversion of the persistent store from the older 200 and 350 versions to the 370 version - both for JDBC and for file-based stores. The first time imqbrokerd starts, if the utility detects an older store it will migrate the store to the new format, leaving the old store behind.

If you should need to roll back this upgrade, you can uninstall Message Queue 3.7 UR1 and then reinstall the version you were previously running. Because the older copy of the store is left intact, the broker can run with the older copy of the store.

Hardware and Software Requirements

Hardware and software requirements for Message Queue are provided in the Sun Java Enterprise System Installation Guide.

Bugs Fixed in This Release

This section describes the bugs fixed in Message Queue 3.7 UR1.

Table 1–3 Fixed Bugs in Message Queue 3.7 UR1

Bug Number	Description
6193884	Message Queue outputs garbage message to syslog in non-C locale.
6251450	ConcurrentModificationException on connectList during cluster shutdown.
6252763	java.nio.BufferOverflowException in java.nio.HeapByteBuffer.putLong/Int.
6260076	First message published after startup is slow with Oracle storage.
6264003	The queue browser shows uncommitted messages.
6260814	Selector processing on JMSXUserID always evaluates to false.
6264003	The queue browser shows uncommitted messages.
6271876	Connection Flow Control does not work properly when closing a consumer with unconsumed messages.
6284769	The QueueBrowser leaks memory even when a new browser is created and closed for each enumeration.
6294767	Message Queue broker needs to set SO_REUSEADDR on the network sockets it opens.
6304043	The broker does not validate that a clientID is not null for shared nondurable subscriptions.
6307056	The txn log is a performance bottleneck.
6320138	Message Queue C API cannot determine the name of a queue from a reply-to header.
6320325	The broker sometimes picks up JDK version 1.4 before JDK version 1.5 on Solaris OS even if both versions are installed.
6321117	Multibroker cluster initialization throws a java.lang.NullPointerException.
6330053	The jmsclient throws a java.lang.NoClassDefFoundError when committing a transaction from the subscriber.
6340250	Support MESSAGE type in C-API.
6351293	Add support for Derby database.
6381693	The JMSRedelivered flag is set to false for messages redelivered to a remote consumer after the consumer's broker restarts.
6388049	Cannot clean up an incomplete XA transaction.
6403968	Add consumer-based flow control protocol to allow load balancing for multiple receivers.
6403958	A broker exception is raised when the dead message queue tries to remove the oldest non-persistent message.
6406862	Broker error “Monitor destination error mq.metrics.destination.queue.Name”.
6415068	Transaction recovery fails in AS 8.1 UR2, the generic resource adapter for JMS Message Queue.
6421781	Support connection to the broker using the following syntax  —b mqtcp://hostName:portNumber/serviceName
6423696	Session.rollback does not actually roll back consumed messages after COMMIT REPLY error.
6314103	Cannot install Message Queue if the directory name includes a space. .
6314088  6392963	Cannot install Message Queue if a directory name is longer than 6 characters. For example, C:\Software\Sun.

Important Information

This section contains the latest information that is not contained in the core product documentation. This section covers the following topics:

• Installation Notes

• Compatibility Issues

• Documentation Updates for Message Queue 3.7 UR1

Installation Notes

Refer to the Sun Java System Message Queue 3.7 UR1 Installation Guide for information about pre-installation instructions, upgrade procedures, and all other information relevant to installing Message Queue as a stand-alone product on the Solaris, Linux, and Windows platforms.

Refer to the Sun Java Enterprise System Installation Guide for information about pre-installation instructions and all other information relevant to installing the Message Queue product bundled with Java Enterprise System on the Solaris, Linux, HPUX, and Windows operating systems.

Refer to the Sun Java Enterprise System Upgrade and Migration Guide for information about upgrade and migration instructions relevant to upgrading to Message Queue as part of the Java Enterprise System on the Solaris, Linux, HPUX, and Windows operating systems.

Compatibility Issues

This section covers compatibility issues in Message Queue 3.7 UR1.

Interface Stability

Message Queue uses many interfaces that could change over time. Appendix B, Stability of Message Queue Interfaces, in Sun Java System Message Queue 3.7 UR1 Administration Guide classifies the interfaces according to their stability. The more stable an interface, the less likely it is to change in subsequent versions of the product.

Issues Related to the Next Major Release of Message Queue

The next major release of Message Queue might introduce changes that make your clients incompatible with that release. This information is provided now to help you to prepare for these changes.

• The locations of individual files installed as part of Sun Java System Message Queue might change. This adjustment could break existing applications that depend on the current location of certain Message Queue files.

• 3.5 and earlier brokers might no longer be able to operate in a cluster with newer brokers.

• In future releases Message Queue clients may not be able to use JDK versions that are earlier than 1.3.

Documentation Updates for Message Queue 3.7 UR1

The following sections describe updates and changes to Message Queue documentation, other than minor corrections and additions.

Installation Guide

The Sun Java System Message Queue 3.7 UR1 Installation Guide, which documents installation information for the stand-alone version of Message Queue, was updated to reflect platform-specific information.

Developer’s Guide for C Clients

The Sun Java System Message Queue 3.7 UR1 Developer’s Guide for C Clients was updated to reflect the addition of the MQGetDestinationName function, the MQ_Message message type, and the connection property MQ_UPDATE_RELEASE_PROPERTY.

Developer's Guide for Java Clients

The Sun Java System Message Queue 3.7 UR1 Developer’s Guide for Java Clients was updated to include information about setting up secure clients, and about how clients should handle exceptions that occur during automatic reconnection.

Administration Guide

The Sun Java System Message Queue 3.7 UR1 Administration Guide was updated to provide information about the broker's database tables and about configuring the broker to use fixed ports.

Known Issues and Limitations

This section contains a list of the known issues with Message Queue 3.7 UR1. The following product areas are covered:

• General Issues

• LDAP User Repository Properties

• Broker Clusters

• Administration/Configuration

• Broker Issues

• Documentation

• Installation Issues

For a list of current bugs, their status, and workaround, Java Developer Connection^SM members should see the Bug Parade page on the Java Developer Connection web site at http://bugs.sun.com/bugdatabase/index.jsp. Please check that page before you report a new bug. Although all Message Queue bugs are not listed, the page is a good starting place if you want to know whether a problem has been reported.

---

Note –

Java Developer Connection membership is free but requires registration. For details about how to become a Java Developer Connection member, see the Sun’s “For Developers” web page.

---

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

General Issues

• A connection service using SSL is currently limited to supporting only self-signed server certificates, that is, host-trusted mode.

• When a JMS client using the HTTP transport terminates abruptly, for example, using Control-C, the broker takes approximately one minute before releasing the client connection and all the associated resources.

  If another instance of the client is started within the one-minute period that tries to use the same ClientID, durable subscription, or queue, a “Client ID is already in use” exception might occur. This exception is just the side effect of the termination process described above. If the client is started after a delay of approximately one minute, no problem should occur.

LDAP User Repository Properties

In Message Queue 3.7 UR1, the example broker configuration for using an LDAP server as a user repository is provided in the comment area in the config.properties . The LDAP user repository example in the default.properties file has been commented out.

If you previously relied on any property value in the example LDAP user repository properties specified in the default.properties file, once you upgrade to Message Queue 3.7 UR1. your JMS application client will receive a security exception when attempting to create a JMS connection.

When your JMS client tries to make a connection to the Message Queue 3.7 UR1 broker, an error appears in the broker log and your JMS client receives the following exception:

SecurityException.
20/Aug/2004:11:16:41 PDT] ERROR [B4064]: Ldap repository ldap property
.uidattr not defined for authentication type 
basic:com.sun.messaging.jmq.auth.LoginException: 
[B4064]: Ldap repository ldap property .uidattr not defined 
for authentication type basic

Workaround Set the broker property imq.user_repository.ldap.uidattr following the instructions in Chapter 7, Managing Security, in Sun Java System Message Queue 3.7 UR1 Administration Guide.

Broker Clusters

The following items relate to the use of broker clusters.

• Only fully-connected broker clusters are supported in this release. Therefore, every broker in a cluster must communicate directly with every other broker in the cluster. If you are connecting brokers using the imqbrokerd -cluster command line argument, ensure that all brokers in the cluster are included.

• A client connected to a broker that is part of a cluster cannot currently use QueueBrowser to browse queues that are located on remote brokers in that cluster. The client can only browse the contents of queues that are located on the broker to which it is directly connected. The client may still send messages to any queue or consume messages from any queue on any broker in the cluster. The limitation only affects browsing.

• If a master broker is not used in a broker cluster, persistent information stored by a broker being added to the cluster is not propagated to other brokers in the cluster.

• In a broker cluster, a broker will queue messages to a remote connection that has not been started (Bug ID 4951010).

  WorkaroundThe messages will be received by the consumer once the connection is started. The messages will be redelivered to another consumer if the consumer’s connection is closed.

Administration/Configuration

The following issues pertain to administration and configuration of Message Queue.

• The imqadmin and imqobjmgr utilities throw an error when the CLASSPATH contains double quotes on Windows machines (Bug ID 5060769)

  Workaround You can ignore this error message. The broker correctly handles notifying consumers of any error. This error does not affect the reliability of the system.

• The -javahome option in all Solaris and Windows scripts does not work if the value provided contains a space (Bug ID 4683029).

  The javahome option is used by Message Queue commands and utilities to specify an alternate Java 2 compatible runtime to use. However, the path name to the alternate Java runtime must not contain spaces. For example:

  Windows: C:/jdk 1.4

  Solaris: /work/java 1.4

  Workaround Install the Java runtime at a location or path that does not contain spaces.

• The imqQueueBrowserMaxMessagesPerRetrieve attribute specifies the maximum number of messages that the client runtime retrieves at one time when browsing the contents of a queue destination. The client application will always get all the messages on the queue. Therefore, the imqQueueBrowserMaxMessagesPerRetrieve attribute affects how the queued messages are divided to be delivered to the client runtime, either in several smaller pieces orfewer large chunks. This attribute does not affect the total messages browsed. Changing the value of this attribute might affect performance, but it will not result in the client application getting a different amount of data (Bug ID 6387631).

Broker Issues

The following issues affect the Message Queue broker.

• HTTPS createQueueConnection occasionally throws an exception on Windows 2000. (Bug ID 4953348).

  Workaround Retry the connection.

• When using Control-C to shut down a broker, transactions might be cleaned up after store is closed (Bug ID 4934446).

  The broker might show the errors message “Store method accessed after the store is closed” if the broker is shut down while messages or transactions are processed.

  Workaround You can ignore this error message. The broker correctly handles notifying consumers of any error. This error does not affect the reliability of the system.

• Consumers are orphaned when a destination is destroyed (Bug ID 5060787).

  Active consumers are orphaned when a destination is destroyed. Once the consumers have been orphaned, they will no longer receive messages even if the destination is re-created.

  Workaround None.

• Message selection using JMSMessageID doesnot work (Bug ID 6196233).

  Change the selector from the following expression

  JMSMessageID = "ID:message-id-string"

  to the following expression

  JMSMessageID IN (’ID:message-id-string’, ’message-id-string’)

Documentation

Message Queue 3.7 UR1 does not include a stand-alone product. For this release, you must install Message Queue using the Java Enterprise System Installer. Consult the Sun Java System Installation Guide for instructions.

• Message Queue menu->Index shows incorrect locations for the product documentation URL and the Read Me First file Bug ID 6515574

  Description Older documentation is displayed when the user selects documentation from the Message Queue entry in the Windows Start menu.

  WorkaroundAccess the documentation from http://docs.sun.com/app/docs/coll/1307.2http://docs.sun.com/app/docs/coll/1307.2.

Installation Issues

• The Add/Remove Programs Control Panel lists Sun Java Enterprise System instead of Message Queue

• The file Config_MQ.txt contains incorrect information. The following items correct some of the errors:

  • The Configure Automatically and Configure Manually options are not available with Message Queue, and no option exists to set the Administrator password

  • The Configure Automatically option installs and starts the Message Queue Broker Windows service automatically.

  • The Configure Manually option enables you to install the Message Queue Broker without starting it as a Windows service.

• The error messages that appear when attempting to install on a disk without sufficient disk space are potentially confusing. For example, "Error: -1603 Fatal error during installation."

• mq/bin was not added to the path during installationBug ID 6515557

  DescriptionThe Message Queue executables can not be found from a Windows command prompt. For example, typing imqcmd will trigger the following error: 'imqcmd' is not recognized as an internal or external command, operable program or batch file.

  Workaround Edit the PATH variable to include install-MQ-directory/bin or run the applications from the install-MQ-directory/bin directory.

• Message Queue Install does not support automated installation of shared components.

  WorkaroundUse JDK version 1.6.0 (SOAP components in 1.6.0) or Install Application Server on Windows which will install SOAP shared components.

Redistributable Files

Sun Java System Message Queue 3.7 UR1 contains the following set of files that you may use and distribute in binary form:

jms.jar	libmqcrt.so (UNIX)
imq.jar	libmqcrt.so (HPUX)
imqxm.jar	mqcrt1.dll (Windows)
fscontext.jar

In addition, you can also redistribute the LICENSE and COPYRIGHT files.

Accessibility Features for People With Disabilities

To obtain accessibility features that have been released since the publishing of this media, consult Section 508 product assessments,available from Sun upon request, to determine which versions are best suited for deploying accessible solutions. Updated versions of applications can be found at http://sun.com/software/javaenterprisesystem/get.html.

For information on Sun’s commitment to accessibility, visit http://sun.com/access.

How to Report Problems and Provide Feedback

If you have problems with Sun Java System Message Queue, contact Sun customer support using one of the following mechanisms:

• Sun Software Support services online at http://www.sun.com/service/sunone/software.

  This site has links to the Knowledge Base, Online Support Center, and Product Tracker, as well as to maintenance programs and support contact numbers.

• The telephone dispatch number associated with your maintenance contract.

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

• Description of the problem, including the situation where the problem occurs and its impact on your operation.

• Machine type, operating system version, and product version, including any patches and other software that might be affecting the problem.

• Detailed steps on the methods you have used to reproduce the problem.

• Any error logs or core dumps.

Message Queue Software Forum

A Sun Java System Message Queue forum is available at the following location:http://swforum.sun.com/jive/forum.jspa?forumID=24

We welcome your participation.

Java Technology Forum

TheJMS forum in the Java Technology Forums might be of interest and is located at: http://forum.java.sun.com

Sun Welcomes Your Comments

Sun is interested in improving its documentation and welcomes your comments and suggestions.

To share your comments, go to http://docs.sun.com and click Send Comments. In the online form, provide the document title and part number. The part number is a seven-digit or nine-digit number that can be found on the title page of the book or at the top of the document. For example, the title of this book is Sun Java System Message Queue 3.7 UR1 Release Notes for Microsoft Windows, and the part number is 819-5693.

Additional Sun Resources

Useful Message Queue information can be found at the following Internet locations:

• Documentation

  http://docs.sun.com/prod/java.sys

• Professional Services

  http://www.sun.com/service/sunps/sunone

• Software Products and Service

  http://www.sun.com/software

• Software Support Services

  http://www.sun.com/service/sunone/software

• Support and Knowledge Base

  http://www.sun.com/service/support/software

• Sun Support and Training Services

  http://training.sun.com

• Consulting and Professional Services

  http://www.sun.com/service/sunps/sunone

• Developer Information

  http://developers.sun.com

• Sun Developer Support Services

  http://www.sun.com/developers/support

• Software Training

  http://www.sun.com/software/training