Sun Java System Message Queue 4.1 Installation Guide

Chapter 1 Introduction

This chapter provides an overall introduction to installing the Sun Java^TM System Message Queue 4.1 product. It covers the following topics:

Product Editions

Before the release of Version 3.7 UR1, the Sun Java System Message Queue product was available in two editions, Platform and Enterprise, each containing different features and corresponding to a different licensed capacity. Versions beginning with 3.7 UR1 combine the functionality of both editions. If you have an earlier version installed under a Platform Edition license, upgrading to Version 4.1 will give you access to the full range of Message Queue functionality, including the following features formerly available only under the Enterprise Edition license:

Multiple-broker clusters
Scalable connection capability
Secure connection services
Hypertext Transfer Protocol (HTTP) and Secure Hypertext Transfer Protocol HTTPS) connections
Queue delivery to more than three consumers
C client support

In addition, the following features, added since the Platform and Enterprise Editions were combined, are available to all users of Version 4.1:

High-availability message services
Support for plug-in client authentication using Java Authentication and Authorization Services (JAAS)
Connection event notification
Client runtime logging
Enhanced broker administration
Programmatic configuration and monitoring of Message Queue operations by means of the Java Management Extensions (JMX) API and monitoring by means of the Java Enterprise System Monitoring Framework (JESMF)

Supported Platforms and Components

Message Queue 4.1 is supported on Solaris, Linux, and Windows operating system platforms. Table 1–1 shows the supported versions of each of these platforms. The chapters that follow describe the hardware and software requirements for each of these platforms and provide platform-specific installation instructions.

Table 1–1 Supported Platform Versions


Platform	Supported Versions
Solaris	Solaris 9 (SunOS 5.9), all updates (SPARC, `x`86) Solaris 10 (SunOS 5.10), all updates (SPARC, `x`86, `x`64)
Linux	Red Hat Enterprise Linux Advanced Server 3.0, 4.0, 5.0, all updates, 32– and 64–bit versions (`x`86, `x`64) Red Hat Enterprise Linux Enterprise Server 3.0, 4.0, 5.0, all updates, 32– and 64–bit versions (`x`86, `x`64)
Windows	Windows XP Professional, SP2 (`x`86) [No Home, Tablet PC, or Media Center Edition support] Windows 2000 Advanced Server, SP4 (`x`86) [No Professional or Server Edition support] Windows Server 2003 Standard and Enterprise Editions, SP1, 32– and 64–bit versions (`x`86, `x`64) [No Web or Small Business Server Edition support]

In addition to platform-specific requirements, Message Queue 4.1 also depends on certain basic components that must be installed in order to develop and run Message Queue clients. Table 1–2 describes these components. Other versions or vendor implementations can also be used, but they are untested by Sun Microsystems and therefore not officially supported.

Note –

The Message Queue 4.1 Installer automatically installs the required JDK version as of the time of release.

Table 1–2 Required Support Components


Component	Supports	Supported Versions
Java Runtime Environment (JRE)	Message Queue broker and administration tools	J2SE^TM Runtime Environment 1.5.0_12 Java SE Runtime Environment 1.6.0 (Sun Microsystems versions only)
Java Software Development Kit (JDK), Standard Edition	Java client development and deployment	J2SE Development Kit 1.5.0_12 Java SE Development Kit 1.6.0 (Sun Microsystems production versions only)

Table 1–3 shows additional components that you can install to provide further support for Message Queue clients. You may not need all of the components listed: for example, if you are not writing a C client, you will not need the C compiler, C++ runtime library, NSPR, or NSS.

Table 1–3 Optional Support Components


Component	Supports	Supported Versions
Application server	HTTP/HTTPS	Sun Java System Application Server Enterprise Edition, Version 9.1
Web server	HTTP/HTTPS	Sun Java System Web Server Enterprise Edition, Version 7.0, Update 1
Database	Plugged-in persistence	HADB, Version 4.4.3.5 Java DB (Apache Derby), Version 10.2.2 Oracle9i, Version 9.2 Note – The PointBase database is no longer supported.
Lightweight Directory Access Protocol (LDAP) directory server	Message Queue user repository and administered objects	Sun Java System Directory Server, Version 6.0
Java Naming and Directory Interface (JNDI)	Administered object support and LDAP user repository	JNDI Version 1.2.1 LDAP Service Provider, Version 1.2.2 File System Service Provider, Version 1.2 Beta 3 [Administered object support only; supported for development and testing, but not for deployment in a production environment]
C Compiler and compatible C++ runtime library	Message Queue C clients	Solaris: Sun Studio, Version 11 or later, C++ compiler with standard mode and C compiler Linux: gcc/g++, Version 3.2.3 Windows: Microsoft Windows Visual C++, Version 6.0 SP3
Netscape Portable Runtime (NSPR)	Message Queue C clients	Version bundled with Sun Java Enterprise System 5, Update 1 (Version 3.4.7) [Bundled as a shared package in the download bundle]
Network Security Services (NSS)	Message Queue C clients	Version bundled with Sun Java Enterprise System 5, Update 1 (Version 3.11.7)

