Sun ONE Message Queue 3.0.1 SP2 Installation Guide |
Chapter 1
IntroductionThis chapter provides an overall introduction to installing the MQ product. The topics covered are:
Product EditionsThe 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).
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 ProductsMQ 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:
JDK/JRE 1.4.1:
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:
Version 1.3.1_053:
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
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 ModulesThe following table identifies the full set of software modules included with the MQ product (see Table 1-2 for their installed location).
Installing from Web and CD-ROMYou 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 StructureThe 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.
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:
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.0MQ 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).
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
When upgrading from iMQ 2.0 to MQ 3.0.1, you should consider the following:
- An MQ 3.0.1 broker will support the iMQ 2.0 client runtime (but without additional MQ 3.0.1 capabilities), but an iMQ 2.0 broker will not support the MQ 3.0.1 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 NextWhen 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.