Sun GlassFish Message Queue 4.4 Release Notes

Chapter 1 Release Notes

Version 4.4

Part Number 821-0025

These release notes contain important information available at the time of release of Sun GlassFish Message Queue 4.4. New features and enhancements, known issues and limitations, and other information are addressed here. Read this document before you begin using Message Queue 4.4.

These release notes also contain information about the 4.3, 4.2, 4.1, and 4.0 releases of Message Queue. For example, see New Features in Message Queue 4.2, New Features in Message Queue 4.1, and New Features in Message Queue 4.0, respectively, for information about features introduced in those releases.

The most up-to-date version of these release notes can be found at the Sun GlassFish Message Queue documentation web site, http://docs.sun.com/coll/1307.7. 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:

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.

Release Notes Revision History

The following table lists the dates for all 4.x releases of the Message Queue product and describes the changes in this document associated with each release.

Table 1–1 Revision History

Date 

Description of Changes 

December 2009 

Second release of this document for Message Queue 4.4. Corrects errors and omissions. 

October 2009 

Release of this document for Message Queue 4.4. Adds new features for this release. 

May 2009 

Initial release of this document for Message Queue 4.4 Beta. Adds new features for this release. 

December 2008 

Release of this document for Message Queue 4.3. Adds new features for this release. 

August 2008 

Release of this document for Message Queue 4.2. Adds new features for this release. 

September 2007 

Third release of this document for Message Queue 4.1. Adds description of support for Java Enterprise System Monitoring Framework, fixed C ports, bug fixes, and other features. 

April 2007 

Second release of this document for Message Queue 4.1 Beta. Adds high availability feature. 

January 2007 

Initial release of this document for Message Queue 4.1 Beta. Adds description of JAAS support. 

May 2006 

Initial release of this document for Message Queue 4.0. 

About Message Queue 4.4

Sun GlassFish Message Queue is a full-featured message service that provides reliable, asynchronous messaging in conformance with 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 4.4 is a minor release created to participate in the 2.1.1 release of Sun GlassFish Application Server. As a consequence, no separately downloadable, installable distribution of Message Queue 4.4 is available.

Message Queue 4.4 Supported Platforms and Components

This section covers the following topics regarding Message Queue 4.4 system requirements:

Operating System Platform Support

Message Queue 4.4 is supported on Solaris, Linux, Windows, and AIX operating system platforms. Table 1–2 shows the supported versions of each of these platforms. For the hardware requirements of each platform see the Sun Java System Message Queue 4.3 Installation Guide

Table 1–2 Supported Platform Versions

Platform 

Supported Versions 

Solaris 

Solaris 9 (SunOS 5.9), all updates (SPARC, x86)

Solaris 10 (SunOS 5.10), all updates (SPARC, x86, x64)

OpenSolaris 

OpenSolaris 2008.11 (x86, x64)

OpenSolaris 2009.06 (x86, x64)

Linux 

Red Hat Enterprise Linux Advanced Server 4.0, 5.0, all updates, 32– and 64–bit versions (x86, x64)

Red Hat Enterprise Linux Enterprise Server 4.0, 5.0, all updates, 32– and 64–bit versions (x86, x64)

AIX 

AIX 6.1 

Windows 

Windows Vista 

Windows XP Professional, SP2 (x86) [No Home, Tablet PC, or Media Center Edition support]

Windows Server 2003 Standard and Enterprise Editions, SP2, 32– and 64–bit versions (x86, x64) [No Web or Small Business Server Edition support]

Windows Server 2008 Standard and Enterprise Editions, SP2, 32– and 64–bit versions (x86, x64)

System Virtualization Support

System virtualization is a technology that enables multiple operating system (OS) instances to execute independently on shared hardware. Functionally, software deployed to an OS hosted in a virtualized environment is generally unaware that the underlying platform has been virtualized. Sun performs testing of its Sun Java System products on select system virtualization and OS combinations to help validate that the Sun Java System products continue to function on properly sized and configured virtualized environments as they do on non-virtualized systems. For information about Sun support for Sun Java System products in virtualized environments, see http://download.oracle.com/820-4651.

Component Dependencies

In addition to platform-specific requirements, Message Queue 4.4 also depends on certain basic components that must be installed in order to develop and run Message Queue clients. Table 1–3 describes these components. Other versions or vendor implementations can also be used, but they are untested by Sun Microsystems and therefore not officially supported.

Table 1–3 Required Support Components

Component 

Supports 

Supported Versions [Sun Microsystems production versions only]

Java Runtime Environment (JRE)

Message Queue broker and administration tools 

J2SETM Runtime Environment 1.5.0 or later

JavaTM SE Runtime Environment1.6.0

Java Software Development Kit (JDK), Standard Edition

Java client development and deployment 

J2SE Development Kit 1.5.0 or later 

Java SE Development Kit 1.6.0. Note that JMX requires version 1.6.0_10 or later.

Table 1–4 shows additional components that you can install to provide additional support for Message Queue clients. You may not need all of the components listed: for example, if you are not writing a C client, you will not need the C compiler, C++ runtime library, NSPR, or NSS.

Table 1–4 Optional Support Components

Component 

Supports 

Supported Versions 

Application server 

HTTP/HTTPS

Sun GlassFish Application Server Enterprise Edition, Version 9.1.1  

Sun GlassFish Enterprise Server v2.1, v2.1.1 

Web server 

HTTP/HTTPS

Sun GlassFish Web Server Enterprise Edition, Version 7.0, Update 3 

Database 