Message Queue Software Modules

Table 1–4 shows the full set of software modules included with the Message Queue 4.1 product.

Table 1–4 Software Modules


Module	Contents
Broker	Server-side software for routing and delivering messages. Requires the Java runtime module
Administration tools	Command-line utilities and GUI tools for administering a Message Queue messaging system. Requires the client runtime and Java runtime modules
Java client runtime	`.jar` files needed to write and compile Java clients using the Message Queue Java application programming interface (API)
C client runtime	Libraries and header files needed to write and compile C clients using the Message Queue C application programming interface (API)
Documentation	API documentation needed by Java client application developers, in JavaDoc format
Example applications	Example client applications

Migration Issues

This section covers issues you need to be aware of when migrating to Message Queue 4.1 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.6 is not supported.

Platform Issues

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

Solaris

On the Solaris platform, you can upgrade to Message Queue 4.1 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.1 (see Compatibility Issues).

Linux

On the Linux platform, you can upgrade to Message Queue 4.1 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.1 (see Compatibility Issues).

Windows

Upgrading directly to Message Queue 4.1 from earlier versions is not supported on the Windows platform, but Version 4.1 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.1 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.1.
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.1 in a different location in your file system.

If you choose to uninstall your previous version before installing Message Queue 4.1, 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.1 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.1, remove any references to uninstalled versions’ IMQ_HOME\bin directories from the system’s PATH environment variable and add the new Message Queue 4.1 installation’s IMQ_HOME\bin directory.

Compatibility Issues

Message Queue 4.1 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 migration from the earlier versions to Version 4.1.

The Message Queue 4.1 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.1, 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.1 include the following:

Broker Compatibility

A Message Queue 4.1 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.1 and requires no migration.
Message Queue 3.6 data is generally compatible with Message Queue 4.1 and requires no migration.
Data from Message Queue 3.5 must be migrated by upgrading to Message Queue 3.6 or later before installing Message Queue 4.1.

When upgrading from Message Queue 3.6 or 3.7 to Message Queue 4.1, 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.1 brokers.

Any persistent Message Queue 3.6 or 3.7 data (messages, destinations, and durable subscriptions) is automatically converted to Message Queue 4.1 data when starting up a Message Queue 4.1 broker for the first time. For example, existing destinations will be converted to Message Queue 4.1 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.1 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.1 brokers in a cluster, the master broker must be of the oldest version in the cluster, and the cluster will run as a cluster of that oldest version.

Client Compatibility

Message Queue 4.1 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.1 broker will support a Message Queue 3.6 or 3.7 Java client, and a Message Queue 4.1 Java client can connect to a Message Queue 3.6 or 3.7 broker. Expanded Message Queue 4.1 capabilities are unavailable in such cases, however.

Administered Object Compatibility

Message Queue 4.1 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.1.

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.1 form, using default values for the new attributes. The Message Queue 4.1 client runtime will also look up and instantiate administered objects from those earlier versions and convert them for use by Message Queue 4.1 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.1. For attributes that have been renamed in Message Queue 4.1, the old names will still work. (Recompiling the client with Message Queue 4.1 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.1,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 4.1 administration tools (Administration Console and command line utilities) will work only with Message Queue 4.1 brokers. All commands and command options from earlier Message Queue versions remain supported, however.

Where to Go Next

Before proceeding to install Message Queue 4.1, be sure to consult the section Installation Issues in the Sun Java System Message Queue 4.1 Release Notes for the latest information on issues and limitations affecting Message Queue 4.1 installation. The Release Notes are also an important general resource for up-to-date code and documentation changes, open bugs, and important technical notes relating to the current Message Queue release.

In addition, the following sources provide further useful information on Sun Java System Message Queue:

For information on where to find documentation, news, and updates and how to send feedback, see the README file included in your Message Queue installation.
For an introduction to Message Queue concepts, see the Message Queue Technical Overview.
For details on configuring brokers and managing a Message Queue messaging system, see the Message Queue Administration Guide.
For an introduction to writing and compiling Message Queue client applications, see the Message Queue Developer’s Guide for Java Clients or the Message Queue Developer’s Guide for C Clients.
For information on the Message Queue Java Management Extensions (JMX) API, see the Message Queue Developer’s Guide for JMX Clients.
For class and member information useful when writing a client application, browse the API documentation in JavaDoc format included in your Message Queue installation; see Table P–6 for locations, depending on your platform.