Who Should Use This Book

This guide is meant principally
for developers of Java applications that use Sun GlassFish 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 book 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.

Before You Read This Book

You must read the Sun GlassFish Message Queue 4.4 Technical Overview to become
familiar with the Message Queue 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.

Describes message-based monitoring, a customized solution to metrics
gathering that allows metrics data to be accessed programmatically and then
to be processed in whatever way suits the consuming client.

Typographic Conventions

The following table describes the typographic conventions that are used
in this book.

Table P–2 Typographic Conventions

Typeface

Meaning

Example

AaBbCc123

The names of commands, files, and directories, and onscreen computer
output

Edit your .login file.

Use ls -a to list all files.

machine_name% you have mail.

AaBbCc123

What you type, contrasted with onscreen computer output

machine_name%su

Password:

aabbcc123

Placeholder: replace with a real name or value

The command to remove a file is rmfilename.

AaBbCc123

Book titles, new terms, and terms to be emphasized

Read Chapter 6 in the User's Guide.

A cache is a copy that is stored locally.

Do not save the file.

Note: Some emphasized items appear
bold online.

Symbol Conventions

The following table explains symbols that might be used in this book.

Table P–3 Symbol Conventions

Symbol

Description

Example

Meaning

[ ]

Contains optional arguments and command options.

ls [-l]

The -l option is not required.

{ | }

Contains a set of choices for a required command option.

-d {y|n}

The -d option requires that you use either the y argument or the n argument.

${ }

Indicates a variable reference.

${com.sun.javaRoot}

References the value of the com.sun.javaRoot variable.

-

Joins simultaneous multiple keystrokes.

Control-A

Press the Control key while you press the A key.

+

Joins consecutive multiple keystrokes.

Ctrl+A+N

Press the Control key, release it, and then press the subsequent keys.

->

Indicates menu item selection in a graphical user interface.

File -> New -> Templates

From the File menu, choose New. From the New submenu, choose Templates.

Shell Prompt Conventions

The following table shows the conventions used in Message Queue documentation
for the default UNIX® system prompt
and superuser prompt for the C shell, Bourne shell, Korn shell, and for the
Windows operating system.

Table P–4 Shell Prompt Conventions

Shell

Prompt

C shell on UNIX, Linux, or AIX

machine-name%

C shell superuser on UNIX, Linux, or AIX

machine-name#

Bourne shell and Korn shell on UNIX, Linux, or AIX

$

Bourne shell and Korn shell superuser on UNIX, Linux, or AIX

#

Windows command line

C:\>

Directory Variable Conventions

Message Queue documentation makes use of three directory variables;
two of which represent environment variables needed by Message Queue. (How
you set the environment variables varies from platform to platform.)

The following table describes the directory variables that might be
found in this book and how they are used. When installed from the IPS (pkg(5)) image distribution, Message Queue is installed in a directory
referred to as mqInstallHome, and some of the directory
variables in Table P–5 reference
this mqInstallHome directory.

For installations from the IPS image distribution on any platform, IMQ_HOME denotes the directory mqInstallHome/mq, where mqInstallHome is specified when
you install Message Queue.

For installations from Solaris SVR4 packages, IMQ_HOME is
unused.

For installations from Linux RPM packages, IMQ_HOME is
unused.

IMQ_VARHOME

Directory in which Message Queue temporary or dynamically created configuration
and data files are stored; IMQ_VARHOME can be explicitly set
as an environment variable to point to any directory or will default as described
below:

For installations from the IPS image distribution on any platform, IMQ_VARHOME defaults to mqInstallHome/var/mq.

For installations from Solaris SVR4 packages, IMQ_VARHOME defaults
to /var/imq.

For installations from Linux RPM packages, IMQ_VARHOME defaults
to /var/opt/sun/mq.

IMQ_JAVAHOME

An environment variable that points to the location of the Java runtime
environment (JRE) required by Message Queue executable
files:

On Solaris, Linux and Windows, Message Queue looks for the
latest JDK, but you can optionally set the value of IMQ_JAVAHOME to
wherever the preferred JRE resides.

On AIX, IMQ_JAVAHOME is set to point to
an existing Java runtime when you perform Message Queue installation.

Related Documentation

The information resources listed in this section provide further information
about Message Queue in addition to that contained in this manual. The section
covers the following resources:

Message Queue Documentation Set

The documents that comprise the Message Queue documentation set are
listed in the following table in the order in which you might normally use
them. These documents are available through the Sun documentation Web site
at

Java Message Service (JMS) Specification

The Message Queue message service conforms to the Java Message Service
(JMS) application programming interface, described in the Java Message Service Specification. This document can be found
at the URL

JavaDoc

JMS and Message Queue API documentation
in JavaDoc format is included in your Message Queue installation at the locations
shown in Table P–7, depending
on your installation method. This documentation can be viewed
in any HTML browser. It includes standard JMS API documentation as well as Message Queue–specific APIs.

Table P–7 JavaDoc Locations

Installation Method

Location

IPS image

IMQ_HOME/javadoc/index.html [IMQ_HOME is the Message Queue home directory.]

Solaris SVR4 packages

/usr/share/javadoc/imq/index.html

Linux RPM packages

/opt/sun/mq/javadoc/index.html

Example Client Applications

Message Queue provides a number of example client applications to assist
developers.

Example Java Client Applications

Example Java client applications are located in the following directories,
depending on installation method. See the README files
located in these directories and their subdirectories for descriptive information
about the example applications.

Installation Method

Location

IPS image

IMQ_HOME/examples [IMQ_HOME is the Message Queue home directory.]

Solaris SVR4 packages

/usr/demo/imq

Linux RPM packages

/opt/sun/mq/examples

Example C Client Programs

Example C client applications are located in the following directories,
depending on installation method. See the README files
located in these directories and their subdirectories for descriptive information
about the example applications.

Installation Method

Location

IPS image

IMQ_HOME/examples/C [IMQ_HOME is the Message Queue home directory.]

Solaris SVR4 packages

/opt/SUNWimq/demo/C

Linux RPM packages

/opt/sun/mq/examples/C

Example JMX Client Programs

Example Java Management Extensions (JMX) client applications are located
in the following directories, depending on installation method. See the README files located in these directories and their subdirectories
for descriptive information about the example applications.

Third-Party Web Site References

Where relevant, this manual refers to third-party URLs
that provide additional, related information.

Note –

Sun is not responsible for the availability of third-party Web
sites mentioned in this manual. Sun does not endorse and is not responsible
or liable for any content, advertising, products, or other materials available
on or through such sites or resources. Sun will not be responsible or liable
for any actual or alleged damage or loss caused or alleged to be caused by
or in connection with the use of or reliance on any such content, goods, or
services available on or through such sites or resources.

Searching Sun Product Documentation

Besides searching Sun product documentation from the docs.sun.com web site, you can
use a search engine by typing the following syntax in the search field: