|
| |
| Sun Java System Message Queue 3.5 SP1 Installation Guide | |
Chapter 1
IntroductionThis chapter provides an overall introduction to installing the Sun Java™ System Message Queue 3.5 SP1 (formerly Sun™ ONE Message Queue) product. The topics covered are the following:
Product EditionsThe Sun Java System 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 Message Queue from one edition to another, see Migration Issues 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 Java System Application Server product and Java Enterprise System. The Platform Edition places no limit on the number of JMS client connections supported by each Message Queue 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).
Note
The 90-day trial license can be enabled by starting the Message Queue message service—a Message Queue broker instance—with the -license command line option (see the Message Queue Administration Guide) and passing “try” as the license to use:
imqbrokerd -license try
You must use this option each time you start the broker instance, otherwise it defaults back to the basic Platform Edition license.
The trial license usage period starts the first time you run the broker, regardless of which edition you start using. For example, if you enable the trial license sixty days after the first time you run the broker, you would only have thirty days left on the 90-day trial license. If you need additional time, you can do one of the following:
- Reinstall the product to establish a new starting date for your trial license.
- Send mail to imq-feedback@sun.com to extend your trial license.
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 ProductsMessage Queue 3.5 SP1 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 Message Queue clients.
Table 1-1 Message Queue 3.5 SP1 Basic Product Support Matrix
Platform/Product
Used For
Supported Platform/Product Version1
Java Runtime Environment (JRE)
(Sun Microsystems versions only)Message Queue broker (message server) and Message Queue administration tools
JRE 1.4.2_04:
- 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, 3.0.
JRE 1.4.2 is bundled on Message Queue CD distribution, but not yet with Linux platform.- Windows XP Professional SP3, 2000 all editions SP4, Windows Server 2003 Enterprise Edition.
JRE 1.4.2 is bundled and installed with Message Queue.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_04:
Version 1.3.12:
Version 1.2.2: Not supported, but should work (in case you cannot upgrade to a later version)
1Check the Message Queue Release Notes for any updates to supported versions.
2Download 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 a Message Queue 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.
Message Queue Software ModulesThe following table identifies the full set of software modules included with the Message Queue product (see Table 1-3 for their installed location).
Installing from Web and CD-ROMYou have the option of either downloading Message Queue 3.5 SP1 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.
Migration IssuesThis section covers issues you need to be aware of when migrating to Message Queue 3.5 SP1 from Message Queue 3.x versions. These issues fall into two general categories: platform issues and compatibility issues. This section presents two use cases: migrating from version 3.5 to 3.5 SP1 and migrating from version 3.0.x to 3.5 SP1.
Migrating from 3.5 to 3.5 SP1
Message Queue 3.5 SP1 is fully backward compatible with Message Queue 3.5. Therefore this section describes platform issues only.
Platform Issues
This section describes issues specific to the Solaris, Linux, and Windows platforms.
Solaris
On the Solaris platform, you can install Message Queue 3.5 SP1 on top of Message Queue 3.5 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 Message Queue.
Windows
On the Windows platform, you should un-install Message Queue 3.5 before installing Message Queue 3.5 SP1.
Linux
On the Linux platform, you should un-install Message Queue 3.5 before installing Message Queue 3.5 SP1.
Migrating from 3.0.x to 3.5 SP1
This section describes platform and compatibility issues when migrating from Message Queue 3.0.x to Message Queue 3.5SP1.
Platform Issues
This section describes issues and precautions to take when migrating to Message Queue 3.5 SP1 on the three supported platforms: Solaris, Linux, and Windows.
Solaris
On the Solaris platform, you can install Message Queue 3.5 SP1 on top of Message Queue 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 Message Queue 3.5 SP1 (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 Message Queue 3.5 SP1 there are no sym links files.
Linux
On the Linux platform, you should un-install any prior Message Queue versions before installing Message Queue 3.5 SP1, and not try to install Message Queue 3.5 SP1 on top of them. This is due to the fact that the installed directory structure has been changed for Message Queue 3.5 SP1, 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 Message Queue 3.0 to Message Queue 3.5 SP1. A new utility, mqmigrate, is provided to ease the migration of this data (see Finding and Removing Earlier Message Queue Versions).
Users need to uninstall the 3.0.1 RPM’s with -e (erase) and then to install the 3.5 SP1 RPM’s using the -i (install) option as described in this guide.
Windows
On the Windows platform, if you are upgrading from a prior Message Queue version product to Message Queue 3.5 SP1, 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 SP1 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.x in a non-default location and are installing Message Queue 3.5 SP1 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 SP1 in a location different from Message Queue 3.0.x, 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
Message Queue 3.5 SP1 is generally compatible with Message Queue 3.0.x. However, changes have been made in broker properties, administered objects, persistence schema, file locations, and administration tools that can impact a migration from Message Queue 3.0.x versions to Message Queue 3.5 SP1.
The Message Queue 3.5 SP1 install operation does not remove or over-write the Message Queue 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 Message Queue 3.5 SP1, and can be preserved using the instructions in the following sections.
The issues that you might need to address when migrating from Message Queue 3.0.x to Message Queue 3.5 SP1 include the following:
Broker Compatibility
A Message Queue 3.5 SP1 broker will inter-operate with a Message Queue 3.0.x broker, however changes have been made in broker properties and the persistent store schema. Some Message Queue 3.0.x data is compatible with Message Queue 3.5 SP1, as shown in Table 1-4, and can be used after migrating to Message Queue 3.5 SP1.
When migrating from Message Queue 3.0.x to Message Queue 3.5 SP1, you should consider the following:
- You can use Message Queue 3.0.x config.properties files, or you can copy them to another location and consult the property settings they contain when you configure Message Queue 3.5 SP1 brokers.
- Any persistent Message Queue 3.0.x data—messages, destinations, durable subscriptions—is automatically converted to Message Queue 3.5 SP1 data when starting up a Message Queue 3.5 SP1 broker for the first time. For example, any existing Message Queue 3.0.x destinations will be converted to Message Queue 3.5 SP1 destinations, preserving existing attributes and using default values of new attributes.
The automatic migration of persistent data leaves the Message Queue 3.0.x data intact. You can delete this data by using the following option when starting up the Message Queue 3.5 SP1 broker for the first time:
imqbrokerd -upgrade-store-nobackup.
If you do not use this option, you should delete the old persistent store manually:
- You can continue to use the Message Queue 3.0.x user repository and access control properties files after installing Message Queue 3.5 SP1, however these files have been made instance-specific and are now placed in the …/instances/instanceName/etc directories. The Message Queue 3.5 SP1 installer does not overwrite the Message Queue 3.0.x files. When you first start up a Message Queue 3.5 SP1 broker, copies of the Message Queue 3..x files are placed in the appropriate Message Queue 3.5 SP1 location (see the Message Queue Administration Guide, Appendix A). 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 brokers and Message Queue 3.5 SP1 brokers in a cluster, the master broker must be a Message Queue 3.0.x broker, and the cluster will run as a Message Queue 3.0.x. cluster.
Administered Object Compatibility
Message Queue 3.5 SP1 administered objects have been enhanced with new attributes and some Message Queue 3.0.x attributes have been renamed. Therefore, when migrating from Message Queue 3.0.x to Message Queue 3.5 SP1, you should consider the following:
- You can use the same object store and administered objects that you created in Message Queue 3.0.x; however, it is best to upgrade your administered objects after installing Message Queue 3.5 SP1. The Administration Console (imqadmin) and the ObjectManager command line utility (imqobjmgr), when performing an update operation, will convert Message Queue 3.0.x administered objects into Message Queue 3.5 SP1 administered objects.
- The Message Queue 3.5 SP1 client runtime will look up and instantiate Message Queue 3.0.x administered objects and convert them for use by Message Queue 3.5 SP1 clients. However, this will not convert Message Queue 3.0.x administered objects residing in the object store from which the lookup was made.
- Existing Message Queue 3.0 clients (applications and/or components)—that is, clients that directly instantiate administered objects—are compatible with Message Queue 3.5 SP1. However, if they are to use the new administered object attributes (see Chapter 4 and Appendix A of the Message Queue Java Client Developer’s Guide for information on administered object attributes), they will need to be rewritten. (Re-compiling Message Queue 3.0.x clients with Message Queue 3.5 SP1 will show which Message Queue 3.0.x attributes have been renamed in Message Queue 3.5 SP1. 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 Message Queue 3.5 SP1. However, if they are to use the new administered object attributes (see Chapter 4 and Appendix A of the Message Queue 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 Message Queue 3.5 SP1 administration tools (the Administration Console and command line utilities) only work with Message Queue 3.5 SP1 brokers. However, all Message Queue 3.0 commands and command options remain supported.
Client Compatibility
When upgrading from Message Queue 3.0.x to Message Queue 3.5 SP1, you should consider the following, regarding Java clients:
- A Message Queue 3.5 SP1 broker will support a Message Queue 3.0.x client (but without additional Message Queue 3.5 SP1 capabilities).
- A Message Queue 3.5 SP1 Java client can connect to a Message Queue 3.0.x broker (but without additional Message Queue 3.5 SP1 capabilities).
- Java clients built on JDK 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 each platform as follows:
- C clients programs cannot connect to a Message Queue 3.0.x broker; they are supported only by Message Queue 3.5 or 3.5 SP1 brokers running with a trial or enterprise license.
Where To Go NextWhen you are ready to install Message Queue 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.