This section covers issues you need to be aware of when migrating to Message Queue 4.3 from earlier versions of Message Queue. These issues fall into two general categories: platform issues and compatibility issues.
Upgrade from Message Queue versions earlier than 3.6 is not supported.
This section describes issues specific to the Solaris, Linux, and Windows platforms.
On the Solaris platform, you can upgrade to Message Queue 4.3 from an existing installation of Version 3.6 or 3.7, and your existing instance data (configuration properties, file-based persistent data store, log files, flat-file user repository, access control properties file) will be used by Version 4.3 (see Compatibility Issues).
On the Linux platform, you can upgrade to Message Queue 4.3 from an existing installation of Version 3.6 or 3.7, and your existing instance data (configuration properties, file-based persistent data store, log files, flat-file user repository, access control properties file) will be used by Version 4.3 (see Compatibility Issues).
Upgrading directly to Message Queue 4.3 from earlier versions is not supported on the Windows platform, but Version 4.3 can coexist with Versions 3.6 and 3.7 in different locations on the same system. How you treat existing Message Queue installations when installing Message Queue 4.3 depends on the previously installed version:
If you have an existing installation of Message Queue 3.5 or earlier, you should uninstall it (or upgrade it to Version 3.6 or later), using the uninstallation procedures described in the edition of the Message Queue Installation Guide corresponding to that version, before installing Message Queue 4.3.
If you have an existing installation of Message Queue 3.6 or 3.7, you can either uninstall it or leave it intact and simply install Message Queue 4.3 in a different location in your file system.
If you choose to uninstall your previous version before installing Message Queue 4.3, you may first want to back up any instance data (configuration properties, file-based persistent data store, log files, flat-file user repository, access control properties file) that you want to preserve. Instance data is not automatically migrated to the new Message Queue 4.3 location, so you must move or copy it manually from its old location in the previous installation’s IMQ_VARHOME\instances directory to that of the new installation (by default, C:\Program Files\Sun\MessageQueue\var\instances). After installing Message Queue 4.3, remove any references to uninstalled versions’ IMQ_HOME\bin directories from the system’s PATH environment variable and add the new Message Queue 4.3 installation’s IMQ_HOME\bin directory.
Message Queue 4.3 is generally compatible with Message Queue Versions 3.6 and 3.7. However, changes have been made in broker properties, administered objects, persistence schemas, file locations, and administration tools that can affect upgrade from the earlier versions to Version 4.3.
The Message Queue 4.3 Installer does not remove or overwrite the Message Queue 3.6 or 3.7 IMQ_VARHOME directory. This directory contains configuration and security-related files (see Broker Compatibility). Most of this data is compatible with Message Queue 4.3, and can be preserved using the instructions in the following sections.
Compatibility issues that you may need to address when migrating from Message Queue 3.6 or 3.7 to Message Queue 4.3 include the following:
A Message Queue 4.3 message broker will interoperate with one from Versions 3.0.x, 3.5, 3.6, or 3.7, and is able to migrate data from Versions 3.6 or 3.7. However, some changes have been made in broker properties and the persistent store schema. The degree of compatibility depends on the earlier Message Queue version from which you are upgrading:
Message Queue 3.7 data is fully compatible with Message Queue 4.3 and requires no data migration.
Message Queue 3.6 data is generally compatible with Message Queue 4.3 and requires no data migration.
Data from Message Queue 3.5 must be migrated by upgrading to Message Queue 3.6 or later before installing Message Queue 4.3.
When upgrading from Message Queue 3.6 or 3.7 to Message Queue 4.3, you can choose either of two approaches to handling the older versions’ instance configuration (config.properties) files:
Use the older config.properties files directly.
Copy the files to another location and consult the property settings they contain when you configure Message Queue 4.3 brokers.
Any persistent Message Queue 3.6 or 3.7 data (messages, destinations, and durable subscriptions) is automatically converted to Message Queue 4.3 data when starting up a Message Queue 4.3 broker for the first time. For example, existing destinations will be converted to Message Queue 4.3 destinations, preserving existing attributes and using default values for new attributes.
For Message Queue 3.6, the automatic upgrade leaves the original data intact in its original location. You can delete this data in either of the following ways:
Use the Broker utility’s -upgrade-store-nobackup option when starting up the Message Queue 4.3 broker for the first time:
imqbrokerd -upgrade-store-nobackup
Manually delete the old file-based persistent data store, located at
…/instances/instanceName/fs350
If you mix Message Queue 3.5, 3.6, or 3.7 brokers together with Message Queue 4.3 brokers in a cluster, you should consider the following issues:
Mixed broker versions. A conventional cluster can contain brokers of different versions if all brokers have a version at least as great as that of the master broker. If the cluster is not configured to use a master broker, then all brokers must be of the same version.
Matching broker property values. In addition to cluster configuration properties, the following broker properties also must have the same value for all brokers in a cluster:
imq.service.activelist
imq.autocreate.queue
imq.autocreate.topic
imq.autocreate.queue.maxNumActiveConsumers
imq.autocreate.queue.maxNumBackupConsumers
This restriction is particularly important when a cluster contains mixed broker versions that might contain properties with different default values. For example, If you are clustering a Message Queue version 4.3 broker together with versions 3.x, you must set the value of the imq.autocreate.queue.maxNumActiveConsumers property, which has different default values before and after version 4.1 (1 and -1, respectively), to be the same. Otherwise the brokers will not be able to establish a cluster connection.
When upgrading a broker cluster from versions 3.x to versions 4.x, it is recommended that you shut down all client applications and all brokers in the cluster, perform the Message Queue upgrades, check any data migrations, and then restart the cluster and client applications. It is not recommended that you attempt a rolling upgrade in which you successively upgrade brokers while maintaining messaging operations.
Message Queue 4.3 message brokers and Java clients (applications and components) are two-way compatible with those from Message Queue 3.6 or 3.7: that is, a Message Queue 4.3 broker will support a Message Queue 3.6 or 3.7 Java client, and a Message Queue 4.3 Java client can connect to a Message Queue 3.6 or 3.7 broker. Expanded Message Queue 4.3 capabilities are unavailable in such cases, however.
Message Queue 4.3 administered objects have been enhanced with new attributes, and some attributes have been renamed from earlier versions. Although you can continue to use object stores and administered objects created in Message Queue 3.6 or 3.7, it is best to upgrade your administered objects after installing Message Queue 4.3.
When performing an update operation, the Administration Console (imqadmin) and the Object Manager utility (imqobjmgr) will automatically convert administered objects from Versions 3.6 and 3.7 to Message Queue 4.3 form, using default values for the new attributes. The Message Queue 4.3 client runtime will also look up and instantiate administered objects from those earlier versions and convert them for use by Message Queue 4.3 clients, but this will not convert the objects permanently in the object store in which they reside.
Existing Message Queue clients that directly instantiate administered objects are compatible with Message Queue 4.3. For attributes that have been renamed in Message Queue 4.3, the old names will still work. (Recompiling the client with Message Queue 4.3 will show which attributes have been renamed.) However, clients will need to be rewritten if they are to use any of the new administered object attributes. Similarly, scripts that start Java clients and set administered object attribute values using command line options are compatible with Message Queue 4.3,but must be rewritten in order to use the new attributes.
Because of the addition of new commands and new administrative capabilities, the Message Queue 4.3 administration tools (Administration Console and command line utilities) will work only with Message Queue 4.3 brokers. All commands and command options from earlier Message Queue versions remain supported, however.