Sun Java System Message Queue 3.7 UR1 Installation Guide

Migration Issues

This section covers issues you need to be aware of when migrating to Message Queue 3.7 UR1 from earlier versions of Message Queue. These issues fall into two general categories: platform issues and compatibility issues.

Note –

Migration from Message Queue versions earlier than 3.0.1 is not supported.

Platform Issues

This section describes issues specific to the Solaris, Linux, and Windows platforms.

Solaris

On the Solaris platform, you can install Message Queue 3.7 UR1 on top of Versions 3.0.x, 3.5, and 3.6, and your existing instance data (configuration properties, file-based persistent data store, log files, flat-file user repository, and access control properties file) will be used by Version 3.7 UR1 (see Compatibility Issues).

If you depended on the .jar files listed below to be in their Version 3.0.x locations, please note that they have been moved to the /usr/share/lib directory:

`activation.jar`	`jaxm-api.jar`
`commons-logging.jar`	`jms.jar`
`fscontext.jar`	`mail.jar`
`imq.jar`	`saaj-api.jar`
`imqxm.jar`	`saaj-impl.jar`

In Message Queue 3.0, these files were in the /usr/share/lib/imq directory; in Message Queue 3.0.1, they were in the /usr/share/lib directory with symbolic links in the /usr/share/lib/imq directory. In Message Queue 3.7 UR1, there are no symbolic links files.

Linux

On the Linux platform, you should not try to install Message Queue 3.7 UR1 on top of earlier versions, but should instead uninstall any earlier versions of Message Queue before installing Version 3.7 UR1. This is because the installed directory structure has been changed as of Message Queue 3.6, and this complicates the migration of instance data (configuration properties, file-based persistent data store, log files, flat-file user repository, and access control properties file) from Versions 3.0.x and 3.5 to Version 3.7 UR1. A utility program, mqmigrate, is provided to ease the migration of these data files from versions earlier than 3.6 (see Finding and Removing Earlier Message Queue Versions). (If you are upgrading from Message Queue 3.6, you do not need to use the mqmigrate utility, since the files are already in the correct locations.) After migrating the instance data files if necessary, you should uninstall any Message Queue 3.0.x, 3.5, and 3.6 Red Hat Package Manager (RPM) packages and then install the 3.7 UR1 RPM packages using mqinstall.

Scripts that use hard-coded paths to the Linux installations of Message Queue Versions 3.0.x or 3.5 will need to be changed to the new directory location for Message Queue 3.7 UR1. If you need symbolic links that point the old locations to the new locations, you must install the sun-mq-compat RPM package; this package may not be supported in future releases.

Windows

The upgrade procedure for Message Queue 3.7 UR1on the Windows platform varies depending on the previously installed version of Message Queue, as described in the following sections.

Message Queue 3.5 and 3.6

Before installingMessage Queue 3.7 UR1, you should uninstall any existing installations of Message Queue 3.5 or 3.6. If you are installing Version 3.7 UR1 in a different location than Versions 3.5 or 3.6, you must first move any instance data (configuration properties, file-based persistent data store, log files, flat-file user repository, and access control properties file) that you want to preserve from its old location, corresponding to the old value of the directory variable IMQ_VARHOME/instances/, to the new location, corresponding to the new value of IMQ_VARHOME/instances.

Message Queue 3.0.`x`

If you are upgrading from Message Queue 3.0.x to 3.7 UR1, it is likely that you will have to manually migrate any previous instance data (configuration properties, file-based persistent data store, log files, flat-file user repository, and access control properties file) from its Message Queue 3.0.x location to the new Message Queue 3.7 UR1 location, specified as follows:

IMQ_VARHOME\instances\instanceName

Compatibility Issues

Message Queue 3.7 UR1 is generally compatible with Message Queue 3.0.x, 3.5, and 3.6. However, changes have been made in broker properties, administered objects, persistence schemas, file locations, and administration tools that can affect migration from the earlier versions to Version 3.7 UR1.

The Message Queue 3.7 UR1 install operation does not remove or overwrite the Message Queue 3.0.x, 3.5, or 3.6 IMQ_VARHOME directory. This directory contains configuration and security-related files (see Broker Compatibility). Most of this data is compatible with Message Queue 3.7 UR1, 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.0.x, 3.5, or 3.6 to Message Queue 3.7 UR1 include the following:

Broker Compatibility

A Message Queue 3.7 UR1 message broker will interoperate with one from Versions 3.0.x, 3.5, or 3.6. 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.6 data is generally compatible with Message Queue 3.7 UR1 and requires no migration.
Message Queue 3.5 data is generally compatible with Message Queue 3.7 UR1 and can be used after migration to Message Queue 3.7 UR1.
Some Message Queue 3.0.x data is compatible with Message Queue 3.7 UR1, as described below, and can be used after migration to Message Queue 3.7 UR1.

When upgrading from Message Queue 3.0.x, 3.5, or 3.6 to Message Queue 3.7 UR1, 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 3.7 UR1 brokers.

