Chapter 1 Introduction

This chapter provides an overall introduction to installing the MQ product. The topics covered are:

Product Editions

The Sun™ ONE Message Queue product is available in two editions: Platform and Enterprise—each corresponding to a different licensed capacity, as described below. (To upgrade MQ from one edition to another, see the instructions in the MQ Installation Guide.)

Platform Edition

This edition can be downloaded free from the Sun website and is also bundled with the latest Sun ONE Application Server platform. The Platform Edition places no limit on the number of JMS client connections supported by each MQ message service. It comes with two licenses, as described below:

a basic license. This license provides basic JMS support (it’s a full 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, and multiple queue delivery policies. 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, and multiple queue delivery policies) 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 MQ message service—an MQ broker instance—with the -license command line option (see the MQ Administrator’s 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.

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, and multiple queue delivery policies. 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, but specifies the number of CPUs that are supported.

Supported Platforms and Products

MQ 3.0.1, SP2 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 MQ 3.0.1 Product Support Matrix
Platform/Product	Used For	Supported Platform/Product Version1
Java Runtime Environment (JRE) (Sun Microsystems production versions only)	MQ broker (message server) and MQ administration tools	JDK/JRE 1.4.1_03: Solaris 9—MQ depends on platform-bundled JDK/JRE 1.4.1_03 Solaris 8—platform-bundled JRE 1.3 needs to be removed and replaced by JDK/JRE 1.4.1_03 Windows—JRE 1.4.1_03 is bundled and installed with MQ JDK/JRE 1.4.1: Linux— JRE 1.4.1 is bundled on MQ CD distribution, but not yet with Linux platform
Java Software Development Kit (JDK), Standard Edition (Sun Microsystems production versions only)	JMS client development (SOAP messaging clients are supported only on JDK 1.4.1_03)	Version 1.4.1_032: SPARC on Solaris 8 and Solaris 9 x86 on Solaris 9, update 4 or higher Windows XP professional, 2000 Professional SP2, 2000 Server SP2, 2000 Advanced Server SP2 Linux RedHat 7.2 Version 1.3.1_053: (SPARC only) Solaris 8 and Solaris 9 Windows XP professional, 2000 Professional SP2, 2000 Server SP2, 2000 Advanced Server SP2 Version 1.2.2_08: Not supported, but should work (in case you cannot upgrade to a later version)
LDAP Directory Server	MQ user repository and administered object support	Sun ONE Directory Server version 5.1
Web Server	HTTP and HTTPS support	Sun ONE Web Server, Enterprise Edition 6.0 SP4
Database	Plugged-in persistence support	Cloudscape (version 3.0) Oracle 8i, version 8.1.7 and Oracle 9i, version 9.0.1
JNDI	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.)

1Check the MQ Release Notes for any updates to supported versions

2Download this JDK from: http://java.sun.com/j2se/1.4/index.html

3Download this JDK from: http://java.sun.com/j2se/1.3/index.html

MQ Software Modules

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

Table 1-2 MQ 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 an MQ messaging system. This module requires the client runtime and Java runtime modules.
Client runtime	The client-side software needed to support client applications.
Documentation	API documentation needed by 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 an MQ messaging system.

Installing from Web and CD-ROM

You have the option of either downloading the MQ 3.0.1, SP2 product from the Sun ONE website or installing it from CD-ROM. For detailed instructions, see the platform-specific instructions in subsequent chapters.

Installed Directory Structure

The install image below reflects a full Solaris installation (all packages) or a full (“Typical”) Windows installation. This image might vary if you perform a partial installation.


Note	On Windows, the COPYRIGHT, LICENSE, and README files have a .txt filename extension.

