Chapter 1   Introduction


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

• Product Editions

• Supported Platforms and Products

• MQ Software Modules

• Installing from Web and CD-ROM

• Installed Directory Structure

• Upgrading from Version 2.0

• Where To Go Next

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 subsequent chapters of this book.)

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 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, and is therefore best suited for evaluating the enterprise features which are available in the Enterprise Edition of the product (see "Enterprise Edition").

The Platform Edition places no limits on the number of JMS client connections supported by each MQ message service. (For information on how to switch from the basic license to the enterprise license, see the license command line option described in the MQ Administrator's Guide.)

Enterprise Edition. This edition is for deploying and running messaging applications in a production environment. 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, nor on the number of client connections supported by each broker. However the license specifies the number of CPU's that it will support.

Supported Platforms and Products

---

MQ 3.0 is supported on Solaris, Linux, and Windows operating systems and platforms. It also requires the support of 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 Product Support Matrix 

Platform/Product	Supported Version
Java Runtime Environment (JRE) (Sun Microsystems production versions only)	The broker and MQ administration tools are supported on the JDK/JRE 1.4 only. Solaris 9: MQ depends on platform-bundled JDK/JRE Solaris 8: platform-bundled JRE 1.3 needs to be removed and replaced by JDK/JRE 1.4 Windows: JRE 1.4 is bundled and installed with MQ Linux: JRE 1.4 not bundled with platform or with MQ
Java 2 Software Development Kit (JDK), Standard Edition (Sun Microsystems production versions only)	JMS clients are supported as follows: Version 1.41: (SPARC only) Solaris 8 and Solaris 9; Windows XP professional, 2000 Professional SP2, 2000 Server SP2, 2000 Advanced Server SP2; and Linux RedHat 7.1 Version 1.3.0_052: (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 (user repository and administered object support)	Sun ONE Directory Server (Netscape Directory Server) version 5.1
Web Server (HTTP and HTTPS support)	Sun ONE Web Server, Enterprise Edition 6.0 SP2b
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 Note: The File System Service Provider is supported for development and testing, but not for deployment in a production environment.

1 Download this JDK from: http://java.sun.com/j2se/1.4/index.html 2 Download 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	Version 1.4 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 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/imq directory	./lib directory	Contains files used to build and run client applications (MQ client runtime): /*jar contains jar files used to build and run client applications /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 password and access control files), 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)

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

Upgrading from Version 2.0

---

MQ 3.0 is generally not compatible with iMQ 2.0, largely because of changes in internal and external data used by MQ 3.0. For this reason it is strongly recommended that you un-install iMQ 2.0 before installing MQ 3.0, and not try to install MQ 3.0 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 and can be preserved using the instructions in the following section.

Compatibilities and Incompatibilities

Due to changes made to improve features, MQ 3.0 is 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:

• Broker Compatibility

• Administered Object Compatibility

• Administration Tool Compatibility

• Client Compatibility

Broker Compatibility

An MQ 3.0 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, as shown in Table 1-4, and can be preserved when upgrading to MQ 3.0. When upgrading from iMQ 2.0 to MQ 3.0, 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 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 brokers.

• You can continue to use iMQ 2.0 user repository and access control properties files after installing MQ 3.0. The MQ 3.0 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 with iMQ 2.0 Data
  
  

  iMQ 2.0 Data Category	Location of iMQ 2.0 Data	Compatibility with MQ 3.0
  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.
  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 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, 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. 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 administered objects.

• The MQ 3.0 client runtime will look up and instantiate iMQ 2.0 administered objects by converting them into local MQ 3.0 administered objects, but this will not convert iMQ 2.0 administered objects in the object store into MQ 3.0 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 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, 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. If you wish to preserve the old Console settings when upgrading from iMQ 2.0 to MQ 3.0, 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

When upgrading from iMQ 2.0 to MQ 3.0, you should consider the following:

• An MQ 3.0 broker will support the iMQ 2.0 client runtime (but without additional MQ 3.0 capabilities), but an iMQ 2.0 broker will not support the MQ 3.0 client runtime.

• JMS 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).

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.