Sun Java Enterprise System 5 Upgrade Guide for Microsoft Windows

Chapter 5 Message Queue

This chapter describes how to upgrade Message Queue software from previous Java ES versions to Java ES 5: Sun Java System Message Queue 3.7 UR 1.

The chapter provides a general overview of Message Queue upgrade issues and procedures for the different upgrade paths supported by Java ES 5. This chapter covers the following topics:

Note –

File locations in this chapter are specified with respect to a fixed directory path referred to as MessageQueue-base. The default value of MessageQueue-base is C:\Program Files\Sun\JavaES5\mq.

Overview of Message Queue Upgrades

The following sections describe general aspects of Message Queue that affect upgrading to Release 5:

About Java ES 5 Message Queue

Java ES 5 Message Queue represents minor code fixes with no new features, enhancements, or compatibility issues.

With Java ES 5 Message Queue, the Platform Edition is deprecated and Message Queue includes all Enterprise Edition features. An upgrade from an earlier Java ES version to Java ES 5 converts any installed Platform Edition to full Message Queue enterprise-level features.

Message Queue Upgrade Roadmap

The following table shows the supported Message Queue upgrade paths to Java ES 5.

Table 5–1 Upgrade Paths to Java ES 5 Message Queue 3.7 UR1


Java ES Release	Message Queue Release	General Approach	Reconfiguration Required
Release 4	Sun Java System Message Queue 2005Q4 (3.6 SP3) Enterprise Edition only	Direct upgrade:Performed using coexistence	Need manual steps to migrate data

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. Table 5–2 shows the type of data that could be impacted by an upgrade of Message Queue software.

In the table, Instance-Name identifies the name of the Message Queue broker instance with which the data is associated and MessageQueue-base is the installation directory for Message Queue.

For Java ES 5, C:\Program Files\Sun\JavaES5\mq is the default installation location for Message Queue . For Java ES 4, C:\Sun\MessageQueue is the default installation location.

Table 5–2 Message Queue Data Usage


Data Category	Location	Usage
Broker instance configuration properties	`MessageQueue-base\var\instances\Instance-Name\config.properties`	Broker and related services configurations
Persistent store for dynamic application data	Release 4: `MessageQueue-base\var\instances\Instance-Name\fs350` Release 5: `MessageQueue-base\var\instances\Instance-Name\fs370` or accessible through the Java Database Connectivity (JDBC^TM) API	Stores messages, destinations, durable subscriptions, transactions, and other dynamic data
Administered objects (object store)	Local directory of your choice or an LDAP Directory Server	Objects used to configure client/broker connections
Security: user repository	`MessageQueue-base\var\instances\Instance-Name\etc\passwd`	Stores user data used for authentication and authorization
Security: access control file (default location)	`MessageQueue-base\var\instances\Instance-Name\etc\accesscontrol.properties`	Sets the rules that authorize user access to destinations and related capabilities
Security: passfile directory (default location)	`MessageQueue-base\var\instances\Instance-Name\etc\`	Stores encrypted password information.
Security: broker’s keystore file location	`MessageQueue-base\etc`	Stores encrypted certificate information for secure messaging.

Message Queue Dependencies

Message Queue dependencies on other Java ES components can impact the procedure for upgrading and reconfiguring 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, as listed in Table 1–7.
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, 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 or from Java ES Application Server.
Databases (optional). You can configure Java DB or a third-party database as a data store for the Message Queue persistence layer.

Upgrading Message Queue from Java ES Release 4

This section includes information about upgrading Message Queue from Java ES 4 to Java ES 5. The section covers the following topics:

Introduction to Upgrading Message Queue

When upgrading Java ES 4 Message Queue to Java ES 5, consider the following aspects of the upgrade process:

General Upgrade Approach. Java ES 5 does not provide any in place upgrade support.
Upgrade Dependencies. Message Queue has dependencies on a number of Java ES shared components, as listed in Table 1–7. Java ES 5 Message Queue is compatible with the Java ES 4 versions of all the components except NSS and NSPR. For this reason, you must upgrade these components while upgrading to Java ES 5.

In addition, Java ES 5 Message Queue is optionally dependent on Directory Server and Web Server (or Application Server), as described in Message Queue Dependencies. However, upgrade of these components is optional.
Backward Compatibility. Java ES 5 Message Queue is fully compatible with Java ES 4 with respect to protocols, broker compatibility, administered objects, administration tools, and client applications.
Upgrade Rollback. Java ES 5 does not provide any utility to roll back the Message Queue upgrade to Java ES 4. You have to remove the upgraded components and manually restore the previous version and configuration data.

Message Queue Upgrade

This section describes how to perform a Message Queue upgrade from Java ES 4 to Java ES 5. This section contains the following sections:

Pre-Upgrade Tasks

Before you upgrade Message Queue, perform the procedures described in the following sections.

Upgrading Message Queue Dependencies

All Java ES 4 components on a computer system and in a computing environment should be upgraded to Java ES 5. However, because Message Queue does not require upgrading the Java ES 4 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 items that might already have been upgraded.

Shared Components. Release 5 installer automatically installs all required shared components in the parallel path..
Directory Server (optional). Instructions for upgrading Directory Server to Java ES 5 are provided in Chapter 2, Directory Server.
Web Container Software (optional). Instructions for upgrading Web Server or Application Server are provided in Chapter 4, Web Server and Chapter 6, Application Server respectively.

To Verify Current Version Information

Start the Message Queue broker with -version option.

imqbrokerd -version

The outputs that indicate the Message Queue version are:

Release 5: Sun Java System Message Queue 3.7 UR1
Release 4: Sun Java System Message Queue 3 2005Q4 Version: 3.6 SP3

To Upgrade Message Queue

Before You Begin

Back up application data in a production environment before performing an upgrade. For Message Queue data locations, refer Table 5–2.

Stop any running Java ES 4 Message Queue instances.

If Message Queue is being used in an Application Server environment, shut down Application Server, as well.

Stop any running brokers.

Install the Java ES 5 Message Queue.

For Java ES 5 Message Queue installation instructions, see the Sun Java Enterprise System 5 Installation Guide for Microsoft Windows.

(Optional) Migrate the Release 4 Message Queue data, as listed in Table 5–2, to the Release 5 Message Queue installation location.

You need to perform this step only if you wish to preserve any Message Queue broker data from Release 4.

(Optional) Uninstall Release 4 Message Queue.

Note –
Uninstall of Release 4 Message Queue is optional because Java ES versions 4 and 5 can coexist on a system.

To Verify Message Queue Upgrade

Start the Message Queue broker with -version option.

imqbrokerd -version

The outputs that indicate the Message Queue version are:

Release 5: Sun Java System Message Queue 3.7 UR1
Release 4: Sun Java System Message Queue 3 2005Q4 Version: 3.6 SP3

Post-Upgrade Tasks

If you have upgraded the web container and are using the Message Queue HTTP tunneling servlet, you may need to redeploy the servlet in the new web container. Otherwise, you do not need to redeploy the servlet after upgrading Message Queue. For more information about HTTP support, see the Sun Java System Message Queue 3.7 UR1 Administration Guide.

To Roll Back the Upgrade

Stop any running Release 5 Message Queue instances.

If Message Queue is being used in an Application Server environment, shut down Application Server as well.

Stop any running brokers.

Migrate back the Release 4 Message Queue data, as listed in Table 5–2, to the Release 4 Message Queue installation location.

Start the Release 4 Message Queue.