Table 1-3 Installed Directory Structure
File and directory (Solaris)	File and directory (Windows and Linux)1	Contents
COPYRIGHT (not installed)	./COPYRIGHT	Copyright text file
LICENSE (not installed)	./LICENSE	License text file
README (not installed)	./README	README text file
/usr/bin directory	./bin directory	Contains the executables for the broker (imqbrokerd) and the following MQ administration tools: Administration Console (imqadmin) Command (imqcmd) Object Manager (imqobjmgr) User Manager (imqusermgr) Database Manager (imqdbmgr) Key Tool (imqkeytool) On Windows, the files named above have a .bat filename extension. This directory also includes the utility to install and uninstall the broker as a Windows Service (imqsvcadmin) as well other executables (imqbrokersvc).
/usr/share/lib directory	./lib directory	Contains files that support the MQ client runtime: /*jar contains jar files used to build and run JMS client applications
/usr/share/lib/imq directory	./lib directory	Contains files used to support MQ tools and processes: /ext/*jar location for placing jar files needed for plug-in persistence capabilitiy /props subdirectory contains the broker’s default configuration file /help subdirectory contains MQ help files /images
/etc/imq directory	./etc directory	Contains license files, security-related files (such as passfile, access control files, and flat-file user repository), and (on Solaris only) rc script configuration files that can be used for automatic startup
/var/imq directory	./var directory	Working storage directory for MQ. /instances subdirectory which will contain configuration files, log files, and file-based persistent data stores for each broker instance
/usr/share/javadoc/imq directory	./javadoc directory	Contains the MQ and JMS API documentation distributed as Javadoc (HTML)
/usr/demo/imq directory	./demo directory	Source code for and instructions on how to run client example applications
	./jre directory	The JRE 1.4 files (on Windows only)

1Paths are relative to IMQ_HOME (see Directory Variable Conventions).

Upgrading from Version 2.0

MQ 3.0.1, SP2 is fully compatible with MQ 3.0.1 and MQ 3.0.1 SP1, and upgrading from MQ 3.0.1 or MQ 3.0.1 SP1 to MQ 3.0.1, SP2 requires no changes in broker configuration, administered objects, administration tools, or client applications.

However, MQ 3.0.1 versions are generally not compatible with iMQ 2.0, largely because of changes in internal and external data used by MQ 3.0.1 versions. For this reason it is strongly recommended that you uninstall iMQ 2.0 before installing any MQ 3.0.1 version, and not try to install MQ 3.0.1 over iMQ 2.0.

Uninstalling iMQ 2.0

If you are running iMQ 2.0, Service Pack 1, you should first uninstall the Service Pack, using the uninstall instructions in the Service Pack Installation Guide, and then uninstall iMQ 2.0, using the uninstall instructions in the iMQ 2.0 Installation Guide.

The uninstall operation does not remove the iMQ 2.0 IMQ_VARHOME directory. This directory (by default /var/opt/SUNWjmq on Solaris and Linux operating systems, and c:\Program files\iPlanetMessageQueue2.0\var on Windows systems) contains transient and security-related files (see Table 1-4). Some of this data is compatible with MQ 3.0.1 and can be preserved using the instructions in the following section.

Compatibilities and Incompatibilities

Due to changes made to improve features, MQ 3.0.1 versions are generally not compatible with iMQ 2.0. In particular, there are a number of issues that you might need to address when upgrading from iMQ 2.0 to MQ 3.0.1, SP2:

Broker Compatibility

An MQ 3.0.1 broker will not inter-operate with an iMQ 2.0 broker due to changes in broker properties and the persistent store schema. However, some iMQ 2.0 data is compatible with MQ 3.0.1, as shown in Table 1-4, and can be preserved when upgrading to MQ 3.0.1. When upgrading from iMQ 2.0 to MQ 3.0.1, you should consider the following:

You can copy iMQ 2.0 config.properties files to another location and, in most cases, consult the property settings they contain when you configure MQ 3.0.1 brokers.

Any persistent iMQ 2.0 data—messages, destinations, durable subscriptions—cannot be re-used. In particular, you will need to re-create iMQ 2.0 destinations in your MQ 3.0.1 brokers.

You can continue to use iMQ 2.0 user repository and access control properties files after installing MQ 3.0.1. The MQ 3.0.1 installer does not overwrite these files. You will have to move them to the appropriate MQ 3.0 location (see the MQ Administrator’s Guide, Appendix C).

Table 1-4 Compatibility of MQ 3.0.1 with iMQ 2.0 Data
iMQ 2.0 Data Category	Location of iMQ 2.0 Data	Compatibility with MQ 3.0.1
Broker properties	IMQ_VARHOME/stores/brokerName/ props/config.properties	Incompatible; do not use.
Persistent store (messages, destinations, durable subscriptions)	IMQ_VARHOME/stores/brokerName/ filestore/ or JDBC-accessible data store	Incompatible; do not use.
Administered objects	local directory or LDAP server	Compatible; can use and/or convert to 3.0.1.
Security: user repositories	IMQ_VARHOME/security/passwd or LDAP server	Compatible. Move to following location: IMQ_HOME/etc/passwd (/etc/imq/passwd on Solaris)
Security: access control file	IMQ_VARHOME/security/ accesscontrol.properties	Compatible. Move to following location: IMQ_HOME/etc/... (/etc/imq/... on Solaris)

Administered Object Compatibility

MQ 3.0.1 administered objects have been enhanced with new attributes and iMQ 2.0 attributes have been renamed. Therefore, when upgrading from iMQ 2.0 to MQ 3.0.1, you should consider the following:

You can use the same object store and administered objects that you created in iMQ 2.0; however, it is best to upgrade your administered objects after installing MQ 3.0.1. The Administration Console (imqadmin) and the ObjectManager command line utility (imqobjmgr), when performing an update operation, will convert iMQ 2.0 administered objects into MQ 3.0.1 administered objects.

The MQ 3.0.1 client runtime will look up and instantiate iMQ 2.0 administered objects by converting them into local MQ 3.0.1 administered objects, but this will not convert iMQ 2.0 administered objects in the object store into MQ 3.0.1 administered objects.

JMS clients (applications and/or components) that directly instantiate administered objects—that is, that are JMS provider-dependent—need to be rewritten to accommodate new administered object attribute names (see Chapter 4 and Appendix A of the MQ Developer’s Guide for information on administered object attributes).

Scripts that start JMS clients and which set administered object attribute values using command line options need to be rewritten to accommodate the new administered object attribute names (see Chapter 4 and Appendix A of the MQ Developer’s Guide for information on administered object attributes).

Administration Tool Compatibility

Because of the renaming of many files and directories (specifically to replace the string “jmq” with “imq”), all MQ 3.0.1 command line utilities, broker properties, administered object attributes, and internal file names have changed. Therefore, when upgrading from iMQ 2.0 to MQ 3.0.1, you should consider the following:

Any scripts that use command line utilities (imqbrokerd, imqcmd, imqobjmgr, and so forth) need to be edited to replace the old commands with the newly-named commands. Note, especially, that the jmqbroker command is now imqbrokerd.

The Administration Console (imqadmin) allows you to manage several brokers and/or object stores concurrently, and saves the list of managed entities that are displayed in the navigational pane on the left side of the screen. Thus each time you launch the Console, the list of managed entities is redisplayed. The name of the directory in which user settings for the iMQ 2.0 Administration Console were stored has changed for MQ 3.0.1. If you wish to preserve the old Console settings when upgrading from iMQ 2.0 to MQ 3.0.1, you need to change the name of the directory where the brokerlist.properties and objstorelist.properties files are stored from user.home/.jmq/admin to user.home/.imq/admin, where user.home is a java system property.

Client Compatibility

Where To Go Next

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