JDBC-based data store 

HADB, Versions 4.4.3, 4.5, 4.6

Java DB (Apache Derby), Version 10.4

MySQL Community/Enterprise Edition, Version 5.1 

Oracle 9.2i, 10g, and 11g 

postgreSQL, Version 8.1 


Note –

The PointBase database is no longer supported.


Highly-available database 

High-availability broker clusters 

HADB, Versions 4.4.3, 4.5, 4.6

MySQL Cluster Edition, Version 5.1.39–ndb–7.0.9 

Oracle 10g and 11g 

Lightweight Directory Access Protocol (LDAP) directory server

Message Queue user repository and administered objects 

Sun GlassFish Directory Server, Version 6.0 

Java Naming and Directory Interface (JNDI)

Administered object support and LDAP user repository

JNDI Version 1.2.1

LDAP Service Provider, Version 1.2.2

File System Service Provider, Version 1.2 Beta 3 [Administered object support only; supported for development and testing, but not for deployment in a production environment]

C Compiler and compatible C++ runtime library 

Message Queue C clients 

Solaris: Sun Studio, Version 12 or later, C++ compiler with standard mode and C compiler

Linux: gcc/g++, Version 3.4.6

Windows: Microsoft Windows Visual Studio, Version 2008 SP1

Netscape Portable Runtime (NSPR)

Message Queue C clients 

Version 4.7 

Network Security Services (NSS)

Message Queue C clients 

Version 3.12.3 

New Features in Message Queue 4.4 and Recent Releases

The new features in Message Queue 4.4 and previous releases in the Message Queue 4.x family are described in the following sections:

New Features in Message Queue 4.4

Message Queue 4.4 is a minor release that includes a number of feature enhancements and bug fixes. This section describes the new features included in this release:

JMS Bridge Service

Because the JMS specification does not define a wire protocol for communication between brokers and clients, each JMS provider (including Message Queue) has defined and uses its own propriety protocol. This situation has led to non-interoperability across JMS providers.

The JMS bridge service in Message Queue 4.4 closes this gap by enabling a Message Queue broker to map its destinations to destinations in external JMS providers. This mapping effectively allows the Message Queue broker to communicate with clients of the external JMS provider.

The JMS bridge service supports mapping destinations in external JMS providers that:

Many open source and commercial JMS providers meet these requirements, which makes the JMS bridge service an effective way to integrate Message Queue into an existing messaging environment that employs other JMS providers.

For more information about the JMS bridge service see:

STOMP Bridge Service

As mentioned earlier, the JMS specification does not define a wire protocol for communication between brokers and clients. The STOMP (Streaming Text Oriented Messaging Protocol) open source project at http://stomp.codehaus.org defines a simple wire protocol that clients written in any language can use to communicate with any messaging provider that supports the STOMP protocol.

Message Queue 4.4 provides support for the STOMP protocol through the STOMP bridge service. This service enables a Message Queue broker communicate with STOMP clients.

For more information about the STOMP bridge service see:

Additional Enhancements

The following additional enhancements are also provided in Message Queue 4.4:

New Universal Message Service (UMS) Functions

The UMS now provides functions that use HTTP GET to offer several services:

For information about these new features, see Query and utility functions using HTTP GET in https://mq.dev.java.net/4.4-content/imqums/protocol.html.

For an overview of UMS, see Universal Message Service (UMS). For documentation of the UMS API, see https://mq.dev.java.net/4.4-content/imqums/protocol.html. For programming examples in several languages, see https://mq.dev.java.net/4.4-content/imqums/examples/README.html.

IPS Package Support

Message Queue is now packaged for distribution using the open source Image Packaging System (IPS), also known as the pkg(5) system. This packaging method has been added in order for Message Queue to integrate with Sun GlassFish Enterprise Server 2.1.1.

Audit Logging Feature Reinstated

Message Queue 3.7 provided an audit logging feature that was removed in Message Queue 4.0. This feature has been reinstated in Message Queue 4.4. For information about this feature, see Audit Logging in Sun GlassFish Message Queue 4.4 Administration Guide.

New Features in Message Queue 4.3

Message Queue 4.3 was a minor release that included a number of feature enhancements and bug fixes. This section describes the new features included in this release:

Universal Message Service (UMS)

Message Queue 4.3 introduces a new universal messaging service (UMS) and messaging API that provides access to Message Queue from any http-enabled device. As a result, almost any application can communicate with any other application and benefit from the reliability and guaranteed delivery of JMS messaging. In addition, the UMS provides enhanced scalability for JMS messaging, allowing the number of messaging clients to reach internet-scale proportions.

Architecture

The basic UMS architecture is shown in the following figure:

Figure 1–1 UMS Architecture

Illustration showing that the UMS as a gateway between
Non-JMS clients and a JMS provider.

The UMS, which runs in a web server, is language neutral and platform independent. The UMS serves as a gateway between any non-JMS client application and a JMS provider. It receives messages sent using the UMS API, transforms them into JMS messages, and produces them to destinations in the JMS provider by way of the provider's native protocol. Similarly, it retrieves messages from destinations in the JMS provider, transforms them into text or SOAP messages, and sends the messages to non-JMS clients as requested by the clients through the UMS API.

The simple, language-independent, protocol-based UMS API supports both Web-based and non-Web-based applications, and can be used with both scripting and programming languages. The API is offered in two styles: a simple messaging API that uses a Representational State Transfer (REST)-style protocol, and an XML messaging API that embeds the protocol in a SOAP message header. In both cases, however, the API requires only a single http request to send or receive a message.

