The J2EE 1.4 tutorial

Citation preview

The J2EE™ 1.4 Tutorial For Sun Java System Application Server Platform Edition 8.1 2005Q2 UR2

Eric Armstrong Jennifer Ball Stephanie Bodoff Debbie Bode Carson Ian Evans Dale Green Kim Haase Eric Jendrock

June 7, 2005

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 supplements. This distribution may include materials developed by third parties. Sun, Sun Microsystems, the Sun logo, Java, JavaBeans, JavaServer, JavaServer Pages, Enterprise JavaBeans, 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, samples) is provided under this License. Products covered by and information contained in this service manual are controlled by U.S. Export Control 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 prohibited. 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 MERCHANTABILITY, 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, ÉtatsUnis. 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 dispositions 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 JavaBeans, 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 (articles 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, directement 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 participer, 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 Specially Designated Nationals and Blocked Persons "),, sont rigoureusement interdites. LA DOCUMENTATION EST FOURNIE "EN L’ÉTAT" ET TOUTES AUTRES CONDITIONS, DECLARATIONS 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.

Contents Foreword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxxi About This Tutorial. . . . . . . . . . . . . . . . . . . . . . . . . xxxiii Who Should Use This Tutorial Prerequisites How to Read This Tutorial About the Examples Further Information How to Buy This Tutorial How to Print This Tutorial Typographical Conventions Acknowledgments Feedback

Chapter 1:

xxxiii xxxiii xxxiv xxxvi xxxix xl xl xl xli xlii

Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Distributed Multitiered Applications J2EE Components J2EE Clients Web Components Business Components Enterprise Information System Tier J2EE Containers Container Services Container Types Web Services Support XML SOAP Transport Protocol WSDL Standard Format UDDI and ebXML Standard Formats

2 3 4 6 6 8 8 8 9 10 11 12 12 12 iii

iv

CONTENTS

Packaging Applications Development Roles J2EE Product Provider Tool Provider Application Component Provider Application Assembler Application Deployer and Administrator J2EE 1.4 APIs Enterprise JavaBeans Technology Java Servlet Technology JavaServer Pages Technology Java Message Service API Java Transaction API JavaMail API JavaBeans Activation Framework Java API for XML Processing Java API for XML-Based RPC SOAP with Attachments API for Java Java API for XML Registries J2EE Connector Architecture JDBC API Java Naming and Directory Interface Java Authentication and Authorization Service Simplified Systems Integration Sun Java System Application Server Platform Edition 8 Technologies Tools Starting and Stopping the Application Server Starting the Admin Console Starting the deploytool Utility Starting and Stopping the PointBase Database Server Debugging J2EE Applications

Chapter 2:

13 15 15 15 16 16 17 18 18 19 19 19 19 20 20 20 20 21 21 22 22 22 23 24 24 25 26 27 28 29 29 30

Understanding XML. . . . . . . . . . . . . . . . . . . . . . . . . . 33 Introduction to XML What Is XML? Why Is XML Important? How Can You Use XML? Generating XML Data Writing a Simple XML File

33 33 38 40 43 43

v

CONTENTS

Defining the Root Element Writing Processing Instructions Introducing an Error Substituting and Inserting Text Creating a Document Type Definition Documents and Data Defining Attributes and Entities in the DTD Referencing Binary Entities Defining Parameter Entities and Conditional Sections Resolving a Naming Conflict Using Namespaces Designing an XML Data Structure Saving Yourself Some Work Attributes and Elements Normalizing Data Normalizing DTDs Summary

Chapter 3:

44 48 49 50 54 59 59 66 68 72 73 76 77 77 79 81 81

Getting Started with Web Applications . . . . . . . . . 83 Web Application Life Cycle Web Modules Packaging Web Modules Deploying Web Modules Listing Deployed Web Modules Updating Web Modules Undeploying Web Modules Configuring Web Applications Mapping URLs to Web Components Declaring Welcome Files Setting Initialization Parameters Mapping Errors to Error Screens Declaring Resource References Duke’s Bookstore Examples Accessing Databases from Web Applications Populating the Example Database Creating a Data Source in the Application Server Specifying a Web Application’s Resource Reference Mapping the Resource Reference to a Data Source Further Information

86 88 90 92 95 96 98 99 99 101 102 102 103 103 104 105 105 106 107 107

vi

CONTENTS

Chapter 4:

Java API for XML Processing . . . . . . . . . . . . . . . . .109 The JAXP APIs An Overview of the Packages The Simple API for XML APIs The SAX Packages The Document Object Model APIs The DOM Packages The Extensible Stylesheet Language Transformations APIs The XSLT Packages Using the JAXP Libraries Where Do You Go from Here?

Chapter 5:

109 110 111 114 114 116 117 118 118 118

Simple API for XML . . . . . . . . . . . . . . . . . . . . . . . . . 121 When to Use SAX Echoing an XML File with the SAX Parser Creating the Skeleton Importing Classes Setting Up for I/O Implementing the ContentHandler Interface Setting up the Parser Writing the Output Spacing the Output Handling Content Events Compiling and Running the Program Checking the Output Identifying the Events Compressing the Output Inspecting the Output Documents and Data Adding Additional Event Handlers Identifying the Document’s Location Handling Processing Instructions Summary Handling Errors with the Nonvalidating Parser Displaying Special Characters and CDATA Handling Special Characters Handling Text with XML-Style Syntax Handling CDATA and Other Characters Parsing with a DTD DTD’s Effect on the Nonvalidating Parser

122 123 124 124 125 125 127 128 128 129 134 135 136 138 140 141 141 142 144 145 145 153 153 154 155 156 156

vii

CONTENTS

Tracking Ignorable Whitespace Cleanup Empty Elements, Revisited Echoing Entity References Echoing the External Entity Summarizing Entities Choosing Your Parser Implementation Using the Validating Parser Configuring the Factory Validating with XML Schema Experimenting with Validation Errors Error Handling in the Validating Parser Parsing a Parameterized DTD DTD Warnings Handling Lexical Events How the LexicalHandler Works Working with a LexicalHandler Using the DTDHandler and EntityResolver The DTDHandler API The EntityResolver API Further Information

Chapter 6:

157 159 159 160 160 161 161 162 162 163 166 168 168 170 170 171 172 177 178 179 179

Document Object Model . . . . . . . . . . . . . . . . . . . 181 When to Use DOM Documents Versus Data Mixed-Content Model A Simpler Model Increasing the Complexity Choosing Your Model Reading XML Data into a DOM Creating the Program Additional Information Looking Ahead Displaying a DOM Hierarchy Convert DomEcho to a GUI Application Create Adapters to Display the DOM in a JTree Finishing Up Examining the Structure of a DOM Displaying a Simple Tree Displaying a More Complex Tree

182 182 183 184 185 187 188 188 192 194 195 195 201 211 211 211 214

viii

CONTENTS

Finishing Up Constructing a User-Friendly JTree from a DOM Compressing the Tree View Acting on Tree Selections Handling Modifications Finishing Up Creating and Manipulating a DOM Obtaining a DOM from the Factory Normalizing the DOM Other Operations Finishing Up Validating with XML Schema Overview of the Validation Process Configuring the DocumentBuilder Factory Validating with Multiple Namespaces Further Information

Chapter 7:

220 221 221 227 237 237 237 237 241 243 246 246 247 247 249 252

Extensible Stylesheet Language Transformations 253 Introducing XSL, XSLT, and XPath The JAXP Transformation Packages How XPath Works XPath Expressions The XSLT/XPath Data Model Templates and Contexts Basic XPath Addressing Basic XPath Expressions Combining Index Addresses Wildcards Extended-Path Addressing XPath Data Types and Operators String-Value of an Element XPath Functions Summary Writing Out a DOM as an XML File Reading the XML Creating a Transformer Writing the XML Writing Out a Subtree of the DOM Summary Generating XML from an Arbitrary Data Structure

254 254 255 255 256 257 257 258 259 259 260 261 261 262 265 265 266 267 270 271 272 272

ix

CONTENTS

Creating a Simple File Creating a Simple Parser Modifying the Parser to Generate SAX Events Using the Parser as a SAXSource Doing the Conversion Transforming XML Data with XSLT Defining a Simple Document Type Creating a Test Document Writing an XSLT Transform Processing the Basic Structure Elements Writing the Basic Program Trimming the Whitespace Processing the Remaining Structure Elements Process Inline (Content) Elements Printing the HTML What Else Can XSLT Do? Transforming from the Command Line with Xalan Concatenating Transformations with a Filter Chain Writing the Program Understanding How the Filter Chain Works Testing the Program Further Information

Chapter 8:

273 275 277 284 286 287 287 289 290 291 295 297 300 304 309 309 311 311 311 315 316 318

Building Web Services with JAX-RPC . . . . . . . . . . 319 Setting the Port Creating a Simple Web Service and Client with JAX-RPC Coding the Service Endpoint Interface and Implementation Class Building the Service Packaging and Deploying the Service Static Stub Client Types Supported by JAX-RPC J2SE SDK Classes Primitives Arrays Value Types JavaBeans Components Web Service Clients Dynamic Proxy Client Dynamic Invocation Interface Client Application Client

320 320 322 323 324 327 330 331 331 332 332 332 333 333 336 340

x

CONTENTS

More JAX-RPC Clients Web Services Interoperability and JAX-RPC Further Information

Chapter 9:

343 344 344

SOAP with Attachments API for Java . . . . . . . . . .345 Overview of SAAJ Messages Connections Tutorial Creating and Sending a Simple Message Adding Content to the Header Adding Content to the SOAPPart Object Adding a Document to the SOAP Body Manipulating Message Content Using SAAJ or DOM APIs Adding Attachments Adding Attributes Using SOAP Faults Code Examples Request.java MyUddiPing.java HeaderExample.java DOMExample.java and DOMSrcExample.java Attachments.java SOAPFaultTest.java Further Information

346 346 350 352 353 362 363 364 364 365 368 373 378 378 380 387 388 392 394 395

Chapter 10: Java API for XML Registries . . . . . . . . . . . . . . . . . . 397 Overview of JAXR What Is a Registry? What Is JAXR? JAXR Architecture Implementing a JAXR Client Establishing a Connection Querying a Registry Managing Registry Data Using Taxonomies in JAXR Clients Running the Client Examples Before You Compile the Examples Compiling the Examples

397 397 398 399 400 401 406 411 419 424 425 427

xi

CONTENTS

Running the Examples Using JAXR Clients in J2EE Applications Coding the Application Client: MyAppClient.java Coding the PubQuery Session Bean Editing the Properties File Compiling the Source Files Starting the Application Server Creating JAXR Resources Creating and Packaging the Application Deploying the Application Running the Application Client Further Information

427 432 433 433 434 434 434 434 435 438 439 439

Chapter 11: Java Servlet Technology . . . . . . . . . . . . . . . . . . . . 441 What Is a Servlet? The Example Servlets Troubleshooting Servlet Life Cycle Handling Servlet Life-Cycle Events Handling Errors Sharing Information Using Scope Objects Controlling Concurrent Access to Shared Resources Accessing Databases Initializing a Servlet Writing Service Methods Getting Information from Requests Constructing Responses Filtering Requests and Responses Programming Filters Programming Customized Requests and Responses Specifying Filter Mappings Invoking Other Web Resources Including Other Resources in the Response Transferring Control to Another Web Component Accessing the Web Context Maintaining Client State Accessing a Session Associating Objects with a Session Session Management

441 442 446 447 448 450 450 451 452 453 454 455 456 458 461 461 463 466 467 468 470 471 472 472 472 473

xii

CONTENTS

Session Tracking Finalizing a Servlet Tracking Service Requests Notifying Methods to Shut Down Creating Polite Long-Running Methods Further Information

474 475 476 476 477 478

Chapter 12: JavaServer Pages Technology . . . . . . . . . . . . . . .479 What Is a JSP Page? Example The Example JSP Pages The Life Cycle of a JSP Page Translation and Compilation Execution Creating Static Content Response and Page Encoding Creating Dynamic Content Using Objects within JSP Pages Expression Language Deactivating Expression Evaluation Using Expressions Variables Implicit Objects Literals Operators Reserved Words Examples Functions JavaBeans Components JavaBeans Component Design Conventions Creating and Using a JavaBeans Component Setting JavaBeans Component Properties Retrieving JavaBeans Component Properties Using Custom Tags Declaring Tag Libraries Including the Tag Library Implementation Reusing Content in JSP Pages Transferring Control to Another Web Component jsp:param Element Including an Applet

479 480 484 491 491 493 495 495 496 496 497 498 499 500 500 502 502 503 503 504 505 506 507 508 511 511 512 514 515 516 517 517

xiii

CONTENTS

Setting Properties for Groups of JSP Pages Further Information

520 523

Chapter 13: JavaServer Pages Documents . . . . . . . . . . . . . . . 525 The Example JSP Document Creating a JSP Document Declaring Tag Libraries Including Directives in a JSP Document Creating Static and Dynamic Content Using the jsp:root Element Using the jsp:output Element Identifying the JSP Document to the Container

526 531 534 536 537 541 542 546

Chapter 14: JavaServer Pages Standard Tag Library . . . . . . . 547 The Example JSP Pages Using JSTL Tag Collaboration Core Tag Library Variable Support Tags Flow Control Tags URL Tags Miscellaneous Tags XML Tag Library Core Tags Flow Control Tags Transformation Tags Internationalization Tag Library Setting the Locale Messaging Tags Formatting Tags SQL Tag Library query Tag Result Interface Functions Further Information

548 551 553 554 554 555 558 559 560 562 563 564 564 565 566 566 567 569 572 573

Chapter 15: Custom Tags in JSP Pages . . . . . . . . . . . . . . . . . . . 575 What Is a Custom Tag? The Example JSP Pages Types of Tags

576 576 581

xiv

CONTENTS

Tags with Attributes Tags with Bodies Tags That Define Variables Communication between Tags Encapsulating Reusable Content Using Tag Files Tag File Location Tag File Directives Evaluating Fragments Passed to Tag Files Examples Tag Library Descriptors Top-Level Tag Library Descriptor Elements Declaring Tag Files Declaring Tag Handlers Declaring Tag Attributes for Tag Handlers Declaring Tag Variables for Tag Handlers Programming Simple Tag Handlers Including Tag Handlers in Web Applications How Is a Simple Tag Handler Invoked? Tag Handlers for Basic Tags Tag Handlers for Tags with Attributes Tag Handlers for Tags with Bodies Tag Handlers for Tags That Define Variables Cooperating Tags Examples

581 584 585 585 586 588 589 597 598 602 603 604 607 609 610 612 613 613 613 614 616 617 620 622

Chapter 16: Scripting in JSP Pages . . . . . . . . . . . . . . . . . . . . . .631 The Example JSP Pages Using Scripting Disabling Scripting Declarations Initializing and Finalizing a JSP Page Scriptlets Expressions Programming Tags That Accept Scripting Elements TLD Elements Tag Handlers Tags with Bodies Cooperating Tags Tags That Define Variables

632 633 634 635 635 636 636 637 638 638 640 642 644

xv

CONTENTS

Chapter 17: JavaServer Faces Technology . . . . . . . . . . . . . . . 647 JavaServer Faces Technology Benefits What Is a JavaServer Faces Application? Framework Roles A Simple JavaServer Faces Application Steps in the Development Process Creating the Pages Defining Page Navigation Developing the Beans Adding Managed Bean Declarations User Interface Component Model User Interface Component Classes Component Rendering Model Conversion Model Event and Listener Model Validation Model Navigation Model Backing Bean Management How the Pieces Fit Together The Life Cycle of a JavaServer Faces Page Request Processing Life Cycle Scenarios Standard Request Processing Life Cycle Further Information

649 650 651 652 652 655 658 659 661 662 663 664 669 670 671 672 674 677 680 681 682 687

Chapter 18: Using JavaServer Faces Technology in JSP Pages . . 689 The Example JavaServer Faces Application Setting Up a Page Using the Core Tags Using the HTML Component Tags UI Component Tag Attributes The UIForm Component The UIColumn Component The UICommand Component The UIData Component The UIGraphic Component The UIInput and UIOutput Components The UIPanel Component The UISelectBoolean Component

690 694 697 699 700 702 703 704 706 709 710 714 717

xvi

CONTENTS

The UISelectMany Component 717 The UIMessage and UIMessages Components 718 The UISelectOne Component 719 The UISelectItem, UISelectItems, and UISelectItemGroup Components 720 Using Localized Messages 724 Referencing a ResourceBundle from a Page 724 Referencing a Localized Message 725 Using the Standard Converters 726 Using DateTimeConverter 727 Using NumberConverter 729 Registering Listeners on Components 731 Registering a Value-Change Listener on a Component 731 Registering an Action Listener on a Component 732 Using the Standard Validators 732 Requiring a Value 734 Using the LongRangeValidator 734 Binding Component Values and Instances to External Data Sources 735 Binding a Component Value to a Property 736 Binding a Component Value to an Implicit Object 738 Binding a Component Instance to a Bean Property 739 Referencing a Backing Bean Method 741 Referencing a Method That Performs Navigation 741 Referencing a Method That Handles an Action Event 742 Referencing a Method That Performs Validation 743 Referencing a Method That Handles a Value-change Event 743 Using Custom Objects 744 Using a Custom Converter 745 Using a Custom Validator 746 Using a Custom Component 747

Chapter 19: Developing with JavaServer Faces Technology .749 Writing Component Properties Writing Properties Bound to Component Values Writing Properties Bound to Component Instances Performing Localization Creating a Resource Bundle Localizing Dynamic Data Localizing Messages

750 750 759 761 761 762 762

xvii

CONTENTS

Creating a Custom Converter Implementing an Event Listener Implementing Value-Change Listeners Implementing Action Listeners Creating a Custom Validator Implementing the Validator Interface Creating a Custom Tag Writing Backing Bean Methods Writing a Method to Handle Navigation Writing a Method to Handle an Action Event Writing a Method to Perform Validation Writing a Method to Handle a Value-Change Event

764 767 768 769 770 771 775 777 777 779 779 780

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 Specifying the Component Family 804 Performing Encoding 804 Performing Decoding 806 Enabling Value-Binding of Component Properties 807 Saving and Restoring State 808 Delegating Rendering to a Renderer 810 Creating the Renderer Class 810 Identifying the Renderer Type 812 Handling Events for Custom Components 812

xviii

CONTENTS

Chapter 21: Configuring JavaServer Faces Applications . . . . 815 Application Configuration Resource File Configuring Beans Using the managed-bean Element Initializing Properties using the managed-property Element Initializing Maps and Lists Registering Messages Registering a Custom Validator Registering a Custom Converter Configuring Navigation Rules Registering a Custom Renderer with a Render Kit Registering a Custom Component Basic Requirements of a JavaServer Faces Application Configuring an Application Using deploytool Including the Required JAR Files Including the Classes, Pages, and Other Resources

816 817 818 819 825 827 828 828 829 833 835 837 838 843 843

Chapter 22: Internationalizing and Localizing Web Applications . 845 Java Platform Localization Classes Providing Localized Messages and Labels Establishing the Locale Setting the Resource Bundle Retrieving Localized Messages Date and Number Formatting Character Sets and Encodings Character Sets Character Encoding Further Information

845 846 847 847 848 849 849 849 850 853

Chapter 23: Enterprise Beans . . . . . . . . . . . . . . . . . . . . . . . . . . . 855 What Is an Enterprise Bean? Benefits of Enterprise Beans When to Use Enterprise Beans Types of Enterprise Beans What Is a Session Bean? State Management Modes When to Use Session Beans What Is an Entity Bean?

855 855 856 857 857 857 858 859

xix

CONTENTS

What Makes Entity Beans Different from Session Beans? 859 Container-Managed Persistence 861 When to Use Entity Beans 864 What Is a Message-Driven Bean? 864 What Makes Message-Driven Beans Different from Session and Entity Beans? 865 When to Use Message-Driven Beans 866 Defining Client Access with Interfaces 866 Remote Clients 867 Local Clients 868 Local Interfaces and Container-Managed Relationships 868 Deciding on Remote or Local Access 869 Web Service Clients 870 Method Parameters and Access 870 The Contents of an Enterprise Bean 871 Naming Conventions for Enterprise Beans 872 The Life Cycles of Enterprise Beans 873 The Life Cycle of a Stateful Session Bean 873 The Life Cycle of a Stateless Session Bean 875 The Life Cycle of an Entity Bean 875 The Life Cycle of a Message-Driven Bean 877 Further Information 878

Chapter 24: Getting Started with Enterprise Beans . . . . . . . . . 879 Creating the J2EE Application Creating the Enterprise Bean Coding the Enterprise Bean Compiling the Source Files Packaging the Enterprise Bean Creating the Application Client Coding the Application Client Compiling the Application Client Packaging the Application Client Specifying the Application Client’s Enterprise Bean Reference Creating the Web Client Coding the Web Client Compiling the Web Client Packaging the Web Client Specifying the Web Client’s Enterprise Bean Reference Mapping the Enterprise Bean References

880 880 881 882 883 884 885 887 888 889 889 889 891 891 892 893

xx

CONTENTS

Specifying the Web Client’s Context Root Deploying the J2EE Application Running the Application Client Running the Web Client Modifying the J2EE Application Modifying a Class File Adding a File Modifying a Deployment Setting

894 895 895 896 897 897 898 898

Chapter 25: Session Bean Examples . . . . . . . . . . . . . . . . . . . . .899 The CartBean Example Session Bean Class Home Interface Remote Interface Helper Classes Building the CartBean Example Creating the Application Packaging the Enterprise Bean Packaging the Application Client A Web Service Example: HelloServiceBean Web Service Endpoint Interface Stateless Session Bean Implementation Class Building HelloServiceBean Building the Web Service Client Running the Web Service Client Other Enterprise Bean Features Accessing Environment Entries Comparing Enterprise Beans Passing an Enterprise Bean’s Object Reference Using the Timer Service Creating Timers Canceling and Saving Timers Getting Timer Information Transactions and Timers The TimerSessionBean Example Building TimerSessionBean Handling Exceptions

899 900 904 906 906 906 907 907 908 911 911 911 912 915 916 916 916 917 918 919 919 920 921 921 921 923 928

xxi

CONTENTS

Chapter 26: Bean-Managed Persistence Examples . . . . . . . . 931 The SavingsAccountBean Example Entity Bean Class Home Interface Remote Interface Running the SavingsAccountBean Example Mapping Table Relationships for Bean-Managed Persistence One-to-One Relationships One-to-Many Relationships Many-to-Many Relationships Primary Keys for Bean-Managed Persistence The Primary Key Class Primary Keys in the Entity Bean Class Getting the Primary Key deploytool Tips for Entity Beans with Bean-Managed Persistence

931 932 943 945 946 947 948 951 959 962 963 964 965 965

Chapter 27: Container-Managed Persistence Examples . . . . 967 Overview of the RosterApp Application The PlayerBean Code Entity Bean Class Local Home Interface Local Interface Method Invocations in RosterApp Creating a Player Adding a Player to a Team Removing a Player Dropping a Player from a Team Getting the Players of a Team Getting a Copy of a Team’s Players Finding the Players by Position Getting the Sports of a Player Building and Running the RosterApp Example Creating the Database Tables Creating the Data Source Capturing the Table Schema Building the Enterprise Beans Creating the Enterprise Application Packaging the Enterprise Beans Packaging the Enterprise Application Client Deploying the Enterprise Application

967 969 969 974 975 975 976 977 978 979 980 982 984 985 987 987 988 988 989 989 989 998 999

xxii

CONTENTS

Running the Client Application 1000 A Guided Tour of the RosterApp Settings 1001 RosterApp 1001 RosterClient 1003 RosterJAR 1003 TeamJAR 1004 Primary Keys for Container-Managed Persistence 1010 The Primary Key Class 1011 Advanced CMP Topics: The OrderApp Example 1013 Structure of OrderApp 1013 Bean Relationships in OrderApp 1014 Primary Keys in OrderApp’s Entity Beans 1016 Entity Bean Mapped to More Than One Database Table 1019 Finder and Selector Methods 1019 Using Home Methods 1020 Cascade Deletes in OrderApp 1020 BLOB and CLOB Database Types in OrderApp 1020 Building and Running the OrderApp Example 1021 deploytool Tips for Entity Beans with Container-Managed Persistence 1030 Selecting the Persistent Fields and Abstract Schema Name 1031 Defining EJB QL Queries for Finder and Select Methods 1031 Defining Relationships 1032 Creating the Database Tables at Deploy Time in deploytool 1032

Chapter 28: A Message-Driven Bean Example . . . . . . . . . . .1033 Example Application Overview The Application Client The Message-Driven Bean Class The onMessage Method The ejbCreate and ejbRemove Methods Deploying and Running SimpleMessageApp Creating the Administered Objects Deploying the Application Running the Client Removing the Administered Objects deploytool Tips for Message-Driven Beans Specifying the Bean’s Type Setting the Message-Driven Bean’s Characteristics deploytool Tips for Components That Send Messages

1033 1034 1035 1035 1037 1037 1037 1038 1039 1039 1040 1040 1040 1041

xxiii

CONTENTS

Setting the Resource References Setting the Message Destination References Setting the Message Destinations

1042 1042 1043

Chapter 29: Enterprise JavaBeans Query Language1045 Terminology Simplified Syntax Example Queries Simple Finder Queries Finder Queries That Navigate to Related Beans Finder Queries with Other Conditional Expressions Select Queries Full Syntax BNF Symbols BNF Grammar of EJB QL FROM Clause Path Expressions WHERE Clause SELECT Clause ORDER BY Clause EJB QL Restrictions

1046 1046 1047 1047 1049 1050 1052 1052 1053 1053 1057 1060 1062 1071 1074 1075

Chapter 30: Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1077 What Is a Transaction? Container-Managed Transactions Transaction Attributes Rolling Back a Container-Managed Transaction Synchronizing a Session Bean’s Instance Variables Compiling the BankBean Example Packaging the BankBean Example Methods Not Allowed in Container-Managed Transactions Bean-Managed Transactions JDBC Transactions Deploying and Running the WarehouseBean Example Compiling the WarehouseBean Example Packaging the WarehouseBean Example JTA Transactions Deploying and Running the TellerBean Example

1077 1078 1078 1082 1084 1085 1085 1089 1089 1090 1091 1091 1092 1095 1096

xxiv

CONTENTS

Compiling the TellerBean Example Packaging the TellerBean Example Returning without Committing Methods Not Allowed in Bean-Managed Transactions Summary of Transaction Options for Enterprise Beans Transaction Timeouts Isolation Levels Updating Multiple Databases Transactions in Web Components

1096 1097 1100 1100 1101 1102 1102 1103 1105

Chapter 31: Resource Connections . . . . . . . . . . . . . . . . . . . . . 1107 JNDI Naming DataSource Objects and Connection Pools Database Connections Coding a Database Connection Specifying a Resource Reference Creating a Data Source Mail Session Connections Running the ConfirmerBean Example URL Connections Running the HTMLReaderBean Example Further Information

1107 1109 1110 1110 1111 1112 1113 1114 1116 1117 1118

Chapter 32: Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1119 Overview Realms, Users, Groups, and Roles Managing Users Setting Up Security Roles Mapping Roles to Users and Groups Web-Tier Security Protecting Web Resources Setting Security Requirements Using deploytool Specifying a Secure Connection Using Programmatic Security in the Web Tier Understanding Login Authentication Using HTTP Basic Authentication Using Form-Based Authentication Using Client-Certificate Authentication Using Mutual Authentication

1119 1120 1122 1123 1123 1125 1127 1128 1130 1131 1133 1133 1134 1135 1136

xxv

CONTENTS

Using Digest Authentication Configuring Authentication Example: Using Form-Based Authentication Installing and Configuring SSL Support What Is Secure Socket Layer Technology? Understanding Digital Certificates Using SSL XML and Web Services Security Transport-Level Security Example: Basic Authentication with JAX-RPC Example: Client-Certificate Authentication over HTTP/SSL with JAX-RPC EJB-Tier Security Declaring Method Permissions Configuring IOR Security Using Programmatic Security in the EJB Tier Unauthenticated User Name Application Client-Tier Security EIS-Tier Security Container-Managed Sign-On Component-Managed Sign-On Configuring Resource Adapter Security Propagating Security Identity Configuring a Component’s Propagated Security Identity Configuring Client Authentication What Is Java Authorization Contract for Containers? Further Information

1138 1139 1139 1148 1148 1149 1156 1159 1160 1161 1167 1175 1175 1176 1178 1178 1178 1179 1180 1180 1181 1182 1183 1184 1184 1185

Chapter 33: The Java Message Service API . . . . . . . . . . . . . . 1187 Overview What Is Messaging? What Is the JMS API? When Can You Use the JMS API? How Does the JMS API Work with the J2EE Platform? Basic JMS API Concepts JMS API Architecture Messaging Domains Message Consumption The JMS API Programming Model Administered Objects

1188 1188 1188 1189 1191 1192 1192 1193 1195 1196 1197

xxvi

CONTENTS

Connections 1199 Sessions 1199 Message Producers 1200 Message Consumers 1201 Messages 1204 Exception Handling 1207 Writing Simple JMS Client Applications 1208 A Simple Example of Synchronous Message Receives 1208 A Simple Example of Asynchronous Message Consumption 1219 Running JMS Client Programs on Multiple Systems 1223 Creating Robust JMS Applications 1228 Using Basic Reliability Mechanisms 1229 Using Advanced Reliability Mechanisms 1236 Using the JMS API in a J2EE Application 1248 Using Session and Entity Beans to Produce and to Synchronously Receive Messages 1248 Using Message-Driven Beans 1250 Managing Distributed Transactions 1252 Using the JMS API with Application Clients and Web Components1255 Further Information 1255

Chapter 34: J2EE Examples Using the JMS API . . . . . . . . . . . .1257 A J2EE Application That Uses the JMS API with a Session Bean 1258 Writing the Application Components 1259 Creating and Packaging the Application 1261 Deploying the Application 1266 Running the Application Client 1266 A J2EE Application That Uses the JMS API with an Entity Bean 1267 Overview of the Human Resources Application 1268 Writing the Application Components 1269 Creating and Packaging the Application 1271 Deploying the Application 1274 Running the Application Client 1274 An Application Example That Consumes Messages from a Remote J2EE Server 1276 Overview of the Applications 1276 Writing the Application Components 1277 Creating and Packaging the Applications 1278 Deploying the Applications 1280 Running the Application Client 1281

CONTENTS

An Application Example That Deploys a Message-Driven Bean on Two J2EE Servers 1282 Overview of the Applications 1283 Writing the Application Components 1284 Creating and Packaging the Applications 1285 Deploying the Applications 1288 Running the Application Client 1289

Chapter 35: The Coffee Break Application. . . . . . . . . . . . . . . 1291 Common Code 1293 JAX-RPC Coffee Supplier Service 1293 Service Interface 1293 Service Implementation 1294 Publishing the Service in the Registry 1295 Deleting the Service From the Registry 1300 SAAJ Coffee Supplier Service 1302 SAAJ Client 1303 SAAJ Service 1310 Coffee Break Server 1317 JSP Pages 1318 JavaBeans Components 1318 RetailPriceListServlet 1321 JavaServer Faces Version of Coffee Break Server 1321 JSP Pages 1322 JavaBeans Components 1324 Resource Configuration 1326 Building, Packaging, Deploying, and Running the Application 1327 Setting the Port 1327 Setting the Registry Properties 1328 Using the Provided WARs 1329 Building the Common Classes 1329 Building, Packaging, and Deploying the JAX-RPC Service 1330 Building, Packaging, and Deploying the SAAJ Service 1332 Building, Packaging, and Deploying the Coffee Break Server 1333 Building, Packaging, and Deploying the JavaServer Faces Technology Coffee Break Server 1335 Running the Coffee Break Client 1336 Removing the Coffee Break Application 1338

xxvii

xxviii

CONTENTS

Chapter 36: The Duke’s Bank Application . . . . . . . . . . . . . . . . 1339 Enterprise Beans Session Beans Entity Beans Helper Classes Database Tables Protecting the Enterprise Beans Application Client The Classes and Their Relationships BankAdmin Class EventHandle Class DataModel Class Web Client Design Strategies Client Components Request Processing Protecting the Web Client Resources Internationalization Building, Packaging, Deploying, and Running the Application Setting Up the Servers Compiling the Duke’s Bank Application Code Packaging and Deploying the Duke’s Bank Application Reviewing JNDI Names Running the Clients Running the Application Client Running the Web Client

1340 1341 1344 1345 1346 1347 1347 1349 1350 1352 1353 1355 1357 1358 1361 1363 1365 1366 1367 1368 1368 1378 1380 1380 1381

Appendix A: Java Encoding Schemes . . . . . . . . . . . . . . . . . . . 1383 Further Information

1384

Appendix B: XML and Related Specs: Digesting the Alphabet Soup 1385 Basic Standards SAX StAX DOM JDOM and dom4j DTD Namespaces

1386 1386 1387 1387 1387 1388 1389

xxix

CONTENTS

XSL XSLT (+XPath) Schema Standards XML Schema RELAX NG SOX Schematron Linking and Presentation Standards XML Linking XHTML Knowledge Standards RDF RDF Schema XTM Standards That Build on XML Extended Document Standards e-Commerce Standards Summary

1389 1389 1390 1391 1391 1391 1392 1392 1392 1393 1393 1393 1394 1394 1394 1395 1395 1396

Appendix C: HTTP Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 1397 HTTP Requests HTTP Responses

1398 1398

Appendix D: J2EE Connector Architecture . . . . . . . . . . . . . . . 1399 About Resource Adapters Resource Adapter Contracts Management Contracts Outbound Contracts Inbound Contracts Common Client Interface Further Information

1399 1401 1402 1403 1404 1405 1406

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1407 About the Authors . . . . . . . . . . . . . . . . . . . . . . . . 1445 Current Writers Past Writers

1445 1446

xxx

CONTENTS

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1447

Foreword When the first edition of The J2EE™ Tutorial was released, the Java™ 2 Platform, Enterprise Edition (J2EE) was the new kid on the block. Modeled after its forerunner, the Java 2 Platform, Standard Edition (J2SE™), the J2EE platform brought the benefits of “Write Once, Run Anywhere™” API compatibility to enterprise application servers. Now at version 1.4 and with widespread conformance in the application server marketplace, the J2EE platform has firmly established its position as the standard for enterprise application servers. The J2EE™ Tutorial, Second Edition covers the J2EE 1.4 platform and more. If you have used the first edition of The J2EE™ Tutorial you may notice that the second edition is triple the size. This reflects a major expansion in the J2EE platform and the availability of two upcoming J2EE technologies in the Sun Java System Application Server Platform Edition 8.1 2005Q1, the software on which the tutorial is based. One of the most important additions to the J2EE 1.4 platform is substantial support for web services with the JAX-RPC 1.1 API, which enables web service endpoints based on servlets and enterprise beans. The platform also contains web services support APIs for handling XML data streams directly (SAAJ) and for accessing web services registries (JAXR). In addition, the J2EE 1.4 platform requires WS-I Basic Profile 1.0. This means that in addition to platform independence and complete web services support, the J2EE 1.4 platform offers web services interoperability. The J2EE 1.4 platform contains major enhancements to the Java servlet and JavaServer Pages (JSP) technologies that are the foundation of the web tier. The tutorial also showcases two exciting new technologies, not required by the J2EE 1.4 platform, that simplify the task of building J2EE application user interfaces: JavaServer Pages Standard Tag Library (JSTL) and JavaServer Faces. These new

xxxi

xxxii

FOREWORD

technologies are available in the Sun Java System Application Server. They will soon be featured in new developer tools and are strong candidates for inclusion in the next version of the J2EE platform. Readers conversant with the core J2EE platform enterprise bean technology will notice major upgrades with the addition of the previously mentioned web service endpoints, as well as a timer service, and enhancements to EJB QL and messagedriven beans. With all of these new features, I believe that you will find it well worth your time and energy to take on the J2EE 1.4 platform. You can increase the scope of the J2EE applications you develop, and your applications will run on the widest possible range of application server products. To help you to learn all about the J2EE 1.4 platform, The J2EE™ Tutorial, Second Edition follows the familiar Java Series tutorial model of concise descriptions of the essential features of each technology with code examples that you can deploy and run on the Sun Java System Application Server. Read this tutorial and you will become part of the next wave of J2EE application developers.

Jeff Jackson Vice President, J2EE Platform and Application Servers Sun Microsystems Santa Clara, CA June 7, 2005

About This Tutorial THE J2EE™ 1.4 Tutorial is a guide to developing enterprise applications for the Java 2 Platform, Enterprise Edition (J2EE) version 1.4. Here we cover all the things you need to know to make the best use of this tutorial.

Who Should Use This Tutorial This tutorial is intended for programmers who are interested in developing and deploying J2EE 1.4 applications on the Sun Java System Application Server Platform Edition 8.1 2005Q1.

Prerequisites Before proceeding with this tutorial you should have a good knowledge of the Java programming language. A good way to get to that point is to work through all the basic and some of the specialized trails in The Java™ Tutorial, Mary Campione et al., (Addison-Wesley, 2000). In particular, you should be familiar with relational database and security features described in the trails listed in Table 1. Table 1 Prerequisite Trails in The Java™ Tutorial Trail

URL

JDBC

http://java.sun.com/docs/books/tutorial/jdbc

Security

http://java.sun.com/docs/books/tutorial/security1.2

xxxiii

xxxiv

ABOUT THIS TUTORIAL

How to Read This Tutorial The J2EE 1.4 platform is quite large, and this tutorial reflects this. However, you don’t have to digest everything in it at once. This tutorial opens with three introductory chapters, which you should read before proceeding to any specific technology area. Chapter 1 covers the J2EE 1.4 platform architecture and APIs along with the Sun Java System Application Server Platform Edition 8.1 2005Q1. Chapters 2 and 3 cover XML basics and getting started with web applications. When you have digested the basics, you can delve into one or more of the four main technology areas listed next. Because there are dependencies between some of the chapters, Figure 1 contains a roadmap for navigating through the tutorial. • The Java XML chapters cover the technologies for developing applications that process XML documents and implement web services components: • The Java API for XML Processing (JAXP) • The Java API for XML-based RPC (JAX-RPC) • SOAP with Attachments API for Java (SAAJ) • The Java API for XML Registries (JAXR) • The web-tier technology chapters cover the components used in developing the presentation layer of a J2EE or stand-alone web application: • Java Servlet • JavaServer Pages (JSP) • JavaServer Pages Standard Tag Library (JSTL) • JavaServer Faces • web application internationalization and localization • The Enterprise JavaBeans (EJB) technology chapters cover the components used in developing the business logic of a J2EE application: • Session beans • Entity beans • Message-driven beans

ABOUT THIS TUTORIAL

• Enterprise JavaBeans Query Language • The platform services chapters cover the system services used by all the J2EE component technologies: • Transactions • Resource connections • Security • Java Message Service

Figure 1 Roadmap to This Tutorial

xxxv

xxxvi

ABOUT THIS TUTORIAL

After you have become familiar with some of the technology areas, you are ready to tackle the case studies, which tie together several of the technologies discussed in the tutorial. The Coffee Break Application (Chapter 35) describes an application that uses the web application and web services APIs. The Duke’s Bank Application (Chapter 36) describes an application that employs web application technologies and enterprise beans. Finally, the appendixes contain auxiliary information helpful to the J2EE application developer along with a brief summary of the J2EE Connector architecture: • • • •

Java encoding schemes (Appendix A) XML Standards (Appendix B) HTTP overview (Appendix C) J2EE Connector architecture (Appendix D)

About the Examples This section tells you everything you need to know to install, build, and run the examples.

Required Software Tutorial Bundle The tutorial example source is contained in the tutorial bundle. If you are viewing this online, you need to download tutorial bundle from: http://java.sun.com/j2ee/1.4/download.html#tutorial

After you have installed the tutorial bundle, the example source code is in the /j2eetutorial14/examples/ directory, with subdirectories for each of the technologies discussed in the tutorial.

Application Server The Sun Java System Application Server Platform Edition 8.1 2005Q1is targeted as the build and runtime environment for the tutorial examples. To build, deploy,

ABOUT THIS TUTORIAL

and run the examples, you need a copy of the Application Server and the Java 2 Software Development Kit, Standard Edition (J2SE SDK) 1.4.2_06 or higher. If you already have a copy of the J2SE SDK, you can download the Application Server from: http://java.sun.com/j2ee/1.4/download.html#sdk

You can also download the J2EE 1.4 SDK—which contains the Application Server and the J2SE SDK—from the same site.

Application Server Installation Tips In the Admin configuration pane of the Application Server installer, • Select the Don’t Prompt for Admin User Name radio button. This will save the user name and password so that you won’t need to provide them when performing administrative operations with asadmin and deploytool. You will still have to provide the user name and password to log in to the Admin Console. • Note the HTTP port at which the server is installed. This tutorial assumes that you are accepting the default port of 8080. If 8080 is in use during installation and the installer chooses another port or if you decide to change it yourself, you will need to update the common build properties file (described in the next section) and the configuration files for some of the tutorial examples to reflect the correct port. In the Installation Options pane, check the Add Bin Directory to PATH checkbox so that Application Server scripts (asadmin, asant, deploytool, and wscompile) override other installations.

Registry Server You need a registry server to run the examples discussed in Chapters 10 and 35. Directions for obtaining and setting up a registry server are provided in those chapters.

Building the Examples Most of the tutorial examples are distributed with a configuration file for asant, a portable build tool contained in the Application Server. This tool is an extension of the Ant tool developed by the Apache Software Foundation

xxxvii

xxxviii

ABOUT THIS TUTORIAL

(http://ant.apache.org). The asant utility contains additional tasks that invoke the Application Server administration utility asadmin. Directions for building the examples are provided in each chapter. Build properties and targets common to all the examples are specified in the files /j2eetutorial14/examples/common/build.properties and /j2eetutorial14/examples/common/targets.xml. Build properties and targets common to a particular technology are specified in the files /j2eetutorial14/examples/tech/common/build.properties

and /j2eetutorial14/examples/tech/common/targets.xml. To run the asant scripts, you must set common build properties in the file /j2eetutorial14/examples/common/build.properties as follows: • Set the j2ee.home property to the location of your Application Server installation. The build process uses the j2ee.home property to include the libraries in /lib/ in the classpath. All examples that run on the Application Server include the J2EE library archive— /lib/j2ee.jar—in the build classpath. Some examples use additional libraries in /lib/ and /lib/endorsed/; the required libraries are enumerated in the individual technology chapters. refers to the directory where you have installed the Application Server or the J2EE 1.4 SDK. Note: On Windows, you must escape any backslashes in the j2ee.home property with another backslash or use forward slashes as a path separator. So, if your Application Server installation is C:\Sun\AppServer, you must set j2ee.home as follows: j2ee.home = C:\\Sun\\AppServer

or j2ee.home=C:/Sun/AppServer

• Set the j2ee.tutorial.home property to the location of your tutorial. This property is used for asant deployment and undeployment. For example on Unix: j2ee.tutorial.home=/home/username/j2eetutorial14

ABOUT THIS TUTORIAL

On Windows: j2ee.tutorial.home=C:/j2eetutorial14

You should not install the tutorial to a location with spaces in the path. • If you did not use the default value (admin) for the admin user, set the admin.user property to the value you specified when you installed the Application Server. • If you did not use port 8080, set the domain.resources.port property to the value specified when you installed the Application Server. • Set the admin user’s password in /j2eetutorial14/examples/common/admin-password.txt

to the value you specified when you installed the Application Server. The format of this file is AS_ADMIN_PASSWORD=password. For example: AS_ADMIN_PASSWORD=mypassword

Tutorial Example Directory Structure To facilitate iterative development and keep application source separate from compiled files, the source code for the tutorial examples is stored in the following structure under each application directory: • build.xml: asant build file • src: Java source of servlets and JavaBeans components; tag libraries • web: JSP pages and HTML pages, tag files, and images The asant build files (build.xml) distributed with the examples contain targets to create a build subdirectory and to copy and compile files into that directory.

Further Information This tutorial includes the basic information that you need to deploy applications on and administer the Application Server. For reference information on the tools distributed with the Application Server, see the man pages at http://docs.sun.com/db/doc/817-6092.

xxxix

xl

ABOUT THIS TUTORIAL

See the Sun Java™ System Application Server Platform Edition 8 Developer’s Guide at http://docs.sun.com/db/doc/817-6087 for information about developer features of the Application Server. See the Sun Java™ System Application Server Platform Edition 8 Administration Guide at http://docs.sun.com/db/doc/817-6088 for information about administering the Application Server. For information about the PointBase database included with the Application Server see the PointBase web site at www.pointbase.com.

How to Buy This Tutorial This tutorial has been published in the Java Series by Addison-Wesley as The Java Tutorial, Second Edition. For information on the book and links to online booksellers, go to http://java.sun.com/docs/books/j2eetutorial/index.html#second

How to Print This Tutorial To print this tutorial, follow these steps: 1. Ensure that Adobe Acrobat Reader is installed on your system. 2. Open the PDF version of this book. 3. Click the printer icon in Adobe Acrobat Reader.

Typographical Conventions Table 2 lists the typographical conventions used in this tutorial. Table 2 Typographical Conventions Font Style

Uses

italic

Emphasis, titles, first occurrence of terms

ABOUT THIS TUTORIAL

Table 2 Typographical Conventions Font Style

Uses

monospace

URLs, code examples, file names, path names, tool names, application names, programming language keywords, tag, interface, class, method, and field names, properties

italic monospace

Variables in code, file paths, and URLs

User-selected file path components

Menu selections indicated with the right-arrow character →, for example, First→Second, should be interpreted as: select the First menu, then choose Second from the First submenu.

Acknowledgments The J2EE tutorial team would like to thank the J2EE specification leads: Bill Shannon, Pierre Delisle, Mark Roth, Yutaka Yoshida, Farrukh Najmi, Phil Goodwin, Joseph Fialli, Kate Stout, and Ron Monzillo and the J2EE 1.4 SDK team members: Vivek Nagar, Tony Ng, Qingqing Ouyang, Ken Saks, Jean-Francois Arcand, Jan Luehe, Ryan Lubke, Kathy Walsh, Binod P G, Alejandro Murillo, and Manveen Kaur. The chapters on custom tags and the Coffee Break and Duke’s Bank applications use a template tag library that first appeared in Designing Enterprise Applications with the J2EE™ Platform, Second Edition, Inderjeet Singh et al., (Addison-Wesley, 2002). The JavaServer Faces technology and JSP Documents chapters benefited greatly from the invaluable documentation reviews and example code contributions of these engineers: Ed Burns, Justyna Horwat, Roger Kitain, Jan Luehe, Craig McClanahan, Raj Premkumar, Mark Roth, and especially Jayashri Visvanathan. The OrderApp example application described in the Container-Managed Persistence chapter was coded by Marina Vatkina with contributions from Markus Fuchs, Rochelle Raccah, and Deepa Singh. Ms. Vatkina’s JDO/CMP team provided extensive feedback on the tutorial’s discussion of CMP. The security chapter writers are indebted to Raja Perumal, who was a key contributor both to the chapter and to the examples.

xli

xlii

ABOUT THIS TUTORIAL

Monica Pawlan and Beth Stearns wrote the Overview and J2EE Connector chapters in the first edition of The J2EE Tutorial and much of that content has been carried forward to the current edition. We are extremely grateful to the many internal and external reviewers who provided feedback on the tutorial. Their feedback helped improve the technical accuracy and presentation of the chapters and eliminate bugs from the examples. We would like to thank our manager, Alan Sommerer, for his support and steadying influence. We also thank Duarte Design, Inc., and Zana Vartanian for developing the illustrations in record time. Thanks are also due to our copy editor, Betsy Hardinger, for helping this multi-author project achieve a common style. Finally, we would like to express our profound appreciation to Ann Sellers, Elizabeth Ryan, and the production team at Addison-Wesley for graciously seeing our large, complicated manuscript to publication.

Feedback To send comments, broken link reports, errors, suggestions, and questions about this tutorial to the tutorial team, please use the feedback form at http://java.sun.com/j2ee/1.4/docs/tutorial/information/sendusmail.html.

1 Overview TODAY, more and more developers want to write distributed transactional applications for the enterprise and thereby leverage the speed, security, and reliability of server-side technology. If you are already working in this area, you know that in the fast-moving and demanding world of e-commerce and information technology, enterprise applications must be designed, built, and produced for less money, with greater speed, and with fewer resources than ever before. To reduce costs and fast-track application design and development, the Java™ 2 Platform, Enterprise Edition (J2EE™) provides a component-based approach to the design, development, assembly, and deployment of enterprise applications. The J2EE platform offers a multitiered distributed application model, reusable components, a unified security model, flexible transaction control, and web services support through integrated data interchange on Extensible Markup Language (XML)-based open standards and protocols. Not only can you deliver innovative business solutions to market faster than ever, but also your platform-independent J2EE component-based solutions are not tied to the products and application programming interfaces (APIs) of any one vendor. Vendors and customers enjoy the freedom to choose the products and components that best meet their business and technological requirements. This tutorial uses examples to describe the features and functionalities available in the J2EE platform version 1.4 for developing enterprise applications. Whether you are a new or an experienced developer, you should find the examples and accompanying text a valuable and accessible knowledge base for creating your own solutions. 1

2

OVERVIEW

If you are new to J2EE enterprise application development, this chapter is a good place to start. Here you will review development basics, learn about the J2EE architecture and APIs, become acquainted with important terms and concepts, and find out how to approach J2EE application programming, assembly, and deployment.

Distributed Multitiered Applications The J2EE platform uses a distributed multitiered application model for enterprise applications. Application logic is divided into components according to function, and the various application components that make up a J2EE application are installed on different machines depending on the tier in the multitiered J2EE environment to which the application component belongs. Figure 1–1 shows two multitiered J2EE applications divided into the tiers described in the following list. The J2EE application parts shown in Figure 1–1 are presented in J2EE Components (page 3). • • • •

Client-tier components run on the client machine. Web-tier components run on the J2EE server. Business-tier components run on the J2EE server. Enterprise information system (EIS)-tier software runs on the EIS server.

Although a J2EE application can consist of the three or four tiers shown in Figure 1–1, J2EE multitiered applications are generally considered to be three-tiered applications because they are distributed over three locations: client machines, the J2EE server machine, and the database or legacy machines at the back end. Three-tiered applications that run in this way extend the standard two-tiered client and server model by placing a multithreaded application server between the client application and back-end storage.

J2EE COMPONENTS

Figure 1–1 Multitiered Applications

J2EE Components J2EE applications are made up of components. A J2EE component is a self-contained functional software unit that is assembled into a J2EE application with its related classes and files and that communicates with other components. The J2EE specification defines the following J2EE components: • Application clients and applets are components that run on the client. • Java Servlet and JavaServer Pages™ (JSP™) technology components are web components that run on the server. • Enterprise JavaBeans™ (EJB™) components (enterprise beans) are business components that run on the server. J2EE components are written in the Java programming language and are compiled in the same way as any program in the language. The difference between J2EE components and “standard” Java classes is that J2EE components are assembled into a J2EE application, are verified to be well formed and in compliance with the J2EE specification, and are deployed to production, where they are run and managed by the J2EE server.

3

4

OVERVIEW

J2EE Clients A J2EE client can be a web client or an application client.

Web Clients A web client consists of two parts: (1) dynamic web pages containing various types of markup language (HTML, XML, and so on), which are generated by web components running in the web tier, and (2) a web browser, which renders the pages received from the server. A web client is sometimes called a thin client. Thin clients usually do not query databases, execute complex business rules, or connect to legacy applications. When you use a thin client, such heavyweight operations are off-loaded to enterprise beans executing on the J2EE server, where they can leverage the security, speed, services, and reliability of J2EE server-side technologies.

Applets A web page received from the web tier can include an embedded applet. An applet is a small client application written in the Java programming language that executes in the Java virtual machine installed in the web browser. However, client systems will likely need the Java Plug-in and possibly a security policy file in order for the applet to successfully execute in the web browser. Web components are the preferred API for creating a web client program because no plug-ins or security policy files are needed on the client systems. Also, web components enable cleaner and more modular application design because they provide a way to separate applications programming from web page design. Personnel involved in web page design thus do not need to understand Java programming language syntax to do their jobs.

Application Clients An application client runs on a client machine and provides a way for users to handle tasks that require a richer user interface than can be provided by a markup language. It typically has a graphical user interface (GUI) created from the Swing or the Abstract Window Toolkit (AWT) API, but a command-line interface is certainly possible.

J2EE CLIENTS

Application clients directly access enterprise beans running in the business tier. However, if application requirements warrant it, an application client can open an HTTP connection to establish communication with a servlet running in the web tier.

The JavaBeans™ Component Architecture The server and client tiers might also include components based on the JavaBeans component architecture (JavaBeans components) to manage the data flow between an application client or applet and components running on the J2EE server, or between server components and a database. JavaBeans components are not considered J2EE components by the J2EE specification. JavaBeans components have properties and have get and set methods for accessing the properties. JavaBeans components used in this way are typically simple in design and implementation but should conform to the naming and design conventions outlined in the JavaBeans component architecture.

J2EE Server Communications Figure 1–2 shows the various elements that can make up the client tier. The client communicates with the business tier running on the J2EE server either directly or, as in the case of a client running in a browser, by going through JSP pages or servlets running in the web tier. Your J2EE application uses a thin browser-based client or thick application client. In deciding which one to use, you should be aware of the trade-offs between keeping functionality on the client and close to the user (thick client) and offloading as much functionality as possible to the server (thin client). The more functionality you off-load to the server, the easier it is to distribute, deploy, and manage the application; however, keeping more functionality on the client can make for a better perceived user experience.

5

6

OVERVIEW

Figure 1–2 Server Communications

Web Components J2EE web components are either servlets or pages created using JSP technology (JSP pages). Servlets are Java programming language classes that dynamically process requests and construct responses. JSP pages are text-based documents that execute as servlets but allow a more natural approach to creating static content. Static HTML pages and applets are bundled with web components during application assembly but are not considered web components by the J2EE specification. Server-side utility classes can also be bundled with web components and, like HTML pages, are not considered web components. As shown in Figure 1–3, the web tier, like the client tier, might include a JavaBeans component to manage the user input and send that input to enterprise beans running in the business tier for processing.

Business Components Business code, which is logic that solves or meets the needs of a particular business domain such as banking, retail, or finance, is handled by enterprise beans running in the business tier. Figure 1–4 shows how an enterprise bean receives data from client programs, processes it (if necessary), and sends it to the enter-

BUSINESS COMPONENTS

prise information system tier for storage. An enterprise bean also retrieves data from storage, processes it (if necessary), and sends it back to the client program.

Figure 1–3 Web Tier and J2EE Applications

Figure 1–4 Business and EIS Tiers

There are three kinds of enterprise beans: session beans, entity beans, and message-driven beans. A session bean represents a transient conversation with a client. When the client finishes executing, the session bean and its data are gone. In contrast, an entity bean represents persistent data stored in one row of a database table. If the client terminates or if the server shuts down, the underlying services ensure that the entity bean data is saved. A message-driven bean combines fea-

7

8

OVERVIEW

tures of a session bean and a Java Message Service (JMS) message listener, allowing a business component to receive JMS messages asynchronously.

Enterprise Information System Tier The enterprise information system tier handles EIS software and includes enterprise infrastructure systems such as enterprise resource planning (ERP), mainframe transaction processing, database systems, and other legacy information systems. For example, J2EE application components might need access to enterprise information systems for database connectivity.

J2EE Containers Normally, thin-client multitiered applications are hard to write because they involve many lines of intricate code to handle transaction and state management, multithreading, resource pooling, and other complex low-level details. The component-based and platform-independent J2EE architecture makes J2EE applications easy to write because business logic is organized into reusable components. In addition, the J2EE server provides underlying services in the form of a container for every component type. Because you do not have to develop these services yourself, you are free to concentrate on solving the business problem at hand.

Container Services Containers are the interface between a component and the low-level platformspecific functionality that supports the component. Before a web component, enterprise bean, or application client component can be executed, it must be assembled into a J2EE module and deployed into its container. The assembly process involves specifying container settings for each component in the J2EE application and for the J2EE application itself. Container settings customize the underlying support provided by the J2EE server, including services such as security, transaction management, Java Naming and Directory

CONTAINER TYPES

Interface™ (JNDI) lookups, and remote connectivity. Here are some of the highlights: • The J2EE security model lets you configure a web component or enterprise bean so that system resources are accessed only by authorized users. • The J2EE transaction model lets you specify relationships among methods that make up a single transaction so that all methods in one transaction are treated as a single unit. • JNDI lookup services provide a unified interface to multiple naming and directory services in the enterprise so that application components can access naming and directory services. • The J2EE remote connectivity model manages low-level communications between clients and enterprise beans. After an enterprise bean is created, a client invokes methods on it as if it were in the same virtual machine. Because the J2EE architecture provides configurable services, application components within the same J2EE application can behave differently based on where they are deployed. For example, an enterprise bean can have security settings that allow it a certain level of access to database data in one production environment and another level of database access in another production environment. The container also manages nonconfigurable services such as enterprise bean and servlet life cycles, database connection resource pooling, data persistence, and access to the J2EE platform APIs described in section J2EE 1.4 APIs (page 18). Although data persistence is a nonconfigurable service, the J2EE architecture lets you override container-managed persistence by including the appropriate code in your enterprise bean implementation when you want more control than the default container-managed persistence provides. For example, you might use bean-managed persistence to implement your own finder (search) methods or to create a customized database cache.

Container Types The deployment process installs J2EE application components in the J2EE containers illustrated in Figure 1–5.

9

10

OVERVIEW

Figure 1–5 J2EE Server and Containers

J2EE server The runtime portion of a J2EE product. A J2EE server provides EJB and web containers. Enterprise JavaBeans (EJB) container Manages the execution of enterprise beans for J2EE applications. Enterprise beans and their container run on the J2EE server. Web container Manages the execution of JSP page and servlet components for J2EE applications. web components and their container run on the J2EE server. Application client container Manages the execution of application client components. Application clients and their container run on the client. Applet container Manages the execution of applets. Consists of a web browser and Java Plugin running on the client together.

Web Services Support Web services are web-based enterprise applications that use open, XML-based standards and transport protocols to exchange data with calling clients. The J2EE

XML

platform provides the XML APIs and tools you need to quickly design, develop, test, and deploy web services and clients that fully interoperate with other web services and clients running on Java-based or non-Java-based platforms. To write web services and clients with the J2EE XML APIs, all you do is pass parameter data to the method calls and process the data returned; or for document-oriented web services, you send documents containing the service data back and forth. No low-level programming is needed because the XML API implementations do the work of translating the application data to and from an XML-based data stream that is sent over the standardized XML-based transport protocols. These XML-based standards and protocols are introduced in the following sections. The translation of data to a standardized XML-based data stream is what makes web services and clients written with the J2EE XML APIs fully interoperable. This does not necessarily mean that the data being transported includes XML tags because the transported data can itself be plain text, XML data, or any kind of binary data such as audio, video, maps, program files, computer-aided design (CAD) documents and the like. The next section introduces XML and explains how parties doing business can use XML tags and schemas to exchange data in a meaningful way.

XML XML is a cross-platform, extensible, text-based standard for representing data. When XML data is exchanged between parties, the parties are free to create their own tags to describe the data, set up schemas to specify which tags can be used in a particular kind of XML document, and use XML stylesheets to manage the display and handling of the data. For example, a web service can use XML and a schema to produce price lists, and companies that receive the price lists and schema can have their own stylesheets to handle the data in a way that best suits their needs. Here are examples: • One company might put XML pricing information through a program to translate the XML to HTML so that it can post the price lists to its intranet. • A partner company might put the XML pricing information through a tool to create a marketing presentation. • Another company might read the XML pricing information into an application for processing.

11

12

OVERVIEW

SOAP Transport Protocol Client requests and web service responses are transmitted as Simple Object Access Protocol (SOAP) messages over HTTP to enable a completely interoperable exchange between clients and web services, all running on different platforms and at various locations on the Internet. HTTP is a familiar request-and response standard for sending messages over the Internet, and SOAP is an XMLbased protocol that follows the HTTP request-and-response model. The SOAP portion of a transported message handles the following: • Defines an XML-based envelope to describe what is in the message and how to process the message • Includes XML-based encoding rules to express instances of applicationdefined data types within the message • Defines an XML-based convention for representing the request to the remote service and the resulting response

WSDL Standard Format The Web Services Description Language (WSDL) is a standardized XML format for describing network services. The description includes the name of the service, the location of the service, and ways to communicate with the service. WSDL service descriptions can be stored in UDDI registries or published on the web (or both). The Sun Java System Application Server Platform Edition 8 provides a tool for generating the WSDL specification of a web service that uses remote procedure calls to communicate with clients.

UDDI and ebXML Standard Formats Other XML-based standards, such as Universal Description, Discovery and Integration (UDDI) and ebXML, make it possible for businesses to publish information on the Internet about their products and web services, where the information can be readily and globally accessed by clients who want to do business.

PACKAGING APPLICATIONS

Packaging Applications A J2EE application is delivered in an Enterprise Archive (EAR) file, a standard Java Archive (JAR) file with an .ear extension. Using EAR files and modules makes it possible to assemble a number of different J2EE applications using some of the same components. No extra coding is needed; it is only a matter of assembling (or packaging) various J2EE modules into J2EE EAR files. An EAR file (see Figure 1–6) contains J2EE modules and deployment descriptors. A deployment descriptor is an XML document with an .xml extension that describes the deployment settings of an application, a module, or a component. Because deployment descriptor information is declarative, it can be changed without the need to modify the source code. At runtime, the J2EE server reads the deployment descriptor and acts upon the application, module, or component accordingly. There are two types of deployment descriptors: J2EE and runtime. A J2EE deployment descriptor is defined by a J2EE specification and can be used to configure deployment settings on any J2EE-compliant implementation. A runtime deployment descriptor is used to configure J2EE implementation-specific parameters. For example, the Sun Java System Application Server Platform Edition 8 runtime deployment descriptor contains information such as the context root of a web application, the mapping of portable names of an application’s resources to the server’s resources, and Application Server implementation-specific parameters, such as caching directives. The Application Server runtime deployment descriptors are named sun-moduleType.xml and are located in the same directory as the J2EE deployment descriptor.

13

14

OVERVIEW

Figure 1–6 EAR File Structure

A J2EE module consists of one or more J2EE components for the same container type and one component deployment descriptor of that type. An enterprise bean module deployment descriptor, for example, declares transaction attributes and security authorizations for an enterprise bean. A J2EE module without an application deployment descriptor can be deployed as a stand-alone module. The four types of J2EE modules are as follows: • EJB modules, which contain class files for enterprise beans and an EJB deployment descriptor. EJB modules are packaged as JAR files with a .jar extension. • Web modules, which contain servlet class files, JSP files, supporting class files, GIF and HTML files, and a web application deployment descriptor. Web modules are packaged as JAR files with a .war (web archive) extension. • Application client modules, which contain class files and an application client deployment descriptor. Application client modules are packaged as JAR files with a .jar extension. • Resource adapter modules, which contain all Java interfaces, classes, native libraries, and other documentation, along with the resource adapter deployment descriptor. Together, these implement the Connector architecture (see J2EE Connector Architecture, page 22) for a particular EIS. Resource adapter modules are packaged as JAR files with an .rar (resource adapter archive) extension.

DEVELOPMENT ROLES

Development Roles Reusable modules make it possible to divide the application development and deployment process into distinct roles so that different people or companies can perform different parts of the process. The first two roles involve purchasing and installing the J2EE product and tools. After software is purchased and installed, J2EE components can be developed by application component providers, assembled by application assemblers, and deployed by application deployers. In a large organization, each of these roles might be executed by different individuals or teams. This division of labor works because each of the earlier roles outputs a portable file that is the input for a subsequent role. For example, in the application component development phase, an enterprise bean software developer delivers EJB JAR files. In the application assembly role, another developer combines these EJB JAR files into a J2EE application and saves it in an EAR file. In the application deployment role, a system administrator at the customer site uses the EAR file to install the J2EE application into a J2EE server. The different roles are not always executed by different people. If you work for a small company, for example, or if you are prototyping a sample application, you might perform the tasks in every phase.

J2EE Product Provider The J2EE product provider is the company that designs and makes available for purchase the J2EE platform APIs, and other features defined in the J2EE specification. Product providers are typically operating system, database system, application server, or web server vendors who implement the J2EE platform according to the Java 2 Platform, Enterprise Edition specification.

Tool Provider The tool provider is the company or person who creates development, assembly, and packaging tools used by component providers, assemblers, and deployers.

15

16

OVERVIEW

Application Component Provider The application component provider is the company or person who creates web components, enterprise beans, applets, or application clients for use in J2EE applications.

Enterprise Bean Developer An enterprise bean developer performs the following tasks to deliver an EJB JAR file that contains the enterprise bean(s): • Writes and compiles the source code • Specifies the deployment descriptor • Packages the .class files and deployment descriptor into the EJB JAR file

Web Component Developer A web component developer performs the following tasks to deliver a WAR file containing the web component(s): • • • •

Writes and compiles servlet source code Writes JSP and HTML files Specifies the deployment descriptor Packages the .class, .jsp, and.html files and deployment descriptor into the WAR file

Application Client Developer An application client developer performs the following tasks to deliver a JAR file containing the application client: • Writes and compiles the source code • Specifies the deployment descriptor for the client • Packages the .class files and deployment descriptor into the JAR file

Application Assembler The application assembler is the company or person who receives application modules from component providers and assembles them into a J2EE application

APPLICATION DEPLOYER AND ADMINISTRATOR

EAR file. The assembler or deployer can edit the deployment descriptor directly or can use tools that correctly add XML tags according to interactive selections. A software developer performs the following tasks to deliver an EAR file containing the J2EE application: • Assembles EJB JAR and WAR files created in the previous phases into a J2EE application (EAR) file • Specifies the deployment descriptor for the J2EE application • Verifies that the contents of the EAR file are well formed and comply with the J2EE specification

Application Deployer and Administrator The application deployer and administrator is the company or person who configures and deploys the J2EE application, administers the computing and networking infrastructure where J2EE applications run, and oversees the runtime environment. Duties include such things as setting transaction controls and security attributes and specifying connections to databases. During configuration, the deployer follows instructions supplied by the application component provider to resolve external dependencies, specify security settings, and assign transaction attributes. During installation, the deployer moves the application components to the server and generates the container-specific classes and interfaces. A deployer or system administrator performs the following tasks to install and configure a J2EE application: • Adds the J2EE application (EAR) file created in the preceding phase to the J2EE server • Configures the J2EE application for the operational environment by modifying the deployment descriptor of the J2EE application • Verifies that the contents of the EAR file are well formed and comply with the J2EE specification • Deploys (installs) the J2EE application EAR file into the J2EE server

17

18

OVERVIEW

J2EE 1.4 APIs Figure 1–7 illustrates the availability of the J2EE 1.4 platform APIs in each J2EE container type. The following sections give a brief summary of the technologies required by the J2EE platform and the J2SE enterprise APIs that would be used in J2EE applications.

Figure 1–7 J2EE Platform APIs

Enterprise JavaBeans Technology An Enterprise JavaBeans™ (EJB™) component, or enterprise bean, is a body of code having fields and methods to implement modules of business logic. You can think of an enterprise bean as a building block that can be used alone or with other enterprise beans to execute business logic on the J2EE server. As mentioned earlier, there are three kinds of enterprise beans: session beans, entity beans, and message-driven beans. Enterprise beans often interact with databases. One of the benefits of entity beans is that you do not have to write any SQL code or use the JDBC™ API (see JDBC API, page 22) directly to perform

JAVA SERVLET TECHNOLOGY

database access operations; the EJB container handles this for you. However, if you override the default container-managed persistence for any reason, you will need to use the JDBC API. Also, if you choose to have a session bean access the database, you must use the JDBC API.

Java Servlet Technology Java servlet technology lets you define HTTP-specific servlet classes. A servlet class extends the capabilities of servers that host applications that are accessed by way of a request-response programming model. Although servlets can respond to any type of request, they are commonly used to extend the applications hosted by web servers.

JavaServer Pages Technology JavaServer Pages™ (JSP™) technology lets you put snippets of servlet code directly into a text-based document. A JSP page is a text-based document that contains two types of text: static data (which can be expressed in any text-based format such as HTML, WML, and XML) and JSP elements, which determine how the page constructs dynamic content.

Java Message Service API The Java Message Service (JMS) API is a messaging standard that allows J2EE application components to create, send, receive, and read messages. It enables distributed communication that is loosely coupled, reliable, and asynchronous.

Java Transaction API The Java Transaction API (JTA) provides a standard interface for demarcating transactions. The J2EE architecture provides a default auto commit to handle transaction commits and rollbacks. An auto commit means that any other applications that are viewing data will see the updated data after each database read or write operation. However, if your application performs two separate database access operations that depend on each other, you will want to use the JTA API to demarcate where the entire transaction, including both operations, begins, rolls back, and commits.

19

20

OVERVIEW

JavaMail API J2EE applications use the JavaMail™ API to send email notifications. The JavaMail API has two parts: an application-level interface used by the application components to send mail, and a service provider interface. The J2EE platform includes JavaMail with a service provider that allows application components to send Internet mail.

JavaBeans Activation Framework The JavaBeans Activation Framework (JAF) is included because JavaMail uses it. JAF provides standard services to determine the type of an arbitrary piece of data, encapsulate access to it, discover the operations available on it, and create the appropriate JavaBeans component to perform those operations.

Java API for XML Processing The Java API for XML Processing (JAXP) supports the processing of XML documents using Document Object Model (DOM), Simple API for XML (SAX), and Extensible Stylesheet Language Transformations (XSLT). JAXP enables applications to parse and transform XML documents independent of a particular XML processing implementation. JAXP also provides namespace support, which lets you work with schemas that might otherwise have naming conflicts. Designed to be flexible, JAXP lets you use any XML-compliant parser or XSL processor from within your application and supports the W3C schema. You can find information on the W3C schema at this URL: http://www.w3.org/XML/Schema.

Java API for XML-Based RPC The Java API for XML-based RPC (JAX-RPC) uses the SOAP standard and HTTP, so client programs can make XML-based remote procedure calls (RPCs) over the Internet. JAX-RPC also supports WSDL, so you can import and export WSDL documents. With JAX-RPC and a WSDL, you can easily interoperate with clients and services running on Java-based or non-Java-based platforms such as .NET. For example, based on the WSDL document, a Visual Basic .NET client can be configured to use a web service implemented in Java technology, or a web service can be configured to recognize a Visual Basic .NET client.

SOAP WITH ATTACHMENTS API FOR JAVA

JAX-RPC relies on the HTTP transport protocol. Taking that a step further, JAXRPC lets you create service applications that combine HTTP with a Java technology version of the Secure Socket Layer (SSL) and Transport Layer Security (TLS) protocols to establish basic or mutual authentication. SSL and TLS ensure message integrity by providing data encryption with client and server authentication capabilities. Authentication is a measured way to verify whether a party is eligible and able to access certain information as a way to protect against the fraudulent use of a system or the fraudulent transmission of information. Information transported across the Internet is especially vulnerable to being intercepted and misused, so it’s very important to configure a JAX-RPC web service to protect data in transit.

SOAP with Attachments API for Java The SOAP with Attachments API for Java (SAAJ) is a low-level API on which JAX-RPC depends. SAAJ enables the production and consumption of messages that conform to the SOAP 1.1 specification and SOAP with Attachments note. Most developers do not use the SAAJ API, instead using the higher-level JAXRPC API.

Java API for XML Registries The Java API for XML Registries (JAXR) lets you access business and generalpurpose registries over the web. JAXR supports the ebXML Registry and Repository standards and the emerging UDDI specifications. By using JAXR, developers can learn a single API and gain access to both of these important registry technologies. Additionally, businesses can submit material to be shared and search for material that others have submitted. Standards groups have developed schemas for particular kinds of XML documents; two businesses might, for example, agree to use the schema for their industry’s standard purchase order form. Because the schema is stored in a standard business registry, both parties can use JAXR to access it.

21

22

OVERVIEW

J2EE Connector Architecture The J2EE Connector architecture is used by J2EE tools vendors and system integrators to create resource adapters that support access to enterprise information systems that can be plugged in to any J2EE product. A resource adapter is a software component that allows J2EE application components to access and interact with the underlying resource manager of the EIS. Because a resource adapter is specific to its resource manager, typically there is a different resource adapter for each type of database or enterprise information system. The J2EE Connector architecture also provides a performance-oriented, secure, scalable, and message-based transactional integration of J2EE-based web services with existing EISs that can be either synchronous or asynchronous. Existing applications and EISs integrated through the J2EE Connector architecture into the J2EE platform can be exposed as XML-based web services by using JAX-RPC and J2EE component models. Thus JAX-RPC and the J2EE Connector architecture are complementary technologies for enterprise application integration (EAI) and end-to-end business integration.

JDBC API The JDBC API lets you invoke SQL commands from Java programming language methods. You use the JDBC API in an enterprise bean when you override the default container-managed persistence or have a session bean access the database. With container-managed persistence, database access operations are handled by the container, and your enterprise bean implementation contains no JDBC code or SQL commands. You can also use the JDBC API from a servlet or a JSP page to access the database directly without going through an enterprise bean. The JDBC API has two parts: an application-level interface used by the application components to access a database, and a service provider interface to attach a JDBC driver to the J2EE platform.

Java Naming and Directory Interface The Java Naming and Directory Interface™ (JNDI) provides naming and directory functionality. It provides applications with methods for performing standard directory operations, such as associating attributes with objects and searching for

JAVA AUTHENTICATION AND AUTHORIZATION SERVICE

objects using their attributes. Using JNDI, a J2EE application can store and retrieve any type of named Java object. J2EE naming services provide application clients, enterprise beans, and web components with access to a JNDI naming environment. A naming environment allows a component to be customized without the need to access or change the component’s source code. A container implements the component’s environment and provides it to the component as a JNDI naming context. A J2EE component locates its environment naming context using JNDI interfaces. A component creates a javax.naming.InitialContext object and looks up the environment naming context in InitialContext under the name java:comp/env. A component’s naming environment is stored directly in the environment naming context or in any of its direct or indirect subcontexts. A J2EE component can access named system-provided and user-defined objects. The names of system-provided objects, such as JTA UserTransaction objects, are stored in the environment naming context, java:comp/env. The J2EE platform allows a component to name user-defined objects, such as enterprise beans, environment entries, JDBC DataSource objects, and message connections. An object should be named within a subcontext of the naming environment according to the type of the object. For example, enterprise beans are named within the subcontext java:comp/env/ejb, and JDBC DataSource references in the subcontext java:comp/env/jdbc. Because JNDI is independent of any specific implementation, applications can use JNDI to access multiple naming and directory services, including existing naming and directory services such as LDAP, NDS, DNS, and NIS. This allows J2EE applications to coexist with legacy applications and systems. For more information on JNDI, see The JNDI Tutorial: http://java.sun.com/products/jndi/tutorial/index.html

Java Authentication and Authorization Service The Java Authentication and Authorization Service (JAAS) provides a way for a J2EE application to authenticate and authorize a specific user or group of users to run it.

23

24

OVERVIEW

JAAS is a Java programing language version of the standard Pluggable Authentication Module (PAM) framework, which extends the Java 2 Platform security architecture to support user-based authorization.

Simplified Systems Integration The J2EE platform is a platform-independent, full systems integration solution that creates an open marketplace in which every vendor can sell to every customer. Such a marketplace encourages vendors to compete, not by trying to lock customers into their technologies but instead by trying to outdo each other in providing products and services that benefit customers, such as better performance, better tools, or better customer support. The J2EE APIs enable systems and applications integration through the following: • • • • • • •

Unified application model across tiers with enterprise beans Simplified request-and-response mechanism with JSP pages and servlets Reliable security model with JAAS XML-based data interchange integration with JAXP, SAAJ, and JAX-RPC Simplified interoperability with the J2EE Connector architecture Easy database connectivity with the JDBC API Enterprise application integration with message-driven beans and JMS, JTA, and JNDI

You can learn more about using the J2EE platform to build integrated business systems by reading J2EE Technology in Practice, by Rick Cattell and Jim Inscore (Addison-Wesley, 2001): http://java.sun.com/j2ee/inpractice/aboutthebook.html

Sun Java System Application Server Platform Edition 8 The Sun Java System Application Server Platform Edition 8 is a fully compliant implementation of the J2EE 1.4 platform. In addition to supporting all the APIs described in the previous sections, the Application Server includes a number of

TECHNOLOGIES

J2EE technologies and tools that are not part of the J2EE 1.4 platform but are provided as a convenience to the developer. This section briefly summarizes the technologies and tools that make up the Application Server, and instructions for starting and stopping the Application Server, starting the Admin Console, starting deploytool, and starting and stopping the PointBase database server. Other chapters explain how to use the remaining tools.

Technologies The Application Server includes two user interface technologies—JavaServer Pages Standard Tag Library and JavaServer™ Faces—that are built on and used in conjunction with the J2EE 1.4 platform technologies Java servlet and JavaServer Pages.

JavaServer Pages Standard Tag Library The JavaServer Pages Standard Tag Library (JSTL) encapsulates core functionality common to many JSP applications. Instead of mixing tags from numerous vendors in your JSP applications, you employ a single, standard set of tags. This standardization allows you to deploy your applications on any JSP container that supports JSTL and makes it more likely that the implementation of the tags is optimized. JSTL has iterator and conditional tags for handling flow control, tags for manipulating XML documents, internationalization tags, tags for accessing databases using SQL, and commonly used functions.

JavaServer Faces JavaServer Faces technology is a user interface framework for building web applications. The main components of JavaServer Faces technology are as follows: • A GUI component framework. • A flexible model for rendering components in different kinds of HTML or different markup languages and technologies. A Renderer object generates the markup to render the component and converts the data stored in a model object to types that can be represented in a view.

25

26

OVERVIEW

• A standard RenderKit for generating HTML/4.01 markup. The following features support the GUI components: • • • • •

Input validation Event handling Data conversion between model objects and components Managed model object creation Page navigation configuration

All this functionality is available via standard Java APIs and XML-based configuration files.

Tools The Application Server contains the tools listed in Table 1–1. Basic usage information for many of the tools appears throughout the tutorial. For detailed information, see the online help in the GUI tools and the man pages at http:// docs.sun.com/db/doc/817-6092 for the command-line tools. Table 1–1 Application Server Tools Component

Description

Admin Console

A web-based GUI Application Server administration utility. Used to stop the Application Server and manage users, resources, and applications.

asadmin

A command-line Application Server administration utility. Used to start and stop the Application Server and manage users, resources, and applications.

asant

A portable command-line build tool that is an extension of the Ant tool developed by the Apache Software Foundation (see http:// ant.apache.org/). asant contains additional tasks that interact with the Application Server administration utility.

appclient

A command-line tool that launches the application client container and invokes the client application packaged in the application client JAR file.

STARTING AND STOPPING THE APPLICATION SERVER

Table 1–1 Application Server Tools Component

Description

capture-schema

A command-line tool to extract schema information from a database, producing a schema file that the Application Server can use for container-managed persistence.

deploytool

A GUI tool to package applications, generate deployment descriptors, and deploy applications on the Application Server.

package-appclient

A command-line tool to package the application client container libraries and JAR files.

PointBase database

An evaluation copy of the PointBase database server.

verifier

A command-line tool to validate J2EE deployment descriptors.

wscompile

A command-line tool to generate stubs, ties, serializers, and WSDL files used in JAX-RPC clients and services.

wsdeploy

A command-line tool to generate implementation-specific, ready-todeploy WAR files for web service applications that use JAX-RPC.

Starting and Stopping the Application Server To start and stop the Application Server, you use the asadmin utility. To start the Application Server, open a terminal window or command prompt and execute the following: asadmin start-domain --verbose domain1

A domain is a set of one or more Application Server instances managed by one administration server. Associated with a domain are the following: • The Application Server’s port number. The default is 8080. • The administration server’s port number. The default is 4848. • An administration user name and password. You specify these values when you install the Application Server. The examples in this tutorial assume that you choose the default ports.

27

28

OVERVIEW

With no arguments, the start-domain command initiates the default domain, which is domain1. The --verbose flag causes all logging and debugging output to appear on the terminal window or command prompt (it will also go into the server log, which is located in /domains/domain1/logs/ server.log). Or, on Windows, you can choose Programs→Sun Microsystems→J2EE 1.4 SDK→Start Default Server After the server has completed its startup sequence, you will see the following output: Domain domain1 started.

To stop the Application Server, open a terminal window or command prompt and execute asadmin stop-domain domain1

Or, on Windows, choose Programs→Sun Microsystems→J2EE 1.4 SDK→Stop Default Server When the server has stopped you will see the following output: Domain domain1 stopped.

Starting the Admin Console To administer the Application Server and manage users, resources, and J2EE applications, you use the Admin Console tool. The Application Server must be running before you invoke the Admin Console. To start the Admin Console, open a browser at the following URL: http://localhost:4848/asadmin/

On Windows, from the Start menu, choose Programs→Sun Microsystems→J2EE 1.4 SDK→Admin Console

STARTING THE DEPLOYTOOL UTILITY

Starting the deploytool Utility To package J2EE applications, specify deployment descriptor elements, and deploy applications on the Application Server, you use the deploytool utility. To start deploytool, open a terminal window or command prompt and execute deploytool

On Windows, from the Start menu, choose Programs→Sun Microsystems→J2EE 1.4 SDK→Deploytool

Starting and Stopping the PointBase Database Server The Application Server includes an evaluation copy of the PointBase database. To start the PointBase database server, follow these steps. 1. In a terminal window, go to /pointbase/tools/serveroption. 2. Execute the startserver script. On Windows, from the Start menu, choose Programs→Sun Microsystems→J2EE 1.4 SDK→Start PointBase To stop the PointBase server, follow these steps. 1. In a terminal window, go to /pointbase/tools/serveroption. 2. Execute the stopserver script. On Windows, from the Start menu, choose Programs→Sun Microsystems→J2EE 1.4 SDK→Stop PointBase For information about the PointBase database included with the Application Server see the PointBase web site at www.pointbase.com.

29

30

OVERVIEW

Debugging J2EE Applications This section describes how to determine what is causing an error in your application deployment or execution.

Using the Server Log One way to debug applications is to look at the server log in / The log contains output from the Application Server and your applications. You can log messages from any Java class in your application with System.out.println and the Java Logging APIs (documented at http://java.sun.com/j2se/1.4.2/docs/guide/util/logging/ index.html) and from web components with the ServletContext.log method.

domains/domain1/logs/server.log.

If you start the Application Server with the --verbose flag, all logging and debugging output will appear on the terminal window or command prompt and the server log. If you start the Application Server in the background, debugging information is only available in the log. You can view the server log with a text editor or with the Admin Console log viewer. To use the log viewer: 1. Select the Application Server node. 2. Select the Logging tab. 3. Click the Open Log Viewer button. The log viewer will open and display the last 40 entries. If you wish to display other entries: 1. Click the Modify Search button. 2. Specify any constraints on the entries you want to see. 3. Click the Search button at the bottom of the log viewer.

Using a Debugger The Application Server supports the Java Platform Debugger Architecture (JPDA). With JPDA, you can configure the Application Server to communicate debugging information via a socket. In order to debug an application using a debugger: 1. Enable debugging in the Application Server using the Admin Console as follows: a. Select the Application Server node.

DEBUGGING J2EE APPLICATIONS

b. Select the JVM Settings tab. The default debug options are set to: -Xdebug -Xrunjdwp:transport=dt_socket,server=y, suspend=n,address=1044

As you can see, the default debugger socket port is 1044. You can change it to a port not in use by the Application Server or another service.

2. 3. 4. 5.

c. Check the Enabled box of the Debug field. d. Click the Save button. Stop the Application Server and then restart it. Compile your Java source with the -g flag. Package and deploy your application. Start a debugger and connect to the debugger socket at the port you set when you enabled debugging.

31

32

OVERVIEW

2 Understanding XML T

HIS chapter describes Extensible Markup Language (XML) and its related specifications. It also gives you practice in writing XML data so that you can become comfortably familiar with XML syntax. Note: The XML files mentioned in this chapter can be found in /j2eetutorial14/examples/xml/samples/.

Introduction to XML This section covers the basics of XML. The goal is to give you just enough information to get started so that you understand what XML is all about. (You’ll learn more about XML in later sections of the tutorial.) We then outline the major features that make XML great for information storage and interchange, and give you a general idea of how XML can be used.

What Is XML? XML is a text-based markup language that is fast becoming the standard for data interchange on the web. As with HTML, you identify data using tags (identifiers enclosed in angle brackets: ). Collectively, the tags are known as markup. But unlike HTML, XML tags identify the data rather than specify how to display it. Whereas an HTML tag says something like, “Display this data in bold font”

33

34

UNDERSTANDING XML

(...), an XML tag acts like a field name in your program. It puts a label on a piece of data that identifies it (for example, ...). Note: Because identifying the data gives you some sense of what it means (how to interpret it, what you should do with it), XML is sometimes described as a mechanism for specifying the semantics (meaning) of the data.

In the same way that you define the field names for a data structure, you are free to use any XML tags that make sense for a given application. Naturally, for multiple applications to use the same XML data, they must agree on the tag names they intend to use. Here is an example of some XML data you might use for a messaging application:

[email protected] [email protected] XML Is Really Cool

How many ways is XML cool? Let me count the ways...

Note: Throughout this tutorial, we use boldface text to highlight things we want to bring to your attention. XML does not require anything to be in bold!

The tags in this example identify the message as a whole, the destination and sender addresses, the subject, and the text of the message. As in HTML, the tag has a matching end tag: . The data between the tag and its matching end tag defines an element of the XML data. Note, too, that the content of the tag is contained entirely within the scope of the .. tag. It is this ability for one tag to contain others that lets XML represent hierarchical data structures. Again, as with HTML, whitespace is essentially irrelevant, so you can format the data for readability and yet still process it easily with a program. Unlike HTML, however, in XML you can easily search a data set for messages containing, say, “cool” in the subject, because the XML tags identify the content of the data rather than specify its representation.

WHAT IS XML?

Tags and Attributes Tags can also contain attributes—additional information included as part of the tag itself, within the tag’s angle brackets. The following example shows an email message structure that uses attributes for the to, from, and subject fields:

How many ways is XML cool? Let me count the ways...

As in HTML, the attribute name is followed by an equal sign and the attribute value, and multiple attributes are separated by spaces. Unlike HTML, however, in XML commas between attributes are not ignored; if present, they generate an error. Because you can design a data structure such as equally well using either attributes or tags, it can take a considerable amount of thought to figure out which design is best for your purposes. Designing an XML Data Structure (page 76), includes ideas to help you decide when to use attributes and when to use tags.

Empty Tags One big difference between XML and HTML is that an XML document is always constrained to be well formed. There are several rules that determine when a document is well formed, but one of the most important is that every tag has a closing tag. So, in XML, the tag is not optional. The element is never terminated by any tag other than . Note: Another important aspect of a well-formed document is that all tags are completely nested. So you can have ......, but never ....... A complete list of requirements is contained in the list of XML frequently asked questions (FAQ) at http://www.ucc.ie/xml/#FAQ-VALIDWF. (This FAQ is on the W3C “Recommended Reading” list at http://www.w3.org/XML/.)

Sometimes, though, it makes sense to have a tag that stands by itself. For example, you might want to add a tag that flags the message as important: .

35

36

UNDERSTANDING XML

This kind of tag does not enclose any content, so it’s known as an empty tag. You create an empty tag by ending it with /> instead of >. For example, the following message contains an empty flag tag:

How many ways is XML cool? Let me count the ways...

Note: Using the empty tag saves you from having to code in order to have a well-formed document. You can control which tags are allowed to be empty by creating a schema or a document type definition, or DTD (page 1388). If there is no DTD or schema associated with the document, then it can contain any kinds of tags you want, as long as the document is well formed.

Comments in XML Files XML comments look just like HTML comments:

Defining the Root Element After the declaration, every XML file defines exactly one element, known as the root element. Any other elements in the file are contained within that element. Enter the following highlighted text to define the root element for this file, slideshow:



45

46

UNDERSTANDING XML Wake up to WonderWidgets!

Here you have also added a type attribute to the slide. The idea of this attribute is that you can earmark slides for a mostly technical or mostly executive audience using type="tech" or type="exec", or identify them as suitable for both audiences using type="all". More importantly, this example illustrates the difference between things that are more usefully defined as elements (the title element) and things that are more suitable as attributes (the type attribute). The visibility heuristic is primarily at work here. The title is something the audience will see, so it is an element. The type, on the other hand, is something that never gets presented, so it is an attribute. Another way to think about that distinction is that an element is a container, like a bottle. The type is a characteristic of the container (tall or short, wide or narrow). The title is a characteristic of the contents (water, milk, or tea). These are not hard-and-fast rules, of course, but they can help when you design your own XML structures.

Adding HTML-Style Text Because XML lets you define any tags you want, it makes sense to define a set of tags that look like HTML. In fact, the XHTML standard does exactly that. You’ll see more about that toward the end of the SAX tutorial. For now, type the following highlighted text to define a slide with a couple of list item entries that use an HTML-style tag for emphasis (usually rendered as italicized text): ...

Overview Why WonderWidgets are great Who buys WonderWidgets

DEFINING THE ROOT ELEMENT

Note that defining a title element conflicts with the XHTML element that uses the same name. Later in this tutorial, we discuss the mechanism that produces the conflict (the DTD), along with possible solutions.

Adding an Empty Element One major difference between HTML and XML is that all XML must be well formed, which means that every tag must have an ending tag or be an empty tag. By now, you’re getting pretty comfortable with ending tags. Add the following highlighted text to define an empty list item element with no contents: ...



Overview Why WonderWidgets are great

Who buys WonderWidgets

The colon makes the target name into a kind of “label” that identifies the intended recipient of the instruction. However, even though the W3C spec allows a colon in a target name, some versions of Internet Explorer 5 (IE5) consider it an error. For this tutorial, then, we avoid using a colon in the target name. Save a copy of this file as slideSample02.xml so that you can use it when experimenting with processing instructions.

Introducing an Error The parser can generate three kinds of errors: a fatal error, an error, and a warning. In this exercise, you’ll make a simple modification to the XML file to introduce a fatal error. Later, you’ll see how it’s handled in the Echo application.

49

50

UNDERSTANDING XML

Note: The XML structure you’ll create in this exercise is in slideSampleBad1.xml. (The browsable version is slideSampleBad1-xml.html.)

One easy way to introduce a fatal error is to remove the final / from the empty element to create a tag that does not have a corresponding end tag. That constitutes a fatal error, because all XML documents must, by definition, be well formed. Do the following: item

1. Copy slideSample02.xml to slideSampleBad1.xml. 2. Edit slideSampleBad1.xml and remove the character shown here: ...

Overview ...

Financial Forecast Market Size < predicted Anticipated Penetration Expected Revenues Profit Margin

When you use an XML parser to echo this data, you will see the desired output: Market Size < predicted

SUBSTITUTING AND INSERTING TEXT

You see an angle bracket ( How it Works First we fozzle the frobmorten Then we framboze the staten Finally, we frenzle the fuznaten

^ | | = fozzle V | = framboze staten-------------------------+ = frenzle

]]>

53

54

UNDERSTANDING XML

When you echo this file with an XML parser, you see the following output: Diagram: frobmorten

The DTD tag ATTLIST begins the series of attribute definitions. The name that follows ATTLIST specifies the element for which the attributes are being defined. In this case, the element is the slideshow element. (Note again the lack of hierarchy in DTD specifications.) Each attribute is defined by a series of three space-separated values. Commas and other separators are not allowed, so formatting the definitions as shown here is helpful for readability. The first element in each line is the name of the attribute: title, date, or author, in this case. The second element indicates the type of the data: CDATA is character data—unparsed data, again, in which a left angle bracket ( slide (tech | exec | all) #IMPLIED title (#PCDATA)> item (#PCDATA | item)* >

This specification says that the slide element’s type attribute must be given as type="tech", type="exec", or type="all". No other values are acceptable. (DTD-aware XML editors can use such specifications to present a pop-up list of choices.) The last entry in the attribute specification determines the attribute’s default value, if any, and tells whether or not the attribute is required. Table 2–4 shows the possible choices. Table 2–4 Attribute-Specification Parameters Specification #REQUIRED

Specifies... The attribute value must be specified in the document.

61

62

UNDERSTANDING XML

Table 2–4 Attribute-Specification Parameters Specification

Specifies...

#IMPLIED

The value need not be specified in the document. If it isn’t, the application will have a default value it uses.

“defaultValue”

The default value to use if a value is not specified in the document.

#FIXED “fixedValue”

The value to use. If the document specifies any value at all, it must be the same.

Finally, save a copy of the DTD as slideshow1b.dtd for use when you experiment with attribute definitions.

Defining Entities in the DTD So far, you’ve seen predefined entities such as & and you’ve seen that an attribute can reference an entity. It’s time now for you to learn how to define entities of your own. Note: The XML you’ll create here is contained in browsable version is slideSample06-xml.html.)

slideSample06.xml.

(The

Add the following highlighted text to the DOCTYPE tag in your XML file:

]>

The ENTITY tag name says that you are defining an entity. Next comes the name of the entity and its definition. In this case, you are defining an entity named product that will take the place of the product name. Later when the product name changes (as it most certainly will), you need only change the name in one place, and all your slides will reflect the new value. The last part is the substitution string that replaces the entity name whenever it is referenced in the XML document. The substitution string is defined in quotes, which are not included when the text is inserted into the document.

DEFINING ATTRIBUTES AND ENTITIES IN THE DTD

Just for good measure, we defined two versions—one singular and one plural— so that when the marketing mavens come up with “Wally” for a product name, you will be prepared to enter the plural as “Wallies” and have it substituted correctly. Note: Truth be told, this is the kind of thing that really belongs in an external DTD so that all your documents can reference the new name when it changes. But, hey, this is only an example.

Now that you have the entities defined, the next step is to reference them in the slide show. Make the following highlighted changes:

"™"> "®"> "©">

This is the standard copyright message that our lawyers make us put everywhere so we don't have to shell out a million bucks every time someone spills hot coffee in their lap...

...

You’ll notice that the newline that follows the comment in the file is echoed as a character, but that the comment itself is ignored. This newline is the reason that the copyright message appears to start on the next line after the element instead of on the same line: the first character echoed is actually the newline that follows the comment.

65

66

UNDERSTANDING XML

Summarizing Entities An entity that is referenced in the document content, whether internal or external, is termed a general entity. An entity that contains DTD specifications that are referenced from within the DTD is termed a parameter entity. (More on that later.) An entity that contains XML (text and markup), and is therefore parsed, is known as a parsed entity. An entity that contains binary data (such as images) is known as an unparsed entity. (By its nature, it must be external.) In the next section, we discuss references to unparsed entities.

Referencing Binary Entities This section discusses the options for referencing binary files such as image files and multimedia data files.

Using a MIME Data Type There are two ways to reference an unparsed entity such as a binary image file. One is to use the DTD’s NOTATION specification mechanism. However, that mechanism is a complex, unintuitive holdover that exists mostly for compatibility with SGML documents. Note: SGML stands for Standard Generalized Markup Language. It was extremely powerful but so general that a program had to read the beginning of a document just to find out how to parse the remainder of it. Some very large document-management systems were built using it, but it was so large and complex that only the largest organizations managed to deal with it. XML, on the other hand, chose to remain small and simple—more like HTML than SGML—and, as a result, it has enjoyed rapid, widespread deployment. This story may well hold a moral for schema standards as well. Time will tell.

We will have occasion to discuss the subject in a bit more depth when we look at the DTDHandler API, but suffice it for now to say that the XML namespaces standard, in conjunction with the MIME data types defined for electronic messaging attachments, together provide a much more useful, understandable, and extensible mechanism for referencing unparsed external entities.

REFERENCING BINARY ENTITIES

Note: The XML described here is in slideshow1b.dtd. (The browsable version is It shows how binary references can be made, assuming that the application that will process the XML data knows how to handle such references. slideshow1b-dtd.html.)

To set up the slide show to use image files, add the following highlighted text to your slideshow1b.dtd file:

slide (image?, title, item*)> slide (tech | exec | all) #IMPLIED title (#PCDATA)> item (#PCDATA | item)* > image EMPTY> image CDATA #IMPLIED CDATA #REQUIRED CDATA "image/gif"

These modifications declare image as an optional element in a slide, define it as empty element, and define the attributes it requires. The image tag is patterned after the HTML 4.0 img tag, with the addition of an image type specifier, type. (The img tag is defined in the HTML 4.0 specification.) The image tag’s attributes are defined by the ATTLIST entry. The alt attribute, which defines alternative text to display in case the image can’t be found, accepts character data (CDATA). It has an implied value, which means that it is optional and that the program processing the data knows enough to substitute something such as “Image not found.” On the other hand, the src attribute, which names the image to display, is required. The type attribute is intended for the specification of a MIME data type, as defined at http://www.iana.org/assignments/media-types/. It has a default value: image/gif. Note: It is understood here that the character data (CDATA) used for the type attribute will be one of the MIME data types. The two most common formats are image/gif and image/jpeg. Given that fact, it might be nice to specify an attribute list here, using something like type ("image/gif", "image/jpeg")

67

68

UNDERSTANDING XML

That won’t work, however, because attribute lists are restricted to name tokens. The forward slash isn’t part of the valid set of name-token characters, so this declaration fails. Also, creating an attribute list in the DTD would limit the valid MIME types to those defined today. Leaving it as CDATA leaves things more open-ended so that the declaration will continue to be valid as additional types are defined.

In the document, a reference to an image named “intro-pic” might look something like this:

The Alternative: Using Entity References Using a MIME data type as an attribute of an element is a flexible and expandable mechanism. To create an external ENTITY reference using the notation mechanism, you need DTD NOTATION elements for JPEG and GIF data. Those can, of course, be obtained from a central repository. But then you need to define a different ENTITY element for each image you intend to reference! In other words, adding a new image to your document always requires both a new entity definition in the DTD and a reference to it in the document. Given the anticipated ubiquity of the HTML 4.0 specification, the newer standard is to use the MIME data types and a declaration such as image, which assumes that the application knows how to process such elements.

Defining Parameter Entities and Conditional Sections Just as a general entity lets you reuse XML data in multiple places, a parameter entity lets you reuse parts of a DTD in multiple places. In this section you’ll see how to define and use parameter entities. You’ll also see how to use parameter entities with conditional sections in a DTD.

Creating and Referencing a Parameter Entity Recall that the existing version of the slide presentation can not be validated because the document uses tags, and they are not part of the DTD. In general, we’d like to use a variety of HTML-style tags in the text of a slide, and not

DEFINING PARAMETER ENTITIES AND CONDITIONAL SECTIONS

just one or two, so using an existing DTD for XHTML makes more sense than defining such tags ourselves. A parameter entity is intended for exactly that kind of purpose. Note: The DTD specifications shown here are contained in slideshow2.dtd and xhtml.dtd. The XML file that references it is slideSample08.xml. (The browsable versions are slideshow2-dtd.html, xhtml-dtd.html, and slideSample08xml.html.)

Open your DTD file for the slide presentation and add the following highlighted text to define a parameter entity that references an external DTD file:

%xhtml; tag to define a parameter entity, just as for a general entity, but you use a somewhat different syntax. You include a percent sign (%) before the entity name when you define the entity, and you use the percent sign instead of an ampersand when you reference it. Also, note that there are always two steps to using a parameter entity. The first is to define the entity name. The second is to reference the entity name, which actually does the work of including the external definitions in the current DTD. Because the uniform resource identifier (URI) for an external entity could contain slashes (/) or other characters that are not valid in an XML name, the definition step allows a valid XML name to be associated with an actual document. (This same technique is used in the definition of namespaces and anywhere else that XML constructs need to reference external documents.) Notes: • The DTD file referenced by this definition is xhtml.dtd. (The browsable version is xhtml-dtd.html.) You can either copy that file to your system or modify the SYSTEM identifier in the tag to point to the correct URL.

69

70

UNDERSTANDING XML

• This file is a small subset of the XHTML specification, loosely modeled after the Modularized XHTML draft, which aims at breaking up the DTD for XHTML into bite-sized chunks, which can then be combined to create different XHTML subsets for different purposes. When work on the modularized XHTML draft has been completed, this version of the DTD should be replaced with something better. For now, this version will suffice for our purposes. The point of using an XHTML-based DTD is to gain access to an entity it defines that covers HTML-style tags like and . Looking through xhtml.dtd reveals the following entity, which does exactly what we want:

This entity is a simpler version of those defined in the Modularized XHTML draft. It defines the HTML-style tags we are most likely to want to use—emphasis, bold, and break—plus a couple of others for images and anchors that we may or may not use in a slide presentation. To use the inline entity, make the following highlighted changes in your DTD file:

These changes replace the simple #PCDATA item with the inline entity. It is important to notice that #PCDATA is first in the inline entity and that inline is first wherever we use it. That sequence is required by XML’s definition of a mixed-content model. To be in accord with that model, you also must add an asterisk at the end of the title definition. Save the DTD as slideshow2.dtd for use when you experiment with parameter entities. Note: The Modularized XHTML DTD defines both inline and Inline entities, and does so somewhat differently. Rather than specify #PCDATA|em|b|a|img|br, the definitions are more like (#PCDATA|em|b|a|img|br)*. Using one of those definitions, therefore, looks more like this:

DEFINING PARAMETER ENTITIES AND CONDITIONAL SECTIONS

Conditional Sections Before we proceed with the next programming exercise, it is worth mentioning the use of parameter entities to control conditional sections. Although you cannot conditionalize the content of an XML document, you can define conditional sections in a DTD that become part of the DTD only if you specify include. If you specify ignore, on the other hand, then the conditional section is not included. Suppose, for example, that you wanted to use slightly different versions of a DTD, depending on whether you were treating the document as an XML document or as a SGML document. You can do that with DTD definitions such as the following: someExternal.dtd:

... common definitions

The conditional sections are introduced by . In this case, the XML definitions are included, and the SGML definitions are excluded. That’s fine for XML documents, but you can’t use the DTD for SGML documents. You could change the keywords, of course, but that only reverses the problem. IGNORE

The solution is to use references to parameter entities in place of the INCLUDE and IGNORE keywords: someExternal.dtd:

... common definitions

71

72

UNDERSTANDING XML

Then each document that uses the DTD can set up the appropriate entity definitions:

]>

...

This procedure puts each document in control of the DTD. It also replaces the INCLUDE and IGNORE keywords with variable names that more accurately reflect the purpose of the conditional section, producing a more readable, self-documenting version of the DTD.

Resolving a Naming Conflict The XML structures you have created thus far have actually encountered a small naming conflict. It seems that xhtml.dtd defines a title element that is entirely different from the title element defined in the slide-show DTD. Because there is no hierarchy in the DTD, these two definitions conflict. Note: The Modularized XHTML DTD also defines a title element that is intended to be the document title, so we can’t avoid the conflict by changing xhtml.dtd. The problem would only come back to haunt us later.

You can use XML namespaces to resolve the conflict. You’ll take a look at that approach in the next section. Alternatively, you can use one of the more hierarchical schema proposals described in Schema Standards (page 1390). The simplest way to solve the problem for now is to rename the title element in slideshow.dtd. Note:

The

XML

shown here is contained in slideshow3.dtd and which references copyright.xml and xhtml.dtd. (The browsable versions are slideshow3-dtd.html, slideSample09-xml.html, copyright-xml.html, and xhtml-dtd.html.) slideSample09.xml,

USING NAMESPACES

To keep the two title elements separate, you’ll create a hyphenation hierarchy. Make the following highlighted changes to change the name of the title element in slideshow.dtd to slide-title:



Overview ...

Save a copy of this file as slideSample09.xml.

Using Namespaces As you saw earlier, one way or another it is necessary to resolve the conflict between the title element defined in slideshow.dtd and the one defined in xhtml.dtd when the same name is used for different purposes. In the preceding exercise, you hyphenated the name in order to put it into a different namespace. In this section, you’ll see how to use the XML namespace standard to do the same thing without renaming the element.

73

74

UNDERSTANDING XML

The primary goal of the namespace specification is to let the document author tell the parser which DTD or schema to use when parsing a given element. The parser can then consult the appropriate DTD or schema for an element definition. Of course, it is also important to keep the parser from aborting when a “duplicate” definition is found and yet still generate an error if the document references an element such as title without qualifying it (identifying the DTD or schema to use for the definition). Note: Namespaces apply to attributes as well as to elements. In this section, we consider only elements. For more information on attributes, consult the namespace specification at http://www.w3.org/TR/REC-xml-names/.

Defining a Namespace in a DTD In a DTD, you define a namespace that an element belongs to by adding an attribute to the element’s definition, where the attribute name is xmlns (“xml namespace”). For example, you can do that in slideshow.dtd by adding an entry such as the following in the title element’s attribute-list definition:

Declaring the attribute as FIXED has several important features: • It prevents the document from specifying any nonmatching value for the xmlns attribute. • The element defined in this DTD is made unique (because the parser understands the xmlns attribute), so it does not conflict with an element that has the same name in another DTD. That allows multiple DTDs to use the same element name without generating a parser error. • When a document specifies the xmlns attribute for a tag, the document selects the element definition that has a matching attribute. To be thorough, every element name in your DTD would get exactly the same attribute, with the same value. (Here, though, we’re concerned only about the title element.) Note, too, that you are using a CDATA string to supply the URI. In this case, we’ve specified a URL. But you could also specify a universal resource name (URN), possibly by specifying a prefix such as urn: instead of

USING NAMESPACES http:.

(URNs are currently being researched. They’re not seeing a lot of action at the moment, but that could change in the future.)

Referencing a Namespace When a document uses an element name that exists in only one of the DTDs or schemas it references, the name does not need to be qualified. But when an element name that has multiple definitions is used, some sort of qualification is a necessity. Note: In fact, an element name is always qualified by its default namespace, as defined by the name of the DTD file it resides in. As long as there is only one definition for the name, the qualification is implicit.

You qualify a reference to an element name by specifying the xmlns attribute, as shown here:

Overview

The specified namespace applies to that element and to any elements contained within it.

Defining a Namespace Prefix When you need only one namespace reference, it’s not a big deal. But when you need to make the same reference several times, adding xmlns attributes becomes unwieldy. It also makes it harder to change the name of the namespace later. The alternative is to define a namespace prefix, which is as simple as specifying a colon (:), and the prefix name before the attribute value:

xmlns,

...

This definition sets up SL as a prefix that can be used to qualify the current element name and any element within it. Because the prefix can be used on any of

75

76

UNDERSTANDING XML

the contained elements, it makes the most sense to define it on the XML document’s root element, as shown here. Note: The namespace URI can contain characters that are not valid in an XML name, so it cannot be used directly as a prefix. The prefix definition associates an XML name with the URI, and that allows the prefix name to be used instead. It also makes it easier to change references to the URI in the future.

When the prefix is used to qualify an element name, the end tag also includes the prefix, as highlighted here:

...

Overview

...

Finally, note that multiple prefixes can be defined in the same element:

...

With this kind of arrangement, all the prefix definitions are together in one place, and you can use them anywhere they are needed in the document. This example also suggests the use of a URN instead of a URL to define the xhtml prefix. That definition would conceivably allow the application to reference a local copy of the XHTML DTD or some mirrored version, with a potentially beneficial impact on performance.

Designing an XML Data Structure This section covers some heuristics you can use when making XML design decisions.

SAVING YOURSELF SOME WORK

Saving Yourself Some Work Whenever possible, use an existing schema definition. It’s usually a lot easier to ignore the things you don’t need than to design your own from scratch. In addition, using a standard DTD makes data interchange possible, and may make it possible to use data-aware tools developed by others. So if an industry standard exists, consider referencing that DTD by using an external parameter entity. One place to look for industry-standard DTDs is at the web site created by the Organization for the Advancement of Structured Information Standards (OASIS). You can find a list of technical committees at http://www.oasis-open.org/ or check its repository of XML standards at http://www.XML.org. Note: Many more good thoughts on the design of XML structures are at the OASIS page http://www.oasis-open.org/cover/elementsAndAttrs.html.

Attributes and Elements One of the issues you will encounter frequently when designing an XML structure is whether to model a given data item as a subelement or as an attribute of an existing element. For example, you can model the title of a slide this way:

This is the title

Or you can do it this way: ...

In some cases, the different characteristics of attributes and elements make it easy to choose. Let’s consider those cases first and then move on to the cases where the choice is more ambiguous.

77

78

UNDERSTANDING XML

Forced Choices Sometimes, the choice between an attribute and an element is forced on you by the nature of attributes and elements. Let’s look at a few of those considerations: • The data contains substructures: In this case, the data item must be modeled as an element. It can’t be modeled as an attribute, because attributes take only simple strings. So if the title can contain emphasized text (The Best Choice) then the title must be an element. • The data contains multiple lines: Here, it also makes sense to use an element. Attributes need to be simple, short strings or else they become unreadable, if not unusable. • Multiple occurrences are possible: Whenever an item can occur multiple times, such as paragraphs in an article, it must be modeled as an element. The element that contains it can have only one attribute of a particular kind, but it can have many subelements of the same type. • The data changes frequently: When the data will be frequently modified with an editor, it may make sense to model it as an element. Many XMLaware editors make it easy to modify element data, whereas attributes can be somewhat harder to get to. • The data is a small, simple string that rarely if ever changes: This is data that can be modeled as an attribute. However, just because you can does not mean that you should. Check the Stylistic Choices section next, to be sure. • The data is confined to a small number of fixed choices: If you are using a DTD, it really makes sense to use an attribute. A DTD can prevent an attribute from taking on any value that is not in the preapproved list, but it cannot similarly restrict an element. (With a schema, on the other hand, both attributes and elements can be restricted, so you could use either element or an attribute.)

Stylistic Choices As often as not, the choices are not as cut-and-dried as those just shown. When the choice is not forced, you need a sense of “style” to guide your thinking. The question to answer, then, is what makes good XML style, and why. Defining a sense of style for XML is, unfortunately, as nebulous a business as defining style when it comes to art or music. There are, however, a few ways to

NORMALIZING DATA

approach it. The goal of this section is to give you some useful thoughts on the subject of XML style. One heuristic for thinking about XML elements and attributes uses the concept of visibility. If the data is intended to be shown—to be displayed to an end user— then it should be modeled as an element. On the other hand, if the information guides XML processing but is never seen by a user, then it may be better to model it as an attribute. For example, in order-entry data for shoes, shoe size would definitely be an element. On the other hand, a manufacturer’s code number would be reasonably modeled as an attribute. Another way of thinking about the visibility heuristic is to ask, who is the consumer and the provider of the information? The shoe size is entered by a human sales clerk, so it’s an element. The manufacturer’s code number for a given shoe model, on the other hand, may be wired into the application or stored in a database, so that would be an attribute. (If it were entered by the clerk, though, it should perhaps be an element.) Perhaps the best way of thinking about elements and attributes is to think of an element as a container. To reason by analogy, the contents of the container (water or milk) correspond to XML data modeled as elements. Such data is essentially variable. On the other hand, the characteristics of the container (whether a blue or a white pitcher) can be modeled as attributes. That kind of information tends to be more immutable. Good XML style separates each container’s contents from its characteristics in a consistent way. To show these heuristics at work, in our slide-show example the type of the slide (executive or technical) is best modeled as an attribute. It is a characteristic of the slide that lets it be selected or rejected for a particular audience. The title of the slide, on the other hand, is part of its contents. The visibility heuristic is also satisfied here. When the slide is displayed, the title is shown but the type of the slide isn’t. Finally, in this example, the consumer of the title information is the presentation audience, whereas the consumer of the type information is the presentation program.

Normalizing Data In Saving Yourself Some Work (page 77), you saw that it is a good idea to define an external entity that you can reference in an XML document. Such an entity has all the advantages of a modularized routine: changing that one copy affects every document that references it. The process of eliminating redundancies is

79

80

UNDERSTANDING XML

known as normalizing, and defining entities is one good way to normalize your data. In an HTML file, the only way to achieve that kind of modularity is to use HTML links, but then the document is fragmented rather than whole. XML entities, on the other hand, suffer no such fragmentation. The entity reference acts like a macro: the entity’s contents are expanded in place, producing a whole document rather than a fragmented one. And when the entity is defined in an external file, multiple documents can reference it. The considerations for defining an entity reference, then, are pretty much the same as those you would apply to modularized program code: • Whenever you find yourself writing the same thing more than once, think entity. That lets you write it in one place and reference it in multiple places. • If the information is likely to change, especially if it is used in more than one place, definitely think in terms of defining an entity. An example is defining productName as an entity so that you can easily change the documents when the product name changes. • If the entity will never be referenced anywhere except in the current file, define it in the local subset of the document’s DTD, much as you would define a method or inner class in a program. • If the entity will be referenced from multiple documents, define it as an external entity, in the same way that you would define any generally usable class as an external class. External entities produce modular XML that is smaller, easier to update, and easier to maintain. They can also make the resulting document somewhat more difficult to visualize, much as a good object-oriented design can be easy to change, after you understand it, but harder to wrap your head around at first. You can also go overboard with entities. At an extreme, you could make an entity reference for the word the. It wouldn’t buy you much, but you could do it. Note: The larger an entity is, the more likely it is that changing it will have the expected effect. For example, when you define an external entity that covers a whole section of a document, such as installation instructions, then any changes you make will likely work out fine wherever that section is used. But small inline substitutions can be more problematic. For example, if productName is defined as an entity and if the name changes to a different part of speech, the results can be unfortunate. Suppose the product name is something like HtmlEdit. That’s a verb. So you write a sentence like, “You can HtmlEdit your file...”, using the productName entity. That sentence works, because a verb fits in that context. But if the name is eventually

NORMALIZING DTDS

changed to “HtmlEditor”, the sentence becomes “You can HtmlEditor your file...”, which clearly doesn’t work. Still, even if such simple substitutions can sometimes get you into trouble, they also have the potential to save a lot of time. (One way to avoid the problem would be to set up entities named productNoun, productVerb, productAdj, and productAdverb.)

Normalizing DTDs Just as you can normalize your XML document, you can also normalize your DTD declarations by factoring out common pieces and referencing them with a parameter entity. Factoring out the DTDs (also known as modularizing) gives the same advantages and disadvantages as normalized XML—easier to change, somewhat more difficult to follow. You can also set up conditionalized DTDs. If the number and size of the conditional sections are small relative to the size of the DTD as a whole, conditionalizing can let you single-source the same DTD for multiple purposes. If the number of conditional sections gets large, though, the result can be a complex document that is difficult to edit.

Summary Congratulations! You have now created a number of XML files that you can use for testing purposes. Table 2–5 describes the files you have constructed. Table 2–5 Listing of Sample XML Files File

Contents

slideSample01.xml

A basic file containing a few elements and attributes as well as comments.

slideSample02.xml

Includes a processing instruction.

SlideSampleBad1.xml

A file that is not well formed.

slideSample03.xml

Includes a simple entity reference (