Any persistent Message Queue 3.0.x, 3.5, or 3.6 data (messages, destinations, and durable subscriptions) is automatically converted to Message Queue 3.7 UR1 data when starting up a Message Queue 3.7 UR1 broker for the first time. For example, existing destinations will be converted to Message Queue 3.7 UR1 destinations, preserving existing attributes and using default values for new attributes.

For Message Queue 3.0.x, the automatic migration of persistent data leaves the original data intact in its original location. The migrated data, however,can no longer be used by a Message Queue 3.0.x broker. If this is a concern, save the original data to a secure location after migration. Otherwise, you can delete this data in any of the following ways:

Use the Broker utility's -upgrade-store-nobackup option when starting up the Message Queue 3.7 UR1 broker for the first time:

imqbrokerd -upgrade-store-nobackup
Delete the old persistent data store manually:
- For a file-based data store, delete the old persistent store, located at
  
  …/instances/instanceName/filestore/
- For a JDBC-based data store, delete the old tables using the command
  
  imqdbmgr delete oldtbl

Note: Applies to Message Queue 3.0.x only. You can continue to use the Message Queue 3.0.x user repository and access control properties files after installing Message Queue 3.7 UR1, however these files have been made instance-specific and are now placed in the …/instances/instanceName/etc directories. The Message Queue 3.7 UR1 installer does not overwrite the Message Queue 3.0.x files. When you first start up a Message Queue 3.7 UR1 broker, copies of the Message Queue 3.0.x files are placed in the appropriate Message Queue 3.7 UR1 location (see Appendix A, Platform-Specific Locations of Message Queue Data, in Sun Java System Message Queue 3.7 UR1 Administration Guide). If Message Queue 3.0.x user repository and access control properties files are not found at the old location, new files will be created in the …/instances/instanceName/etc directory.
If you mix Message Queue 3.0.x, 3.5, or 3.6 brokers and Message Queue 3.7 UR1 brokers in a cluster, the master broker must be a Message Queue 3.0.x, 3.5, or 3.6 broker (whichever is older), and the cluster will run as a Message Queue 3.0.x, 3.5, or 3.6 cluster.

Table 1–4 Compatibility of Message Queue 3.0.x Data with Message Queue 3.7 UR1


Data Category	Message Queue 3.0.`x` Location	Message Queue 3.7 UR1 Compatibility
Broker properties	IMQ_VARHOME/instances/`instanceName` /props/config.properties	New properties added Some property names changed Old property names still recognized
Persistent data store (messages, destinations, durable subscriptions)	IMQ_VARHOME/instances/`instanceName`/filestore/ or JDBC-accessible data store	Converted to Message Queue 3.7 UR1 format at `IMQ_VARHOME/instanceName/fs370` when Message Queue 3.7 UR1 broker started for the first time
Flat-file user repository	Solaris: `/etc/imq/passwd` Linux: `IMQ_HOME/etc/passwd` Windows: `IMQ_HOME\etc\passwd`	Compatible Automatically copied to `/instances/instName/etc/passwd` when Message Queue 3.7 UR1 broker started for the first time
Access control properties file	Solaris: `/etc/imq/accesscontrol.properties` Linux: `IMQ_HOME/etc/accesscontrol.properties` Windows: `IMQ_HOME\etc\accesscontrol.properties`	Compatible Automatically copied to `/instances/instName/etc/accesscontrol.properties` when Message Queue 3.7 UR1 broker started for the first time

Client Compatibility

Message Queue 3.7 UR1 message brokers and Java clients (applications and components) are two-way compatible with those from Message Queue 3.0.x, 3.5, or 3.6: that is, a Message Queue 3.7 UR1 broker will support a Message Queue 3.0.x, 3.5, or 3.6 Java client, and a Message Queue 3.7 UR1 Java client can connect to a Message Queue 3.0x, 3.5, or 3.6 broker. Expanded Message Queue 3.7 UR1 capabilities are unavailable in such cases, however.

Note –

C client programs cannot connect to a Message Queue 3.0.x broker; they are supported only by Message Queue 3.7 UR1 brokers or by Message Queue 3.5 and 3.6 brokers running with a trial or enterprise license.

Administered Object Compatibility

Message Queue 3.7 UR1 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.0.x, 3.5, or 3.6, it is best to upgrade your administered objects after installing Message Queue 3.7 UR1.

When performing an update operation, the Administration Console (imqadmin) and the ObjectManager command line utility (imqobjmgr) will automatically convert administered objects from Versions 3.0.x, 3.5, and 3.6 into Message Queue 3.7 UR1 form, using default values for the new attributes. The Message Queue 3.7 UR1 client runtime will also look up and instantiate administered objects from those earlier versions and convert them for use by Message Queue 3.7 UR1 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 3.7 UR1. For attributes that have been renamed in Message Queue 3.7 UR1, the old names will still work. (Recompiling the client with Message Queue 3.7 UR1 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 3.7 UR1,but must be rewritten in order to use the new attributes.

Administration Tool Compatibility

Because of the addition of new commands and new administrative capabilities, the Message Queue 3.7 UR1 administration tools (Administration Console and command line utilities) will work only with Message Queue 3.7 UR1 brokers. All Message Queue 3.0.x, 3.5, and 3.6 commands and command options remain supported, however.