The simplicity and flexibility of the UMS API means that AJAX, .NET, Python, C, Java, and many other applications can send text message and/or SOAP (with attachment) messages to JMS destinations or receive messages from JMS destinations. For example, Python applications can communicate with .NET applications, iPhone can communicate with Java applications, and so forth.

For Message Queue 4.3, the UMS supports only Message Queue as a JMS provider.

Additional Features

The UMS serves as more than the simple gateway described above. It supports stateful as well as stateless client sessions. If requested by the client, the UMS will maintain session state for the client application across multiple service requests. The UMS can use container-managed authentication, or be configured to authenticate clients with the Message Queue broker, or both. The UMS also supports transactions, enabling client applications to commit or roll back multiple service requests as a single atomic unit.

Because the UMS can support a large number of clients on a single connection to the Message Queue broker, it eases the load on the broker's connection services, allowing for maximum scalability. In addition, UMS capacity can be increased by horizontal scaling, allowing for internet-scale messaging loads.

On the client side, because of the simplicity of the protocol-based UMS API, no client libraries are required. As a result, the API can be extended in the future to implement additional JMS features without any need to upgrade client applications.

Using the UMS

To use the UMS, you deploy the UMS into a web container that supports Servlet 2.4 or later specifications, start the Message Queue broker, create the appropriate destinations, and write a messaging application that uses the UMS API to send or receive messages.

The UMS imqums.war file, contained in the Message Queue 4.3 distribution, is installed in the following location, depending on platform:

You can rename the .war file as appropriate.

Table 1–5 Location of imqums.war file

Platform 

Location of imqums.war

Solaris 

/usr/share/lib/imq

Linux 

/opt/sun/mq/share/lib

AIX 

IMQ_HOME/lib

Windows 

IMQ_HOME\lib

After you have deployed the imqums.war into a web container at localhost:port, you can find UMS documentation at:

http://localhost:port/imqums

Otherwise you can find UMS documentation as follows:

Supported Web Containers

UMS is currently supported on the following web containers:

AIX Platform Support

Message Queue 4.3 provides AIX platform packages and an Installer for installing them).

The Message Queue AIX implementation supports the following software:

For installation instructions, see Chapter 4, AIX Installation, in Sun Java System Message Queue 4.3 Installation Guide.

On the AIX platform, Message Queue files are installed under a single Message Queue home directory, IMQ_HOME. IMQ_HOME denotes the directory mqInstallHome/mq, where mqInstallHome is the installation home directory you specify when installing the product (by default, home-directory/MessageQueue).

The resulting Message Queue directory structure is the same as that for the Windows platform (see the Windows section of Appendix A, Platform-Specific Locations of Message Queue Data, in Sun GlassFish Message Queue 4.4 Administration Guide.)

Message Queue support for the AIX platform includes support for the Message Queue C-API. For instructions on building and compiling C applications on the AIX platform, see XREF.

New Zip-Based Installer

Message Queue 4.3 introduces a new installer for Zip-based distributions, as opposed to native package distributions. The installer is used to install the new Message Queue .zip distributions for the AIX platform.

The new installer extracts Message Queue .zip files to any directory for which you have write access (you do not need root privileges) and it also enables you to register your Message Queue installation with Sun Connection.

To minimize the size of download bundles, the Java Runtime is no longer be included in the zip-based distribution (most sites will already have it). As a result, the installer command requires that a JDK or JRE be specified, either by using the JAVA_HOME environment variable or by using the -j option on the command line, as follows:

$ installer -j JDK/JRE-path

where JDK/JRE-path is the path of the specified JDK or JRE.

Extended Platform Support

The following updated platform support will be certified for Message Queue 4.3:

Additional Enhancements

The following additional enhancements are included in Message Queue 4.3:

New Directory Structure on Windows Platform

The installed directory structure for Message Queue on the Windows platform has been modified from previous versions to match that of the AIX platform. This directory structure will be adopted as well by the Solaris and Linux platforms in the future, to facilitate multiple installations on single computer and automatic update of Message Queue through Sun Connection, a Sun-hosted service that helps you track, organize, and maintain Sun hardware and software (see Installer Support for Sun Connection Registration).

New Broker Properties

The following new properties are available for configuring a broker:

Table 1–6 Broker Routing and Delivery Properties

Property 

Type 

Default Value 

Description 

imq.transaction.producer.maxNumMsgs

Integer 

1000

The maximum number of messages that a producer can process in a single transaction. It is recommended that the value be less than 5000 to prevent the exhausting of resources. 

imq.transaction.consumer.maxNumMsgs

Integer 

100

The maximum number of messages that a consumer can process in a single transaction. It is recommended that the value be less than 1000 to prevent the exhausting of resources. 

imq.persist.jdbc.connection.limit

Integer 

5

The maximum number of connections that can be opened to the database. 

JMX Administration API Enhancements

A new attribute and composite data keys have been added to the JMX API as follows:

For more information see Chapter 3, Message Queue MBean Reference, in Sun GlassFish Message Queue 4.4 Developer’s Guide for JMX Clients.

Listing Durable Subscriptions for Wildcard Subscribers

The command for listing durable subscriptions:

list dur [-d topicName]

has been enhanced to make specification of the topic name optional. If the topic is not specified, the command lists all durable subscriptions for all topics (including those with wildcard naming conventions)

New Features in Message Queue 4.2

Message Queue 4.2 was a minor release that included a number of new features, some feature enhancements, and bug fixes. This section describes the new features in the 4.2 release and provides further references for your use:

