| Sun ONE Message Queue 3.5 Installation Guide |
Chapter 1
IntroductionThis chapter provides an overall introduction to installing the MQ product. The topics covered are:
Product EditionsThe Sun ONE Message Queue product is available in two editions: Platform and Enterprise—each containing different features and corresponding to a different licensed capacity, as described below. (To upgrade MQ from one edition to another, see "Upgrade Issues from MQ 3.0.x Versions" and the relevant instructions for each platform in this manual.)
Platform Edition
This edition can be downloaded free from the Sun website and is also bundled with the Sun ONE Application Server product. The Platform Edition places no limit on the number of JMS client connections supported by each MQ message server. It comes with two licenses, as described below:
- a basic license. This license provides basic JMS support (it’s a fully compliant JMS provider), but does not include such enterprise features as load balancing (multi-broker message service), HTTP/HTTPS connections, secure connection services, scalable connection capability, queue delivery to more than three consumers, and C client support. The license has an unlimited duration, and can therefore be used in less demanding production environments.
- a 90-day trial enterprise license. This license includes all enterprise features (such as support for multi-broker message services, HTTP/HTTPS connections, secure connection services, scalable connection capability, queue delivery to more than three consumers, and C- client support) not included in the basic license. However, the license has a limited 90-day duration enforced by the software, making it suitable for evaluating the enterprise features available in the Enterprise Edition of the product (see "Enterprise Edition").
Enterprise Edition
This edition is for deploying and running messaging applications in a production environment. It includes support for multi-broker message services, HTTP/HTTPS connections, secure connection services, scalable connection capability, client connection failover, queue delivery to more than three consumers, and C client support. You can also use the Enterprise Edition for developing, debugging, and load testing messaging applications and components. The Enterprise Edition has an unlimited duration license that places no limit on the number of brokers in a multi-broker message service. Licenses are purchased based on the number of CPU’s.
Supported Platforms and ProductsMQ 3.5 is supported on Solaris, Linux, and Windows operating systems and platforms. It also depends upon other technologies, as indicated in the following table. Other versions or vendor implementations can also be used but they are untested by Sun Microsystems and therefore not supported.
Table 1-1 lists and describes the basic components that you must install in order to be able to develop and run MQ clients.
Table 1-1 MQ 3.5 Basic Product Support Matrix
Platform/Product
Used For
Supported Platform/Product Version1
Java Runtime Environment (JRE)
(Sun Microsystems versions only)MQ broker (message server) and MQ administration tools
JRE 1.4.2_02:
- Solaris 8 (SPARC), Solaris 9 (SPARC and X86)
Platform-bundled JRE might need to be upgraded.- Linux Red Hat Advanced Server 2.1 Update 2
JRE 1.4.2 is bundled on MQ CD distribution, but not yet with Linux platform.- Windows XP Professional, 2000 Professional SP3, 2000 Advanced Server SP3, .NET Server 2003 Enterprise Edition
JRE 1.4.2 is bundled and installed with MQ.Java Software Development Kit (JDK), Standard Edition
(Sun Microsystems production versions only)Java client development and deployment
(Java SOAP/JAXM clients are supported only on JDK 1.4.0, 1.4.1, and 1.4.2)
JDK 1.4.0, 1.4.1, and 1.4.2_02:
Version 1.3.12:
Version 1.2.2: Not supported, but should work (in case you cannot upgrade to a later version)
1. Check the MQ Release Notes for any updates to supported versions
2. Download this JDK from: http://java.sun.com/j2se/1.4
Table 1-2 lists and describes the components that you can install in order to provide additional support for an MQ client. You might just need some of the components listed. For example, if you are not writing a C client to Message Queue, you will not need any of the components required for C client support.
MQ Software ModulesThe following table identifies the full set of software modules included with the MQ product (see Table 1-3 for their installed location).
Installing from Web and CD-ROMYou have the option of either downloading MQ 3.5 from the product website:
or installing it from CD-ROM. For detailed instructions, see the platform-specific instructions in subsequent chapters. The installed directory structure is described for each platform in the chapter describing that platform.
Upgrade Issues from MQ 3.0.x VersionsThis section covers issues you need to be aware of when upgrading to MQ 3.5 from MQ 3.0.x versions. These issues fall into two general categories: platform issues and compatibility issues.
Platform Issues
This section describes issues and precautions to take when upgrading to MQ 3.5 on the three supported platforms: Solaris, Linux, and Windows.
Solaris
On the Solaris platform, you can install MQ 3.5 on top of MQ 3.0.x versions, and your previous instance data (configuration properties, flat-file persistent store, log files, flat-file user repository, and/or access control properties file) will be used by MQ 3.5 (see "Compatibility Issues").
If you depended on jar files being in their 3.0.x locations, please note that these have been moved to the /usr/share/lib directory. This applies to the following .jar files: jms.jar, imq.jar, imqxm.jar, activation.jar, saaj-api.jar, saaj-impl.jar, mail.jar, commons-logging.jar, jaxm-api.jar, fscontext.jar.
In MQ 3.5 there are no sym links files.
Linux
On the Linux platform, you should un-install any MQ 3.0 versions before installing MQ 3.5, and not try to install MQ 3.5 on top of them. This is due to the fact that the installed directory structure has been changed for MQ 3.5, and this complicates the migration of instance data (configuration properties, flat-file persistent store, log files, flat-file user repository, and/or access control properties file) from MQ 3.0 to MQ 3.5. A new utility, mqmigrate, is provided to ease the migration of this data (see "Finding and Removing Earlier MQ Versions").
Users need to uninstall the 3.0.1 RPM with -e (erase) and then to install the 3.5 RPM using the -i (install) option as described in this guide.
Windows
On the Windows platform, if you are upgrading from a Message Queue 3.0 version product to Message Queue 3.5, it is likely that you will have to manually migrate any previous instance data (configuration properties, flat-file persistent store, log files, flat-file user repository, and/or access control properties file) from the Message Queue 3.0 location to the Message Queue 3.5 location.
This is because the default Message Queue installation directory (represented by the IMQ_HOME directory variable) has been changed on the Windows platform. The same issue arises if you installed Message Queue 3.0 in a non-default location and are installing Message Queue 3.5 in a different location.
Instance data is stored in the following directory:
IMQ_VARHOME\instances\instanceName
where IMQ_VARHOME defaults to IMQ_HOME\var
When you install Message Queue 3.5 in a location different from Message Queue 3.0, you have to move any instance data you wish to preserve from the old location, corresponding to the old value of IMQ_VARHOME, to the new location, corresponding to the new value of IMQ_VARHOME.
Compatibility Issues
MQ 3.5 is generally compatible with MQ 3.0 (and subsequent versions 3.0.1, 3.0.1 SP1, and 3.0.1 SP2). However, changes have been made in broker properties, administered objects, persistence schema, file locations, and administration tools that can impact an upgrade from MQ 3.0 versions to MQ 3.5.
The MQ 3.5 install operation does not remove or over-write the MQ 3.0.x IMQ_VARHOME directory. This directory contains configuration and security-related files (see Table 1-4). Most of this data is compatible with MQ 3.5, and can be preserved using the instructions in the following sections.
The issues that you might need to address when upgrading from MQ 3.0 to MQ 3.5 include the following:
Broker Compatibility
An MQ 3.5 broker will inter-operate with an MQ 3.0 broker, however changes have been made in broker properties and the persistent store schema. Some MQ 3.0 data is compatible with MQ 3.5, as shown in Table 1-4, and can be used after upgrading to MQ 3.5.
When upgrading from MQ 3.0.x to MQ 3.5, you should consider the following:
- You can use MQ 3.0.x config.properties files, or you can copy them to another location and consult the property settings they contain when you configure MQ 3.5 brokers.
- Any persistent MQ 3.0.x data—messages, destinations, durable subscriptions—is automatically converted to MQ 3.5 data when starting up an MQ 3.5 broker for the first time. For example, any existing MQ 3.0.x destinations will be converted to MQ 3.5 destinations, preserving existing attributes and using default values of new attributes.
- You can continue to use the MQ 3.0.x user repository and access control properties files after installing MQ 3.5, however these files have been made instance-specific and are now placed in the …/instances/instanceName/etc directories. The MQ 3.5 installer does not overwrite the MQ 3.0.x files. When you first start up an MQ 3.5 broker, copies of the MQ 3.0.x files are placed in the appropriate MQ 3.5 location (see the MQ Administrator’s Guide, Appendix A). If MQ 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 MQ 3.0.x brokers and MQ 3.5 brokers in a cluster, the master broker must be a MQ 3.0.x broker, and the cluster will run as an MQ 3.0.x. cluster.
Administered Object Compatibility
MQ 3.5 administered objects have been enhanced with new attributes and some MQ 3.0.x attributes have been renamed. Therefore, when upgrading from MQ 3.0 to MQ 3.5, you should consider the following:
- You can use the same object store and administered objects that you created in MQ 3.0.x; however, it is best to upgrade your administered objects after installing MQ 3.5. The Administration Console (imqadmin) and the ObjectManager command line utility (imqobjmgr), when performing an update operation, will convert MQ 3.0.x administered objects into MQ 3.5 administered objects.
- The MQ 3.5 client runtime will look up and instantiate MQ 3.0.x administered objects and convert them for use by MQ 3.5 clients. However, this will not convert MQ 3.0.x administered objects residing in the object store from which the lookup was made.
- Existing MQ 3.0 clients (applications and/or components)—that is, clients that directly instantiate administered objects—are compatible with MQ 3.5. However, if they are to use the new administered object attributes (see Chapter 4 and Appendix A of the MQ Java Client Developer’s Guide for information on administered object attributes), they will need to be rewritten. (Re-compiling MQ 3.0 clients with MQ 3.5 will show which MQ 3.0 attributes have been renamed in MQ 3.5. 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 MQ 3.5. However, if they are to use the new administered object attributes (see Chapter 4 and Appendix A of the MQ Java Client Developer’s Guide 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, the MQ 3.5 administration tools (the Administration Console and command line utilities) only work with MQ 3.5 brokers. However, all MQ 3.0 commands and command options remain supported.
Client Compatibility
When upgrading from MQ 3.0.x to MQ 3.5, you should consider the following, regarding Java clients:
- An MQ 3.5 broker will support an MQ 3.0.x client (but without additional MQ 3.5 capabilities).
- An MQ 3.5 Java client can connect to an MQ 3.0.x broker (but without additional MQ 3.5 capabilities).
- Java clients built on JDK 1.2, 1.3, or 1.4 can inter-operate with a broker running JRE 1.4. However, clients that use a secure (SSL-based) connection to a broker will require additional JSSE and JNDI libraries if they are not built on JDK 1.4 (which includes these libraries). These libraries are provided on Solaris in the SUNWiqsup package, which is not installed by default; they are provided on Windows as part of a “custom” install; on linux they are installed as part of the default MQ install.
- C clients programmed cannot connect to an MQ 3.0.x broker; they are supported only by MQ 3.5 brokers running with a trial or enterprise license.
Where To Go NextWhen you are ready to install MQ on a specific platform, see the appropriate chapter for your platform (Solaris, Linux, or Windows). Each chapter contains hardware and software requirements, installation procedures, and other relevant instructions, such as how to upgrade editions and how to proceed after installation.
