|
| |
| Sun Java System Message Queue 3 2005Q1 Installation Guide | |
Chapter 1
IntroductionThis chapter provides an overall introduction to installing the Sun Java™ System Message Queue 3 2005Q1 (3.6) 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.)
Platform Edition
This edition can be downloaded free from the Sun web site and is also bundled with the Sun Java System Application Server product. 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 is a fully compliant JMS provider), but does not include such enterprise features as load balancing (multi-broker message service), HTTP/HTTPS connections, 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 only bundled with Sun JavaTM Enterprise System. 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 CPUs.
Supported Platforms and ProductsMessage Queue 3 2005Q1 is supported on Solaris and Linux, and Windows operating systems and platforms. It also depends upon other technologies, as indicated in the Message Queue Release Notes. Other versions or vendor implementations can also be used but they are untested by Sun Microsystems and therefore not supported.
Message Queue Software ModulesTable 1-1 identifies the full set of software modules included with the Message Queue product.
Installing from WebYou can download Message Queue 3 2005Q1 from the product web site:
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 2005Q1 from Message Queue 3.5 and 3.0.x versions. These issues fall into two general categories: platform issues and compatibility issues.
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 2005Q1 on top of Message Queue 3.0.x and 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 3 2005Q1 (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 2005Q1 there are no symbolic links files.
Linux
On the Linux platform, you should uninstall any prior Message Queue versions before installing Message Queue 3 2005Q1, and not try to install Message Queue 3 2005Q1 on top of them. This is due to the fact that the installed directory structure has been changed for Message Queue 3 2005Q1, 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.x and 3.5 to Message Queue 3 2005Q1. The 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.x or 3.5 Red Hat Package Manager (RPM) packages and then to install the 3 2005Q1 RPM packages using mqinstall.
Script Compatibility
Scripts that use hard-coded paths to the previous Linux installation of Message Queue will need to be changed to the new location of Message Queue. 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.
Windows
Message Queue 3.0.x and 3.5
On the Windows platform, you should uninstall the previous version of Message Queue before installing Message Queue 3 2005Q1 (3.6).
If you are upgrading from a 3.0.x Message Queue version product to Message Queue 3 2005Q1, 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 2005Q1 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 2005Q1 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 2005Q1 in a location different from Message Queue 3.0.x, you have to move any instance data you want 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 2005Q1 is generally compatible with Message Queue 3.0.x and 3.5. 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 and 3.5 versions to Message Queue 3 2005Q1.
The Message Queue 3 2005Q1 install operation does not remove or over-write the Message Queue 3.0.x or 3.5 IMQ_VARHOME directory. This directory contains configuration and security-related files (see Table 1-2). Most of this data is compatible with Message Queue 3 2005Q1, 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 and 3.5 to Message Queue 3 2005Q1 include the following:
Broker Compatibility
A Message Queue 3 2005Q1 broker will inter-operate with a Message Queue 3.0.x or 3.5 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 2005Q1, as shown in Table 1-2, and can be used after migrating to Message Queue 3 2005Q1.
Message Queue 3.5 data is generally compatible with Message Queue 3 2005Q1, and can be used after migrating to Message Queue 3 2005Q1.
When migrating from Message Queue 3.0.x or 3.5 to Message Queue 3 2005Q1, you should consider the following:
- You can use Message Queue 3.0.x or 3.5 config.properties files, or you can copy them to another location and consult the property settings they contain when you configure Message Queue 3 2005Q1 brokers.
- Any persistent Message Queue 3.0.x or 3.5 data—messages, destinations, durable subscriptions—is automatically converted to Message Queue 3 2005Q1 data when starting up a Message Queue 3 2005Q1 broker for the first time. For example, any existing Message Queue 3.0.x or 3.5 destinations will be converted to Message Queue 3 2005Q1 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 2005Q1 broker for the first time:
imqbrokerd -upgrade-store-nobackup
If you do not use this option, you should delete the old persistent store manually:
- 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 2005Q1, however these files have been made instance-specific and are now placed in the …/instances/instanceName/etc directories. The Message Queue 3 2005Q1 installer does not overwrite the Message Queue 3.0.x files. When you first start up a Message Queue 3 2005Q1 broker, copies of the Message Queue 3.0.x files are placed in the appropriate Message Queue 3 2005Q1 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 or 3.5 brokers and Message Queue 3 2005Q1 brokers in a cluster, the master broker must be a Message Queue 3.0.x or 3.5 broker (whichever is older), and the cluster will run as a Message Queue 3.0.x or 3.5 cluster.
Administered Object Compatibility
Message Queue 3 2005Q1 administered objects have been enhanced with new attributes and some Message Queue 3.0.x and 3.5 attributes have been renamed. Therefore, when migrating from Message Queue 3.0.x or 3.5 to Message Queue 3 2005Q1, you should consider the following:
- You can use the same object store and administered objects that you created in Message Queue 3.0.x or 3.5; however, it is best to upgrade your administered objects after installing Message Queue 3 2005Q1. The Administration Console (imqadmin) and the ObjectManager command line utility (imqobjmgr), when performing an update operation, will convert Message Queue 3.0.x and 3.5 administered objects into Message Queue 3 2005Q1 administered objects.
- The Message Queue 3 2005Q1 client runtime will look up and instantiate Message Queue 3.0.x and 3.5 administered objects and convert them for use by Message Queue 3 2005Q1 clients. However, this will not convert Message Queue 3.0.x and 3.5 administered objects residing in the object store from which the lookup was made.
- Existing Message Queue 3.0 and 3.5 clients (applications and/or components)—that is, clients that directly instantiate administered objects—are compatible with Message Queue 3 2005Q1. However, if they are to use the new administered object attributes (see Chapter 2 of the Message Queue Developer’s Guide for Java Clients and Chapter 16 of the Message Queue Administration Guide for information on administered object attributes), they will need to be rewritten. (Re-compiling Message Queue 3.0.x and 3.5 clients with Message Queue 3 2005Q1 will show which Message Queue 3.0.x and 3.5 attributes have been renamed in Message Queue 3 2005Q1. 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 2005Q1. However, if they are to use the new administered object attributes (see Chapter 2 of the Message Queue Developer’s Guide for Java Clients and Chapter 16 of the Message Queue Administration 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 2005Q1 administration tools (the Administration Console and command line utilities) only work with Message Queue 3 2005Q1 brokers. However, all Message Queue 3.0.x and 3.5 commands and command options remain supported.
Client Compatibility
When upgrading from Message Queue 3.0.x or 3.5 to Message Queue 3 2005Q1, you should consider the following, regarding Java clients:
- A Message Queue 3 2005Q1 broker will support a Message Queue 3.0.x or 3.5 client (but without additional Message Queue 3 2005Q1 capabilities).
- A Message Queue 3 2005Q1 Java client can connect to a Message Queue 3.0.x or 3.5 broker (but without additional Message Queue 3 2005Q1 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 client programs cannot connect to a Message Queue 3.0.x broker; they are supported only by Message Queue 3.5, 3.5 SPx, or 3 2005Q1 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 or 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.