For information about features introduced in Message Queue 4.1 and 4.0, see New Features in Message Queue 4.1 and New Features in Message Queue 4.0, respectively.

Multiple Destinations for a Publisher or Subscriber

With Message Queue 4.2, a publisher can publish messages to multiple topic destinations and a subscriber can consume messages from multiple topic destinations. This capability is achieved by using a topic destination name that includes wildcard characters, representing multiple destinations. Using such symbolic names allows administrators to create additional topic destinations, as needed, consistent with the wildcard naming scheme. Publishers and subscribers automatically publish to and consume from the added destinations. (Wildcard topic subscribers are more common than publishers.)


Note –

This feature does not apply to queue destinations.


The format of symbolic topic destination names and examples of their use is described in Supported Topic Destination Names in Sun GlassFish Message Queue 4.4 Administration Guide.

Schema Validation of XML Payload Messages

This feature, introduced in Message Queue 4.2, enables validation of the content of a text (not object) XML message against an XML schema at the point the message is sent to the broker. The location of the XML schema (XSD) is specified as a property of a Message Queue destination. If no XSD location is specified, the DTD declaration within the XML document is used to perform DTD validation. (XSD validation, which includes data type and value range validation, is more rigorous than DTD validation.)

For information on the use of this feature, see Schema Validation of XML Payload Messages in Sun GlassFish Message Queue 4.4 Developer’s Guide for Java Clients.

C-API Support for Distributed Transactions

According to the X/Open distributed transaction model, support for distributed transactions relies upon a distributed transaction manager which tracks and manages operations performed by one or more resource managers. With Message Queue 4.2, the Message Queue C-API supports the XA interface (between a distributed transaction manager and Message Queue as a XA-compliant resource manager), allowing Message Queue C-API clients running in a distributed transaction processing environment (such as BEA Tuxedo) to participate in distributed transactions.

This distributed transaction support consists of the following new C-API functions (and new parameters and error codes) used to implement the XA interface specification:

MQGetXAConnection()
MQCreateXASession()

If a C-client application is to be used in the context of a distributed transaction, then it must obtain a connection by using MQGetXAConnection() and create a session for producing and consuming messages by using MQCreateXASession(). The start, commit, and rollback, of any distributed transaction is managed through APIs provided by the distributed transaction manager.

For details of using the distributed transaction functions, see Working With Distributed Transactions in Sun GlassFish Message Queue 4.4 Developer’s Guide for C Clients.

Message Queue 4.2 provides programming examples based on the Tuxedo transaction manager. For information on the use of these sample programs, see Distributed Transaction Sample Programs in Sun GlassFish Message Queue 4.4 Developer’s Guide for C Clients.


Note –

The distributed transaction functionality is supported on Solaris, Linux, and Windows platforms, however, to date it has only been certified on the Solaris platform.


Installer Support for Sun Connection Registration

The Message Queue installer has been enhanced to allow for registration of Message Queue with Sun Connection, a Sun-hosted service that helps you track, organize, and maintain Sun hardware and software.

As part of Message Queue installation, you can choose to register Message Queue with Sun Connection. Information about the installed Message Queue, such as the release version, host name, operating system, installation date, and other such basic information is securely transmitted to the Sun Connection database. The Sun Connection inventory service can help you organize your Sun hardware and software, while the update service can inform you of the latest available security fixes, recommended updates, and feature enhancements.

For details of registering Message Queue with Sun Connection, see Sun Java System Message Queue 4.3 Installation Guide.

Support for MySQL Database

Message Queue 4.2 introduced support for MySQL database as a JDBC-based data store. MySQL Cluster Edition can be used as a JDBC database for a standalone broker, and MySQL Cluster Edition can be used as the highly-available shared data store needed for an enhanced broker cluster. For information on configuring Message Queue to use MySQL, see Configuring a JDBC-Based Data Store in Sun GlassFish Message Queue 4.4 Administration Guide and also Enhanced Broker Cluster Properties in Sun GlassFish Message Queue 4.4 Administration Guide.

Additional Enhancements

In addition to the features described above, Message Queue 4.2 included the following enhancements:

New Features in Message Queue 4.1

Message Queue 4.1 was a minor release that included a number of new features, some feature enhancements, and bug fixes. This section describes the new features in the 4.1 release and provides further references for your use:

For information about features introduced in Message Queue 4.0, see New Features in Message Queue 4.0.

High-Availability Broker Clusters

Message Queue 4.1 introduced a new, enhanced broker cluster. As compared to a conventional broker cluster, which provides only messaging service availability (if a broker fails, another broker is available to provide messaging service), the enhanced broker cluster also provides data availability (if a broker fails, its persistent messages and state data are available to another broker to use to take over message delivery).

The high-availability implementation introduced in Message Queue 4.1 uses a shared JDBC-based data store: instead of each broker in a broker cluster having its own persistent data store, all brokers in the cluster share the same JDBC-compliant database. If a particular broker fails, another broker within the cluster takes over message delivery for the failed broker. In doing so, the failover broker uses data and state information in the shared data store. Messaging clients of the failed broker reconnect to the failover broker, which provides uninterrupted messaging service.

The shared JDBC-based store used in the Message Queue 4.1 high-availability implementation must itself be highly available. If you do not have a highly available database or if uninterrupted message delivery is not important to you, you can continue to use conventional clusters, which provide service availability without data availability.

To configure a Message Queue 4.1 enhanced broker cluster, you specify the following broker properties for each broker in the cluster:

