Sun Java Enterprise System 2005Q4 Upgrade Guide |
Chapter 7
Message QueueThis chapter describes how to upgrade Message Queue software from previous Java ES versions to Java ES 2005 (Release 4): Sun Java System Message Queue 3 Enterprise Edition 2005Q4.
The chapter provides a general overview of Message Queue upgrade issues and procedures for the different upgrade paths supported by Java ES Release 4. The chapter covers upgrades on both the Solaris and Linux operating systems:
Overview of Message Queue UpgradesThis section describes the following general aspects of Message Queue that impact upgrading to Java ES 2005Q4 (Release 4):
About Java ES Release 4 Message Queue
Java ES Release 4 Message Queue represents minor code fixes with no new features or enhancements. As such, Release 4 does not introduce any new compatibility issues (see Compatibility Issues).
Message Queue software includes two editions, a Platform Edition and an Enterprise Edition, each corresponding to a different feature set and licensed capacity. Enterprise edition is for deploying and running messaging applications in an enterprise production environment. Platform Edition is mainly for developing, debugging, and load testing messaging applications and components. The Platform Edition can be downloaded free from the Sun website and is also bundled with the Solaris OS and with the Java ES Application Server platform. An upgrade from an earlier Java ES release version to Release 4 converts any installed Platform Edition to Enterprise Edition.
Message Queue Upgrade Roadmap
Table 7-1 shows the supported Message Queue upgrade paths to Java ES Release 4. The table applies to both Solaris and Linux operating systems.
Table 7-1 Upgrade Paths to Java ES Release 4 Message Queue 3.6 SP3 2005Q4
Java ES Release
Message Queue Version
General Approach
Re-configuration Required
Release 3
Sun Java System Message Queue
2005Q2 (3.6)
Enterprise Edition onlyDirect upgrade:
Performed using the mqupgrade script.None
Release 2
Sun Java System Message Queue
2004Q2 (3.5)
Platform and Enterprise EditionsDirect upgrade:
Performed using the mqupgrade script.Performed automatically on Solaris platforms, and an mqmigrate script is available on Linux platforms.
Release 1
Sun Java System Message Queue
3.01 SP2
Platform and Enterprise EditionsDirect upgrade not certified:
But can be performed using the mqupgrade script.Performed automatically on Solaris platforms, and an mqmigrate script is available on Linux platforms.
Pre-dates Java ES releases
Sun Java System Message Queue
3.01 SP1 and earlier versions
Platform and Enterprise EditionsNo direct upgrade:
But you can upgrade first to Release 3 using procedures in the Java Enterprise System 2005Q1 Upgrade and Migration Guide
(http://docs.sun.com/doc/819-0062).Then upgrade from Release 3 to Release 4.
In addition to the Java ES releases of Message Queue shown in Table 7-1, Message Queue Platform Edition is also bundled with Solaris operating system software. Upgrade of the bundled versions of Message Queue to Release 4 Enterprise Edition can be performed by the Java ES installer. You simply select Message Queue for installation by the installer, as in a new install, and the installer software will automatically upgrade the bundled version, performing any re-configuration of Message Queue that might be necessary.
Message Queue Data
Message Queue, like other Java ES components, makes use of various kinds of data that for any specific upgrade might need to be migrated to an upgraded version. The following table shows the type of data that could be impacted by an upgrade of Message Queue software.
Table 7-2 shows the location of data on Solaris systems. The location on Linux systems is similar, and can be found in the Message Queue Administration Guide (http://docs.sun.com/doc/819-2571). In Table 7-2, instanceName identifies the name of the Message Queue broker instance with which the data is associated.
Compatibility Issues
Release 4 Message Queue introduces no new incompatibilities over Release 3. The following general Message Queue compatibility issues relate to versions earlier than Release 3.
Protocol Compatibility
Message Queue has a dependency on a web container to provide HTTP protocol support between Message Queue clients and broker. Due to a protocol change, when using Sun Java System Web Server to provide a web container for the Message Queue imqhttp.war application, you cannot upgrade the Web Server component without also upgrading Message Queue (see Post-Upgrade Tasks on (more...) and(more...) .
Broker Compatibility
A Release 4 Message Queue broker will inter-operate with a Release 3 or Release 2 broker, however changes in broker properties and the persistent store schema with respect to Release 2 can impact compatibility.
Release 4 Message Queue can use Release 3 and Release 2 data, except that on Linux systems, Release 2 data must be first migrated to Release 4.
When updating to Release 4 Message Queue, consider the following:
- You can use earlier Message Queue config.properties files. You can also copy them to another location and consult the property settings they contain when you configure Release 4 Message Queue brokers.
- Any persistent Message Queue data—messages, destinations, durable subscriptions—is automatically converted, if necessary, to Release 4 Message Queue data when starting up a broker for the first time. For example, any existing destinations will be converted, if necessary, to Release 4 Message Queue destinations, preserving existing attributes and using default values of new attributes.
- If you mix Message Queue Release 2 brokers and Message Queue Release 4 brokers in a cluster, the master broker must be a Message Queue Release 2 broker (whichever is older), and the cluster will run as a Message Queue Release 2 cluster.
Administered Object Compatibility
Release 4 Message Queue administered objects are identical to Release 3 administered objects. However, some Release 3 administered objects were renamed or enhanced with new attributes with respect to earlier versions. Therefore, when upgrading from Release 2 Message Queue to Release 4, you should consider the following:
- You can use the same object store and administered objects that you created in Release 2; however, it is best to migrate your administered objects to Release 4. The Administration Console (imqadmin) and the ObjectManager command line utility (imqobjmgr), when performing an update operation, will convert Release 2 administered objects into Release 4 administered objects.
- The Release 4 client runtime will look up and instantiate Release 2 administered objects and convert them for use by Release 4 clients. However, this will not convert Release 2 administered objects residing in the object store from which the lookup was made.
- Existing Release 2 clients (applications and/or components)—that is, clients that directly instantiate administered objects rather than look them up—are compatible with Release 4. However, if they are to use the new administered object attributes (see Chapter 16 of the Message Queue Administration Guide (http://docs.sun.com/doc/819-2571) for information on administered object attributes), they will need to be rewritten. (Re-compiling Release 2 clients with Release 4 will show which Message Queue Release 2 attributes have been renamed in Release 4. The old names will still work.)
- Scripts that start Java clients and which set administered object attribute values using command line options are compatible with Release 4. However, if they are to use the new administered object attributes (see Chapter 16 of the Message Queue Administration Guide (http://docs.sun.com/doc/819-2571) for information on administered object attributes), they will need to be rewritten.
Administration Tool Compatibility
Because of the addition of new commands and new administrative capabilities in Release 3, the Release 4 administration tools (the Administration Console and command line utilities) only work with Release 3 and Release 4 brokers. However, all Release 2 commands and command options remain supported.
Client Compatibility
Release 3 clients are completely compatible with Release 4 Message Queue. When upgrading from Release 2 to Release 4, however, you should consider the following compatibility issues, regarding Java clients:
- A Release 4 broker will support a Release 2 client (but without additional Release 4 capabilities).
- A Release 4 Java client can connect to a Release 2 broker (but without additional Release 4 capabilities).
- C client programs are supported only by Release 2, Release 3, or Release 4 brokers running with a trial license (Platform Edition) or Enterprise Edition license.
Message Queue Dependencies
Message Queue dependencies on other Java ES components can impact the procedure for upgrading and re-configuring Message Queue software. Changes in Message Queue interfaces or functions, for example, could require upgraded version of components upon which Message Queue depends. The need to upgrade such components depends upon the specific upgrade path.
Message Queue has dependencies on the following Java ES components:
- Shared components. Message Queue has dependencies on specific Java ES shared components (see Table 1-6).
- Directory Server (optional). If you want to configure Message Queue to store administered objects and/or user data in an LDAP directory rather than locally, then you can use Directory Server for that purpose.
- Web Container (optional). If you need HTTP messaging between client and broker, then Message Queue requires web container support from Java ES Web Server, Java ES Application Server, or third-party web containers.
Upgrading Message Queue from Java ES Release 3This section includes information about upgrading Message Queue from Java ES 2005Q1 (Release 3) to Java ES Release 4. The section covers the following topics:
Introduction
When upgrading Java ES Release 3 Message Queue to Release 4, consider the following aspects of the upgrade process:
- General Upgrade Approach. The upgrade is performed using an mqupgrade script that replaces previous software packages with new ones and migrates configuration data from Release 3 automatically.
- Upgrade Dependencies. While Message Queue has dependencies on a number of Java ES shared components (see Table 1-6), Release 4 Message Queue is compatible with the Release 3 versions of all these components. Upgrade of these shared components is therefore optional with respect to upgrade of Message Queue to Release 4.
In addition, Release 4 Message Queue is optionally dependent on Directory Server and Web Server (or Application Server), as described in Message Queue Dependencies. However, these are soft upgrade dependencies; upgrade of these components is optional with respect to upgrade of Message Queue to Release 4.
- Backward Compatibility. Release 4 Message Queue is fully compatible with Release 3 (see Compatibility Issues).
- Upgrade Rollback. There is no utility for rolling back the Message Queue upgrade to Release 3. You have to remove the upgraded components and manually restore the previous version and configuration data.
- Platform Issues. The general approach for upgrading Message Queue is the same on both Solaris and Linux operating systems. The procedures that follow indicate platform-specific commands or file locations where appropriate.
Release 3 Message Queue Upgrade
This section describes how to perform a Message Queue upgrade from Java ES Release 3 to Java ES Release 4:
Pre-Upgrade Tasks
Before you upgrade Message Queue, perform the procedures described in the following sections. Where the procedure depends on platform-specific commands, the task will indicate the operating system to which it applies.
Verify Current Version Information (Solaris Systems)
You can determine the version and edition of Message Queue installed on your system by starting the Message Queue broker with the -version option:
imqbrokerd -version
Upgrade Message Queue Dependencies
It is generally recommended that all Java ES components on a computer system (and in a computing environment) be upgraded to Java ES Release 4. However, because Message Queue does not require upgrading the Java ES Release 3 components upon on which it depends, this task is optional.
However, if you choose to upgrade all Message Queue dependencies, they should be upgraded in the following order, all before you upgrade Message Queue. You can skip any that might already have been upgraded.
- Shared Components. Instructions for upgrading Java ES shared components to Release 4 are provided in Chapter 2, "Upgrading Java ES Shared Components").
- Directory Server (optional). Instructions for upgrading Directory Server to Release 4 are provided in Chapter 4, "Directory Server and Administration Server".
- Web Container Software (optional). Instructions for upgrading Web Server or Application Server are provided in Chapter 6, "Web Server" and Chapter 9, "Application Server", respectively.
Back Up Message Queue
There is no script for rolling back Message Queue to its pervious state. Because Release 4 data is compatible with Release 3 data, there is no reason to back up configuration data. In addition, there is no reason to back up the installed image because you can use the Release 3 installer should you need to roll back Release 4 Message Queue to Release 3.
Upgrading Release 3 Message Queue
The upgrade of Message Queue software to Java ES Release 4 makes use of the mqupgrade script, which installs freshbitted packages that contain the patches shown in Table 7-4.
Table 7-4 Patches1 to Upgrade Message Queue
Component
SPARC
Solaris 8, 9, & 10
X86
Solaris 9 & 10
Linux
Message Queue Core
119132-06
119133-06
119136-06
Message Queue C-runtime
119134-04
119135-04
Message Queue
jmsclient & xmlclient
119137-04
Message Queue localization
119691-03
119692-03
119693-03
1Patch revision numbers are the minimum required for upgrade to Java ES Release 4. If newer revisions become available, use the newer ones instead of those shown in the table.
The upgrade procedure consists of the following steps:
- Stop any running Message Queue client applications.
If Message Queue is being used in an Application Server environment, shut down Application Server, as well.
- Stop any running brokers. You will be prompted for the admin user name and password.
imqcmd shutdown bkr [-b hostName:port]
- If you do not want to preserve dynamic data, the Message Queue flat-file user repository, and the Message Queue access control file associated with each broker instance, remove this data using the following command.
imqbrokerd -name instanceName -remove instance
Otherwise, dynamic data and configuration information will be retained and used for Release 4 Message Queue.
- Log in as Root.
su -
- Change directories to the location of the Tools directory of the Java ES distribution.
On Solaris SPARC:
cd Solaris_sparc/Product/message_queue/ToolsOn Solaris x86:
cd Solaris_x86/Product/message_queue/ToolsOn Linux x86:
cd Linux_x86/Product/message_queue/Tools- Run the mqupgrade script.
- Start the script:
./mqupgrade
The mqupgrade script lists installed Message Queue components.
- Enter y (yes) to upgrade Message Queue components.
The mqupgrade script detects and lists installed localization files.
If you do not want to upgrade Message Queue components, enter n (no). The mqupgrade script will exit without upgrading Message Queue components.
- If prompted, enter y (yes) to upgrade localization files.
The mqupgrade script sends output to a log file in the following location:
/var/sadm/install/logs/Message_Queue_upgrade_'date'.log
Verifying the Message Queue Upgrade
After you finish the upgrade procedure, verify that it was successful by starting the Message Queue broker with the -version option.
The command returns the Java ES version number as well as the Message Queue-specific version number.
Post-Upgrade Tasks
If you have upgraded the web container and are using the Message Queue HTTP tunneling servelet, you may need to re-deploy it in the new web container. Otherwise, there has been no change to the HTTP tunneling servlet between Release 3 and Release 4, and you do not need to re-deploy it after upgrading Message Queue to Release 4. See the Message Queue Administration Guide, (http://docs.sun.com/doc/819-2571) for more information on HTTP support.
Rolling Back the Upgrade
No scripts are provided for rolling back Message Queue to its pre-upgrade state. The process must be performed manually using the following steps:
- Stop any running Message Queue client applications.
- Stop any running brokers. You will be prompted for the admin user name and password.
imqcmd shutdown bkr [-b hostName:port]
- If you want to delete dynamic data, the Message Queue flat-file user repository, and the Message Queue access control file associated with each broker instance, remove this data using the following command.
imqbrokerd -name instanceName -remove instance
- Log in as root or become superuser.
su -
- Retrieve the list of installed Message Queue packages with the following command:
Solaris:
pkginfo | grep -i "message queue"Linux:
rpm -qa | grep mq- Remove the Message Queue packages, using the following command:
Solaris:
pkgrm packageName
where packageName is any of the Message Queue packages. To remove multiple packages, separate the package names by a space.Linux:
rpm -e --nodeps RPMName
where RPMName is any of the Message Queue rpm components. To remove multiple components, separate the RPM names by a space.Because other products might be using Message Queue packages, be careful about removing them. The pkgrm command will warn you of any dependencies on a package before removing it. When prompted, confirm your removal request by typing y (yes).
- Type “q” to quit.
- Exit the root shell.
- Re-install Release 3 Message Queue.
Use the Java ES Release 3 installer. Release 4 Message Queue data will work fine.
Multiple Instance Upgrades
To upgrade a Message Queue cluster, in which multiple brokers interact to provide a scalable message service, you can do a rolling upgrade in which the cluster remains online as each Message Queue instance is upgraded from Release 3 to Release 4. The two conditions to keep in mind when performing a cluster upgrade are:
Otherwise the procedure is straightforward: you shut down, upgrade, and restart the brokers one at a time until all have been upgraded.
Upgrading Message Queue from Java ES Release 2The procedure for upgrading Java ES 2004Q2 (Release 2) Message Queue to Release 4 is nearly the same as that for upgrading Release 3 Message Queue to Release 4 (see Upgrading Message Queue from Java ES Release 3). For upgrading from Release 2, however, there is a small difference between operating system platforms.
In addition, the pre-upgrade tasks should include the upgrading of all shared components upon which Message Queue depends (see Table 1-6) from their Release 2 versions to Release 4.
Instructions for upgrading Java ES shared components to Release 4 are provided in Chapter 2, "Upgrading Java ES Shared Components".
Upgrading Release 2 Message Queue (Solaris)
Use the instructions in Upgrading Message Queue from Java ES Release 3, except substitute Release 2 wherever Release 3 is referenced.
Upgrading Release 2 Message Queue (Linux)
On Linux systems, an upgrade from Release 2 to Release 4 includes a data migration step that is not needed in updating from Release 3 to Release 4, namely the migration of broker instance data to the appropriate Release 4 location. If you want to preserve your Release 2 data in upgrading to Release 4, Message Queue provides a migration tool, mqmigrate, to perform this migration.
Upgrade Procedure
To upgrade from Release 2 to Release 3, you use the same instructions as used in Upgrading Message Queue from Java ES Release 3, except you run the mqmigrate script before you run the mqupgrade script, as detailed in the following procedure.
- Stop any running Message Queue client applications.
- Stop any running brokers. You will be prompted for the admin user name and password.
imqcmd shutdown bkr [-b hostName:port]
- If you do not want to preserve dynamic data, the Message Queue flat-file user repository, and the Message Queue access control file associated with each broker instance, remove this data using the following command.
imqbrokerd -name instanceName -remove instance
Otherwise, dynamic data and configuration information will be retained and used for Release 4 Message Queue.
- Log in as root or become superuser.
su -
- Change directories to the location Tools directory of the Java ES distribution.
cd Linux_x86/Product/message_queue/Tools
- Migrate broker instance data using the following command:
./mqmigrate
The mqmigrate script will move Release 2 broker instance configuration data to the appropriate R4 location.
- Run the mqupgrade script.
- Start the script:
./mqupgrade
The mqupgrade script lists installed Message Queue components.
- Enter y (yes) to upgrade Message Queue components.
The mqupgrade script detects and lists installed localization files.
If you do not want to upgrade Message Queue components, enter n (no). The mqupgrade script will exit without upgrading Message Queue components.
- If prompted, enter y (yes) to upgrade localization files.
The mqupgrade script sends output to a log file in the following location:
/var/sadm/install/logs/Message_Queue_upgrade_'date'.log
Installing the Compatibility Package
If you have scripts or your Release 2 client applications contain scripts that depend on the location of Release 4 installed files, you will need to install the sun-mq-compat package, which contains symlinks from Release 2 file locations to Release 4 file locations.
The sun-mq-compat package is in the following location where you unzipped the Java ES distribution.
Linux_x86/Product/message_queue/Packages
Perform the following steps to Install the sun-mq-compat Package:
Post-Upgrade Tasks
If you are using the HTTP tunneling servlet to provide HTTP connection service support, the upgrade of Message Queue from Release 2 to Release 4 has upgraded the servlet. This requires you to re-deploy it after upgrading Message Queue to Release 4. See the Message Queue Administration Guide, (http://docs.sun.com/doc/819-2571) for more information on HTTP support.
Migrate Release 2 administered objects to their Release 4 versions using the Administration Console (imqadmin) and/or the ObjectManager command line utility (imqobjmgr) to perform an update operation.