Sun Java System Message Queue 4.2 Release Notes

New Features in Message Queue 4.2 and Recent Releases

The new features in Message Queue 4.2, 4.2 and 4.0 are described in the following sections:

New Features in Message Queue 4.2

Sun Java System Message Queue is a full-featured message service that provides reliable, asynchronous messaging that conforms 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 4.2 is a minor release that includes a number of feature enhancements and bug fixes. This section explains how to install or upgrade toMessage Queue 4.2 and describes the new features included in this release:

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

Multiple Destinations for a Publisher or Subscriber

In Message Queue 4.2, a publisher can now 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 the symbolic topic destination name consists of multiple segments, in which wildcard characters (*, **, >) can represent one or more segments of the name. For example, suppose you have a topic destination naming scheme as follows:

size.color.shape

where the topic name segments can have the following values:

size: large, medium, small, ...
color: red, green, blue, ...
shape: circle, triangle, square, ...

Message Queue supports the following wildcard characters:

* matches a single segment
** matches one or more segments
> matches any number of successive segments

You can therefore indicate multiple topic destinations as follows:

large.*.circle would represent:

large.red.circle
large.green.circle
...

**.square would represent all names ending in .square, for example:

small.green.square
medium.blue.square
...

small.> would represent all destination names starting with small., for example:

small.blue.circle
small.red.square
...

To use this multiple destination feature, you create topic destinations using a naming scheme similar to that described above. Client applications can then create wildcard publishers or wildcard consumers using symbolic destination names. For example:

...
String DEST_LOOKUP_NAME = "large.*.circle";
Topic t = (Destination) ctx.lookup(DEST_LOOKUP_NAME);
TopicPublisher myPublisher = mySession.createPublisher(t)
myPublisher.send(myMessage);

...
String DEST_LOOKUP_NAME = "**.square";
Topic t = (Destination) ctx.lookup(DEST_LOOKUP_NAME);
TopicSubscriber mySubscriber = mySession.createSubscriber(t);
Message m = mySubscriber.receive();

In the first example, the broker will place a copy of the message in any destination that matches the symbolic name large.*.circle. In the second example, a subscriber will be created if there is at least one destination that matches the symbolic name **.square and will receive messages from all destinations that match that symbolic name. If there are no destinations matching the symbolic name, the subscriber will not be created until such a destination exists.

If an administrator creates additional destinations that match a symbolic name, then wildcard publishers created using that symbolic name will subsequently publish to that destination and wildcard subscribers created using that symbolic name will subsequently receive messages from that destination.

In addition, Message Queue administration tools, in addition to reporting the total number of publishers (producers) and subscribers (consumers) for a topic destination, will also report the number of publishers that are wildcard publishers (including their corresponding symbolic destination names) and the number of subscribers that are wildcard subscribers (including their symbolic destination names), if any.

Schema Validation of XML Payload Messages

This new feature 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.)

Client applications using this new feature should upgrade Java SE version to JRE 1.5 or above.

To enable XML schema validation, you set the following physical destination properties:

Table 1–5 Physical Destination Properties for XML Schema Validation


Property	Type	Default Value	Description
`validateXMLSchemaEnabled`	Boolean	`false`	XML schema validation is enabled? If set to `false` or not set, then XML schema validation is not enabled for the destination.
`XMLSchemaURIList`	String	null	Space separated list of XML schema document (XSD) URI strings The URIs point to the location of one or more XSDs to use for XML schema validation, if enabled. Use double quotes around this value if multiple URIs are specified. Example: “`http://foo/flap.xsd http://test.com/test.xsd`” If this property is not set or null and XML validation is enabled, XML validation is performed using a DTD specified in the XML document.
`reloadXMLSchemaOnFailure`	Boolean	`false`	Reload XML schema on failure enabled? If set to false or not set, then the schema is not reloaded if validation fails.

When XML validation is enabled, the Message Queue client runtime will attempt to validate an XML message against the specified XSDs (or against the DTD, if no XSD is specified) before sending it to the broker. If the specified schema cannot be located or the message cannot be validated, the message is not sent, and an exception is thrown.

The XML validation properties can be set at destination creation or update time by using the imqcmd create dst or imqcmd update dst command, respectively. The XML validation properties should be set when a destination is inactive: that is, when it has no consumers and producers, and when there are no messages in the destination.

Note –

If an XSD is not accessible at runtime, it might be necessary to modify the XMLSchemaURIList while a destination is active.

If any of the XML validation properties are set while a destination is active (for example, if a producer is connected to the destination), the change will not take effect until the producer reconnects to the broker. Similarly, if an XSD is changed, as a result of changing application requirements, all client applications producing XML messages based on the changed XSD must reconnect to the broker.

