Java Message Service API Tutorial and Reference

278 Pages·2002·1.68 MB·English

by  Mark Hapner

Java Message Service API
™
Tutorial
by Kim Haase
Sun Microsystems, Inc.
Copyright 2002 Sun Microsystems, Inc.
901 San Antonio Road, Palo Alto, California 94303 U.S.A.
All rights reserved.
SunMicrosystems,Inc.hasintellectualpropertyrightsrelatingtotechnologyembodiedintheproduct
thatisdescribedinthisdocument.Inparticular,andwithoutlimitation,theseintellectualpropertyrights
mayincludeoneormoreoftheU.S.patentslistedathttp://www.sun.com/patentsandoneormoreaddi-
tional patents or pending patent applications in the U.S. and in other countries.
Thisdocumentandtheproducttowhichitpertainsaredistributedunderlicensesrestrictingtheiruse,
copying,distribution,anddecompilation.Nopartoftheproductorofthisdocumentmaybereproduced
in any form by any means without prior written authorization of Sun and its licensors, if any.
Unless otherwise licensed, software code inall technical materials herein (including articles, FAQs,
samples) is provided under this License: http://developer.java.sun.com/berkeley_license.html.
Third-party software, including font technology, is copyrighted and licensed from Sun suppliers.
Sun,SunMicrosystems,theSunlogo,Java,theJavaCoffeeCuplogo,J2EE,J2SE,JavaNamingand
DirectoryInterface,EnterpriseJavaBeans,EJB,JavaServerPages,andJSParetrademarksorregistered
trademarksofSunMicrosystems,Inc.intheUnitedStatesandothercountries. UNIXisaregistered
trademark in the United States and other countries, exclusively licensed through X/Open Company,
Ltd.
DOCUMENTATIONISPROVIDED"ASIS"ANDALLEXPRESSORIMPLIEDCONDITIONS,
REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF
MERCHANTABILITY, FITNESS FOR FOR A PARTICULAR PURPOSE OR NON-INFRINGE-
MENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE
HELD TO BE LEGALLY INVALID.
Contents
1 Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9
1.1 What Is Messaging?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9
1.2 What Is the JMS API? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10
1.3 When Can You Use the JMS API?. . . . . . . . . . . . . . . . . . . . . . . . . . .11
1.4 How Does the JMS API Work with the J2EE™ Platform?. . . . . . . . .12
2 Basic JMS API Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15
2.1 JMS API Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15
2.2 Messaging Domains. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16
2.2.1 Point-to-Point Messaging Domain. . . . . . . . . . . . . . . . . . . .17
2.2.2 Publish/Subscribe Messaging Domain . . . . . . . . . . . . . . . .17
2.3 Message Consumption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19
3 The JMS API Programming Model. . . . . . . . . . . . . . . . . . . . . . . . . .21
3.1 Administered Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22
3.1.1 Connection Factories. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23
3.1.2 Destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24
3.2 Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24
3.3 Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25
3.4 Message Producers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26
3.5 Message Consumers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27
3.5.1 Message Listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28
3.5.2 Message Selectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29
3.6 Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29
3.6.1 Message Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29
3.6.2 Message Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30
3.6.3 Message Bodies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31
3.7 Exception Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32
iii
iv
4 Writing Simple JMS Client Applications. . . . . . . . . . . . . . . . . . . . .33
4.1 Setting Your Environment for Running Applications . . . . . . . . . . . .34
4.2 A Simple Point-to-Point Example . . . . . . . . . . . . . . . . . . . . . . . . . . .35
4.2.1 Writing the PTP Client Programs . . . . . . . . . . . . . . . . . . . .35
4.2.2 Compiling the PTP Clients . . . . . . . . . . . . . . . . . . . . . . . . .43
4.2.3 Starting the JMS Provider . . . . . . . . . . . . . . . . . . . . . . . . . .43
4.2.4 Creating the JMS Administered Objects. . . . . . . . . . . . . . .43
4.2.5 Running the PTP Clients . . . . . . . . . . . . . . . . . . . . . . . . . . .44
4.2.6 Deleting the Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45
4.3 A Simple Publish/Subscribe Example . . . . . . . . . . . . . . . . . . . . . . . .45
4.3.1 Writing the Pub/Sub Client Programs. . . . . . . . . . . . . . . . .45
4.3.2 Compiling the Pub/Sub Clients . . . . . . . . . . . . . . . . . . . . . .54
4.3.3 Starting the JMS Provider . . . . . . . . . . . . . . . . . . . . . . . . . .54
4.3.4 Creating the JMS Administered Objects. . . . . . . . . . . . . . .55
4.3.5 Running the Pub/Sub Clients. . . . . . . . . . . . . . . . . . . . . . . .55
4.3.6 Deleting the Topic and Stopping the Server . . . . . . . . . . . .56
4.4 Running JMS Client Programs on Multiple Systems. . . . . . . . . . . . .57
4.4.1 Communicating Between Two J2EE Servers . . . . . . . . . . .57
4.4.2 Communicating Between a J2EE Server and a System
Not Running a J2EE Server. . . . . . . . . . . . . . . . . . . . . . . . .58
5 Creating Robust JMS Applications. . . . . . . . . . . . . . . . . . . . . . . . . .61
5.1 Using Basic Reliability Mechanisms. . . . . . . . . . . . . . . . . . . . . . . . .62
5.1.1 Controlling Message Acknowledgment. . . . . . . . . . . . . . . .62
5.1.2 Specifying Message Persistence . . . . . . . . . . . . . . . . . . . . .64
5.1.3 Setting Message Priority Levels . . . . . . . . . . . . . . . . . . . . .65
5.1.4 Allowing Messages to Expire . . . . . . . . . . . . . . . . . . . . . . .65
5.1.5 Creating Temporary Destinations . . . . . . . . . . . . . . . . . . . .66
5.2 Using Advanced Reliability Mechanisms . . . . . . . . . . . . . . . . . . . . .66
5.2.1 Creating Durable Subscriptions. . . . . . . . . . . . . . . . . . . . . .67
5.2.2 Using JMS API Local Transactions. . . . . . . . . . . . . . . . . . .70
6 Using the JMS API in a J2EE Application . . . . . . . . . . . . . . . . . . .73
6.1 Using Enterprise Beans to Produce and to Synchronously Receive
Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73
6.1.1 Administered Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74
6.1.2 Resource Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . .74
6.1.3 Transactions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75
6.2 Using Message-Driven Beans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75
6.3 Managing Distributed Transactions. . . . . . . . . . . . . . . . . . . . . . . . . .77
v
6.4 Using the JMS API with Application Clients and Web Components 80
7 A Simple J2EE Application that Uses the JMS API . . . . . . . . . . .81
7.1 Writing and Compiling the Application Components . . . . . . . . . . . .82
7.1.1 Coding the Application Client:SimpleClient.java . . . . . .83
7.1.2 Coding the Message-Driven Bean:MessageBean.java. . . .85
7.1.3 Compiling the Source Files . . . . . . . . . . . . . . . . . . . . . . . . .88
7.2 Creating and Packaging the Application . . . . . . . . . . . . . . . . . . . . . .88
7.2.1 Starting the J2EE Server and the Deploytool. . . . . . . . . . . .89
7.2.2 Creating a Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89
7.2.3 Creating the J2EE Application. . . . . . . . . . . . . . . . . . . . . . .90
7.2.4 Packaging the Application Client . . . . . . . . . . . . . . . . . . . .90
7.2.5 Packaging the Message-Driven Bean . . . . . . . . . . . . . . . . .93
7.2.6 Checking the JNDI Names. . . . . . . . . . . . . . . . . . . . . . . . . .96
7.3 Deploying and Running the Application . . . . . . . . . . . . . . . . . . . . . .96
7.3.1 Looking at the Deployment Descriptor . . . . . . . . . . . . . . . .97
7.3.2 Adding the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .99
7.3.3 Deploying the Application. . . . . . . . . . . . . . . . . . . . . . . . . .99
7.3.4 Running the Client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100
7.3.5 Undeploying the Application. . . . . . . . . . . . . . . . . . . . . . .101
7.3.6 Removing the Application and Stopping the Server . . . . .101
8 A J2EE Application that Uses the JMS API with a Session
Bean. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103
8.1 Writing and Compiling the Application Components . . . . . . . . . . .104
8.1.1 Coding the Application Client:MyAppClient.java. . . . . .105
8.1.2 Coding the Publisher Session Bean. . . . . . . . . . . . . . . . . .106
8.1.3 Coding the Message-Driven Bean:MessageBean.java. . .112
8.1.4 Compiling the Source Files . . . . . . . . . . . . . . . . . . . . . . . .114
8.2 Creating and Packaging the Application . . . . . . . . . . . . . . . . . . . . .115
8.2.1 Starting the J2EE Server and the Deploytool. . . . . . . . . . .115
8.2.2 Creating a Topic. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116
8.2.3 Creating a Connection Factory . . . . . . . . . . . . . . . . . . . . .116
8.2.4 Creating the J2EE Application. . . . . . . . . . . . . . . . . . . . . .117
8.2.5 Packaging the Application Client . . . . . . . . . . . . . . . . . . .117
8.2.6 Packaging the Session Bean. . . . . . . . . . . . . . . . . . . . . . . .119
8.2.7 Packaging the Message-Driven Bean . . . . . . . . . . . . . . . .121
8.2.8 Specifying the JNDI Names. . . . . . . . . . . . . . . . . . . . . . . .123
8.3 Deploying and Running the Application . . . . . . . . . . . . . . . . . . . . .124
8.3.1 Adding the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .124
vi
8.3.2 Deploying the Application. . . . . . . . . . . . . . . . . . . . . . . . .125
8.3.3 Running the Client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .125
8.3.4 Undeploying the Application. . . . . . . . . . . . . . . . . . . . . . .126
8.3.5 Removing the Application and Stopping the Server. . . . .126
9 A J2EE Application that Uses the JMS API with an Entity
Bean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .129
9.1 Overview of the Human Resources Application . . . . . . . . . . . . . . .130
9.2 Writing and Compiling the Application Components . . . . . . . . . . .131
9.2.1 Coding the Application Client:
HumanResourceClient.java. . . . . . . . . . . . . . . . . . . . . . . .132
9.2.2 Coding the Message-Driven Beans . . . . . . . . . . . . . . . . . .138
9.2.3 Coding the Entity Bean . . . . . . . . . . . . . . . . . . . . . . . . . . .151
9.2.4 Compiling the Source Files . . . . . . . . . . . . . . . . . . . . . . . .161
9.3 Creating and Packaging the Application . . . . . . . . . . . . . . . . . . . . .161
9.3.1 Starting the J2EE Server and the Deploytool . . . . . . . . . .162
9.3.2 Creating a Queue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .162
9.3.3 Starting the Cloudscape Database Server . . . . . . . . . . . . .163
9.3.4 Creating the J2EE Application . . . . . . . . . . . . . . . . . . . . .163
9.3.5 Packaging the Application Client . . . . . . . . . . . . . . . . . . .163
9.3.6 Packaging the Equipment Message-Driven Bean . . . . . . .166
9.3.7 Packaging the Office Message-Driven Bean. . . . . . . . . . .169
9.3.8 Packaging the Schedule Message-Driven Bean. . . . . . . . .171
9.3.9 Packaging the Entity Bean. . . . . . . . . . . . . . . . . . . . . . . . .173
9.3.10 Specifying the Entity Bean Deployment Settings . . . . . . .175
9.3.11 Specifying the JNDI Names . . . . . . . . . . . . . . . . . . . . . . .176
9.4 Deploying and Running the Application . . . . . . . . . . . . . . . . . . . . .177
9.4.1 Adding the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .177
9.4.2 Deploying the Application. . . . . . . . . . . . . . . . . . . . . . . . .178
9.4.3 Running the Client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .178
9.4.4 Undeploying the Application. . . . . . . . . . . . . . . . . . . . . . .179
9.4.5 Removing the Application and Stopping the Server. . . . .179
10 An Application Example that Uses Two J2EE Servers. . . . . . . .181
10.1 Overview of the Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .182
10.2 Writing and Compiling the Application Components . . . . . . . . . . .183
10.2.1 Coding the Application Client:
MultiAppServerRequester.java. . . . . . . . . . . . . . . . . . . .183
10.2.2 Coding the Message-Driven Bean:ReplyMsgBean.java. .190
10.2.3 Compiling the Source Files . . . . . . . . . . . . . . . . . . . . . . . .194
vii
10.3 Creating and Packaging the Application . . . . . . . . . . . . . . . . . . . . .194
10.3.1 Starting the J2EE Servers and the Deploytool. . . . . . . . . .195
10.3.2 Creating a Connection Factory . . . . . . . . . . . . . . . . . . . . .195
10.3.3 Creating the First J2EE Application . . . . . . . . . . . . . . . . .196
10.3.4 Packaging the Application Client . . . . . . . . . . . . . . . . . . .197
10.3.5 Creating the Second J2EE Application . . . . . . . . . . . . . . .200
10.3.6 Packaging the Message-Driven Bean . . . . . . . . . . . . . . . .200
10.3.7 Checking the JNDI Names. . . . . . . . . . . . . . . . . . . . . . . . .203
10.4 Deploying and Running the Applications . . . . . . . . . . . . . . . . . . . .204
10.4.1 Adding the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .204
10.4.2 Deploying the Applications. . . . . . . . . . . . . . . . . . . . . . . .205
10.4.3 Running the Client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .206
10.4.4 Undeploying the Applications. . . . . . . . . . . . . . . . . . . . . .206
10.4.5 Removing the Applications and Stopping the Servers . . .207
10.5 Accessing a J2EE Application from a Remote System that Is Not
Running a J2EE Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .207
10.5.1 Accessing a J2EE Application from a Standalone Client .207
10.5.2 Usingrunclient to Access a Remote Application Client.214
Appendix A: JMS Client Examples . . . . . . . . . . . . . . . . . . . . . . . . .215
A.1 Durable Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .215
A.2 Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .225
A.3 Acknowledgment Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .250
A.4 Utility Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .264