To use the enhanced broker cluster implementation, you must do the following:

  1. Install a highly available database.

  2. Install the JDBC driver .jar file.

  3. Create the database schema for the highly available persistent data store.

  4. Set high-availability properties for each broker in the cluster.

  5. Start each broker in the cluster.

For a conceptual discussion of enhanced broker clusters and how they compare to conventional clusters, see Chapter 4, Broker Clusters, in Sun GlassFish Message Queue 4.4 Technical Overview. For procedural and reference information about enhanced broker clusters, see Chapter 10, Configuring and Managing Broker Clusters, in Sun GlassFish Message Queue 4.4 Administration Guide and Cluster Configuration Properties in Sun GlassFish Message Queue 4.4 Administration Guide.

If you have been using a highly available database with Message Queue 4.0 and want to switch to an enhanced broker cluster, you can use the Database Manager utility (imqdbmgr to convert to a shared persistent data store. Also see Broker Clusters for more known issues and limitations.

JAAS Support

In addition to the file-based and LDAP-based built-in authentication mechanisms, Message Queue 4.1 introduced support for the Java Authentication and Authorization Service (JAAS), which allows you to plug an external authentication mechanism into the broker to authenticate Message Queue clients.

For a description of the information that a broker makes available to a JAAS-compliant authentication service and an explanation of how to configure the broker to use such a service, see Using JAAS-Based Authentication in Sun GlassFish Message Queue 4.4 Administration Guide.

Persistent Data Store Format Change

Message Queue 4.1 changed the JDBC-based data store to support enhanced broker clusters. For this reason the format of the JDBC—based data store is increased to version 410. Format versions 350, 370, and 400 are automatically migrated to the 410 version.

Please note that the format of the file-based persistent data store remains at version 370 because no changes were made to it.

Broker Environment Configuration

The property IMQ_DEFAULT_EXT_JARS has been added to the Message Queue 4.1 environment configuration file, imqenv.conf. You can set this property to specify the path names of external .jar files to be included in CLASSPATH when the broker starts up. If you use this property to specify the location of external .jar files, you no longer need to copy these files to the lib/ext directory. External .jar files can refer to JDBC drivers or to JAAS login modules. The following sample poperty, specifies the location of JDBC drivers.

IMQ_DEFAULT_EXT_JARS=/opt/SUNWhadb4/lib/hadbjdbc4.jar:/opt/SUNWjavadb/derby.jar

Java ES Monitoring Framework Support

Message Queue 4.1 introduced support for the Sun Java Enterprise System (Java ES) Monitoring Framework, which allows Java ES components to be monitored using a common graphical interface. This interface is implemented by a web-based console called the Sun Java System Monitoring Console. Administrators can use the Console to view performance statistics, reate rules for automatic monitoring, and acknowledge alarms. If you are running Message Queue along with other Java ES components, you might find it more convenient to use a single interface to manage all of them.

For information on using the Java ES monitoring framework to monitor Message Queue, see XREF.

Enhanced Transaction Management

Previously, only transactions in a PREPARED state were allowed to be rolled back administratively. That is, if a session that was part of a distributed transaction did not terminate gracefully, the transaction remained in a state that could not be cleaned up by an administrator. In Message Queue 4.1, you can now use the Command utility (imqcmd) to clean up (roll back) transactions that are in the following states: STARTED, FAILED, INCOMPLETE, COMPLETE, and PREPARED.

To help you determine whether a particular transaction can be rolled back (especially when it is not in a PREPARED state), the Command utility provides additional data as part of theimqcmd query txn output: it provides the connection id for the connection that started the transaction and specifies the time when the transaction was created. Using this information, an administrator can decide whether the transaction needs to be rolled back. In general, the administrator should avoid rolling back a transaction prematurely.

Fixed Ports for C Client Connections

In Message Queue 4.1, C clients, like Java clients, can now connect to a fixed broker port rather than to a port dynamically assigned by the broker's Port Mapper service. Fixed port connections are useful if you're trying to get through a firewall or if you need to bypass the Port Mapper service for some other reason.

To configure a fixed port connection you need to configure both the broker and the C client run time (both ends of the connection). For example, if you want to connect your client via ssljms to port 1756, you would do the following:


Note –

The MQ_SERVICE_PORT_PROPERTY connection property has been backported to Message Queue 3.7 Update 2.


New Features in Message Queue 4.0

Message Queue 4.0 was a minor release limited to supporting Application Server 9 PE. It included a few new features, some feature enhancements, and bug fixes. This section includes a description of new features in this release:


Caution – Caution –

One of the minor but potentially disruptive changes introduced with version 4.0 was the deprecation of the command-line option to specify a password. Henceforth, you must store all passwords in a file as described in Deprecated Password Option, or enter them when prompted.


Support for JMX Administration API

A new API was added in Message Queue 4.0 for configuring and monitoring Message Queue brokers in conformance with the Java Management Extensions (JMX) specification. Using this API, you can configure and monitor broker functions programmatically from within a Java application. In earlier versions of Message Queue, these functions were accessible only from the command line administration utilities or the Administration Console.

For more information see the Sun GlassFish Message Queue 4.4 Developer’s Guide for JMX Clients.

Client Runtime Logging

Message Queue 4.0 introduced support for client runtime logging of connection and session-related events.

Fore information regarding client runtime logging and how to configure it, see the Java Dev Guide pag 137.

Connection Event Notification API

Message Queue 4.0 introduced an event notification API that allows the client runtime to inform an application about changes in connection state. Connection event notifications allow a Message Queue client to listen for closure and re-connection events and to take appropriate action based on the notification type and the connection state. For example, when a failover occurs and the client is reconnected to another broker, an application might want to clean up its transaction state and proceed with a new transaction.

For information about connection events and how to create an event listener, see the Java Dev Guide, page 96.

Broker Administration Enhancements

In Message Queue 4.0, a new subcommand and several command options were added to the Command utility (imqcmd) to allow administrators to quiesce a broker, to shutdown a broker after a specified interval, to destroy a connection, or to set java system properties (for example, connection related properties).

For complete information about the syntax of the imqcmd command, see Chapter 16, Command Line Reference, in Sun GlassFish Message Queue 4.4 Administration Guide.

Displaying Information About a JDBC-Based Data Store

In Message Queue 4.0 a new query subcommand was added to the Database Manager utility, imqdbmgr. This subcommand is used to display information about a JDBC-based data store, including the database version, the database user, and whether the database tables have been created.

The following is an example of the information displayed by the command.


imqdbmgr query

[04/Oct/2005:15:30:20 PDT] Using plugged-in persistent store:
        version=400
        brokerid=Mozart1756
        database connection url=jdbc:oracle:thin:@Xhome:1521:mqdb
        database user=scott
Running in standalone mode.
Database tables have already been created.

JDBC Provider Support

In Message Queue 4.0, Apache Derby Version 10.1.1 is now supported as a JDBC-based data store provider.

Persistent Data Store Format Changes

Message Queue 4.0 introduced changes to the JDBC-based data store for optimization and to support future enhancements. For this reason the format of the JDBC-based data store was increased to version 400. Note that in Message Queue 4.0, the file-based data store version remains 370 because no changes were made to it.

Additional Message Properties

Message Queue 4.0 added two new properties which are set on all messages that are placed in the dead message queue.

SSL Support

Starting with Message Queue 4.0, the default value for the client connection factory property imqSSLIsHostTrusted is false. If your application depends on the prior default value of true, you need to reconfigure and to set the property explicitly to true.

You might choose to trust the host when the broker is configured to use self-signed certificates. In this case, in addition to specifying that the connection should use an SSL-based connection service (using the imqConnectionType property), you should set the imqSSLIsHostTrusted property to true.

For example, to run client applications securely when the broker uses self-signed certificates, use a command like the following.

java -DimqConnectionType=TLS 
      -DimqSSLIsHostTrusted=true ClientAppName

To use the Command utility (imqcmd) securely when the broker uses self-signed certificates, use a command like the following (for listing connector services).

imqcmd list svc -secure -DimqSSLIsHostTrusted=true

Features to be Deprecated in a Future Release

The following features will be deprecated in a future release:

Bugs Fixed in Message Queue 4.4 and Recent Releases

Message Queue 4.4 includes new bug fixes and also incorporates bugs that were fixed in the previous releases in the Message Queue 4.x family.

The following sections list bugs that were fixed in their respective releases:

Bugs Fixed in Message Queue 4.4

The following table describes the bugs fixed in Message Queue 4.4.

Table 1–7 Bugs Fixed in Message Queue 4.4

Bug 

Description 

6242247 

MQ cluster with masterbroker startup and hangs if both broker is on same machine have same name 

6760937 

Broker does not reconnect to the DB if it is restarted 

6765410 

masterbroker sends local interests 2 times cause slave exception Durable subscription already active 

6796506 

remote PREPARED msg not redelivered after rollback in case timeout in receiving remote PREPARE reply 

6821639 

NPE on rollback/commitTransaction during AS recovery for MQRA-DIRECT mode 

6836364 

wildcard subscriber does not receive remote msg if its topic is created before subscriber 

6836749 

HA(JCAPS):ack exists in store exception on receive after 1 of durables rollback then commit a msg 

6858905 

ConcurrentModificationException in Consumer.destroyConsumer 

Bugs Fixed in Message Queue 4.3

The following table describes the bugs fixed in Message Queue 4.3.

Table 1–8 Bugs Fixed in Message Queue 4. 3

Bug 

Description 

6634033 

Cluster protocol does not propagate value of imqConsumerFlowLimit to remote brokers when a client is created.

6713012 

Destruction of a consumer on a broker in a cluster at the same time that a remote broker is being restarted can result in some messages not being delivered. 

6727555 

Broker log message "Max bytes per msg exceeded" has the actual message size and the max bytes per message values switched.

6737404 

JMX metrics need to provide counts of messages dispatched from destinations (topics and queues) but yet to be delivered to consumers. 

6740568 

Broker throws an exception when consuming too many messages in a single transaction. 

6758524 

The command to list durable subscriptions (imqcmd list dur -d "foo.*") does not accept wildcard characters in the destination name.

6758952 

Setting imq.portmapper.hostname=localhost causes brokers to be unable to connect into a cluster.

6758817 

Setting imq.cluster.hostname=localhost (not recommended) causes brokers on different machines to be unable to connect into a cluster.

Bugs Fixed in Message Queue 4.2

The following table describes the bugs fixed in Message Queue 4.2.

Table 1–9 Bugs Fixed in Message Queue 4.2

Bug 

Description 

6581592 

When the installer or uninstaller is run in text mode (installer –t), the Summary screen shows the directory containing the log/summary files but does not list the names of these files.

6585911 

The installer's JDK Selection screen incorrectly includes the JRE bundled with the installer and used to run the installer. 

6587112 

The installer summary screen shows garbage in multi-byte locales. 

6587127 

When running the installer by referencing an answer file (installer -a filename -s), if the answer file does not exist, the error messages are inconsistent and unclear.

6590969 

Allows DN username format in client connection authentication. 

6594381 

Installation of Message Queue 4.1 localization RPM's (which happens when you select the “Install Message Queue multilingual packages” checkbox on the Multilingual Packages screen) will fail if older versions of Message Queue localization RPM's exist on your system. 

6599144 

When uninstalling Message Queue 4.2, splash screen and uninstaller hangs and screens appear empty and gray on Java SE 6, but work on Java SE 5.  

6615741 

Message delivered in a transacted consumer session that is rolled back is not redelivered if the original consumer closed before rollback. 

6629922 

Distributed transaction handler does not redeliver message to inactive consumer in correct order. 

6635130 

Broker fails to notify producer of non persistent messages to resume production after having been paused because destination had reached memory or message limits. 

6641117 

Message delivered in a transacted consumer session that is rolled back is not redelivered if the original consumer closed after rollback. 

6683897 

Message Queue installer's summary screen reports configuration error even though configuration appears to complete successfully: installer cannot write to /dev/sterr on some computers.

6684069 

In broker cluster in which large number of messages are delivered to remote client in consumer transaction, commit transaction fails. 

6688935 

Default value of Portmapper read timeout is too small. 

6695238 

C-client applications cannot connect to a broker installed in a location that has spaces in the path. 

6710168 

Consumer no longer consumes messages if destination is paused twice without being resumed between the pauses. 

6710169 

JMX operation ConsumerManagerMonitor.getConsumerInfo always returns SESSION_TRANSACTED for the acknowledgement mode.

Bugs Fixed in Message Queue 4.1

The following table describes the bugs fixed in Message Queue 4.1.

Table 1–10 Bugs Fixed in Message Queue 4.1

Bug 

Description 

6381703 

Transacted remote messages can be committed twice if the broker originating the message restarts. 

6388049 

Cannot clean up an uncompleted distributed transaction. 

6401169 

The commit and rollback options for imqcmd do not prompt for confirmation. 

6473052 

Default for autocreated queues should be round robin. (MaxNumberConsumers = -1).

6474990 

Broker log shows ConcurrentModificationException for imqcmd list dst command.

6487413 

Memory leak when limit behavior is REMOVE_OLDEST or REMOVE_LOWER_PRIORITY.

6488340 

Broker spins, and client waits for reply to acknowledge. 

6502744 

Broker does not honor the dead message queue's default limit of 1000 messages. 

6517341 

Client runtime needs to improve reconnect logic when the client is connected to an enhanced broker cluster by allowing the client to reconnect no matter what the value of the imqReconnectEnabled property is.

6528736 

Windows automatic startup service (imqbrokersvc) crashes during startup.

6561494 

Messages are delivered to the wrong consumer when both share a session. 

6567439 

Produced messages in a PREPARED transaction are delivered out of order if they are committed after broker restarts.

Bugs Fixed in Message Queue 4.0

The following table describes the bugs fixed in Message Queue 4.0.

Table 1–11 Bugs Fixed in Message Queue 4.0

Bug Number 

Description 

4986481 

In Message Queue 3.5, calling Session.recover could hang in auto-reconnect mode.

4987325 

Redelivered flag was set to false for redelivered messages after calling Session.recover.

6157073 

Change new connection message to include the number of connections on the service in addition to the total number of connections. 

6193884 

Message Queue outputs garbage message to syslog in locales that use non-ASCII characters for messages. 

6196233 

Message selection using JMSMessageID doesn't work.

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.  

6260814 

Selector processing on JMSXUserID always evaluates to false.

6264003 

The queue browser shows messages that are part of transactions that have not been committed. 

6271876 

Connection Flow Control does not work properly when closing a consumer with unconsumed messages. 

6279833 

Message Queue should not allow two brokers to use the same jdbc tables. 

6293053 

Master broker does not start up correctly if the system's IP address is changed, unless the store is cleared (using —reset store.)

6294767 

Message Queue broker needs to set SO_REUSEADDR on the network sockets it opens.

6304949 

Unable to set ClientID property for TopicConnectionFactory.

6307056 

The txn log is a performance bottleneck.

6320138 

Message Queue C API lacks ability to determine the name of a queue from a reply-to header.  

6320325 

The broker sometimes picks up JDK 1.4 before JDK 1.5 on Solaris even if both versions are installed.  

6321117 

Multibroker cluster initialization throws java.lang.NullPointerException.

6330053 

The jms client throws java.lang.NoClassDefFoundError when committing a transaction from the subscriber.

6340250 

Support MESSAGE type in C-API.

6351293 

Add Support for Apache Derby database.  

Documentation Updates in Message Queue 4.4

This section contains information regarding Message Queue 4.4 documentation updates:

Compatibility Issues

This section covers compatibility issues regarding Message Queue 4.4.

Interface Stability

Sun GlassFish Message Queue uses many interfaces that may change over time. Appendix B, Stability of Message Queue Interfaces, in Sun GlassFish Message Queue 4.4 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 current Message Queue client applications incompatible with that release. This information is provided in the interest of full disclosure.

Changes in the Message Queue 4.4 Documentation Set

The Message Queue 4.4 documentation set includes updates to the Message Queue 4.3 documentation set as described below:

Technical Overview

The Sun GlassFish Message Queue 4.4 Technical Overview reflects new features in Message Queue 4.4.

Administration Guide

The Sun GlassFish Message Queue 4.4 Administration Guide includes minor bug fixes and reflects new features in Message Queue 4.4.

Developer's Guide for Java Clients

The Sun GlassFish Message Queue 4.4 Developer’s Guide for Java Clients includes minor bug fixes.

Developer’s Guide for C Clients

The Sun GlassFish Message Queue 4.4 Developer’s Guide for C Clients includes minor bug fixes.

Developer's Guide for JMX Clients

The Sun GlassFish Message Queue 4.4 Developer’s Guide for JMX Clients reflects the new Message Queue product name and version number.

Known Issues and Limitations

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

For a list of current bugs, their status, and workarounds, Java Developer Connection™ 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 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.

http://bugs.sun.com/bugdatabase/index.jsp


Note –

Java Developer Connection membership is free but requires registration. 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.

Installation Issues

This section describes issues related to the installation of Message Queue version 4.4.

Product Registry and Java ES

Message Queue 4.4, like Message Queue 4.2 and 4.1, is installed by a relatively new installer, which also installs and upgrades the Java Enterprise System (Java ES) shared components required by Message Queue; for example, JDK, NSS, JavaHelp, and so on.

The new Message Queue installer and the older Java ES installer, which was used to install previous Message Queue versions, do not share the same product registry. If a version of Message Queue that was installed with the Java ES installer is removed and then Message Queue 4.4 is subsequently installed by the Message Queue installer, the Java ES product registry might be in an inconsistent state. As a result, if the Java ES uninstaller is run, it may inadvertently remove Message Queue 4.4 and the shared components upon which it depends, even though it did not install them.

The best way to upgrade Message Queue software that was installed by the Java ES installer is as follows.

  1. Use the Java ES uninstaller to remove Message Queue and its shared components.

  2. Use the Message Queue installer to install Message Queue 4.4.

Installing on All Platforms

These issues affect installation on all platforms.

Installing on Windows

When installing Message Queue on Windows, please note the following limitations.

Installing on Solaris

Installing on Linux

The following issues affect installation on the Linux Platform:

Version Anomalies in the Installer

The installer displays Message Queue version information in an opaque form. (Bug 6586507)

Solaris Platform

On the Solaris platform, refer to the following table to determine the Message Queue version displayed by the installer.

Table 1–12 Version String Translation

Version as Displayed by the Installer on Solaris OS 

Corresponding Message Queue Release 

4.4.0.0 

4.4 

4.3.0.0 

4.3 

4.2.0.0 

4.2 

4.1.0.2 

4.1 Patch 2 

4.1.0.1 

4.1 Patch 1 

4.1.0.0 

4.1 

3.7.2.1 

3.7 UR2 Patch 1 

3.7.0.2 

3.7 UR2 

3.7.0.1 

3.7 UR1 

3.6.0.0 

3.6 

3.6.0.4 

3.6 SP4 

3.6.0.3 

3.6 SP3 

3.6.0.2 

3.6 SP2 

3.6.0.1 

3.6 SP1 


Note –

For Patch releases to 3.6 SP4 (for example, 3.6 SP4 Patch 1), the releases string displayed by the installer stays the same. You need to run the command imqbrokerd -version to determine the exact version.


Linux Platform

On the Linux platform, the version number displayed by the installer is in the following form.

majorReleaseNumber.minorReleaseNumber-someNumber

For example, 3.7–22. This tells us only that this is one of the 3.7 releases, but not which specific one. To determine the installed Message Queue version, run the command:

imqbrokerd -version.

Localization Issues

The following issues relate to localization problems.

Deprecated Password Option

In previous versions of Message Queue, you could use the —p or —password option to specify a password interactively for the following commands: imqcmd, imqbrokerd, and imdbmgr. Beginning with version 4.0, these options have been deprecated.

Instead, you can create a password file that specifies the relevant passwords and reference the password file using the -passfile command option, or simply enter a password when prompted by the command.

A password file can contain one or more of the passwords listed below.

In the following example, the password to the JDBC database is set in the password file to abracadabra.

imq.persist.jdbc.mysql.password=abracadabra

You can use a password file in one of the following ways.

Administration/Configuration Issues

The following issues pertain to administration and configuration of Message Queue

Broker Issues

The following issues affect the Message Queue broker.

Broker Clusters

The following issues affect broker clusters.

JMX Issues

On the Windows platform, the getTransactionInfo method of the Transaction Manager Monitor MBean returns transaction information that has incorrect transaction creation time. (Bug 6393359)

Workaround: Use the getTransactionInfoByID method of the Transaction Manager Monitor MBean instead.

SOAP Support

You need to be aware of two issues related to SOAP support

Redistributable Files

Sun GlassFish Message Queue 4.4 contains the following set of files which you may use and freely distribute in binary form:

fscontext.jar

jaxm-api.jar

imq.jar

jms.jar

imqjmx.jar

libmqcrt.sl (HP-UX)

imqxm.jar

libmqcrt.so (UNIX)

imqums.war

mqcrt1.dll (Windows)

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 GlassFish Message Queue, contact Sun 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:

Sun GlassFish Software Forum

There is a Sun GlassFish Message Queue forum available at the following location:

http://swforum.sun.com/jive/forum.jspa?forumID=24

We welcome your participation.

Java Technology Forum

There is a JMS forum in the Java Technology Forums that might be of interest.

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 Release Notes, and the part number is 821-0025.

Additional Sun Resources

Useful Sun GlassFish information can be found at the following Internet locations: