Preface


This book provides information about the concepts and procedures needed by a developer of messaging applications in a Sun™ ONE Message Queue (MQ) environment.

This preface contains the following sections:

• Audience for This Guide

• Organization of This Guide

• Conventions

• Other Documentation Resources

Audience for This Guide

---

This guide is meant principally for developers of applications that exchange messages using an MQ messaging system.

These applications use the Java Message Service (JMS) Application Programming Interface (API). and possibly the Java XML Messaging (JAXM) API, to create, send, receive, and read messages. The JMS and JAXM specifications are open standards.

This Developer's Guide assumes that you are familiar with the JMS API's and with JMS programming guidelines. Its purpose is to help you optimize your JMS client applications by making best use of the features and flexibility of an MQ messaging system.

This Developer's Guide assumes no familiarity, however, with the JAXM APIs or with JAXM programming guidelines. This material is described in Chapter 5 "Working With SOAP Messages, which only assumes basic knowledge of XML.

Organization of This Guide

---

This guide is designed to be read from beginning to end. The following table briefly describes the contents of each chapter:

Table 1    Book Contents

Chapter	Description
Chapter 1 "Overview	A high level overview of Sun ONE Message Queue and of JMS concepts and programming issues.
Chapter 2 "Quick Start Tutorial	A tutorial that acquaints you with the MQ development environment using a simple example client application.
Chapter 3 "Using Administered Objects	Describes how to use MQ administered objects in both a provider- independent and provider-specific way.
Chapter 4 "Optimizing Clients	Explains features of the MQ client runtime and how they can be used to optimize a client application.
Chapter 5 "Working With SOAP Messages	Explains how you send and receive SOAP messages with and without MQ support.
Appendix A "Administered Object Attributes	Summarizes and documents administered object attributes.

Conventions

---

This section provides information about the conventions used in this document.

Text Conventions

Table 2    Document Conventions 

Format	Description
italics	Italicized text represents a placeholder. Substitute an appropriate clause or value where you see italic text. Italicized text is also used to designate a document title, for emphasis, or for a word or phrase being introduced.
monospace	Monospace text represents example code, commands that you enter on the command line, directory, file, or path names, error message text, class names, method names (including all elements in the signature), package names, reserved words, and URL's.
[]	Square brackets to indicate optional values in a command line syntax statement.
ALL CAPS	Text in all capitals represents file system types (GIF, TXT, HTML and so forth), environment variables (IMQ_HOME), or acronyms (MQ, JSP).
Key+Key	Simultaneous keystrokes are joined with a plus sign: Ctrl+A means press both keys simultaneously.
Key-Key	Consecutive keystrokes are joined with a hyphen: Esc-S means press the Esc key, release it, then press the S key.

Environment Variable Conventions

MQ makes use of three environment variables—but how they are used varies from platform to platform. Table 3 describes these environment variables and summarizes how they are used on the Solaris, Windows, and Linux platforms.

Table 3    MQ Environment Variables 

Environment Variable	Description
IMQ_HOME	This is generally the root MQ installation directory in which all installed files are placed: On Solaris, there is no root MQ installation directory. IMQ_HOME is not used by MQ software and is not used in MQ documentation to refer to file locations on Solaris. On Solaris, for Sun ONE Application Server, Evaluation Edition, IMQ_HOME is not used by MQ software, but is used in MQ documentation to refer to the root MQ installation directory (an imq subdirectory under the Application Server installation root directory). On Windows, IMQ_HOME is used by MQ software and is also used in MQ documentation to refer to the root MQ installation directory. The value of IMQ_HOME is set by the MQ installer (by default, as C:\Program Files\Sun Microsystems\Message Queue 3.0). On Linux, IMQ_HOME is not used by MQ software, but is used in MQ documentation to refer to the root MQ installation directory (by default, an imq subdirectory under /opt).
IMQ_VARHOME	This refers to the /var directory in which MQ temporary or dynamically-created configuration and data files are stored: On Solaris, IMQ_VARHOME defaults to the /var/imq directory, but a user can optionally set the value to any directory. On Solaris, for Sun ONE Application Server, Evaluation Edition, IMQ_VARHOME defaults to IMQ_HOME/var, but a user can optionally set the value to any directory. On Windows IMQ_VARHOME defaults to IMQ_HOME/var, but a user can optionally set the value to any directory. On Linux, IMQ_VARHOME defaults to IMQ_HOME/var, but a user can optionally set the value to any directory.
IMQ_JAVAHOME	This refers to the location of the Java runtime (JRE 1.4) required by MQ executables: On Solaris, IMQ_JAVAHOME defaults to the /usr/j2se/jre directory, but a user can optionally set the value to wherever JRE 1.4 resides. On Windows, IMQ_JAVAHOME defaults to IMQ_HOME/jre, but a user can optionally set the value to wherever JRE 1.4 resides. On Linux, IMQ_JAVAHOME defaults to the /usr/java/j2sdk1.0/jre directory, but a user can optionally set the value to wherever JRE 1.4 resides.

In this guide, IMQ_HOME, IMQ_VARHOME, and IMQ_JAVAHOME are shown without platform-specific environment variable notation or syntax (for example, $IMQ_HOME on UNIX). All path names use UNIX file separator notation (/).

Other Documentation Resources

---

In addition to this guide, MQ provides additional documentation resources.

The MQ Documentation Set

The documents that comprise the MQ documentation set are listed in Table 4 in the order in which you would normally use them.

Table 4    MQ Documentation Set 

Document	Audience	Description
MQ Installation Guide	Developers and administrators	Explains how to install MQ software on Solaris, Linux, and Windows platforms.
Release Notes	Developers and administrators	Includes descriptions of new features, limitations, and known bugs, as well as technical notes.
MQ Developer's Guide	Developers	Provides a quick-start tutorial and programming information relevant to the MQ implementation of JMS.
MQ Administrator's Guide	Administrators, also recommended for developers	Provides background and information needed to perform administration tasks using MQ administration tools.

JavaDoc

JMS and MQ API documentation in JavaDoc format, is provided at the following location:

IMQ_HOME/javadoc/index.html
(/usr/share/javadoc/imq/index.html on Solaris)

This documentation can be viewed in any HTML browser such as Netscape or Internet Explorer. It includes standard JMS API documentation as well as MQ-specific API's for MQ administered objects (see Chapter 3 "Using Administered Objects), which are of value to developers of messaging applications.

Example Client Applications

A number of example applications that provide sample client application code are included in the following location:

IMQ_HOME/demo (/usr/demo/imq on Solaris)

See the README file located in that directory and in each of its subdirectories.

The Java Message Service (JMS) Specification

The JMS specification can be found at the following location:

http://java.sun.com/products/jms/docs.html

The specification includes sample client code.

The Java XML Messaging (JAXM) Specification

The JAXM specification can be found at the following location:

http://java.sun.com/xml/downloads/jaxm.htm

The specification includes sample client code.

Books on JMS Programming

For background on using the JMS API, you can consult the following publicly-available books:

• Java Message Service by Richard Monson-Haefel and David A. Chappell, O'Reilly and Associates, Inc., Sebastopol, CA

• Professional JMS Programming by Scott Grant, Michael P. Kovacs, Meeraj Kunnumpurath, Silvano Maffeis, K. Scott Morrison, Gopalan Suresh Raj, Paul Giotta, and James McGovern, Wrox Press Inc., ISBN: 1861004931

• Practical Java Message Service by Tarak Modi, Manning Publications, ISBN: 1930110138