1
C H A P T E R
Overview
T
HISoverviewoftheJava™MessageServiceApplicationProgrammingInterface
(the JMS API) answers the following questions.
• What is messaging?
• What is the JMS API?
• How can you use the JMS API?
• How does the JMS API work with the Java 2 Platform, Enterprise Edition
(J2EE™ platform)?
1.1 What Is Messaging?
Messagingisamethodofcommunicationbetweensoftwarecomponentsorapplica-
tions. A messaging system is a peer-to-peer facility: A messaging client can send
messagesto,andreceivemessagesfrom,anyotherclient.Eachclientconnectstoa
messagingagentthatprovidesfacilitiesforcreating,sending,receiving,andreading
messages.
Messagingenablesdistributedcommunicationthatislooselycoupled.Acom-
ponent sends a message to a destination, and the recipient can retrieve the
messagefromthedestination.However,thesenderandthereceiverdonothaveto
beavailableatthesametimeinordertocommunicate.Infact,thesenderdoesnot
needtoknowanythingaboutthereceiver;nordoesthereceiverneedtoknowany-
thing about the sender. The sender and the receiver need to know only what
message format and what destination to use. In this respect, messaging differs
9
10 CHAPTER1 OVERVIEW
from tightly coupled technologies, such as Remote Method Invocation (RMI),
which require an application to know a remote application’s methods.
Messaging also differs from electronic mail (e-mail), which is a method of
communication between people or between software applications and people.
Messaging is used for communication between software applications or software
components.
1.2 What Is the JMS API?
The Java Message Service is a Java API that allows applications to create, send,
receive, and read messages. Designed by Sun and several partner companies, the
JMS API defines a common set of interfaces and associated semantics that allow
programs written in the Java programming language to communicate with other
messaging implementations.
The JMS API minimizes the set of concepts a programmer must learn to use
messaging products but provides enough features to support sophisticated mes-
sagingapplications.ItalsostrivestomaximizetheportabilityofJMSapplications
across JMS providers in the same messaging domain.
TheJMSAPIenablescommunicationthatisnotonlylooselycoupledbutalso
• Asynchronous. A JMS provider can deliver messages to a client as they ar-
rive; a client does not have to request messages in order to receive them.
• Reliable. The JMS API can ensure that a message is delivered once and only
once. Lower levels of reliability are available for applications that can afford
to miss messages or to receive duplicate messages.
TheJMSSpecificationwasfirstpublishedinAugust1998.Thelatestversion
of the JMS Specification is Version 1.0.2b, which was released in August 2001.
You can download a copy of the Specification from the JMS Web site, http://
java.sun.com/products/jms/.