Preface
This book provides information about the concepts and procedures needed by a developer of Java™ messaging applications (Java clients) in a Sun™ Open Net Environment (Sun ONE) Message Queue (MQ) environment.
This preface contains the following sections:
Audience for This Guide
This guide is meant principally for developers of Java 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. As such, these applications are JMS client and/or JAXM client applications, respectively. The JMS and JAXM specifications are open standards.
This MQ Java Client Developer’s Guide assumes that you are familiar with the JMS APIs 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 book assumes no familiarity, however, with the JAXM APIs or with JAXM programming guidelines. This material is described in Chapter 6, "Working With SOAP Messages," and 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:
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 URLs.
|
|
[]
|
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.
|
Directory Variable Conventions
MQ makes use of three directory variables; how they are set varies from platform to platform. Table 3 describes these variables and summarizes how they are used on the Solaris™, Windows, and Linux platforms.
Table 3 MQ Directory Variables
|
Variable
|
Description
|
|
IMQ_HOME
|
This is generally used in MQ documentation to refer to the MQ base directory (root installation directory):
- On Solaris, there is no root MQ installation directory. Therefore, IMQ_HOME is not used in MQ documentation to refer to file locations on Solaris.
- On Solaris, for Sun ONE Application Server, Evaluation Edition, the root MQ installation directory is:
Application Server base directory/imq.
- On Windows, the root MQ installation directory is set by the MQ installer (by default, as C:\Program Files\Sun\MessageQueue3).
- On Windows, for Sun ONE Application Server, the root MQ installation directory is:
Application Server base directory/imq.
- On Linux, there is no root MQ installation directory. Therefore, IMQ_HOME is not used in MQ documentation to refer to file locations on Linux.
|
|
IMQ_VARHOME
|
This is the /var directory in which MQ temporary or dynamically-created configuration and data files are stored. It can be set as an environment variable to point to any directory.
- On Solaris, IMQ_VARHOME defaults to the /var/imq directory.
- On Solaris, for Sun ONE Application Server, Evaluation Edition, IMQ_VARHOME defaults to the IMQ_HOME/var directory.
- On Windows IMQ_VARHOME defaults to the IMQ_HOME\var directory.
- On Windows, for Sun ONE Application Server, IMQ_VARHOME defaults to the IMQ_HOME\var directory.
- On Linux, IMQ_VARHOME defaults to the /var/opt/imq directory.
|
|
IMQ_JAVAHOME
|
This is an environment variable that points to the location of the Java runtime (JRE) 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 the required JRE resides.
- On Windows, IMQ_JAVAHOME defaults to IMQ_HOME\jre, but a user can optionally set the value to wherever the required JRE resides.
- On Linux, MQ first looks for the java runtime in the /usr/java/j2sdkVersion directory, and then looks in the /usr/java/j2reVersion directory, but a user can optionally set the value of IMQ_JAVAHOME to wherever the required JRE 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). Path names generally use UNIX directory 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.
|
|
MQ Release Notes
|
Developers and administrators
|
Includes descriptions of new features, limitations, and known bugs, as well as technical notes.
|
|
MQ Java Client Developer’s Guide
|
Developers
|
Provides a quick-start tutorial and programming information for developers of Java client programs using the MQ implementation of the JMS and SOAP/JAXM specifications.
|
|
MQ C Client Developer’s Guide
|
Developers
|
Provides programming and reference documentation for developers of C client programs using the C interface (C-API) to the .MQ message service.
|
|
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:
|
Platform
|
Location
|
|
Solaris
|
/usr/share/javadoc/imq/index.html
|
|
Linux
|
/opt/imq/javadoc/index.html/
|
|
Windows
|
IMQ_HOME/javadoc/index.html
|
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 APIs 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 Java client application code are included in the following directories:
|
Platform
|
Location
|
|
Solaris
|
/usr/demo/imq/
|
|
Linux
|
/opt/imq/demo/
|
|
Windows
|
IMQ_HOME\demo\
|
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:
The specification includes sample client code.
The Java XML Messaging (JAXM) Specification
The JAXM specification can be found at the following location:
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