If the reloadXMLSchemaOnFailure property is set to true and XML validation fails, then the Message Queue client runtime will attempt to reload the XSD before attempting again to validate a message. The client runtime will throw an exception if the validation fails using the reloaded SXD.

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. In Message Queue 4.2, the Message Queue C-API now 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 Java System Message Queue 4.2 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 Java System Message Queue 4.2 Developer’s Guide for C Clients

Note –

The distributed transaction functionality is supported 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.

The following installer screen has been added to Message Queue 4.2 for Sun Connection registration:

Registration requires that you have a Sun Online account or create one. If you do not already have an account, the installer provides the following screen for creating a Sun Online account:

Screen for creating a Sun Online account.

You can register Message Queue during installation using the above screens, or wait until after installation has been completed and run the installer in register-only mode, as follows:

# installer -r

The register-only mode requires that Message Queue 4.2 already be installed and will display only the installer screens related to registration.

Support for MySQL Database

Message Queue 4.2 supports 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 a high-availability broker cluster. For information on configuring Message Queue to use MySQL, see Configuring a JDBC-Based Data Store in Sun Java System Message Queue 4.2 Administration Guide and also High-Availability Cluster Properties in Sun Java System Message Queue 4.2 Administration Guide.

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 high-availability broker clusters. As compared to conventional broker clusters, which provide only messaging service availability (if a broker fails, another broker is available to provide messaging service), high-availability broker clusters also provide 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 the message routing and 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 high-availability broker cluster, you specify the following broker properties for each broker in the cluster:

Cluster membership properties, which specify that the broker is in a high-availability broker cluster, the ID of the cluster, and the ID of the broker within the cluster.
Highly available database properties, which specify the persistent data model (JDBC), the name of the database vendor, and vendor-specific configuration properties.
Failure detection and failover properties, which specify how broker failure is detected and handled using a failover broker.

To use the high-availability broker cluster implementation, you must do the following:

Install a highly available database.
Install the JDBC driver .jar file.
Create the database schema for the highly available persistent data store.
Set high-availability properties for each broker in the cluster.
Start each broker in the cluster.

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

If you have been using a highly available database with Message Queue 4.0 and want to switch to a high-availability 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 Java System Message Queue 4.2 Administration Guide.

Persistent Data Store Format Change

Message Queue 4.1 changed the JDBC-based data store to support high-availability 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:

On the client side, set the following properties:

MQ_SERVICE_PORT_PROPERTY=1756

MQ_CONNECTION_TYPE_PROPERTY=SSL
On the broker side, set the imq.serviceName.protocolType.port property as follows:
```
imq.ssljms.tls.port=1756
```

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 –

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 Java System Message Queue 4.2 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).

Quiescing a broker moves it into a quiet state, which allows messages to be drained before the broker is shut down or restarted. No new connections can be created to a broker that is being quiesced. To quiesce the broker, enter a command like the following.

imqcmd quiesce bkr -b Wolfgang:1756
To shut down the broker after a specified interval, enter a command like the following. (The time interval specifies the number of seconds to wait before the broker is shut down.)

imqcmd shutdown bkr -b Hastings:1066 -time 90

If you specify a time interval, the broker will log a message indicating when shutdown will occur. For example,

Shutting down the broker in 29 seconds (29996 milliseconds)

While the broker is waiting to shut down, its behavior is affected in the following ways.
- Administrative jms connections will continue to be accepted.
- No new jms connections will be accepted.
- Existing jms connections will continue to work.
- The broker will not be able to take over for any other broker in a high-availability broker cluster.
- The imqcmd utility will not block, it will send the request to shut down to the broker and return right away.
To destroy a connection, enter a command like the following.

imqcmd destroy cxn -n 2691475382197166336

Use the command imqcmd list cxn or imqcmd query cxn to obtain the connection ID.
To set a system property using imqcmd, use the new –D option. This is useful for setting or overriding JMS connection factory properties or connection-related java system properties. For example:
```
imqcmd list svc -secure -DimqSSLIsHostTrusted=true
imqcmd list svc -secure -Djavax.net.ssl.trustStore=/tmp/mytruststore 
            -Djavax.net.ssl.trustStorePassword=mytrustword
```

For complete information about the syntax of the imqcmd command, see Chapter 15, Command Line Reference, in Sun Java System Message Queue 4.2 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.

JMS_SUN_DMQ_PRODUCING_BROKER indicates the broker where the message was produced.
JMS_SUN_DMQ_DEAD_BROKER indicates the broker who marked the message dead.

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