j2ee tutorial

The J2EE™ 1.4 Tutorial
Eric Armstrong
Jennifer Ball
Stephanie Bodoff
Debbie Bode Carson
Ian Evans
Dale Green
Kim Haase
Eric Jendrock
March 31, 2004
Copyright © 2004 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, U.S.A.
All rights reserved.U.S. Government Rights - Commercial software. Government users are subject to the
Sun Microsystems, Inc. standard license agreement and applicable provisions of the FAR and its supple-
ments.
This distribution may include materials developed by third parties.
Sun, Sun Microsystems, the Sun logo, Java, JavaBeans, JavaServer, JavaServer Pages, Enterprise Java-
Beans, Java Naming and Directory Interface, JavaMail, JDBC, EJB, JSP, J2EE, J2SE, “Write Once, Run
Anywhere”, and the Java Coffee Cup logo are trademarks or registered trademarks of Sun Microsystems,
Inc. in the U.S. and other countries.
Unless otherwise licensed, software code in all technical materials herein (including articles, FAQs, sam-
ples) is provided under this License.
Products covered by and information contained in this service manual are controlled by U.S. Export Con-
trol laws and may be subject to the export or import laws in other countries. Nuclear, missile, chemical
biological weapons or nuclear maritime end uses or end users, whether direct or indirect, are strictly pro-
hibited. Export or reexport to countries subject to U.S. embargo or to entities identified on U.S. export
exclusion lists, including, but not limited to, the denied persons and specially designated nationals lists is
strictly prohibited.
DOCUMENTATION IS PROVIDED "AS IS" AND ALL EXPRESS OR IMPLIED CONDITIONS,
REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MER-
CHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE
DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE

