Preface
This book provides information about concepts and procedures for developing Java messaging applications (Java clients) that work with Sun Java System Message Queue (formerly Sun ONE Message Queue).
This preface contains the following sections:
Who Should Use This Book
This guide is meant principally for developers of Java applications that use Sun Java System Message Queue.
These applications use the Java Message Service (JMS) Application Programming Interface (API), and possibly the SOAP with Attachments API for Java (SAAJ), to create, send, receive, and read messages. As such, these applications are JMS clients and/or SOAP client applications, respectively. The JMS and SAAJ specifications are open standards.
This Message Queue Developer’s Guide for Java Clients 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 a Message Queue messaging system.
This book assumes no familiarity, however, with SAAJ. This material is described in Chapter 5, "Working with SOAP Messages," and only assumes basic knowledge of XML.
Before You Read This Book
You must read the Message Queue Technical Overview to become familiar with Message Queue’s implementation of the Java Message Specification, with the components of the Message Queue service, and with the basic process of developing, deploying, and administering a Message Queue application.
How This Book Is Organized
This guide is designed to be read from beginning to end. The following table briefly describes the contents of each chapter:
Conventions Used in this Book
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 abbreviations (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
Message Queue 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 Message Queue Directory Variables
Variable
|
Description
|
IMQ_HOME
|
This is generally used in Message Queue documentation to refer to the Message Queue base directory (root installation directory):
- On Solaris, there is no root Message Queue installation directory. Therefore, IMQ_HOME is not used in Message Queue documentation to refer to file locations on Solaris.
- On Windows, the root Message Queue installation directory is set by the Message Queue installer (by default, as C:\Program Files\Sun\MessageQueue3).
- On Linux, there is no root Message Queue installation directory. Therefore, IMQ_HOME is not used in Message Queue documentation to refer to file locations on Linux.
- For Sun Java System Application Server, on Windows, Solaris, and Linux, the root Message Queue installation directory is /imq, under the Application Server base directory.
|
IMQ_VARHOME
|
This is the /var directory in which Message Queue 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 Windows IMQ_VARHOME defaults to the IMQ_HOME\var directory.
- On Linux, IMQ_VARHOME defaults to the /var/opt/sun/mq directory.
- For Sun Java System Application Server, on Solaris and Linux, IMQ_VARHOME defaults to the domain/domain1/imq directory under the App Server base directory.
- For Sun Java System Application Server, on Windows, IMQ_VARHOME defaults to the domain\domain1\imq directory under the App Server base directory.
|
IMQ_JAVAHOME
|
This is an environment variable that points to the location of the Java runtime (JRE) required by Message Queue executables:
- On Solaris, IMQ_JAVAHOME looks for the java runtime in the following order, but a user can optionally set the value to wherever the required JRE resides.
Solaris 8 or 9: /usr/jdk/entsys-j2se /usr/jdk/jdk1.5.* /usr/jdk/j2sdk1.5.* /usr/j2se Solaris 10: /usr/jdk/entsys-j2se /usr/java /usr/j2se
- On Linux, Message Queue first looks for the java runtime in the following order, but a user can optionally set the value of IMQ_JAVAHOME to wherever the required JRE resides.
/usr/jdk/entsys-j2se /usr/java/jre1.5.* /usr/java/jdk1.5.* /usr/java/jre1.4.2* /usr/java/j2sdk1.4.2*
- On Windows, IMQ_JAVAHOME defaults to IMQ_HOME\jre, but a user can optionally set the value 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 (/).
Related Documentation
In addition to this guide, Message Queue provides additional documentation resources.
The Message Queue Documentation Set
The documents that comprise the Message Queue documentation set are listed in Table 4 in the order in which you would normally use them.
Table 4 Message Queue Documentation Set
Document
|
Audience
|
Description
|
Message Queue Installation Guide
|
Developers and administrators
|
Explains how to install Message Queue software on Solaris, Linux, and Windows platforms.
|
Message Queue Release Notes
|
Developers and administrators
|
Includes descriptions of new features, limitations, and known bugs, as well as technical notes.
|
Message Queue Technical Overview
|
Developers and administrators
|
Explains basic messaging concepts and processes.
|
Message Queue Developer’s Guide for Java Clients
|
Developers
|
Provides a quick-start tutorial and programming information for developers of Java client programs using JMS and SAAJ and Message Queue software.
|
Message Queue Developer’s Guide for C Clients
|
Developers
|
Provides programming and reference documentation for developers of C client programs that use the Message Queue software.
|
Message Queue Administration Guide
|
Administrators, also recommended for developers
|
Provides background and information needed to perform administration tasks using Message Queue administration tools.
|
JavaDoc
JMS and Message Queue API documentation in JavaDoc format is provided at the following location:
Platform
|
Location
|
Solaris
|
/usr/share/javadoc/imq/index.html
|
Linux
|
/opt/sun/mq/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 Message Queue-specific APIs for Message Queue administered objects (see Chapter 2, "Using Administered Objects").
Example Client Applications
Example applications that provide sample Java client application code are included in the following directories:
Platform
|
Location
|
Solaris
|
/usr/demo/imq/
|
Linux
|
/opt/sun/mq/examples/
|
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 SOAP with Attachments API for Java (SAAJ) Specification
The SAAJ 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 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
Related Third-Party Web Site References
Third-party URLs are referenced in this document and provide additional, related information.
|
Note
|
Sun is not responsible for the availability of third-party Web sites mentioned in this document. Sun does not endorse and is not responsible or liable for any content, advertising, products, or other materials that are available on or through such sites or resources. Sun will not be responsible or liable for any actual or alleged damage or loss caused by or in connection with the use of or reliance on any such content, goods, or services that are available on or through such sites or resources.
|
|
Sun Welcomes Your Comments
Sun is interested in improving its documentation and welcomes your comments and suggestions.
To share your comments, go to http://docs.sun.com and click Send Comments. In the online form, provide the document title and part number. The part number is a seven-digit or nine-digit number that can be found on the title page of the book or at the top of the document.