This chapter provides an overall introduction to installing the Sun Java System Message Queue 3.7 UR1 product. It covers the following topics:
Prior to 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. Version 3.7 UR1 combines the functionality of both editions.
If you have a previous version of Message Queue Enterprise Edition installed, you can upgrade to Version 3.7 UR1 with no loss of functionality.
If you have a previous version of Message Queue Platform Edition installed, you can upgrade to Version 3.7 UR1 and enjoy access to a richer set of features, including:
Support for multiple-broker message services
HTTP/HTTPS connections
Secure connection services
Scalable connection capability
Queue delivery to more than three consumers
C client support
Message Queue 3.7 UR1 is supported on Solaris, Linux, and Windows operating systems and platforms. The following chapters describe the hardware and software requirements for each of these platforms and provide platform-specific installation instructions.
In addition to platform-specific requirements, Message Queue 3.7 UR1 also depends on certain basic components that you must install in order to be able to develop and run Message Queue clients. Table 1–1 describes these components. Other versions or vendor implementations can also be used, but they are untested by Sun Microsystems and therefore not supported.
Table 1–1 Required Support Components
Table 1–2 shows additional components that you can install to provide further support for a Message Queue client. You may not need all of the components listed: for example, if you are not writing a C Message Queue client, you will not need the C compiler, C++ runtime library, NSPR, or NSS. .
Table 1–2 Optional Support Components
Component |
Supports |
Supported Versions |
---|---|---|
LDAP (Lightweight Directory Access Protocol) Directory Server |
Message Queue user repository and administered objects |
Sun Java System Directory Server, Version 6.0 |
Web Server |
HTTP/HTTPS |
Sun Java System Web Server, Enterprise Edition Version 7.0 |
Application Server |
HTTP/HTTPS |
Sun Java System Application Server, Enterprise Edition Version 8.2 |
Database |
Plugged-in persistence |
Apache Derby, Version 10.1.1 Oracle 9i, Version 9.2 The Pointbase database is no longer supported |
JNDI (Java Naming and Directory Interface) |
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 10 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 |
NSPR (Netscape Portable Runtime) |
Message Queue C clients |
Version bundled with Java Enterprise System 5 Bundled as a shared package in the download bundle |
NSS (Network Security Service) |
Message Queue C clients |
Version bundled with Java Enterprise System 5 Bundled as a shared package in the download bundle |
Table 1–3 shows the full set of software modules included with the Message Queue 3.7 UR1 product.
Table 1–3 Message Queue 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. |
JDK runtime |
JDKRuntime Environment (Windows only). |
License |
Software needed to enable the licensed capacity of a Message Queue messaging system. |
You can download Message Queue 3.7 UR1 from the product Web site at
See the subsequent chapters for platform-specific installation instructions and descriptions of the installed directory structures.
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.
Migration from Message Queue versions earlier than 3.0.1 is not supported.
This section describes issues specific to the Solaris, Linux, and Windows platforms.
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.
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.
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.
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.
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
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:
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.
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.
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.
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.
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.