LEGALLY INVALID.
Copyright © 2004 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, États-
Unis. Tous droits réservés.
Droits du gouvernement américain, utlisateurs gouvernmentaux - logiciel commercial. Les utilisateurs
gouvernmentaux sont soumis au contrat de licence standard de Sun Microsystems, Inc., ainsi qu aux dis-
positions en vigueur de la FAR [ (Federal Acquisition Regulations) et des suppléments à celles-ci.
Cette distribution peut comprendre des composants développés pardes tierces parties.
Sun, Sun Microsystems, le logo Sun, Java, JavaBeans, JavaServer, JavaServer Pages, Enterprise Java-
Beans, Java Naming and Directory Interface, JavaMail, JDBC, EJB, JSP, J2EE, J2SE, “Write Once, Run
Anywhere”, et le logo Java Coffee Cup sont des marques de fabrique ou des marques déposées de Sun
Microsystems, Inc. aux États-Unis et dans d’autres pays.
A moins qu’autrement autorisé, le code de logiciel en tous les matériaux techniques dans le présent (arti-
cles y compris, FAQs, échantillons) est fourni sous ce permis.
Les produits qui font l’objet de ce manuel d’entretien et les informations qu’il contient sont régis par la
législation américaine en matière de contrôle des exportations et peuvent être soumis au droit d’autres
pays dans le domaine des exportations et importations. Les utilisations finales, ou utilisateurs finaux, pour
des armes nucléaires, des missiles, des armes biologiques et chimiques ou du nucléaire maritime, directe-
ment ou indirectement, sont strictement interdites. Les exportations ou réexportations vers des pays sous
embargo des États-Unis, ou vers des entités figurant sur les listes d’exclusion d’exportation américaines,
y compris, mais de manière non exclusive, la liste de personnes qui font objet d’un ordre de ne pas partic-
iper, d’une façon directe ou indirecte, aux exportations des produits ou des services qui sont régi par la
législation américaine en matière de contrôle des exportations ("U .S. Commerce Department’s Table of
Denial Orders "et la liste de ressortissants spécifiquement désignés ("U.S. Treasury Department of Spe-
cially Designated Nationals and Blocked Persons "),, sont rigoureusement interdites.
LA DOCUMENTATION EST FOURNIE "EN L’ÉTAT" ET TOUTES AUTRES CONDITIONS, DEC-
LARATIONS ET GARANTIES EXPRESSES OU TACITES SONT FORMELLEMENT EXCLUES,
DANS LA MESURE AUTORISEE PAR LA LOI APPLICABLE, Y COMPRIS NOTAMMENT TOUTE
GARANTIE IMPLICITE RELATIVE A LA QUALITE MARCHANDE, A L’APTITUDE A UNE
UTILISATION PARTICULIERE OU A L’ABSENCE DE CONTREFAÇON.
iii

Foreword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxxi
About This Tutorial. . . . . . . . . . . . . . . . . . . . . . . . .xxxiii
Who Should Use This Tutorial xxxiii
Prerequisites xxxiii
How to Read This Tutorial xxxiv
About the Examples xxxvi
Further Information xxxix
How to Print This Tutorial xxxix
Typographical Conventions xl
Acknowledgments xl
Feedback xli
Chapter 1: Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Distributed Multitiered Applications 2
J2EE Components 3
J2EE Clients 4
Web Components 6
Business Components 6
Enterprise Information System Tier 8
J2EE Containers 8
Container Services 8
Container Types 9
Web Services Support 10
XML 11
SOAP Transport Protocol 12
WSDL Standard Format 12
UDDI and ebXML Standard Formats 13
Packaging 13
Contents
iv CONTENTS
Development Roles 15

J2EE Product Provider 15
Tool Provider 15
Application Component Provider 16
Application Assembler 16
Application Deployer and Administrator 17
J2EE 1.4 APIs 18
Enterprise JavaBeans Technology 18
Java Servlet Technology 19
JavaServer Pages Technology 19
Java Message Service API 19
Java Transaction API 19
JavaMail API 20
JavaBeans Activation Framework 20
Java API for XML Processing 20
Java API for XML-Based RPC 20
SOAP with Attachments API for Java 21
Java API for XML Registries 21
J2EE Connector Architecture 22
JDBC API 22
Java Naming and Directory Interface 22
Java Authentication and Authorization Service 23
Simplified Systems Integration 24
Sun Java System Application Server Platform Edition 8 24
Technologies 25
Tools 26
Starting and Stopping the Application Server 27
Starting the Admin Console 28
Starting the deploytool Utility 29
Starting and Stopping the PointBase Database Server 29
Debugging J2EE Applications 29

Chapter 2: Understanding XML. . . . . . . . . . . . . . . . . . . . . . . . . .33
Introduction to XML 33
What Is XML? 33
Why Is XML Important? 38
How Can You Use XML? 40
Generating XML Data 43
Writing a Simple XML File 43
Defining the Root Element 44
CONTENTS v
Writing Processing Instructions 48
Introducing an Error 49
Substituting and Inserting Text 50
Creating a Document Type Definition 54
Documents and Data 59
Defining Attributes and Entities in the DTD 59
Referencing Binary Entities 66
Defining Parameter Entities and Conditional Sections 68
Resolving a Naming Conflict 72
Using Namespaces 73
Designing an XML Data Structure 76
Saving Yourself Some Work 77
Attributes and Elements 77
Normalizing Data 79
Normalizing DTDs 81
Summary 81
Chapter 3: Getting Started with Web Applications . . . . . . . . . 83
Web Application Life Cycle 86
Web Modules 88
Packaging Web Modules 90
Deploying Web Modules 91

Listing Deployed Web Modules 95
Updating Web Modules 95
Undeploying Web Modules 98
Configuring Web Applications 99
Mapping URLs to Web Components 99
Declaring Welcome Files 101
Setting Initialization Parameters 102
Mapping Errors to Error Screens 102
Declaring Resource References 103
Duke’s Bookstore Examples 103
Accessing Databases from Web Applications 104
Populating the Example Database 105
Creating a Data Source in the Application Server 106
Specifying a Web Application’s Resource Reference 106
Mapping the Resource Reference to a Data Source 107
Further Information 108
vi CONTENTS
Chapter 4: Java API for XML Processing . . . . . . . . . . . . . . . . .109
The JAXP APIs 109
An Overview of the Packages 110
The Simple API for XML (SAX) APIs 111
The SAX Packages 114
The Document Object Model (DOM) APIs 114
The DOM Packages 116
The Extensible Stylesheet Language Transformations (XSLT) APIs
117
The XSLT Packages 118
Using the JAXP Libraries 118
Where Do You Go from Here? 118
Chapter 5: Simple API for XML . . . . . . . . . . . . . . . . . . . . . . . . .121

When to Use SAX 122
Echoing an XML File with the SAX Parser 123
Creating the Skeleton 124
Importing Classes 124
Setting Up for I/O 125
Implementing the ContentHandler Interface 125
Setting up the Parser 127
Writing the Output 128
Spacing the Output 128
Handling Content Events 129
Compiling and Running the Program 134
Checking the Output 135
Identifying the Events 136
Compressing the Output 138
Inspecting the Output 140
Documents and Data 141
Adding Additional Event Handlers 141
Identifying the Document’s Location 142
Handling Processing Instructions 144
Summary 145
Handling Errors with the Nonvalidating Parser 145
Displaying Special Characters and CDATA 153
Handling Special Characters 153
Handling Text with XML-Style Syntax 154
Handling CDATA and Other Characters 155
Parsing with a DTD 156
CONTENTS vii
DTD’s Effect on the Nonvalidating Parser 156
Tracking Ignorable Whitespace 157
Cleanup 159

Empty Elements, Revisited 159
Echoing Entity References 160
Echoing the External Entity 160
Summarizing Entities 161
Choosing Your Parser Implementation 161
Using the Validating Parser 162
Configuring the Factory 162
Validating with XML Schema 163
Experimenting with Validation Errors 166
Error Handling in the Validating Parser 168
Parsing a Parameterized DTD 168
DTD Warnings 170
Handling Lexical Events 170
How the LexicalHandler Works 171
Working with a LexicalHandler 172
Using the DTDHandler and EntityResolver 177
The DTDHandler API 178
The EntityResolver API 179
Further Information 179
Chapter 6: Document Object Model . . . . . . . . . . . . . . . . . . . 181
When to Use DOM 182
Documents Versus Data 182
Mixed-Content Model 183
A Simpler Model 184
Increasing the Complexity 185
Choosing Your Model 187
Reading XML Data into a DOM 188
Creating the Program 188
Additional Information 192
Looking Ahead 195

Displaying a DOM Hierarchy 195
Convert DomEcho to a GUI App 195
Create Adapters to Display the DOM in a JTree 201
Finishing Up 211
Examining the Structure of a DOM 211
Displaying a Simple Tree 212
viii CONTENTS
Displaying a More Complex Tree 214
Finishing Up 220
Constructing a User-Friendly JTree from a DOM 221
Compressing the Tree View 221
Acting on Tree Selections 227
Handling Modifications 237
Finishing Up 237
Creating and Manipulating a DOM 237
Obtaining a DOM from the Factory 237
Normalizing the DOM 241
Other Operations 243
Finishing Up 246
Validating with XML Schema 246
Overview of the Validation Process 247
Configuring the DocumentBuilder Factory 247
Validating with Multiple Namespaces 249
Further Information 252
Chapter 7: Extensible Stylesheet Language Transformations 253
Introducing XSL, XSLT and XPath 254
The JAXP Transformation Packages 254
How XPath Works 255
XPath Expressions 255
The XSLT/XPath Data Model 256

Templates and Contexts 257
Basic XPath Addressing 257
Basic XPath Expressions 258
Combining Index Addresses 259
Wildcards 259
Extended-Path Addressing 260
XPath Data Types and Operators 261
String-Value of an Element 261
XPath Functions 262
Summary 265
Writing Out a DOM as an XML File 265
Reading the XML 266
Creating a Transformer 267
Writing the XML 270
Writing Out a Subtree of the DOM 271
Summary 272
CONTENTS ix
Generating XML from an Arbitrary Data Structure 272
Creating a Simple File 273
Creating a Simple Parser 275
Modifying the Parser to Generate SAX Events 277
Using the Parser as a SAXSource 284
Doing the Conversion 286
Transforming XML Data with XSLT 287
Defining a Simple <article> Document Type 287
Creating a Test Document 289
Writing an XSLT Transform 290
Processing the Basic Structure Elements 291
Writing the Basic Program 295
Trimming the Whitespace 297

Processing the Remaining Structure Elements 300
Process Inline (Content) Elements 304
Printing the HTML 309
What Else Can XSLT Do? 309
Transforming from the Command Line with Xalan 311
Concatenating Transformations with a Filter Chain 311
Writing the Program 311
Understanding How the Filter Chain Works 315
Testing the Program 316
Conclusion 318
Further Information 319
Chapter 8: Building Web Services with JAX-RPC . . . . . . . . . . 321
Setting the Port 322
Creating a Simple Web Service and Client with JAX-RPC 322
Coding the Service Endpoint Interface and Implementation Class 324
Building the Service 325
Packaging the Service 326
Specifying the Endpoint Address 328
Deploying the Service 328
Static Stub Client 329
Types Supported by JAX-RPC 332
J2SE SDK Classes 332
Primitives 333
Arrays 333
Value Types 333
JavaBeans Components 334
x CONTENTS
Web Service Clients 334
Dynamic Proxy Client 334
Dynamic Invocation Interface (DII) Client 337

Application Client 341
More JAX-RPC Clients 345
Web Services Interoperability (WS-I) and JAX-RPC 345
Further Information 346
Chapter 9: SOAP with Attachments API for Java . . . . . . . . . .347
Overview of SAAJ 348
Messages 348
Connections 352
Tutorial 353
Creating and Sending a Simple Message 354
Adding Content to the Header 363
Adding Content to the SOAPPart Object 364
Adding a Document to the SOAP Body 365
Manipulating Message Content Using SAAJ or DOM APIs 366
Adding Attachments 366
Adding Attributes 369
Using SOAP Faults 375
Code Examples 379
Request.java 380
MyUddiPing.java 381
HeaderExample.java 388
DOMExample.java and DOMSrcExample.java 390
Attachments.java 394
SOAPFaultTest.java 396
Further Information 397
Chapter 10: Java API for XML Registries . . . . . . . . . . . . . . . . . .399
Overview of JAXR 399
What Is a Registry? 399
What Is JAXR? 400
JAXR Architecture 401

Implementing a JAXR Client 403
Establishing a Connection 404
Querying a Registry 409
Managing Registry Data 414
CONTENTS xi
Using Taxonomies in JAXR Clients 422
Running the Client Examples 427
Before You Compile the Examples 429
Compiling the Examples 431
Running the Examples 431
Using JAXR Clients in J2EE Applications 436
Coding the Application Client: MyAppClient.java 437
Coding the PubQuery Session Bean 438
Compiling the Source Files 439
Importing Certificates 439
Starting the Application Server 440
Creating JAXR Resources 440
Creating and Packaging the Application 441
Deploying the Application 444
Running the Application Client 444
Further Information 445
Chapter 11: Java Servlet Technology . . . . . . . . . . . . . . . . . . . . 447
What Is a Servlet? 447
The Example Servlets 448
Troubleshooting 452
Servlet Life Cycle 453
Handling Servlet Life-Cycle Events 453
Handling Errors 456
Sharing Information 456
Using Scope Objects 456

Controlling Concurrent Access to Shared Resources 458
Accessing Databases 459
Initializing a Servlet 460
Writing Service Methods 460
Getting Information from Requests 461
Constructing Responses 463
Filtering Requests and Responses 466
Programming Filters 467
Programming Customized Requests and Responses 469
Specifying Filter Mappings 471
Invoking Other Web Resources 473
Including Other Resources in the Response 474
Transferring Control to Another Web Component 475
Accessing the Web Context 476
xii CONTENTS
Maintaining Client State 477
Accessing a Session 478
Associating Objects with a Session 478
Session Management 479
Session Tracking 480
Finalizing a Servlet 481
Tracking Service Requests 481
Notifying Methods to Shut Down 482
Creating Polite Long-Running Methods 483
Further Information 484
Chapter 12: JavaServer Pages Technology . . . . . . . . . . . . . . .485
What Is a JSP Page? 485
Example 486
The Example JSP Pages 490
The Life Cycle of a JSP Page 497

Translation and Compilation 497
Execution 498
Creating Static Content 500
Response and Page Encoding 501
Creating Dynamic Content 501
Using Objects within JSP Pages 502
Expression Language 503
Deactivating Expression Evaluation 504
Using Expressions 504
Variables 505
Implicit Objects 506
Literals 507
Operators 508
Reserved Words 508
Examples 509
Functions 510
JavaBeans Components 511
JavaBeans Component Design Conventions 511
Creating and Using a JavaBeans Component 513
Setting JavaBeans Component Properties 514
Retrieving JavaBeans Component Properties 516
Using Custom Tags 517
Declaring Tag Libraries 517
Including the Tag Library Implementation 519
CONTENTS xiii
Reusing Content in JSP Pages 520
Transferring Control to Another Web Component 522
jsp:param Element 522
Including an Applet 522
Setting Properties for Groups of JSP Pages 525

Further Information 528
Chapter 13: JavaServer Pages Documents . . . . . . . . . . . . . . . 529
The Example JSP Document 530
Creating a JSP Document 535
Declaring Tag Libraries 537
Including Directives in a JSP Document 539
Creating Static and Dynamic Content 541
Using the jsp:root Element 545
Using the jsp:output Element 545
Identifying the JSP Document to the Container 550
Chapter 14: JavaServer Pages Standard Tag Library . . . . . . . 551
The Example JSP Pages 552
Using JSTL 555
Tag Collaboration 556
Core Tag Library 558
Variable Support Tags 558
Flow Control Tags 559
URL Tags 562
Miscellaneous Tags 563
XML Tag Library 564
Core Tags 566
Flow Control Tags 567
Transformation Tags 568
Internationalization Tag Library 568
Setting the Locale 569
Messaging Tags 570
Formatting Tags 570
SQL Tag Library 571
query Tag Result Interface 573
Functions 576

Further Information 577
xiv CONTENTS
Chapter 15: Custom Tags in JSP Pages . . . . . . . . . . . . . . . . . . .579
What Is a Custom Tag? 580
The Example JSP Pages 580
Types of Tags 585
Tags with Attributes 585
Tags with Bodies 588
Tags That Define Variables 589
Communication between Tags 589
Encapsulating Reusable Content Using Tag Files 590
Tag File Location 592
Tag File Directives 592
Evaluating Fragments Passed to Tag Files 601
Examples 601
Tag Library Descriptors 606
Top-Level Tag Library Descriptor Elements 607
Declaring Tag Files 608
Declaring Tag Handlers 611
Declaring Tag Attributes for Tag Handlers 613
Declaring Tag Variables for Tag Handlers 614
Programming Simple Tag Handlers 616
Including Tag Handlers in Web Applications 617
How Is a Simple Tag Handler Invoked? 617
Tag Handlers for Basic Tags 617
Tag Handlers for Tags with Attributes 618
Tag Handlers for Tags with Bodies 620
Tag Handlers for Tags That Define Variables 621
Cooperating Tags 624
Examples 626

Chapter 16: Scripting in JSP Pages . . . . . . . . . . . . . . . . . . . . . .635
The Example JSP Pages 636
Using Scripting 637
Disabling Scripting 638
Declarations 638
Initializing and Finalizing a JSP Page 638
Scriptlets 639
Expressions 640
Programming Tags That Accept Scripting Elements 641
TLD Elements 641
Tag Handlers 641
CONTENTS xv
Tags with Bodies 644
Cooperating Tags 645
Tags That Define Variables 647
Chapter 17: JavaServer Faces Technology . . . . . . . . . . . . . . . 649
JavaServer Faces Technology Benefits 651
What Is a JavaServer Faces Application? 652
Framework Roles 653
A Simple JavaServer Faces Application 654
Steps in the Development Process 654
Creating the Pages 657
Defining Page Navigation 659
Developing the Beans 661
Adding Managed Bean Declarations 662
User Interface Component Model 663
The User Interface Component Classes 664
The Component Rendering Model 666
Conversion Model 670
Event and Listener Model 672

Validation Model 673
Navigation Model 674
Backing Bean Management 676
How the Pieces Fit Together 679
The Life Cycle of a JavaServer Faces Page 682
Request Processing Life Cycle Scenarios 683
Standard Request Processing Life Cycle 684
Further Information 689
Chapter 18: Using JavaServer Faces Technology in JSP Pages . .
691
The Example JavaServer Faces Application 692
Setting Up a Page 696
Using the Core Tags 698
Using the HTML Component Tags 701
UI Component Tag Attributes 702
The UIForm Component 704
The UIColumn Component 705
The UICommand Component 706
The UIData Component 708
xvi CONTENTS
The UIGraphic Component 711
The UIInput and UIOutput Components 712
The UIPanel Component 716
The UISelectBoolean Component 718
The UISelectMany Component 719
The UIMessage and UIMessages Components 720
The UISelectOne Component 721
UISelectItem, UISelectItems, and UISelectItemGroup 722
Using Localized Messages 725
Referencing a ResourceBundle from a Page 726

Referencing a Localized Message 726
Using the Standard Converters 727
Using DateTimeConverter 729
Using NumberConverter 731
Registering Listeners on Components 733
Registering a ValueChangeListener on a Component 733
Registering an ActionListener on a Component 734
Using the Standard Validators 734
Requiring a Value 735
Using the LongRangeValidator 736
Binding Component Values and Instances to External Data Sources
736
Binding a Component Value to a Property 738
Binding a Component Value to an Implicit Object 739
Binding a Component Instance to a Bean Property 740
Referencing a Backing Bean Method 742
Referencing a Method That Performs Navigation 742
Referencing a Method That Handles an ActionEvent 743
Referencing a Method That Performs Validation 744
Referencing a Method That Handles a ValueChangeEvent 744
Using Custom Objects 745
Using a Custom Converter 746
Using a Custom Validator 747
Using a Custom Component 748
Chapter 19: Developing with JavaServer Faces Technology .751
Writing Component Properties 752
Writing Properties Bound to Component Values 752
Writing Properties Bound to Component Instances 761
Performing Localization 763
CONTENTS xvii

Creating a Resource Bundle 763
Localizing Dynamic Data 764
Localizing Messages 764
Creating a Custom Converter 766
Implementing an Event Listener 769
Creating a Custom Validator 772
Implement the Validator Interface 773
Creating a Custom Tag 775
Writing Backing Bean Methods 777
Writing a Method to Handle Navigation 778
Writing a Method to Handle an ActionEvent 779
Writing a Method to Perform Validation 780
Writing a Method to Handle a Value-Change Event 781
Chapter 20: Creating Custom UI Components . . . . . . . . . . . . 783
Determining Whether You Need a Custom Component or Renderer
784
When to Use a Custom Component 784
When to Use a Custom Renderer 785
Component, Renderer, and Tag Combinations 786
Understanding the Image Map Example 787
Why Use JavaServer Faces Technology to Implement an Image Map?
788
Understanding the Rendered HTML 788
Understanding the JSP Page 789
Configuring Model Data 791
Summary of the Application Classes 793
Steps for Creating a Custom Component 794
Creating the Component Tag Handler 795
Defining the Custom Component Tag in a Tag Library Descriptor 800
Creating Custom Component Classes 801

Performing Encoding 804
Performing Decoding 806
Enabling Value-Binding of Component Properties 807
Saving and Restoring State 808
Delegating Rendering to a Renderer 810
Create the Renderer Class 810
Identify the Renderer Type 812
Handling Events for Custom Components 812
xviii CONTENTS
Chapter 21: Configuring JavaServer Faces Applications . . . .815
Application Configuration Resource File 816
Configuring Beans 817
Using the managed-bean Element 818
Initializing Properties using the managed-property Element 819
Initializing Maps and Lists 825
Registering Messages 826
Registering a Custom Validator 827
Registering a Custom Converter 828
Configuring Navigation Rules 829
Registering a Custom Renderer with a Render Kit 832
Registering a Custom Component 834
Basic Requirements of a JavaServer Faces Application 835
Configuring an Application Using deploytool 836
Including the Required JAR Files 841
Including the Classes, Pages, and Other Resources 841
Chapter 22: Internationalizing and Localizing Web Applications.
843
Java Platform Localization Classes 843
Providing Localized Messages and Labels 844
Establishing the Locale 845

Setting the Resource Bundle 846
Retrieving Localized Messages 846
Date and Number Formatting 847
Character Sets and Encodings 848
Character Sets 848
Character Encoding 849
Further Information 852
Chapter 23: Enterprise Beans . . . . . . . . . . . . . . . . . . . . . . . . . . .853
What Is an Enterprise Bean? 853
Benefits of Enterprise Beans 853
When to Use Enterprise Beans 854
Types of Enterprise Beans 855
What Is a Session Bean? 855
State Management Modes 855
When to Use Session Beans 856
What Is an Entity Bean? 857
CONTENTS xix
What Makes Entity Beans Different from Session Beans? 857
Container-Managed Persistence 859
When to Use Entity Beans 862
What Is a Message-Driven Bean? 862
What Makes Message-Driven Beans Different from Session and Entity
Beans? 863
When to Use Message-Driven Beans 864
Defining Client Access with Interfaces 864
Remote Clients 865
Local Clients 866
Local Interfaces and Container-Managed Relationships 866
Deciding on Remote or Local Access 867
Web Service Clients 868

Method Parameters and Access 868
The Contents of an Enterprise Bean 869
Naming Conventions for Enterprise Beans 870
The Life Cycles of Enterprise Beans 871
The Life Cycle of a Stateful Session Bean 871
The Life Cycle of a Stateless Session Bean 873
The Life Cycle of an Entity Bean 873
The Life Cycle of a Message-Driven Bean 875
Further Information 876
Chapter 24: Getting Started with Enterprise Beans . . . . . . . . . 877
Creating the J2EE Application 878
Creating the Enterprise Bean 878
Coding the Enterprise Bean 879
Compiling the Source Files 880
Packaging the Enterprise Bean 881
Creating the Application Client 882
Coding the Application Client 883
Compiling the Application Client 885
Packaging the Application Client 886
Specifying the Application Client’s Enterprise Bean Reference 887
Creating the Web Client 887
Coding the Web Client 887
Compiling the Web Client 889
Packaging the Web Client 889
Specifying the Web Client’s Enterprise Bean Reference 890
Mapping the Enterprise Bean References 891
xx CONTENTS
Specifying the Web Client’s Context Root 892
Deploying the J2EE Application 893
Running the Application Client 893

Running the Web Client 894
Modifying the J2EE Application 895
Modifying a Class File 895
Adding a File 896
Modifying a Deployment Setting 896
Chapter 25: Session Bean Examples . . . . . . . . . . . . . . . . . . . . .897
The CartBean Example 897
Session Bean Class 898
Home Interface 902
Remote Interface 904
Helper Classes 904
Building the CartBean Example 904
Creating the Application 905
Packaging the Enterprise Bean 905
Packaging the Application Client 906
A Web Service Example: HelloServiceBean 909
Web Service Endpoint Interface 909
Stateless Session Bean Implementation Class 909
Building HelloServiceBean 910
Building the Web Service Client 913
Running the Web Service Client 914
Other Enterprise Bean Features 914
Accessing Environment Entries 914
Comparing Enterprise Beans 915
Passing an Enterprise Bean’s Object Reference 916
Using the Timer Service 917
Creating Timers 917
Canceling and Saving Timers 918
Getting Timer Information 919
Transactions and Timers 919

The TimerSessionBean Example 919
Building TimerSessionBean 921
Handling Exceptions 926
CONTENTS xxi
Chapter 26: Bean-Managed Persistence Examples . . . . . . . . 929
The SavingsAccountBean Example 929
Entity Bean Class 930
Home Interface 941
Remote Interface 943
Running the SavingsAccountBean Example 944
Mapping Table Relationships for Bean-Managed Persistence 945
One-to-One Relationships 946
One-to-Many Relationships 949
Many-to-Many Relationships 957
Primary Keys for Bean-Managed Persistence 960
The Primary Key Class 961
Primary Keys in the Entity Bean Class 962
Getting the Primary Key 963
deploytool Tips for Entity Beans with Bean-Managed Persistence 963
Chapter 27: Container-Managed Persistence Examples . . . . 965
Overview of the RosterApp Application 965
The PlayerBean Code 967
Entity Bean Class 967
Local Home Interface 972
Local Interface 973
Method Invocations in RosterApp 973
Creating a Player 974
Adding a Player to a Team 975
Removing a Player 976
Dropping a Player from a Team 977

Getting the Players of a Team 978
Getting a Copy of a Team’s Players 980
Finding the Players by Position 982
Getting the Sports of a Player 983
Building and Running the RosterApp Example 985
Creating the Database Tables 985
Creating the Data Source 986
Capturing the Table Schema 986
Building the Enterprise Beans 987
Creating the Enterprise Application 987
Packaging the Enterprise Beans 987
Packaging the Enterprise Application Client 996
Deploying the Enterprise Application 997
xxii CONTENTS
Running the Client Application 998
A Guided Tour of the RosterApp Settings 999
RosterApp 999
RosterClient 1001
RosterJAR 1001
TeamJAR 1002
Primary Keys for Container-Managed Persistence 1008
The Primary Key Class 1009
Advanced CMP Topics: The OrderApp Example 1011
Structure of OrderApp 1011
Bean Relationships in OrderApp 1012
Primary Keys in OrderApp’s Entity Beans 1014
Entity Bean Mapped to More Than One Database Table 1016
Finder and Selector Methods 1017
Using Home Methods 1017
Cascade Deletes in OrderApp 1018

BLOB and CLOB Database Types in OrderApp 1018
Building and Running the OrderApp Example 1019
deploytool Tips for Entity Beans with Container-Managed Persistence
1028
Selecting the Persistent Fields and Abstract Schema Name 1028
Defining EJB QL Queries for Finder and Select Methods 1029
Defining Relationships 1029
Creating the Database Tables at Deploy Time in deploytool 1030
Chapter 28: A Message-Driven Bean Example . . . . . . . . . . .1031
Example Application Overview 1031
The Application Client 1032
The Message-Driven Bean Class 1033
The onMessage Method 1033
The ejbCreate and ejbRemove Methods 1035
Deploying and Running SimpleMessageApp 1035
Creating the Administered Objects 1035
Deploying the Application 1036
Running the Client 1037
Removing the Administered Objects 1037
deploytool Tips for Message-Driven Beans 1037
Specifying the Bean’s Type 1038
Setting the Message-Driven Bean’s Characteristics 1038
deploytool Tips for Components That Send Messages 1039
CONTENTS xxiii
Setting the Resource References 1040
Setting the Message Destination References 1040
Setting the Message Destinations 1041
Chapter 29: Enterprise JavaBeans
Query Language1043
Terminology 1044

Simplified Syntax 1044
Example Queries 1045
Simple Finder Queries 1045
Finder Queries That Navigate to Related Beans 1047
Finder Queries with Other Conditional Expressions 1048
Select Queries 1050
Full Syntax 1050
BNF Symbols 1051
BNF Grammar of EJB QL 1051
FROM Clause 1055
Path Expressions 1058
WHERE Clause 1060
SELECT Clause 1069
ORDER BY Clause 1072
EJB QL Restrictions 1073
Chapter 30: Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1075
What Is a Transaction? 1075
Container-Managed Transactions 1076
Transaction Attributes 1076
Rolling Back a Container-Managed Transaction 1080
Synchronizing a Session Bean’s Instance Variables 1082
Compiling the BankBean Example 1083
Packaging the BankBean Example 1083
Methods Not Allowed in Container-Managed Transactions 1087
Bean-Managed Transactions 1087
JDBC Transactions 1088
Deploying and Running the WarehouseBean Example 1089
Compiling the WarehouseBean Example 1089
Packaging the WarehouseBean Example 1090
JTA Transactions 1093

Deploying and Running the TellerBean Example 1094
xxiv CONTENTS
Compiling the TellerBean Example 1094
Packaging the TellerBean Example 1095
Returning without Committing 1098
Methods Not Allowed in Bean-Managed Transactions 1098
Summary of Transaction Options for Enterprise Beans 1099
Transaction Timeouts 1100
Isolation Levels 1100
Updating Multiple Databases 1101
Transactions in Web Components 1103
Chapter 31: Resource Connections . . . . . . . . . . . . . . . . . . . . .1105
JNDI Naming 1105
DataSource Objects and Connection Pools 1107
Database Connections 1108
Coding a Database Connection 1108
Specifying a Resource Reference 1109
Creating a Data Source 1110
Mail Session Connections 1111
Running the ConfirmerBean Example 1112
URL Connections 1114
Running the HTMLReaderBean Example 1115
Further Information 1116
Chapter 32: Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1117
Overview 1117
Realms, Users, Groups, and Roles 1118
Managing Users 1119
Setting Up Security Roles 1120
Mapping Roles to Users and Groups 1121
Web-Tier Security 1122

Protecting Web Resources 1124
Setting Security Requirements Using deploytool 1125
Specifying a Secure Connection 1127
Using Programmatic Security in the Web Tier 1128
Understanding Login Authentication 1130
Using HTTP Basic Authentication 1130
Using Form-Based Authentication 1131
Using Client-Certificate Authentication 1132
Using Mutual Authentication 1133
CONTENTS xxv
Using Digest Authentication 1135
Configuring Authentication 1136
Example: Using Form-Based Authentication 1136
Installing and Configuring SSL Support 1144
What Is Secure Socket Layer Technology? 1144
Understanding Digital Certificates 1145
Configuring the SSL Connector 1152
XML and Web Services Security 1155
Example: Basic Authentication with JAX-RPC 1156
Example: Client-Certificate Authentication over HTTP/SSL with
JAX-RPC 1164
EJB-Tier Security 1173
Declaring Method Permissions 1173
Configuring IOR Security 1174
Using Programmatic Security in the EJB Tier 1176
Unauthenticated User Name 1176
Application Client-Tier Security 1176
EIS-Tier Security 1177
Container-Managed Sign-On 1178
Component-Managed Sign-On 1178

Configuring Resource Adapter Security 1179
Propagating Security Identity 1180
Configuring a Component’s Propagated Security Identity 1181
Configuring Client Authentication 1182
What Is Java Authorization Contract for Containers? 1182
Further Information 1183
Chapter 33: The Java Message Service API. . . . . . . . . . . . . . 1185
Overview 1186
What Is Messaging? 1186
What Is the JMS API? 1186
When Can You Use the JMS API? 1187
How Does the JMS API Work with the J2EE Platform? 1189
Basic JMS API Concepts 1190
JMS API Architecture 1190
Messaging Domains 1191
Message Consumption 1193
The JMS API Programming Model 1194
Administered Objects 1195
Connections 1197