Previous Contents Next |
Sun Java System Message Queue 3.5 SP1 Installation Guide

> ## Chapter 1
> Introduction

> This 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 Editions
> - Supported Platforms and Products
> - Message Queue Software Modules
> - Installing from Web and CD-ROM
> - Migration Issues
> - Where To Go Next

> ##

> Product Editions

> The 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 Products

> Message 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: Solaris (same platforms as JRE) Linux (same platforms as JRE) Windows (same platforms as JRE) Version 1.3.12: (SPARC only) Solaris 8 and Solaris 9 Windows XP professional, 2000 Professional SP3, 2000 Advanced Server SP3 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.

> Table 1-2 Message Queue 3.5 SP1 Optional Product Support Matrix

> Product | Used For | Supported Product Version
> --- | --- | ---
> LDAP Directory Server | Message Queue user repository and administered object support | Sun Java System Directory Server Version 5.2 Patch 2
> Web Server | HTTP and HTTPS support | Sun Java System Web Server, Enterprise Edition 6.1 SP1
> Application Server | HTTP and HTTPS support | Sun ONE Application Server 7.0, Update 3, Sun Java System Application Server 7.1, Sun Java System Application Server 8.0 (Note: Message Queue is the JMS provider for Application Server 7)
> Database | Plugged-in persistence support | PointBase, Version 4.8 Oracle 9i, Version 9.2
> JNDI (Java Naming and Directory Interface) | administered object support | JNDI Version 1.2.1 LDAP Service Provider Version 1.2.2 File System Service Provider Version 1.2 Beta 3 (supported for development and testing, but not for deployment in a production environment.)
> C Compiler and compatible C++ runtime library | Message Queue C client support | Solaris: Sun WorkShop 6, Update 2 or later C++ compiler with -compat=5, Sun WorkShop C compiler Linux: gcc/g++ 2.96 Windows: Microsoft Windows Visual C++ 6.0, SP3
> NSPR (Netscape Portable Runtime) | Message Queue C client support | Solaris (SPARC) 4.1.2 Solaris (X86): 4.1.3 Linux: 4.1.6 Windows: 4.1.6
> NSS (Network Security Service) | Message Queue C client support | Solaris (SPARC): 3.3.2 Solaris (X86): 3.3.3 Linux: 3.3.7 Windows: 3.3.7

> ##

> Message Queue Software Modules

> The following table identifies the full set of software modules included with the Message Queue product (see Table 1-3 for their installed location).

> Table 1-3 Message Queue Software Modules

> Module | Contents
> --- | ---
> Broker | The server-side software used to route and deliver messages. This module requires the Java runtime module.
> Administration tools | The command-line utilities and GUI tools used to administer a Message Queue messaging system. This module requires the client runtime and Java runtime modules.
> Java client runtime | Libraries and header files needed to write and compile Java clients using the Message Queue Java API.
> C client runtime | Libraries and header files needed to write and compile C clients using the Message Queue C API (Enterprise Edition only).
> Documentation | API documentation needed by Java client application developers in JavaDoc format.
> Example applications | Example client applications.
> Java runtime | Java Runtime Environment (Windows only).
> License | The software needed to enable the licensed capacity of a Message Queue messaging system.

> ##

> Installing from Web and CD-ROM

> You have the option of either downloading Message Queue 3.5 SP1 from the product website:

> http://www.sun.com/software/message_queue/

> 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 Issues

> This 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.0, these files were in the /usr/share/lib/imq directory
> - In Message Queue 3.0.1, these files were in the /usr/share/lib directory, with sym links in the /usr/share/lib/imq directory

> 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
> - Administered Object Compatibility
> - Administration Tool Compatibility
> - Client Compatibility

> ##### 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:

> - For a built-in (flat file) data store, delete the old persistent store, located at

> …/instances/instanceName/filestore/

> - For a plugged-in (JDBC-compliant) data store, delete the old tables using the following command:

> imqdbmgr delete oldtbl

> Note | When you migrate persistent data from Message Queue 3.0.x to Message Queue 3.5 SP1, the migrated data can no longer be used by a Message Queue 3.0.x broker. If this is a concern, save the old persistent data to a secure location instead of deleting it as directed above.

> - 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.

> Table 1-4 Compatibility of Message Queue 3.5 SP1 with Message Queue 3.0.x Data

> Message Queue 3.0.x Data Category | Location of Message Queue 3.0.x Data | Compatibility with Message Queue 3.5 SP1
> --- | --- | ---
> Broker properties | IMQ_VARHOME/instances/instanceName/ props/config.properties | New properties have been added, and some property names have changed. Old property names are still recognized.
> Persistent store: messages, destinations, durable subscriptions | IMQ_VARHOME/instances/instanceName/ filestore/ or JDBC-accessible data store | Converted to Message Queue 3.5 SP1 format when Message Queue 3.5 SP1 broker is started for the first time. The persistent store is at IMQ_VARHOME/instanceName/fs350
> Security: flat-file user repositories | /etc/imq/passwd (Solaris) IMQ_HOME/etc/passwd (other platforms) | Compatible. File automatically copied to following location at first broker startup: …/instances/instanceName/etc/ passwd
> Security: access control file | /etc/imq/accesscontrol.properties (Solaris) IMQ_HOME/etc/accesscontrol.properties (other platforms) | Compatible. File automatically copied to following location at first broker startup: …/instances/instanceName/etc/ accesscontrol.properties

> ##### 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:
> - on Solaris, in the SUNWiqsup package, which is not installed by default
> - on Linux, as part of the default Message Queue installation
> - on Windows, as part of a custom installation
> - 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 Next

> When 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.

> Previous Contents Next

> Copyright 2004 Sun Microsystems, Inc. All rights reserved.