|
| Sun ONE Message Queue, Version 3.0.1 Release Notes |
|
|
| Sun ONE Message Queue, Version 3.0.1 Release Notes |
These release notes contain important information available at the time of release of Version 3.0.1 of Sun ONE Message Queue (MQ). New features and enhancements, known limitations and problems, technical notes, and other information are addressed here. Read this document before you begin using MQ 3.0.1.
The most up-to-date version of these release notes can be found at the Sun ONE documentation web site: http://docs.sun.com/?p=/coll/S1_MessageQueue_301. Check the web site after installing your software, and then periodically thereafter, to view the most up-to-date version of these notes.
These release notes contain the following sections:
MQ 3.0.1 has been certified as compliant with the Java Message Service (JMS) 1.1 specification: it has passed the JMS 1.1 Compatibility Test Suite (CTS).
MQ 3.0.1, which is the native JMS provider for Sun ONE Application Server 7, has also passed the J2EE 1.3.1 CTS testing of the Sun ONE Application Server 7 (which requires compliance with JMS 1.0.2b)
The following MQ 3.0.1 documents have been updated from Version 3.0 of the product. These updated documents can be found at the Sun ONE documentation web site: http://docs.sun.com/?p=/coll/S1_MessageQueue_301.
The MQ 3.0.1 product includes an updated MQ Installation Guide.
The MQ Administrator's Guide has been updated to include changes in MQ 3.0.1 (see "What's New in MQ 3.0.1").
The MQ Developer's Guide has been updated to include changes in MQ 3.0.1 (see "What's New in MQ 3.0.1").
The MQ 3.0.1 product includes all the new features of MQ 3.0 plus two additional 3.0.1 features.
MQ 3.0.1 includes two new capabilities as compared to MQ 3.0:
MQ 3.0.1 provides message delivery throughput up to double that attained with MQ 3.0, a performance boost that is especially important under heavy load conditions. The improvement was achieved through changes in the marshalling of JMS message properties for transmission over the wire.
MQ 3.0.1 is certified for Sun ONE Application Server 7.0, and is used as its native JMS provider. MQ has been integrated with the Application Server, providing JMS messaging support in an Application Server environment. You can configure the system for an internal MQ message server managed with Application Server administration tools, or an external MQ message server requiring MQ administration tools.
MQ 3.0.1 is now certified for JDK 1.4.1 on Linux Red Hat 7.2 (and still supported on Linux Red Hat 7.1).
MQ 3.0 included a number of changes to Version 2.0 of the product—iMQ 2.0 (and iMQ 2.0, Service Pack 1).
Notable among these changes is that the product is now available in two editions: a Platform Edition and an Enterprise Edition.
Platform Edition Provides basic JMS support, and is best suited to small-scare deployments and development environments
Enterprise Edition Provides HTTP/HTTPS support, enhanced scalability, and security features, and is best suited to large-scale deployments.
(See the introduction to the MQ Administrator's Guide or the MQ Developer's Guide for more information on these editions.)
The descriptions, below, of changes in the MQ 3.0.1 product are grouped according to whether they apply to both editions or to the Enterprise Edition only.
MQ now supports the JTA XA Resource API, meaning that production and consumption of messages can be part of a larger distributed transaction involving other resource managers, such as database managers (see Chapter 1 of the MQ Developer's Guide). This feature is also supported with administrative tools for managing transactions (see Table 6-12 of the MQ Administrator's Guide). Programming information and examples are not yet available in the MQ 3.0.1 release product.
MQ now supports the added features of the JMS 1.1 specification, which provides a simplified approach to JMS client programming as compared to JMS 1.0.2. In particular, a JMS client can perform both point-to-point and publish/subscribe messaging over the same connection and within the same session, and can include both queues and topics in the same transaction.
In short, a JMS client developer need not make a choice between the separate point-to-point and publish/subscribe programming domains of JMS 1.0.2, opting instead for the simpler, unified domain approach of JMS 1.1. This is the preferred approach, however the JMS 1.1 specification continues to support the separate JMS 1.0.2 programming domains. (In fact, the example applications included with the MQ product as well as the code examples provided in the MQ Developer's Guide all use the separate JMS 1.0.2 programming domains.)
Supports creation and delivery of messages that conform to the Simple Object Access Protocol (SOAP) specification, using JAXM—the Java API for XML Messaging. SOAP allows for the exchange of structured XML data between peers in a distributed environment. MQ also supports the delivery of SOAP messages via JMS messaging. See the MQ Developer's Guide for more information.
MQ now provides more flexibility in balancing disk space and performance when using the built-in persistent store (see Table 2-5 of the MQ Administrator's Guide). Also, administrators now have the option of removing only messages or durable subscriptions from the persistent store when restarting a broker (see reset option in Table 5-2 of the MQ Administrator's Guide).
MQ now allows an administrator to better control message server resources by overriding the JMS message header fields that specify message persistence, priority, and expiration (see Table 4-4 of the MQ Developer's Guide).
MQ now supports the purging of all messages for a specified durable subscription (see Table 6-11 of the MQ Administrator's Guide).
MQ now supports more than one network interface card on a computer by letting administrators choose which hostname will be used by MQ connection services (see Table 2-3 of the MQ Administrator's Guide).
MQ now allows an administrator to update the default delivery policy set for a queue destination (see Table 6-10 of the MQ Administrator's Guide).
The broker and MQ administration tools are now supported on the Java Runtime Environment (JRE) 1.4, and JMS clients are now supported on the Java Software Development Kit (JDK) 1.4.
The installed directory structure of MQ 3.0.1 on Solaris has been changed to conform to general file system standards for the platform. MQ 3.0.1 files are no longer installed under a single root installation directory, but are dispersed to standard locations in the Solaris file system.
MQ now supports secure messaging over HTTP (see Appendix B of the MQ Administrator's Guide). This new connection service provides for encryption of messages from message producer through to message consumer (that is, from JMS client, through HTTPS tunnel servlet, to broker, and visa versa).
MQ 3.0.1 is fully compatible with MQ 3.0, and upgrading from MQ 3.0 to MQ 3.0.1 requires no changes in broker configuration, administered objects, administration tools, or client applications.
However, MQ 3.0.1 is generally not compatible with iMQ 2.0. In particular, there are a number of issues that you might need to address when upgrading from iMQ 2.0 (or iMQ 2.0 Service Pack 1) to MQ 3.0.1:
An MQ 3.0.1 broker will not inter-operate with an iMQ 2.0 broker due to changes in broker properties and in the persistent store schema. However, some iMQ 2.0 data is compatible with MQ 3.0.1, as shown in Table 1, and can be preserved when upgrading to MQ 3.0.1. When upgrading from iMQ 2.0 to MQ 3.0.1, you should consider the following:
MQ 3.0.1 administered objects have been enhanced with new attributes and iMQ 2.0 attributes have been renamed. Therefore, when upgrading from iMQ 2.0 to MQ 3.0.1, you should consider the following:
Because of the renaming of many files and directories (specifically to replace the string "jmq" with "imq"), all MQ 3.0.1 command line utilities, broker properties, administered object attributes, and internal file names have changed. Therefore, when upgrading from iMQ 2.0 to MQ 3.0.1, you should consider the following:
When upgrading from iMQ 2.0 to MQ 3.0.1, you should consider the following:
This Message.acknowledge() method now acknowledges all messages consumed in the session at the time the method is called. This change in behavior from the 1.0.2 API (supported by iMQ 2.0) is illustrated in the following example: suppose a client consumes four messages from a queue in the same session, say A, B, C, and D in that order, and all were consumed before the client calls the acknowledge method on message C.
In 1.0.2, only messages A, B, and C, would get acknowledged since D was consumed after message C.
In 1.1, all the messages (including D) are acknowledged since they were all consumed.
The acknowledgement is independent of the order in which messages are consumed, so long as they are consumed in the same session; or stated another way, the message on which the acknowledge() method is called no longer determines which messages get acknowledged.
In iMQ 2.0, the behavior was to automatically set the ClientID to the local IP address of the client if a durable subscription was created without explicitly setting a ClientID value. In MQ 3.0.1, the behavior is to throw an exception if a durable subscription is created without explicitly setting a ClientID value. In other words a ClientID value must always be set—either in client code or using an attribute of the connection factory object—when durable subscriptions and durable connection consumers are used.
In iMQ 2.0, if a string literal contained multi-byte characters, you had to use a double escape on Unicode characters (for example, selector = "property = `\\u033e\\u033f'"). In MQ 3.0.1, the normal representation for Unicode characters can be used (for example, selector = "property = `\u033e\u033f'").
Limitations shown in this section are grouped according to whether they apply to both Enterprise and Platform Editions of MQ 3.0.1 or to the Enterprise Edition only.
IMQ_VARHOME/instances/brokerName/props/config.properties
(/var/imq/instances/brokerName/props/config.properties on Solaris)
Once the config.properties file has been created, edit the file to add any configuration property values and then restart the broker.
If another instance of the client is started within the one minute period and if it tries to use the same ClientID, durable subscription, or queue, it might receive a "Resource in conflict" exception. This is not a real problem; it's just the side effect of the termination process described above. If the client is started after a delay of approximately one minute, everything should work fine.
This section contains a listing of the more important bugs known at the time of the MQ 3.0.1 release.
For a list of current bugs, their status, and workarounds, Java Developer Connection (TM) members should see the Bug Parade page on the Java Developer Connection web site. Please check that page before you report a new bug. Although not all MQ bugs are listed here, it is a good starting place if you want to know whether a problem has been reported.
The relevant page is:
To report a new bug or submit a feature request, send mail to imq-feedback@sun.com.
Below is a short description of the most important bugs fixed in MQ 3.0.1.
(For bugs fixed in MQ 3.0, see the MQ 3.0 Release Notes available at
For more details about any of the following bug fixes you can view the complete report at the Java Developer Connection site:
The JMS specification indicates certain items that are optional-- each JMS provider (vendor) chooses whether or not to implement them. The MQ product handling of each of these optional items is indicated below:
This section contains short write-ups on the following topics:
When using an MQ system, you should be careful to synchronize system clocks and avoid setting them backward.
It is recommended that you synchronize the clocks on all hosts interacting with the MQ system. This is particularly important if you are using message expiration (TimeToLive). Failure to synchronize the hosts' clocks may result in TimeToLive not working as expected (messages may not be delivered). You should synchronize clocks before starting any brokers.
Solaris You can issue the rdate command on a local host to synchronize with remote host. (You must be superuser--that is, root--to run this command.) For example, the following command synchronizes the local host (call it Host 2) with remote host Host1:
# rdate Host1
Linux The command is similar to Solaris, but you must provide the -s option:
# rdate -s Host1
Windows you can issue the net command with the time subcommand to synchronize your local host with a remote host. For example, the following command synchronizes the local host (call it Host 2) with remote host Host1:
net time \\Host1 /set
You should avoid setting the system clock backwards on systems running an MQ broker. MQ uses timestamps to help identify internal objects such as transactions and durable subscriptions. If the system clock is set backwards it is theoretically possible that a duplicate internal identifier can be generated. The broker attempts to compensate for this by introducing some randomness to identifiers and by detecting clock shift when running, but if the system clock is shifted backwards by a significant amount when a broker is not running, then there is a slight risk of identifier duplication.
If you need to set the system clock backwards on a system running a broker by more than a few seconds, it is recommended that you either do it when there are no transactions or durable subscriptions, or do it when the broker is not running, then wait the amount of time you have shifted the clock before bringing the broker back up.
But the ideal approach is to synchronize clocks before starting up any brokers, and then use an appropriate technique to ensure that clocks don't drift significantly after deployment.
On the Solaris and Linux platforms, the shell in which the client or broker is running places a soft limit on the number of file descriptors that a client can use. In the MQ system, each connection a client makes, or each connection a broker accepts, uses one of these file descriptors. As a result, you cannot have a broker or client running with more than 256 connections on Solaris or 1024 on Linux without changing this limit. (The number is actually slightly lower than that due to file descriptors that are used for other purposes, such as for file-based persistence.)
To change this limit, see the ulimit man page or the instructions under "Increasing File Descriptors to Improve File-based Persistence Performance," below. The limit needs to be changed in each shell in which a client or broker will be executing.
On the Solaris and Linux platforms, the speed of storing messages in the default file-based persistence is affected by the number of file descriptors available for use by the file store. (Windows does not have a file descriptor limit.) A large number of descriptors will allow the system to process large numbers of persistent messages faster.
To improve performance for performance testing or deployment, administrators should increase the maximum number of file descriptors available to an application (in this case, the broker process) and then increase the size of the shared file descriptor pool used by the broker by updating the value of the property:
imq.persist.file.message.fdpool.limit
The value of this property must be less than the maximum number of file descriptors available on your system.
On Solaris, for example, you can increase the file descriptor limits using the ulimit command. Processes inherit system limits from their parent (login) shell. On Solaris, there is a "hard" limit and a "soft" limit. For a non-root user, the number of file descriptors for an application cannot exceed the soft limit, which, in turn, cannot exceed the hard limit.
To check the current file descriptor limits:
Hard limit: $ ulimit -Hn
Soft limit: $ ulimit -n
To change the file descriptor limits for "root" user:
# ulimit -Hn unlimited
# ulimit -n unlimited
After this, any process created from this shell will be able to open unlimited file descriptors. So it is safe to run the imqbroker command at this point.
To change the file descriptor limit for non-root user:
$ ulimit -Hn number1
$ ulimit -n number2
where number1 is less than 1024, and number2 is less than number1.
If 1024 is not enough, you have the following options:
The broker uses a persistent store that can contain, among other information, message files that are being temporarily stored. Since these messages might contain proprietary information, it is recommended that the data store be secured against unauthorized access.
A broker can use either the built-in or plugged-in persistence.
A broker using built-in persistence writes persistent data to a flat file data store located at:
IMQ_VARHOME/instances/brokerName/filestore/
(/var/imq/instances/brokerName/filestore/ on Solaris)
where brokerName is a name identifying the broker instance.
The brokerName/filestore/ directory is created when the broker instance is started for the first time. The procedure for securing this directory depends on the operating system on which the broker is running.
Solaris and Linux The permissions on the IMQ_VARHOME/instances/brokerName/filestore/ directory depend on the umask of the user that started the broker instance. Hence, permission to start a broker instance and to read its persistent files can be restricted by appropriately setting the umask. Alternatively, an administrator (superuser) can secure persistent data by setting the permissions on the IMQ_VARHOME/instances directory to 700.
Windows The permissions on the IMQ_VARHOME/instances/brokerName/filestore/ directory can be set using the mechanisms provided by the Windows operating system that you are using. This generally involves opening a properties dialog for the directory.
A broker using plugged-in persistence writes persistent data to a JDBC-compliant database.
For a database managed by a database server (for example, an Oracle database), it is recommended that you create a user name and password to access the MQ database tables (tables whose names start with "IMQ"). If the database does not allow individual tables to be protected, create a dedicated database to be used only by MQ brokers. See the database vendor for documentation on how to create user name/password access.
The user name and password required to open a database connection by a broker can be provided as broker configuration properties. However it is more secure to provide them as command line options when starting up the broker (see MQ Administrator's Guide, Appendix A, "Setting Up Plugged-in Persistence").
For an embedded database that is accessed directly by the broker via the database's JDBC driver (for example, a Cloudscape database), security is usually provided by setting file permissions (as described in "Built-in Persistent Store," above) on the directory where the persistent data will be stored. To ensure that the database is readable and writable by both the broker and the imqdbmgr utility, however, both should be run by the same user.
When the broker gets close to exhausting the JVM heap space used by Java objects, it uses various techniques such as flow control and message swapping to free memory. Under extreme circumstances it even closes client connections in order to free the memory and reduce the message inflow. Hence it is desirable to set the maximum JVM heap space high enough to avoid such circumstances.
However, if the maximum Java heap space is set too high, in relation to system physical memory, the broker can continue to grow the Java heap space until the entire system runs out of memory. This can result in diminished performance, unpredictable broker crashes, and/or affect the behavior of other applications and services running on the system.
This problem can be avoided by configuring a sensible Java heap size limit using the -Xmx Java command line argument. In general it is a good idea to evaluate the normal and peak system memory footprints, and configure the Java heap size so that it is large enough to provide good performance, but not so large as to risk system memory problems.
If you are running a JMS client that deals with large messages or many small messages, it may encounter OutOfMemoryError errors. The client runtime does not have a memory leak--it just has insufficient memory to copy the messages off the network and deliver them to your client.
To eliminate these OutofMemoryError errors, increase the maximum Java heap size. You can do this by passing the appropriate command line option to the java or jre command.
On Java2, use the -Xmx option when running the client application. For example:
java -Xmx128m MyClass
Please note these limitations:
To report a problem, send mail to imq-feedback@sun.com.
If you have a support contract and you have problems with MQ, contact Sun ONE customer support using one of the following mechanisms:
This site has links to the Knowledge Base, Online Support Center, and ProductTracker, as well as to maintenance programs and support contact numbers.
So that we can best assist you in resolving problems, please have the following information available when you contact support:
Beyond the MQ documentation, you can find additional information as indicated below.
A discussion forum is available for MQ customers. It provides a place for customers to exchange ideas on MQ-related topics and share problem-solving tips and techniques.
To subscribe to the jmq-interest list, send e-mail to listserv@java.sun.com and include a message like the following in the message body. Please supply the appropriate data for the first and last name.
subscribe jmq-interest firstname lastname
To unsubscribe to the list, send mail to listserv@java.sun.com and include in the message body:
signoff jmq-interest
| Note |
The jmq-interest forum is meant for general MQ issues. For specific questions about MQ, send your questions to imq-feedback@sun.com. |
There is a Sun ONE Message Queue forum available at the following location:
There is a JMS forum in the Java Technology Forums that might be of interest.
Useful Sun ONE information can be found at the following Internet locations: