Sun ONE Message Queue 3.0.1 SP3 Release Notes
Sun ONE Message Queue Release Notes
Version 3.0.1 SP3
Part Number 817-6265-10
These release notes contain important information available at the time of release of Version 3.0.1 Service Pack 3 (SP3), of Sun Open Net Environment (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 SP3.
The most up-to-date version of these release notes can be found at the Sun ONE documentation web site: http://docs.sun.com/coll/S1_MessageQueue_301_SP3. 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 manuals.
These release notes contain the following sections:
Table 1 Revision History
Description of Changes
The following changes were made to this document:
The following changes were made to this document:
- Slight changes were made in the organization of the document and in clarification of version numbers.
- Added new section, What’s New in Message Queue.
- Added bugs 4879448, 4883126, 4888270, and 4883126 to Known Bugs.
- Added bugs 4683129, 4735757, 4758424, 4758427, 4770212, 4770518, 4809079, 4821708, 4828860, 4835586, 4879448 to Bugs Fixed in Message Queue 3.0.1 Versions.
Initial release of this document
Java Message Service (JMS) Compliance
MQ 3.0.1 versions have 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)
What’s New in Message Queue
This section summarizes the features introduced with each Service Pack release of Message Queue 3.0.1.
In these Release Notes, references to 3.0.1 versions refer to 3.0.1, 3.0.1 SP1, 3.0.1 SP2, and SP3 respectively.
The MQ 3.0.1 SP3 product includes all the new features of previous MQ 3.0.1 SPx releases. It is fully backward compatible with the 3.0.1 SP2 version.
Features New in Message Queue 3.0.1 SP3
MQ 3.0.1 SP3 contains no new features other than bug fixes.
MQ 3.0.1 SP3 adds support for the following:
Features New in Message Queue 3.0.1 SP2
MQ 3.0.1 SP2 includes two new capabilities as compared to MQ 3.0.1:
Features New in Message Queue 3.0.1
MQ 3.0.1 includes two new capabilities as compared to MQ 3.0:
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.
Features New in Message Queue 3.0
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.
Both Enterprise and Platform Editions
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.)
Developers of applications that run in the Sun ONE Application Server environment are limited to using the JMS 1.0.2 API. This is because the Application Server complies with the J2EE 1.3 specification, which supports only JMS 1.0.2. This means that any JMS messaging performed in servlets and EJBs (including message-driven beans) must be based on the domain-specific JMS APIs.
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).
Enterprise Edition Only
Message Queue Documentation Updates
The following MQ 3.0.1 and MQ 3.0.1 SP2 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/coll/S1_MessageQueue_301.
The MQ Installation Guide has been updated to include changes to MQ 3.0.1 SP3 (see "Features New in Message Queue 3.0.1 SP2").
The MQ Administrator’s Guide has been updated to include new features that are in MQ 3.0.1 (see "Features New in Message Queue 3.0.1").
The MQ Developer’s Guide has been updated to include new features that are in MQ 3.0.1 (see "Features New in Message Queue 3.0.1").
MQ 3.0.1 versions are fully compatible with MQ 3.0, and upgrading from MQ 3.0 to MQ 3.0.1 SPx requires no changes in broker configuration, administered objects, administration tools, or client applications.
However, MQ 3.0.1 versions (hereafter in this section simply referred to as 3.0.1) are 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 2, 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:
- You can copy iMQ 2.0 config.properties files to another location and, in most cases, consult the property settings they contain when you configure MQ 3.0.1 brokers.
- Any persistent iMQ 2.0 data—messages, destinations, durable subscriptions—cannot be re-used. In particular, you will need to re-create iMQ 2.0 destinations in your MQ 3.0.1 brokers.
- You can continue to use iMQ 2.0 user repository and access control properties files after installing MQ 3.0.1. The MQ 3.0.1 installer does not overwrite these files. However, you will have to move them to the appropriate MQ 3.0.1 location (see Appendix D of MQ Administrator’s Guide).
Table 2 Compatibility of MQ 3.0.1 with iMQ 2.0 Data
iMQ 2.0 Data Category
Location of iMQ 2.0 Data
Compatibility with MQ 3.0.1
Incompatible; do not use.
Persistent store (messages,
destinations, durable subscriptions, transactions)
or JDBC accessible data store
Incompatible; do not use.
local directory or LDAP server
Compatible; can use and/or convert to 3.0.1
Security: user repositories
or LDAP server
Move to following location:
(/etc/imq/passwd on Solaris)
Security: access control file
Move to following location:
(/etc/imq/... on Solaris)
Administered Object Compatibility
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:
- You can use the same object store and administered objects that you created in iMQ 2.0; however, it is best to upgrade your administered objects after installing MQ 3.0.1. The Administration Console (imqadmin) and the ObjectManager command line utility (imqobjmgr), when performing an update operation, will convert iMQ 2.0 administered objects into MQ 3.0.1 administered objects.
- The MQ 3.0.1 client runtime will look up and instantiate iMQ 2.0 administered objects by converting them into local MQ 3.0.1 administered objects, but this will not convert iMQ 2.0 administered objects in the object store into MQ 3.0.1 administered objects.
- JMS clients (applications and/or components) that directly instantiate administered objects—that is, that are JMS provider-dependent—need to be rewritten to accommodate new administered object attribute names (see Chapter 4 and Appendix A of the MQ Developer’s Guide for information on administered object attributes).
- Scripts that start JMS clients and which set administered object attribute values using command line options need to be rewritten to accommodate the new administered object attribute names (see Chapter 4 and Appendix A of the MQ Developer’s Guide for information on administered object attributes).
Administration Tool Compatibility
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:
- Any scripts that use command line utilities (imqbrokerd, imqcmd, imqobjmgr, and so forth) need to be edited to replace the old commands with the newly-named commands. Note, especially, that the jmqbroker command is now imqbrokerd.
- The Administration Console (imqadmin) allows you to manage several brokers and/or object stores concurrently, and saves the list of managed entities that are displayed in the navigational pane on the left side of the screen. Thus each time you launch the Console, the list of managed entities is re-displayed. The name of the directory in which user settings for the iMQ 2.0 Administration Console were stored has changed for MQ 3.0.1. If you wish to preserve the old Console settings when upgrading from iMQ 2.0 to MQ 3.0.1, you need to change the name of the directory where the brokerlist.properties and objstorelist.properties files are stored from $HOME/.jmq/admin to $HOME/.imq/admin, where $HOME is the Console user’s home directory.
When upgrading from iMQ 2.0 to MQ 3.0.1, you should consider the following:
- An MQ 3.0.1 broker will support the iMQ 2.0 client runtime (but without additional MQ 3.0.1 capabilities), but an iMQ 2.0 broker will not support the MQ 3.0.1 client runtime.
- JMS clients built on JDK 1.2, 1.3, or 1.4 can inter-operate with a broker running JRE 1.4. However, clients that use a secure (SSL-based) connection to a broker will require additional JSSE and JNDI libraries if they are not built on JDK 1.4 (which includes these libraries).
- The JMS 1.1 API (supported by MQ 3.0.1) clarifies the behavior of the Message.acknowledge() method, used to acknowledge message consumption in CLIENT_ACKNOWLEDGE sessions. This might require you to modify existing JMS clients.
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.
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 versions or to the Enterprise Edition only.
Both Enterprise and Platform Editions
- Windows platforms set limits to the number of connections to a broker that can be simultaneously started over TCP/IP, in accordance with the maximum value of the backlog size. Backlog is the buffer for connections in the TCP stack—the number of simultaneous TCP connection startups cannot exceed the backlog size. For example, Windows 2000 Professional limits the backlog to 5, and Windows 2000 Server limits the backlog to 200.
- You cannot edit a broker’s instance configuration file without having started the broker instance at least once. This is because the config.properties file does not exist until the broker instance is first started. To configure a broker to use pluggable persistence or to set other configuration properties, run the broker once (with the instance name that should be used to create the broker) to create the config.properties file:
Enterprise Edition Only
- The broker’s shared thread pool model does not work on Windows platforms (due to a bug in J2SE 1.4.0). This is expected to be fixed in J2SE 1.4.1, but has not yet been tested.
- Only fully-connected broker clusters are supported in this release. This means that every broker in a cluster must communicate directly with every other broker in the cluster. If you are connecting brokers using the imqbrokerd -cluster command line argument, be careful to ensure that all brokers in the cluster are included.
- If a Master Broker is not used in a broker cluster, persistent information stored by a broker being added to the cluster is not propagated to other brokers in the cluster.
- A connection service using SSL is currently limited to supporting only self-signed server certificates, that is, host-trusted mode. The connection configuration property imqSSLIsHostTrusted is set to true by default.
- When a JMS client using the HTTP transport terminates abruptly (for example, using Ctrl-C) the broker takes approximately one minute before the client connection and all the associated resources are released.
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 SP3 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 email@example.com.
Table 3 Bug Descriptions
In extremely rare cases, calling the methods Connection.stop, Connection.start, and Connection.close at the same time as calling the methods Session.recover and Session.rollback (in separate threads) may result in an unexpected message redelivery order.
Workaround: make sure your calls to the Connection… and Session… methods specified above are serialized either by using the same thread or by using synchronization.
The -javahome option in all solaris/win scripts does not work if the value has a space.
The -javahome option is used by the MQ commands and utilities to specify an alternate Java 2 compatible runtime to use. However, the path to the alternate Java runtime must be located at a path that does not contain spaces.
Examples of paths that have spaces are:
C:\jdk 1.4 (On Windows the path can contain spaces if the entire path is placed in quotes; for example, “C:\jdk 1.4”)
Workaround: Install the Java runtime at a location or path that does not contain spaces.
In the Japanese locale, the output of various admin utilities is not properly aligned in columns and the borders are too short.
QueueBrowser should function without first calling connection.start().
Connection.start() must be called on a Connection before a QueueBrowser can browse a Queue. If you fail to call Connection.start() the QueueBrowser enumeration will block on nextElement(), and eventually throw a java.util. NoSuchElementException.
Workaround: Call Connection.start() before calling QueueBrowser.getEnumeration().
Heavy consumer creation/destruction w/ autocreate queues can cause message loss
In rare stress situations it is possible for a message to be lost from an auto-created queue destination.
The error will occur if, after all messages delivered from the queue have been acknowledged, the queue’s last message consumer is removed at the same time a new message producer (on a different connection) sends a message to that queue. What happens is that the queue is “auto-removed” (it is empty without any consumers) just as the new message arrives, causing the new message to be lost.
Workaround: Create queues administratively using MQ administration tools.
The Auto-reconnect feature does not work properly.
The number of consumers grows after each auto-reconnect which causes the broker to send duplicate messages.
Workaround: None. This bug will be fixed in MQ 3.5.
Broker does not release memory when running w/jdk1.4.2 and server vm
Workaround: Use the clientvm. The broker should be started using the following command:
On linux RHAS 2.1, if the broker is under heavy connection loads, new connections may randomly fail with “No threads are available to process a new connection,” even though threads should be available based on the current connection count.
Workaround: Retry the connection.
Bugs Fixed in Message Queue 3.0.1 Versions
Below is a short description of the most important bugs fixed in MQ 3.0.1, 3.0.1 SP1, 3.0.1 SP2, and 3.0.1 SP3 releases. The table also specifies the release in which the bug was fixed.
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:
Table 4 Bugs Fixed in MQ 3.0.1 versions
The HTTP tunnel applets can hang during reload.
Client calling Connection.close() from Exception Listener could cause deadlock.
Client reconnect does not set client identifier on new connection.
Consumers stops receiving messages in some flow control situations.
Re-transmitting a message originally sent in a transaction causes Broker Error
Sun ONE Message Queue Version 3.0.1 is not swapping persistent messages to disk when the heap fills to RED memory states.
There is a boolean expression that determines if a message has incorrect logic. If the logic is incorrect, then the message should be swapped out. This means that in some cases, persistent messages will be swapped out of memory. If the ability to swap non-persistent messages is turned off, it always evaluates correctly for persistent messages
Unbounded growth in Java process native heap segment with server VM.
imqadmin: modal dialogs can get into deadlock situation
Under certain circumstances the broker will not swap messages to disk.
Master broker backup - restore cycle can cause loss of destination information.
MQ performance degrades with selector - gets worse as # of clients increases.
Session.createProducer(null) throws NullPointerException.
The broker does not shut down properly if there are SSL based connections.
Windows broker service terminates on logout.
Pausing and resuming a service causes client connections to hang if the connections have no pending messages.
Round-robin queue consumers can get “stuck” if the last queued message expires prior to delivery.
Performance degrades on round-robin queue when > 10k message backlog.
A consumer will throw an exception if more than 50 messages are received in a transaction prior to calling commit().
Broker log timestamp is incorrect between midnight and 1am.
Corrections in the example applications README file (demo/jms/README)
For messages acknowledged as part of a consumer-side transaction, broker holds on to some unnecessary state information for each acknowledged message until the consumer is closed.
The Administration Console cannot be launched on Solaris or Linux if the CLASSPATH environment variable is set
Client does not clean up local transaction after ending an XA transaction
Standalone JTS/XA transaction completion may fail occasionally, even after a normal, error-free XAConnection.close().
Client can get an EOFException when rapidly creating and closing connections to the broker.
Client sometimes throws JMSException on connection.close() when TLS is used as transport.
Functionality Marked as Optional in JMS
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:
Table 5 Optional JMS Functionality
Section in JMS Specification
Description and MQ Handling
“Since message ID’s take some effort to create and increase a message’s size, some JMS providers may be able to optimize message overhead if they are given a hint that message ID is not used by an application. JMS Message Producer provides a hint to disable message ID.”
MQ implementation: Product does not disable Message ID generation (any setDisableMessageID() call in MessageProducer is ignored). All messages will contain a valid MessageID value.
Overriding Message Header Fields
“JMS does not define specifically how an administrator overrides these header field values. A JMS provider is not required to support this administrative option.”
MQ implementation: The MQ product supports administrative override of the values in message header fields through configuration of connection factory administered objects.
JMS Defined Properties
“JMS Reserves the ’JMSX’ Property name prefix for JMS defined properties.”
“Unless noted otherwise, support for these properties is optional.”
MQ implementation: The JMSX properties defined by the JMS 1.1 specification are supported in the MQ product.
“JMS reserves the ’JMS_<vendor_name>’ property name prefix for provider-specific properties.”
MQ implementation: The purpose of the provider-specific properties is to provide special features needed to support JMS use with provider-native clients. They should not be used for JMS to JMS messaging. MQ 3.0.1 does not use provider-specific properties.
“JMS does not require that a provider support distributed transactions.”
MQ implementation: Distributed transactions are supported in this release of the MQ product.
“For PTP <point-to-point distribution model>, JMS does not specify the semantics of concurrent QueueReceivers for the same queue; however, JMS does not prohibit a provider from supporting this.” See section 5.8 of the JMS specification for more information.
MQ implementation: The MQ implementation supports three queue delivery policies: Failover, Round Robin, and Single (default). For more information, refer to the MQ Administrator’s Guide.
This section contains short write-ups on the following topics:
System Clock Settings
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:
Linux The command is similar to Solaris, but you must provide the -s option:
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:
Avoid Setting System Clocks Backwards
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.
OS-Defined Connection Limitations on Clients and Brokers
On the Solaris and Linux platforms, the shell in which the client or broker is running places a soft limit on the number of file descriptors that a client can use. In the 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.
Increasing File Descriptors to Improve File-based Persistence Performance
On the Solaris and Linux platforms, the speed of storing messages in the default file-based persistence is affected by the number of file descriptors available for use by the file store. (Windows does not have a file descriptor limit.) A large number of descriptors will allow the system to process large numbers of persistent messages faster.
To improve performance for performance testing or deployment, administrators should increase the maximum number of file descriptors available to an application (in this case, the broker process) and then increase the size of the shared file descriptor pool used by the broker by updating the value of the property:
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:
To change the file descriptor limits for “root” user:
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:
where number1 is less than 1024, and number2 is less than number1.
If 1024 is not enough, you have the following options:
Securing Persistent Data
The 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.
Built-in Persistent Store
A broker using built-in persistence writes persistent data to a flat file data store located at:
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.
Plugged-in Persistent Store
A broker using plugged-in persistence writes persistent data to a JDBC Compliant database.
For a database managed by a database server (for example, an Oracle database), it is recommended that you create a user name and password to access the 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.
Broker Memory Configuration
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.
Client Out of Memory Errors
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:
Please note these limitations:
- The maximum limit of the VM’s memory allocation pool (heap size) depends on both the operating system and the JDK release. Please check the JDK documentation for restrictions.
- The size of the VM’s memory allocation pool must be less than or equal to the amount of virtual memory available on the system.
How to Report Problems
To report a problem, send mail to firstname.lastname@example.org.
If you have a support contract and you have problems with MQ, contact Sun customer support using one of the following mechanisms:
- Sun Support & Training web site at http://www.sun.com/supportraining/
This site has links to the Online Support Center, Knowledgebase, and Sun Support Forums as well as to support contact numbers and related support and training information.
- The telephone dispatch number associated with your maintenance contract
So that we can best assist you in resolving problems, please have the following information available when you contact support:
- Description of the problem, including the situation where the problem occurs and its impact on your operation
- Machine type, operating system version, and product version, including any patches and other software that might be affecting the problem
- Detailed steps on the methods you have used to reproduce the problem
- Any error logs or core dumps
For More Information
Beyond the MQ documentation, you can find additional information as indicated below.
Sun ONE Software Forum
There is a Sun ONE MQ forum available at the following location:
Java Technology Forum
There is a JMS forum in the Java Technology Forums that might be of interest.
Sun Welcomes Your Comments
Sun is interested in improving its documentation and welcomes your comments and suggestions. Use the web-based form to provide feedback to Sun:
Please provide the full document title (Sun ONE Message Queue 3.0.1 SP3 Release Notes) and part number in the appropriate fields. 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 part number of these Release Notes document is 817-6265-10.
Additional Sun Resources
Useful Sun ONE information can be found at the following Internet locations:
- Documentation for Sun ONE Message Queue
- Sun ONE Message Queue product information
- Sun ONE Documentation
- Sun ONE Professional Services
- Sun ONE Software Products and Service
- Sun ONE Software Support Services
- Sun ONE Support and Knowledge Base
- Sun Support and Training Services
- Sun ONE Consulting and Professional Services
- Sun ONE Developer Information
- Sun Developer Support Services
- Sun ONE Software Training
- Sun Software Data Sheets
Copyright © 2004 Sun Microsystems, Inc. All rights reserved.
Sun, Sun Microsystems, the Sun logo, Solaris, Java, the Java Coffee Cup logo, JDBC, and JDBC Compliant are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. Use of Sun ONE Message Queue is subject to the terms described in the license agreement accompanying it.