The Java EE 5 TutorialThird EditionFor Sun Java System Application Server Platform Edition 9

Eric Jendrock Jennifer Ball Debbie Carson Ian Evans Scott Fordin Kim Haase

Upper Saddle River, NJ Boston Indianapolis San Francisco New York Toronto Montreal London Munich Paris Madrid Capetown Sydney Tokyo Singapore Mexico City

Copyright 2006 Sun Microsystems, Inc. 4150 Network Circle, Santa Clara, California 95054 U.S.A. All rights reserved. Duke logo designed by Joe Palrang. RESTRICTED RIGHTS LEGEND: Use, duplication, or disclosure by the United States Government is subject to the restrictions set forth in DFARS 252.2277013 (c)(1)(ii) and FAR 52.22719. The release described in this manual may be protected by one or more U.S. patents, foreign patents, or pending applications. Sun Microsystems, Inc. (SUN) hereby grants to you a fully paid, nonexclusive, nontransferable, perpetual, worldwide limited license (without the right to sublicense) under SUNs intellectual property rights that are essential to practice this specication. This license allows and is limited to the creation and distribution of clean room implementations of this specication that: (i) include a complete implementation of the current version of this specication without subsetting or supersetting; (ii) implement all the interfaces and functionality of the required packages of the Java 2 Platform, Standard Edition, as dened by SUN, without subsetting or supersetting; (iii) do not add any additional packages, classes, or interfaces to the java.* or javax.* packages or their subpackages; (iv) pass all test suites relating to the most recent published version of the specication of the Java 2 Platform, Standard Edition, that are available from SUN six (6) months prior to any beta release of the clean room implementation or upgrade thereto; (v) do not derive from SUN source code or binary materials; and (vi) do not include any SUN source code or binary materials without an appropriate and separate license from SUN. Sun, Sun Microsystems, the Sun logo, Solaris, Java, the Duke logo, JVM, JRE, JavaBeans, NetBeans, JDBC, JavaServer, JavaServer Pages, Enterprise JavaBeans, Java Naming and Directory Interface, JavaMail, EJB, JSP, J2SE, the Java Coffee Cup logo, and all Java-based trademarks or logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. UNIX is a registered trademark in the United States and other countries, exclusively licensed through X/Open Company, Ltd. THIS PUBLICATION IS PROVIDED AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. THIS PUBLICATION COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THE PUBLICATION. SUN MICROSYSTEMS, INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS PUBLICATION AT ANY TIME. The publisher offers excellent discounts on this book when ordered in quantity for bulk purchases or special sales, which may include electronic versions and/or custom covers and content particular to your business, training goals, marketing focus, and branding interests. For more information, please contact: U.S. Corporate and Government Sales (800) 3823419 corpsales@pearsontechgroup.com For sales outside the United States please contact: International Sales international@pearsoned.com

This Book Is Safari Enabled The Safari Enabled icon on the cover of your favorite technology book means the book is available through Safari Bookshelf. When you buy this book, you get free access to the online edition for 45 days. Safari Bookshelf is an electronic reference library that lets you easily search thousands of technical books, nd code samples, download chapters, and access technical information whenever and wherever you need it. To gain 45-day Safari Enabled access to this book: Go to http://www.awprofessional.com/safarienabled Complete the brief registration form Enter the coupon code DTCF-3BXD-JXI5-GWDL-S4MT If you have difculty registering on Safari Bookshelf or accessing the online edition, please e-mail customer-service@safaribooksonline.com.

Visit us on the Web: www.awprofessional.com Library of Congress Cataloging-in-Publication Data The Java EE 5 tutorial / Eric Jendrock ... [et al.]. -- 3rd ed. p. cm. Previous ed: The J2EE Tutorial / by Stephanie Bodoff. Includes index. ISBN 0-321-49029-0 (pbk. : alk. paper) 1. Java (Computer program language) 2. Internet programming. I. Jendrock, Eric. QA76.73.J38J3652 2006 005.133--dc22

2006029908

All rights reserved. Printed in the United States of America. This publication is protected by copyright, and permission must be obtained from the publisher prior to any prohibited reproduction, storage in a retrieval system, or transmission in any form or by any means, electronic, mechanical, photocopying, recording, or likewise. For information regarding permissions, write to: Pearson Education, Inc. Rights and Contracts Department 75 Arlington Street, Suite 300 Boston, MA 02116 Fax: (617) 848-7047 Cover art by Nathan Clement. ISBN 0321490290 Text printed in the United States on recycled paper at Courier in Stoughton, Massachusetts. Second Printing, February 2007

ContentsAbout This Tutorial. . . . . . . . . . . . . . . . . . . . . . . . . .xxxiWho Should Use This Tutorial Prerequisites How to Read This Tutorial About the Examples Required Software Building the Examples Tutorial Example Directory Structure Further Information Typographical Conventions Acknowledgments Feedback xxxi xxxi xxxi xxxiv xxxiv xxxvi xxxviii xxxviii xxxix xxxix xli

Chapter 1:

Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Java EE Application Model Distributed Multitiered Applications Security Java EE Components Java EE Clients Web Components Business Components Enterprise Information System Tier Java EE Containers Container Services Container Types Web Services Support XML SOAP Transport Protocol 2 3 4 4 4 7 7 7 8 9 10 11 11 12

vii

viii

CONTENTS

WSDL Standard Format UDDI and ebXML Standard Formats Java EE Application Assembly and Deployment Packaging Applications Development Roles Java EE Product Provider Tool Provider Application Component Provider Application Assembler Application Deployer and Administrator Java EE 5 APIs Enterprise JavaBeans Technology Java Servlet Technology JavaServer Pages Technology JavaServer Pages Standard Tag Library JavaServer Faces Java Message Service API Java Transaction API JavaMail API JavaBeans Activation Framework Java API for XML Processing Java API for XML Web Services (JAX-WS) Java Architecture for XML Binding (JAXB) SOAP with Attachments API for Java Java API for XML Registries J2EE Connector Architecture Java Database Connectivity API Java Persistence API Java Naming and Directory Interface Java Authentication and Authorization Service Simplified Systems Integration Sun Java System Application Server Platform Edition 9 Tools Starting and Stopping the Application Server Starting the Admin Console Starting and Stopping the Java DB Database Server Debugging Java EE Applications

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

CONTENTS

ix

Part One: The Web Tier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Chapter 2: Getting Started with Web Applications . . . . . . . . . 33Web Application Life Cycle Web Modules Packaging Web Modules Deploying a WAR File Testing Deployed Web Modules Listing Deployed Web Modules Updating Web Modules Undeploying Web Modules Conguring Web Applications Mapping URLs to Web Components Declaring Welcome Files Setting Initialization Parameters Mapping Errors to Error Screens Declaring Resource References Dukes Bookstore Examples Accessing Databases from Web Applications Populating the Example Database Creating a Data Source in the Application Server Further Information 36 38 39 40 42 42 43 45 46 46 48 49 51 52 55 55 56 56 57

Chapter 3:

Java Servlet Technology . . . . . . . . . . . . . . . . . . . . . 59What 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 59 60 62 63 63 66 66 67 68 69 70 71 72 74

x

CONTENTS

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 Session Tracking Finalizing a Servlet Tracking Service Requests Notifying Methods to Shut Down Creating Polite Long-Running Methods Further Information

77 77 79 82 84 85 87 88 89 89 89 90 91 92 93 94 94 95

Chapter 4:

JavaServer Pages Technology . . . . . . . . . . . . . . . .97What 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 Unied Expression Language Immediate and Deferred Evaluation Syntax Value and Method Expressions Defining a Tag Attribute Type Deactivating Expression Evaluation Literal Expressions Resolving Expressions Implicit Objects Operators Reserved Words 97 98 101 107 107 108 110 110 111 111 113 115 116 123 125 126 127 130 131 132

CONTENTS

xi 133 134 136 136 138 139 141 141 142 144 145 146 146 147 149 154

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 Setting Properties for Groups of JSP Pages Further Information

Chapter 5:

JavaServer Pages Documents . . . . . . . . . . . . . . . 155The 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 156 158 161 163 165 168 169 173

Chapter 6:

JavaServer Pages Standard Tag Library . . . . . . . 175The Example JSP Pages Using JSTL Tag Collaboration Core Tag Library Variable Support Tags Flow Control Tags URL Tags Miscellaneous Tags 176 177 179 180 180 182 185 186

xii

CONTENTS

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

188 189 190 191 192 193 193 194 195 197 199 201

Chapter 7:

Custom Tags in JSP Pages . . . . . . . . . . . . . . . . . . .203What Is a Custom Tag? The Example JSP Pages Types of Tags 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 204 204 207 207 211 211 211 212 214 215 224 224 229 230 231 234 236 238 240 240 241 241 241 245 246

CONTENTS

xiii 249 251

Cooperating Tags Examples

Chapter 8:

Scripting in JSP Pages . . . . . . . . . . . . . . . . . . . . . . 261The 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 262 263 264 264 265 265 266 267 267 268 270 272 274

Chapter 9:

JavaServer Faces Technology . . . . . . . . . . . . . . . 275JavaServer Faces Technology Benets What Is a JavaServer Faces Application? A Simple JavaServer Faces Application Steps in the Development Process Mapping the FacesServlet Instance Creating the Pages Defining Page Navigation Configuring Error Messages 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 Beans The Life Cycle of a JavaServer Faces Page Further Information 276 277 278 278 280 281 288 289 289 290 291 292 294 298 300 301 302 304 309 315

xiv

CONTENTS

Chapter 10: Using JavaServer Faces Technology in JSP Pages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .317The Example JavaServer Faces Application Setting Up a Page Using the Core Tags Adding UI Components to a Page Using the HTML Component Tags UI Component Tag Attributes Adding a Form Component Using Text Components Using Command Components for Performing Actions and Navigation Using Data-Bound Table Components Adding Graphics and Images with the graphicImage Tag Laying Out Components with the UIPanel Component Rendering Components for Selecting One Value Rendering Components for Selecting Multiple Values The UISelectItem, UISelectItems, and UISelectItemGroup Components Displaying Error Messages with the message and messages Tags Using Localized Data Loading a Resource Bundle Referencing Localized Static Data Referencing Error Messages Using the Standard Converters Converting a Components Value Using DateTimeConverter Using NumberConverter Registering Listeners on Components Registering a Value-Change Listener on a Component Registering an Action Listener on a Component Using the Standard Validators Validating a Components Value Using the LongRangeValidator Binding Component Values and Instances to External Data Sources Binding a Component Value to a Property Binding a Component Value to an Implicit Object Binding a Component Instance to a Bean Property 318 321 324 326 327 330 331 337 339 343 344 347 349 350 354 355 356 357 358 359 360 362 364 366 366 367 369 370 371 371 373 375 376

CONTENTS

xv

Binding Converters, Listeners, and Validators to Backing Bean Properties Referencing a Backing Bean Method Referencing a Method That Performs Navigation Referencing a Method That Handles an Action Event Referencing a Method That Performs Validation Referencing a Method That Handles a Value-change Event Using Custom Objects Using a Custom Converter Using a Custom Validator Using a Custom Component

378 379 380 381 382 382 383 384 385 386

Chapter 11: Developing with JavaServer Faces Technology. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389Writing Bean Properties Writing Properties Bound to Component Values Writing Properties Bound to Component Instances Writing Properties Bound to Converters, Listeners, or Validators Performing Localization Creating a Resource Bundle Localizing Dynamic Data Localizing Messages 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 390 391 399 401 402 402 403 403 405 408 409 410 411 412 416 418 419 421 421 422

xvi

CONTENTS

Chapter 12: Creating Custom UI Components . . . . . . . . . . . . .425Determining Whether You Need a Custom Component or Renderer When to Use a Custom Component When to Use a Custom Renderer Component, Renderer, and Tag Combinations Understanding the Image Map Example Why Use JavaServer Faces Technology to Implement an Image Map? Understanding the Rendered HTML Understanding the JSP Page Configuring Model Data Summary of the Application Classes Steps for Creating a Custom Component Creating Custom Component Classes Specifying the Component Family Performing Encoding Performing Decoding Enabling Component Properties to Accept Expressions Saving and Restoring State Delegating Rendering to a Renderer Creating the Renderer Class Identifying the Renderer Type Handling Events for Custom Components Creating the Component Tag Handler Retrieving the Component Type Setting Component Property Values Providing the Renderer Type Releasing Resources Dening the Custom Component Tag in a Tag Library Descriptor 426 426 428 428 429 430 430 431 433 435 436 437 440 440 442 443 445 446 447 448 449 450 451 451 454 455 455

Chapter 13: Configuring JavaServer Faces Applications . . . .457Application Conguration Resource File Conguring Beans Using the managed-bean Element Initializing Properties Using the managed-property Element Initializing Maps and Lists Registering Custom Error Messages 458 459 460 462 469 470

CONTENTS

xvii 471 472 473 474 478 480 481 483 491 492

Registering Custom Localized Static Text Registering a Custom Validator Registering a Custom Converter Conguring Navigation Rules Registering a Custom Renderer with a Render Kit Registering a Custom Component Basic Requirements of a JavaServer Faces Application Configuring an Application with a Deployment Descriptor Including the Required JAR Files Including the Classes, Pages, and Other Resources

Chapter 14: Internationalizing and Localizing Web Applications . . . . . . . . . . . . . . . . . . . . . . . . . 493Java 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 493 494 495 496 497 498 499 499 500 503

Part Two: Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505 Chapter 15: Building Web Services with JAX-WS . . . . . . . . . . . 507Setting the Port Creating a Simple Web Service and Client with JAX-WS Requirements of a JAX-WS Endpoint Coding the Service Endpoint Implementation Class Building, Packaging, and Deploying the Service Testing the Service without a Client A Simple JAX-WS Client Types Supported by JAX-WS Web Services Interoperability and JAX-WS Further Information 508 508 510 511 511 513 513 516 516 517

xviii

CONTENTS

Chapter 16: Binding between XML Schema and Java Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .519JAXB Architecture Architectural Overview The JAXB Binding Process More about Unmarshalling More about Marshalling More about Validation Representing XML Content Java Representation of XML Schema Binding XML Schemas Simple Type Definitions Default Data Type Bindings Customizing JAXB Bindings Schema-to-Java Java-to-Schema Examples JAXB Compiler Options JAXB Schema Generator Option About the Schema-to-Java Bindings Schema-Derived JAXB Classes Basic Examples Modify Marshal Example Unmarshal Validate Example Customizing JAXB Bindings Why Customize? Customization Overview Customize Inline Example Datatype Converter Example Binding Declaration Files External Customize Example Java-to-Schema Examples j2s-create-marshal Example j2s-xmlAccessorOrder Example j2s-xmlAdapter-field Example j2s-xmlAttribute-field Example j2s-xmlRootElement Example j2s-xmlSchemaType-class Example j2s-xmlType Example Further Information 520 520 521 522 522 522 522 523 523 523 523 526 526 526 533 536 538 539 542 545 546 547 549 550 550 563 569 570 574 575 575 576 580 583 584 585 587 589

CONTENTS

xix

Chapter 17: Streaming API for XML . . . . . . . . . . . . . . . . . . . . . . 591Why StAX? Streaming versus DOM Pull Parsing versus Push Parsing StAX Use Cases Comparing StAX to Other JAXP APIs StAX API Cursor API Iterator API Choosing between Cursor and Iterator APIs Using StAX StAX Factory Classes Resources, Namespaces, and Errors Reading XML Streams Writing XML Streams Suns Streaming XML Parser Implementation Reporting CDATA Events Streaming XML Parser Factories Implementation Example Code Example Code Organization Example XML Document Cursor Example Cursor-to-Event Example Event Example Filter Example Read-and-Write Example Writer Example Further Information 591 592 593 593 594 595 595 596 601 602 603 605 606 609 611 611 612 612 613 614 614 617 619 622 626 628 631

Chapter 18: SOAP with Attachments API for Java . . . . . . . . . . 633Overview 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 634 634 638 639 640 649 650 652 652 653

xx

CONTENTS

Adding Attributes Using SOAP Faults Code Examples Request.java MyUddiPing.java HeaderExample.java DOMExample.java and DOMSrcExample.java Attachments.java SOAPFaultTest.java Further Information

655 661 667 667 669 678 681 686 689 692

Chapter 19: Java API for XML Registries . . . . . . . . . . . . . . . . . .693Overview 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 Running the Examples Using JAXR Clients in Java EE Applications Coding the Application Client: MyAppClient.java Coding the PubQuery Session Bean Editing the Properties File Starting the Application Server Creating JAXR Resources Building, Deploying, and Running the Application Using NetBeans 5.5 Building, Deploying, and Running the Application Using Ant Further Information 693 693 694 695 696 697 702 707 715 720 722 723 724 733 734 734 735 735 735 736 737 739

CONTENTS

xxi

Part Three: Enterprise Beans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 741 Chapter 20: Enterprise Beans . . . . . . . . . . . . . . . . . . . . . . . . . . . 743What 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 a Message-Driven Bean? What Makes Message-Driven Beans Different from Session Beans? When to Use Message-Driven Beans Dening Client Access with Interfaces Remote Clients Local Clients Deciding on Remote or Local Access Web Service Clients Method Parameters and Access The Contents of an Enterprise Bean Naming Conventions for Enterprise Beans The Life Cycles of Enterprise Beans The Life Cycle of a Stateful Session Bean The Life Cycle of a Stateless Session Bean The Life Cycle of a Message-Driven Bean Further Information 743 743 744 745 745 745 746 747 747 749 749 750 751 751 752 753 754 755 755 755 756 757 758

Chapter 21: Getting Started with Enterprise Beans . . . . . . . . . 759Creating the Enterprise Bean Coding the Enterprise Bean Compiling and Packaging the converter Example Creating the Application Client Coding the Application Client Compiling the Application Client Creating the Web Client Coding the Web Client Compiling the Web Client 760 760 761 763 763 765 765 765 767

xxii

CONTENTS

Deploying the Java EE Application Deploying the converter Example Using NetBeans 5.5 Deploying the converter Example Using Ant Running the Application Client Running the Application Client Using NetBeans 5.5 Running the Application Client Using Ant Running the Web Client Modifying the Java EE Application Modifying a Class File

767 768 768 768 768 769 769 770 770

Chapter 22: Session Bean Examples . . . . . . . . . . . . . . . . . . . . .771The cart Example Session Bean Class The Remove Method Helper Classes Building, Packaging, Deploying, and Running the cart Example Undeploying the cart Example A Web Service Example: helloservice The Web Service Endpoint Implementation Class Stateless Session Bean Implementation Class Building, Packaging, Deploying, and Testing the helloservice Example Using the Timer Service The Timeout Method Creating Timers Canceling and Saving Timers Getting Timer Information Transactions and Timers The timersession Example Building, Packaging, Deploying, and Running the timersession Example Handling Exceptions 771 773 776 777 777 779 780 780 781 782 783 784 784 785 785 786 786 787 789

Chapter 23: A Message-Driven Bean Example . . . . . . . . . . . .791Example Application Overview The Application Client The Message-Driven Bean Class The onMessage Method 791 792 793 794

CONTENTS

xxiii

Packaging, Deploying, and Running the SimpleMessage Example Creating the Administered Objects Building, Deploying, and Running the Application Using NetBeans 5.5 Building, Deploying, and Running the Application Using Ant Removing the Administered Objects Creating Deployment Descriptors for Message-Driven Beans

795 795 796 797 798 798

Part Four: Persistence. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 801 Chapter 24: Introduction to the Java Persistence API . . . . . . . 803Entities Requirements for Entity Classes Persistent Fields and Properties in Entity Classes Primary Keys in Entities Multiplicity in Entity Relationships Direction in Entity Relationships Entity Inheritance Managing Entities The Persistence Context The EntityManager Persistence Units 803 804 804 806 808 809 811 816 816 816 822

Chapter 25: Persistence in the Web Tier . . . . . . . . . . . . . . . . . . 825Accessing Databases from Web Applications Defining the Persistence Unit Creating an Entity Class Obtaining Access to an Entity Manager Accessing Data from the Database Updating Data in the Database 825 827 827 829 831 832

Chapter 26: Persistence in the EJB Tier . . . . . . . . . . . . . . . . . . . 835The order Application Entity Relationships in the order Application Primary Keys in the order Application Entity Mapped to More Than One Database Table Cascade Operations in the order Application 835 836 838 842 843

xxiv

CONTENTS

BLOB and CLOB Database Types in the order Application Temporal Types in the order Application Managing the order Applications Entities Building and Running the order Application The roster Application Relationships in the roster Application Entity Inheritance in the roster Application Automatic Table Generation in the roster Application Building and Running the roster Application

844 844 845 848 853 853 854 856 857

Chapter 27: The Java Persistence Query Language . . . . . . . .861Terminology Simplied Syntax Select Statements Update and Delete Statements Example Queries Simple Queries Queries That Navigate to Related Entities Queries with Other Conditional Expressions Bulk Updates and Deletes Full Syntax BNF Symbols BNF Grammar of the Java Persistence Query Language FROM Clause Path Expressions WHERE Clause SELECT Clause ORDER BY Clause The GROUP BY Clause 862 862 862 863 863 864 865 867 869 870 870 871 876 880 881 892 894 895

Part Five: Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .897 Chapter 28: Introduction to Security in Java EE . . . . . . . . . . . .899Overview A Simple Example Security Functions Characteristics of Application Security Security Implementation Mechanisms Java SE Security Implementation Mechanisms Java EE Security Implementation Mechanisms 900 901 904 904 906 906 907

CONTENTS

xxv 910 910 912 913 913 914 915 918 920 921 922 923 923 925 926 932 934

Securing Containers Using Deployment Descriptors for Declarative Security Using Annotations Using Programmatic Security Securing the Application Server Working with Realms, Users, Groups, and Roles What Are Realms, Users, Groups, and Roles? Managing Users and Groups on the Application Server Setting Up Security Roles Mapping Roles to Users and Groups Establishing a Secure Connection Using SSL Installing and Configuring SSL Support Specifying a Secure Connection in Your Application Deployment Descriptor Verifying SSL Support Working with Digital Certificates Enabling Mutual Authentication over SSL Further Information

Chapter 29: Securing Java EE Applications . . . . . . . . . . . . . . . 937Securing Enterprise Beans Accessing an Enterprise Bean Callers Security Context Declaring Security Role Names Referenced from Enterprise Bean Code Defining a Security View of Enterprise Beans Using Enterprise Bean Security Annotations Using Enterprise Bean Security Deployment Descriptor Elements Configuring IOR Security Deploying Secure Enterprise Beans Enterprise Bean Example Applications Example: Securing an Enterprise Bean Example: Using the isCallerInRole and getCallerPrincipal Methods Discussion: Securing the Dukes Bank Example Securing Application Clients Using Login Modules Using Programmatic Login 938 940 942 944 957 958 959 962 963 964 970 977 978 978 979

xxvi

CONTENTS

Securing EIS Applications Container-Managed Sign-On Component-Managed Sign-On Configuring Resource Adapter Security Mapping an Application Principal to EIS Principals Example Applications in the Application Server Further Information

980 980 981 981 983 984 984

Chapter 30: Securing Web Applications . . . . . . . . . . . . . . . . . .987Overview Working with Security Roles Declaring Security Roles Mapping Security Roles to Application Server Groups Checking Caller Identity Programmatically Declaring and Linking Role References Dening Security Requirements for Web Applications Declaring Security Requirements Using Annotations Declaring Security Requirements in a Deployment Descriptor Specifying a Secure Connection Specifying an Authentication Mechanism Examples: Securing Web Applications Example: Using Form-Based Authentication with a JSP Page Example: Basic Authentication with a Servlet Example: Basic Authentication with JAX-WS Further Information 988 989 990 993 994 996 998 999 1002 1009 1010 1018 1020 1031 1041 1049

Chapter 31: The Java Message Service API . . . . . . . . . . . . . .1051Overview What Is Messaging? What Is the JMS API? When Can You Use the JMS API? How Does the JMS API Work with the Java EE Platform? Basic JMS API Concepts JMS API Architecture Messaging Domains Message Consumption The JMS API Programming Model Administered Objects 1051 1052 1052 1053 1054 1055 1056 1056 1059 1059 1060

CONTENTS

xxvii 1062 1063 1064 1064 1067 1070 1070 1071 1072 1082 1087 1093 1098 1099 1106 1119 1120 1120 1121 1124 1126 1127

Connections Sessions Message Producers Message Consumers Messages Queue Browsers Exception Handling Writing Simple JMS Client Applications A Simple Example of Synchronous Message Receives A Simple Example of Asynchronous Message Consumption A Simple Example of Browsing Messages in a Queue Running JMS Client Programs on Multiple Systems Creating Robust JMS Applications Using Basic Reliability Mechanisms Using Advanced Reliability Mechanisms Using the JMS API in a Java EE Application Using @Resource Annotations in Java EE Components Using Session Beans to Produce and to Synchronously Receive Messages Using Message-Driven Beans Managing Distributed Transactions Using the JMS API with Application Clients and Web Components Further Information

Chapter 32: Java EE Examples Using the JMS API . . . . . . . . . 1129A Java EE Application That Uses the JMS API with a Session Bean Writing the Application Components Creating Resources for the Application Building, Deploying, and Running the Application Using NetBeans 5.5 Building, Deploying, and Running the Application Using Ant A Java EE Application That Uses the JMS API with an Entity Overview of the Human Resources Application Writing the Application Components Creating Resources for the Application 1130 1130 1133 1134 1135 1136 1137 1139 1141

xxviii

CONTENTS

Building, Deploying, and Running the Application Using NetBeans 5.5 Building, Deploying, and Running the Application Using Ant An Application Example That Consumes Messages from a Remote Server Overview of the Modules Writing the Module Components Creating Resources for the Application Using Two Application Servers Building, Deploying, and Running the Modules Using NetBeans 5.5 Building, Deploying, and Running the Modules Using Ant An Application Example That Deploys a Message-Driven Bean on Two Servers Overview of the Modules Writing the Module Components Creating Resources for the Modules Using Two Application Servers Building, Deploying, and Running the Modules Using NetBeans 5.5 Building, Deploying, and Running the Modules Using Ant

1141 1144 1146 1147 1148 1148 1149 1149 1151 1153 1154 1154 1156 1157 1157 1161

Chapter 33: Transactions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1165What Is a Transaction? Container-Managed Transactions Transaction Attributes Rolling Back a Container-Managed Transaction Synchronizing a Session Beans Instance Variables Methods Not Allowed in Container-Managed Transactions Bean-Managed Transactions JTA Transactions Returning without Committing Methods Not Allowed in Bean-Managed Transactions Transaction Timeouts Updating Multiple Databases Transactions in Web Components 1165 1166 1167 1171 1172 1172 1173 1173 1174 1174 1174 1175 1177

CONTENTS

xxix

Chapter 34: Resource Connections . . . . . . . . . . . . . . . . . . . . 1179Resources and JNDI Naming DataSource Objects and Connection Pools Resource Injection Field-Based Injection Method-Based Injection Class-Based Injection The conrmer Example Application Running the confirmer Example Application Further Information 1179 1181 1182 1183 1184 1185 1186 1187 1190

Chapter 35: Connector Architecture . . . . . . . . . . . . . . . . . . . 1191About Resource Adapters Resource Adapter Contracts Management Contracts Outbound Contracts Inbound Contracts Common Client Interface Further Information 1191 1193 1193 1195 1195 1196 1197

Part Six: Case Studies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1199 Chapter 36: The Coffee Break Application. . . . . . . . . . . . . . . 1201Common Code JAX-WS Coffee Supplier Service Service Implementation SAAJ Coffee Supplier Service SAAJ Client SAAJ Service Coffee Break Server JSP Pages JavaBeans Components RetailPriceListServlet Resource Configuration Building, Packaging, Deploying, and Running the Application Setting the Port Building, Packaging, and Deploying the JAX-WS Service Building, Packaging, and Deploying the SAAJ Service Building, Packaging, and Deploying the Coffee Break Server 1202 1202 1203 1204 1205 1213 1219 1220 1223 1225 1225 1226 1226 1227 1228 1228

xxx

CONTENTS

Running the Coffee Break Client Removing the Coffee Break Application

1229 1231

Chapter 37: The Dukes Bank Application . . . . . . . . . . . . . . . .1233Enterprise Beans Session Beans Java Persistence Entities Helper Classes Database Tables Protecting the Enterprise Beans Application Client The Classes and Their Relationships BankAdmin Class Web Client Design Strategies Client Components Request Processing Protecting the Web Client Resources Building, Packaging, Deploying, and Running the Application Setting Up the Servers Building, Packaging, and Deploying Dukes Bank Using NetBeans 5.5 Building, Packaging, and Deploying Dukes Bank Using Ant Running the Application Client Using NetBeans 5.5 Running the Application Client Using Ant Running the Web Client 1234 1234 1237 1238 1238 1239 1240 1241 1241 1243 1245 1246 1249 1251 1253 1253 1255 1255 1256 1256 1257

Appendix A: Java Encoding Schemes . . . . . . . . . . . . . . . . . . .1259Further Information 1260

Appendix B: Preparation for Java EE Certification Exams . . .1261CX-310-081: Sun Certied Web Component Developer SL-351: Business Component Development with Enterprise JavaBeans Technology 1262 1263

About the Authors . . . . . . . . . . . . . . . . . . . . . . . . .1265 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1267

About This TutorialTHIS tutorial is a guide to developing enterprise applications for the Java Platform, Enterprise Edition 5 (Java EE 5). Here we cover all the things you need to know to make the best use of this tutorial.

Who Should Use This TutorialThis tutorial is intended for programmers who are interested in developing and deploying Java EE 5 applications on the Sun Java System Application Server Platform Edition 9.

PrerequisitesBefore 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 The Java Tutorial, Fourth Edition, Sharon Zakhour et al. (Addison-Wesley, 2006). You should also be familiar with the relational database features described in JDBC API Tutorial and Reference, Third Edition, Maydene Fisher et al. (Addison-Wesley, 2003).

How to Read This TutorialThe Java EE 5 platform is quite large, and this tutorial reects this. However, you dont have to digest everything in it at once. The tutorial has been divided into parts to help you navigate the content more easily.

xxxi

xxxii

ABOUT THIS TUTORIAL

This tutorial opens with an introductory chapter, which you should read before proceeding to any specic technology area. Chapter 1 covers the Java EE 5 platform architecture and APIs along with the Sun Java System Application Server Platform Edition 9. When you have digested the basics, you can delve into one or more of the ve 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 web-tier technology chapters cover the components used in developing the presentation layer of a Java EE 5 or stand-alone web application: Java Servlet JavaServer Pages (JSP) JavaServer Pages Standard Tag Library (JSTL) JavaServer Faces Web application internationalization and localization The web services technology chapters cover the APIs used in developing standard web services: The Java API for XML-based Web Services (JAX-WS) The Java API for XML Binding (JAXB) The Streaming API for XML (StAX) The SOAP with Attachments API for Java (SAAJ) The Java API for XML Registries (JAXR) The Enterprise JavaBeans (EJB) technology chapters cover the components used in developing the business logic of a Java EE 5 application: Session beans Message-driven beans The Persistence technology chapters cover the Java Persistence API, which is used for accessing databases from Java EE applications: Introduction to the Java Persistence API Persistence in the Web Tier Persistence in the EJB Tier The Java Persistence Query Language

ABOUT THIS TUTORIAL

xxxiii

The platform services chapters cover the system services used by all the Java EE 5 component technologies: Transactions Resource connections Security Java Message Service The Connector architecture

Overview

Getting Started with Web Applications (2)

Building Web Services with JAX-WS (15)

Enterprise Beans (20-30)

Security (28-30)

JAXB (16) Servlets (3) STAX (17)

SAAJ (18) JAXR (19)

JMS (31-32)

Transactions (33)

JSP (4-8) Persistence (24-27) JSF (9-13) Coffee Break Case Study (36) Dukes Bank Case Study (37)

Resource Connections (34)

Connectors (35)

l18n and L10n (14)

Figure 1 Roadmap to 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 describes an application that uses the web application and web services APIs. The Dukes Bank Application describes an application that employs web application technologies, enterprise beans, and the Java Persistence API. Finally, the appendix contains information about Java encoding schemes that may be helpful to the Java EE 5 application developer.

xxxiv

ABOUT THIS TUTORIAL

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

Required SoftwareThe following software is required to run the examples.

Tutorial BundleThe tutorial example source is contained in the tutorial bundle. If you are viewing this online, you need to click on the Download link at the top of any page. After you have installed the tutorial bundle, the example source code is in the /javaeetutorial5/examples/ directory, where is the directory where you installed the tutorial. The examples directory contains subdirectories for each of the technologies discussed in the tutorial.

Java 2 Platform, Standard EditionTo build, deploy, and run the examples, you need a copy of Java 2 Platform, Standard Edition 5.0 (J2SE 5.0). You can download the J2SE 5.0 software from:http://java.sun.com/javase/downloads/index_jdk5.jsp

Download the current JDK update that does not include any other software (such as NetBeans or Java EE).

Java EE 5 SDK with NetBeans 5.5The Sun Java System Application Server Platform Edition 9 is targeted as the build and runtime environment for the tutorial examples. To build, deploy, and run the examples, you need a copy of the Application Server and, optionally, NetBeans 5.5. You can download the Application Server from:http://java.sun.com/javaee/downloads/index.html

ABOUT THIS TUTORIAL

xxxv

Scroll down to the section entitled Java EE 5 SDK Update 2 and click the Download with Tools button. This SDK contains Sun Java System Application Server Platform Edition 9 Update 1 and NetBeans 5.5.

Java EE 5 SDK Installation TipsIn the Admin conguration pane of the SDK installer: Accept the default admin user name and password. The user name is admin, and the password is adminadmin. You will need this user name and password to log in to the Application Server 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 le (described in the next section) and the conguration les for some of the tutorial examples to reect the correct port. This tutorial refers to the directory where you install the Java EE 5 SDK as . For example, the default installation directory on Microsoft Windows is C:\Sun\SDK, so is C:\Sun\SDK. Add the /bin directory to your PATH environment variable.

NetBeans 5.5The NetBeans integrated development environment (IDE) is a free, open-source IDE for developing Java applications, including enterprise applications. NetBeans 5.5 supports the Java EE 5 platform. You can build, package, deploy, and run the tutorial examples from within NetBeans 5.5.

Apache AntAnt is a Java technology-based build tool developed by the Apache Software Foundation (http://ant.apache.org), and is used to build, package, and deploy the tutorial examples. Ant is included with the Application Server. To use the ant command, add /lib/ant/bin to your PATH environment variable.

xxxvi

ABOUT THIS TUTORIAL

Registry ServerYou need a registry server to run the examples discussed in Chapter 19. Instructions for obtaining and setting up a registry server are provided in Chapter 19.

Building the ExamplesThe tutorial examples are distributed with a conguration le for either NetBeans 5.5 or Ant. Directions for building the examples are provided in each chapter. Either NetBeans 5.5 or Ant may be used to build, package, deploy, and run the examples.

Building the Examples Using NetBeans 5.5To run the tutorial examples in NetBeans 5.5, you must register your Application Server installation as a NetBeans Server Instance. Follow these instructions to register the Application Server in NetBeans 5.5. 1. 2. 3. 4. Select ToolsServer Manager to open the Server Manager dialog. Click Add Server. Under Server, select Sun Java System Application Server and click Next. Under Platform Location, enter the location of your Application Server installation. 5. Select Register Local Default Domain and click Next. 6. Under Admin Username and Admin Password, enter the admin name and password created when you installed the Java EE SDK. 7. Click Finish.

Building the Examples on the Command-Line Using Antties

Build properties common to all the examples are specied in the build.properle in the /javaeetutorial5/examples/bp-project/ directory. You must create this le before you can run the examples. Weve included a sample le, build.properties.sample, that you should rename to build.properties and edit to reect your environment. The tutorial examples use the Java BluePrints (http://java.sun.com/reference/blueprints/) build system and application layout structure.

ABOUT THIS TUTORIAL

xxxvii

To run the Ant scripts, you must set common build properties in the le /javaeetutorial5/examples/bp-project/build.properties as follows: Set the javaee.home property to the location of your Java EE 5 SDK installation. The build process uses the javaee.home property to include the libraries in /lib/ in the classpath. All examples that run on the Application Server include the Java EE library archive /lib/javaee.jarin the build classpath. Some examples use additional libraries in /lib/; the required libraries are enumerated in the individual technology chapters.Note: On Windows, you must escape any backslashes in the javaee.home property with another backslash or use forward slashes as a path separator. So, if your Jave EE 5 SDK installation is C:\Sun\SDK, you must set javaee.home as follows:javaee.home = C:\\Sun\\SDK

orjavaee.home=C:/Sun/SDK

Set the javaee.tutorial.home property to the location of your tutorial. This property is used for Ant deployment and undeployment. For example, on UNIX:javaee.tutorial.home=/home/username/javaeetutorial5

On Windows:javaee.tutorial.home=C:/javaeetutorial5

Do not install the tutorial to a location with spaces in the path. If you did not accept the default values for the admin user and password, set the admin.user property to the value you specied when you installed the Java EE 5 SDK, and set the admin users password in the admin-password.txt le in the /javaeetutorial5/examples/common/ directory to the value you specied when you installed the Java EE 5 SDK. If you did not use port 8080, set the domain.resources.port property to the value specied when you installed the Java EE 5 SDK.

xxxviii

ABOUT THIS TUTORIAL

Tutorial Example Directory StructureTo facilitate iterative development and keep application source separate from compiled les, the tutorial examples use the Java BluePrints application directory structure. Each application module has the following structure: build.xml: Ant build le src/java: Java source les for the module src/conf: conguration les for the module, with the exception of web applications web: JSP and HTML pages, style sheets, tag les, and images web/WEB-INF: conguration les for web applications nbproject: NetBeans project les Examples that have multiple application modules packaged into an enterprise application archive (or EAR) have submodule directories that use the following naming conventions: -app-client: Application clients -ejb: Enterprise bean JARs -war: web applications The Ant build les (build.xml) distributed with the examples contain targets to create a build subdirectory and to copy and compile les into that directory; a dist subdirectory, which holds the packaged module le; and a client-jar directory, which holds the retrieved application client JAR.

Further InformationThis tutorial includes the basic information that you need to deploy applications on and administer the Application Server. See the Sun Java System Application Server Platform Edition 9 Developers Guide at http://docs.sun.com/doc/819-3659 for information about developer features of the Application Server. See the Sun Java System Application Server Platform Edition 9 Administration Guide at http://docs.sun.com/doc/819-3658 for information about administering the Application Server.

ABOUT THIS TUTORIAL

xxxix

For information on creating enterprise applications in NetBeans 5.5, see http://www.netbeans.org/kb/55/index.html. For information about the Java DB database included with the Application Server, see http://developers.sun.com/prodtech/javadb. The GlassFish Samples project is a collection of sample applications that demonstrate a broad range of Java EE technologies. The GlassFish Samples are bundled with the Java EE SDK, and are also available from the GlassFish Samples project page: https://glassfish-samples.dev.java.net/.

Typographical ConventionsTable 1 lists the typographical conventions used in this tutorial.Table 1 Typographical Conventions Font Styleitalic

UsesEmphasis, titles, rst occurrence of terms URLs, code examples, le names, path names, tool names, application names, programming language keywords, tag, interface, class, method, and eld names, properties Variables in code, le paths, and URLs User-selected le path components

monospace

italic monospace

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

AcknowledgmentsThe Java EE tutorial team would like to thank the Java EE specication leads: Bill Shannon, Linda DeMichiel, Sekhar Vajjhala, Jan Luehe, Gregory Murray, Arun Gupta, Doug Kohlert, Ed Burns, V B Kumar Jayanti, Binod P. G., Sankara Rao, Dhiru Pandey, Rajiv Mordani, Farrukh Najmi, and Ron Monzillo.

xl

ABOUT THIS TUTORIAL

We would also like to thank the Java EE 5 SDK team members: Anil Gaur, Tony Ng, Inderjeet Singh, Carla Carlson, Nazrul Islam, Jerome Dochez, Jean-Francois Arcand, Chinmay Mehta, Suveen Nadipalli, Vipin Rajan, and Chinmayee Srivathsa. The chapters on custom tags and the Coffee Break and Dukes Bank applications use a template tag library that rst 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 beneted greatly from the invaluable documentation reviews and example code contributions of these engineers: Ed Burns, Roger Kitain, Jan Luehe, Craig McClanahan, and especially Ryan Lubke and Jayashri Visvanathan. The EJB technology and Java Persistence API chapters were written with extensive input from Suns EJB and Persistence teams. Wed like to thank Marina Vatkina, Ken Saks, Geoff Halliwell, Shelly MacGowan, Linda DeMichiel, Markus Fuchs, Rochelle Raccah, Lance Andersen, Vince Kraemer, Michael Bouschen, and Tim Quinn for their contributions to the material and code examples. The security, JAXB, and StAX chapter writers greatly appreciate the input of Raja Perumal, Joseph Fialli, Ryan Shoemaker, Kohsuke Kawaguchi, Rebecca Searls, and Neeraj Bajaj, who were a key contributors both to the chapters and to the examples. Wed like to thank the NetBeans engineering and documentation teams, particularly Petr Jiricka, Jan Chalupa, Ludovic Champenois, Petr Blaha, Peter Williams, Geertjan Wielenga, Jesse Glick, Tomasz Slota, John Jullion-Ceccarelli, and Patrick Keegan, for their help in enabling NetBeans support for the code examples. Stephanie Bodoff and Dale Green contributed much content to the rst and second editions 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 inuence. We also thank Dwayne Wolff for developing and updating the illustrations in record time and our editor, Julie Bettis, for improving the readability and ow of

ABOUT THIS TUTORIAL

xli

the book. Thanks are also due to our copy editor, Hartley Ferguson, for helping this multiauthor project achieve a common style. Finally, we would like to express our profound appreciation to Greg Doench, Elizabeth Ryan, and the production team at Addison-Wesley for graciously seeing our large, complicated manuscript to publication.

FeedbackTo send comments, broken link reports, errors, suggestions, and questions about this tutorial to the tutorial team, please use the feedback form athttp://java.sun.com/javaee/5/docs/tutorial/information/sendusmail.html.

1OverviewDEVELOPERS today increasingly recognize the need for distributed, transactional, and portable applications that leverage the speed, security, and reliability of server-side technology. In the world of information technology, enterprise applications must be designed, built, and produced for less money, with greater speed, and with fewer resources. With the Java Platform, Enterprise Edition (Java EE), development of Java enterprise applications has never been easier or faster. The aim of the Java EE 5 platform is to provide developers a powerful set of APIs while reducing development time, reducing application complexity, and improving application performance. The Java EE 5 platform introduces a simplied programming model. With Java EE 5 technology, XML deployment descriptors are now optional. Instead, a developer can simply enter the information as an annotation directly into a Java source le, and the Java EE server will congure the component at deployment and runtime. These annotations are generally used to embed in a program data that would otherwise be furnished in a deployment descriptor. With annotations, the specication information is put directly in your code next to the program element that it affects. In the Java EE platform, dependency injection can be applied to all resources that a component needs, effectively hiding the creation and lookup of resources from application code. Dependency injection can be used in EJB containers, web containers, and application clients. Dependency injection allows the Java EE container to automatically insert references to other required components or resources using annotations.1

2

OVERVIEW

The Java Persistence API is new to the Java EE 5 platform. The Java Persistence API provides an object/relational mapping for managing relational data in enterprise beans, web components, and application clients. It can also be used in Java SE applications, outside of the Java EE environment. This tutorial uses examples to describe the features and functionalities available in the Java EE 5 platform for developing enterprise applications. Whether you are a new or experienced Enterprise developer, you should nd the examples and accompanying text a valuable and accessible knowledge base for creating your own solutions. If you are new to Java EE enterprise application development, this chapter is a good place to start. Here you will review development basics, learn about the Java EE architecture and APIs, become acquainted with important terms and concepts, and nd out how to approach Java EE application programming, assembly, and deployment.

Java EE Application ModelThe Java EE application model begins with the Java programming language and the Java virtual machine. The proven portability, security, and developer productivity they provide forms the basis of the application model. Java EE is designed to support applications that implement enterprise services for customers, employees, suppliers, partners, and others who make demands on or contributions to the enterprise. Such applications are inherently complex, potentially accessing data from a variety of sources and distributing applications to a variety of clients. To better control and manage these applications, the business functions to support these various users are conducted in the middle tier. The middle tier represents an environment that is closely controlled by an enterprises information technology department. The middle tier is typically run on dedicated server hardware and has access to the full services of the enterprise. The Java EE application model denes an architecture for implementing services as multitier applications that deliver the scalability, accessibility, and manageability needed by enterprise-level applications. This model partitions the work needed to implement a multitier service into two parts: the business and presentation logic to be implemented by the developer, and the standard system services provided by the Java EE platform. The developer can rely on the platform to provide solutions for the hard systems-level problems of developing a multitier service.

DISTRIBUTED MULTITIERED APPLICATIONS

3

Distributed Multitiered ApplicationsThe Java EE 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 Java EE application are installed on different machines depending on the tier in the multitiered Java EE environment to which the application component belongs. Figure 11 shows two multitiered Java EE applications divided into the tiers described in the following list. The Java EE application parts shown in Figure 11 are presented in Java EE Components (page 4). Client-tier components run on the client machine. Web-tier components run on the Java EE server. Business-tier components run on the Java EE server. Enterprise information system (EIS)-tier software runs on the EIS server.

Although a Java EE application can consist of the three or four tiers shown in Figure 11, Java EE multitiered applications are generally considered to be three-tiered applications because they are distributed over three locations: client machines, the Java EE 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.Java EE Application 1 Java EE Application 2 Client Machine

Client Tier Application Client Dynamic HTML Pages

JSP Pages

Web Tier Java EE Server

Enterprise Beans

Enterprise Beans

Business Tier

Database

Database

EIS Tier

Database Server

Figure 11 Multitiered Applications

4

OVERVIEW

SecurityWhile other enterprise application models require platform-specic security measures in each application, the Java EE security environment enables security constraints to be dened at deployment time. The Java EE platform makes applications portable to a wide variety of security implementations by shielding application developers from the complexity of implementing security features. The Java EE platform provides standard declarative access control rules that are dened by the developer and interpreted when the application is deployed on the server. Java EE also provides standard login mechanisms so application developers do not have to implement these mechanisms in their applications. The same application works in a variety of different security environments without changing the source code.

Java EE ComponentsJava EE applications are made up of components. A Java EE component is a self-contained functional software unit that is assembled into a Java EE application with its related classes and les and that communicates with other components. The Java EE specication denes the following Java EE components: Application clients and applets are components that run on the client. Java Servlet, JavaServer Faces, 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. Java EE components are written in the Java programming language and are compiled in the same way as any program in the language. The difference between Java EE components and standard Java classes is that Java EE components are assembled into a Java EE application, are veried to be well formed and in compliance with the Java EE specication, and are deployed to production, where they are run and managed by the Java EE server.

Java EE ClientsA Java EE client can be a web client or an application client.

DISTRIBUTED MULTITIERED APPLICATIONS

5

Web ClientsA 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 Java EE server, where they can leverage the security, speed, services, and reliability of Java EE server-side technologies.

AppletsA 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 le 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 les 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 ClientsAn 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. 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. Application clients written in languages other than Java can interact with Java EE 5 servers, enabling the Java EE 5 platform to interoperate with legacy systems, clients, and non-Java languages.

6

OVERVIEW

The JavaBeans Component ArchitectureThe server and client tiers might also include components based on the JavaBeans component architecture (JavaBeans components) to manage the data ow between an application client or applet and components running on the Java EE server, or between server components and a database. JavaBeans components are not considered Java EE components by the Java EE specication. 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.

Java EE Server CommunicationsFigure 12 shows the various elements that can make up the client tier. The client communicates with the business tier running on the Java EE 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 Java EE 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 off-loading 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.

> Application Client and Optional JavaBeans Components

> Web Browser, Web Pages, Applets, and Optional JavaBeans Components Client Tier

Web Tier

Business Tier

Java EE Server

Figure 12 Server Communication

DISTRIBUTED MULTITIERED APPLICATIONS

7

Web ComponentsJava EE web components are either servlets or pages created using JSP technology (JSP pages) and/or JavaServer Faces technology. 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. JavaServer Faces technology builds on servlets and JSP technology and provides a user interface component framework for web applications. Static HTML pages and applets are bundled with web components during application assembly but are not considered web components by the Java EE specication. Server-side utility classes can also be bundled with web components and, like HTML pages, are not considered web components. As shown in Figure 13, 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 ComponentsBusiness code, which is logic that solves or meets the needs of a particular business domain such as banking, retail, or nance, is handled by enterprise beans running in the business tier. Figure 14 shows how an enterprise bean receives data from client programs, processes it (if necessary), and sends it to the enterprise 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.

Enterprise Information System TierThe 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, Java EE application components might need access to enterprise information systems for database connectivity.

8

OVERVIEW

> Application Client and Optional JavaBeans Components

> Web Browser, Web Pages, Applets, and Optional JavaBeans Components Client Tier

JavaBeans Components (Optional)

JSP Pages Servlets

Web Tier

Business Tier

Java EE Server

Figure 13 Web Tier and Java EE Applications

> Application Client and Optional JavaBeans Components

> Web Browser, Web Pages, Applets, and Optional JavaBeans Components Client Tier

JavaBeans Components (Optional)

JSP Pages Web Tier Servlets

Java Persistence Entities Session Beans Message-Driven Beans

Business Tier

Java EE Server

Database and Legacy Systems

EIS Tier

Figure 14 Business and EIS Tiers

Java EE ContainersNormally, 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 Java EE architecture makes Java EE

JAVA EE CONTAINERS

9

applications easy to write because business logic is organized into reusable components. In addition, the Java EE 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 ServicesContainers are the interface between a component and the low-level platformspecic functionality that supports the component. Before a web, enterprise bean, or application client component can be executed, it must be assembled into a Java EE module and deployed into its container. The assembly process involves specifying container settings for each component in the Java EE application and for the Java EE application itself. Container settings customize the underlying support provided by the Java EE server, including services such as security, transaction management, Java Naming and Directory Interface (JNDI) lookups, and remote connectivity. Here are some of the highlights: The Java EE security model lets you congure a web component or enterprise bean so that system resources are accessed only by authorized users. The Java EE 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 unied interface to multiple naming and directory services in the enterprise so that application components can access these services. The Java EE 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 Java EE architecture provides congurable services, application components within the same Java EE 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.

10

OVERVIEW

The container also manages noncongurable services such as enterprise bean and servlet life cycles, database connection resource pooling, data persistence, and access to the Java EE platform APIs (see Java EE 5 APIs, page 18).

Container TypesThe deployment process installs Java EE application components in the Java EE containers as illustrated in Figure 15.

Application Client Application Client Container Web Browser

Client Machine

Servlet

JSP Page

Web Container Java EE Server

Enterprise Bean

Enterprise Bean

EJB Container

Database

Figure 15 Java EE Server and Containers

Java EE server: The runtime portion of a Java EE product. A Java EE server provides EJB and web containers. Enterprise JavaBeans (EJB) container: Manages the execution of enterprise beans for Java EE applications. Enterprise beans and their container run on the Java EE server. Web container: Manages the execution of JSP page and servlet components for Java EE applications. Web components and their container run on the Java EE 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 Plug-in running on the client together.

WEB SERVICES SUPPORT

11

Web Services SupportWeb services are web-based enterprise applications that use open, XML-based standards and transport protocols to exchange data with calling clients. The Java EE 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 Java EE 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 Java EE 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 les, 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.

XMLXML 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

12

OVERVIEW

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.

SOAP Transport ProtocolClient 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: Denes 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 applicationdened data types within the message Denes an XML-based convention for representing the request to the remote service and the resulting response

WSDL Standard FormatThe 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 specication of a web service that uses remote procedure calls to communicate with clients.

PACKAGING APPLICATIONS

13

UDDI and ebXML Standard FormatsOther 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.

Java EE Application Assembly and DeploymentA Java EE application is packaged into one or more standard units for deployment to any Java EE platform-compliant system. Each unit contains: A functional component or components (enterprise bean, JSP page, servlet, applet, etc.) An optional deployment descriptor that describes its content Once a Java EE unit has been produced, it is ready to be deployed. Deployment typically involves using a platforms deployment tool to specify location-specic information, such as a list of local users that can access it and the name of the local database. Once deployed on a local platform, the application is ready to run.

Packaging ApplicationsA Java EE application is delivered in an Enterprise Archive (EAR) le, a standard Java Archive (JAR) le with an .ear extension. Using EAR les and modules makes it possible to assemble a number of different Java EE applications using some of the same components. No extra coding is needed; it is only a matter of assembling (or packaging) various Java EE modules into Java EE EAR les. An EAR le (see Figure 16) contains Java EE 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 Java EE server reads the deployment descriptor and acts upon the application, module, or component accordingly.

14

OVERVIEW

There are two types of deployment descriptors: Java EE and runtime. A Java EE deployment descriptor is dened by a Java EE specication and can be used to congure deployment settings on any Java EE-compliant implementation. A runtime deployment descriptor is used to congure Java EE implementation-specic parameters. For example, the Sun Java System Application Server Platform Edition 9 runtime deployment descriptor contains information such as the context root of a web application, the mapping of portable names of an applications resources to the servers resources, and Application Server implementation-specic 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 Java EE deployment descriptor.

Assembly Root

META-INF

Web Module

EJB Module

Application Client Module

Resource Adapter Module

application.xml sun-application.xml

Figure 16 EAR File Structure

A Java EE module consists of one or more Java EE 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 Java EE module without an application deployment descriptor can be deployed as a stand-alone module. The four types of Java EE modules are as follows: EJB modules, which contain class les for enterprise beans and an EJB deployment descriptor. EJB modules are packaged as JAR les with a .jar extension. Web modules, which contain servlet class les, JSP les, supporting class les, GIF and HTML les, and a web application deployment descriptor. Web modules are packaged as JAR les with a .war (Web ARchive) extension.

DEVELOPMENT ROLES

15

Application client modules, which contain class les and an application client deployment descriptor. Application client modules are packaged as JAR les 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 23) for a particular EIS. Resource adapter modules are packaged as JAR les with an .rar (resource adapter archive) extension.

Development RolesReusable 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 rst two roles involve purchasing and installing the Java EE product and tools. After software is purchased and installed, Java EE 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 le that is the input for a subsequent role. For example, in the application component development phase, an enterprise bean software developer delivers EJB JAR les. In the application assembly role, another developer combines these EJB JAR les into a Java EE application and saves it in an EAR le. In the application deployment role, a system administrator at the customer site uses the EAR le to install the Java EE application into a Java EE 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.

Java EE Product ProviderThe Java EE product provider is the company that designs and makes available for purchase the Java EE platform APIs, and other features dened in the Java EE specication. Product providers are typically application server vendors who implement the Java EE platform according to the Java EE 5 Platform specication.

16

OVERVIEW

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

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

Enterprise Bean DeveloperAn enterprise bean developer performs the following tasks to deliver an EJB JAR le that contains the enterprise bean(s): Writes and compiles the source code Species the deployment descriptor Packages the .class les and deployment descriptor into the EJB JAR le

Web Component DeveloperA web component developer performs the following tasks to deliver a WAR le containing the web component(s): Writes and compiles servlet source code Writes JSP, JavaServer Faces, and HTML les Species the deployment descriptor Packages the .class, .jsp, and.html les and deployment descriptor into the WAR le

Application Client DeveloperAn application client developer performs the following tasks to deliver a JAR le containing the application client: Writes and compiles the source code Species the deployment descriptor for the client Packages the .class les and deployment descriptor into the JAR le

DEVELOPMENT ROLES

17

Application AssemblerThe application assembler is the company or person who receives application modules from component providers and assembles them into a Java EE application EAR le. 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 le containing the Java EE application: Assembles EJB JAR and WAR les created in the previous phases into a Java EE application (EAR) le Species the deployment descriptor for the Java EE application Veries that the contents of the EAR le are well formed and comply with the Java EE specication

Application Deployer and AdministratorThe application deployer and administrator is the company or person who congures and deploys the Java EE application, administers the computing and networking infrastructure where Java EE applications run, and oversees the runtime environment. Duties include such things as setting transaction controls and security attributes and specifying connections to databases. During conguration, 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-specic classes and interfaces. A deployer or system administrator performs the following tasks to install and congure a Java EE application: Adds the Java EE application (EAR) le created in the preceding phase to the Java EE server Congures the Java EE application for the operational environment by modifying the deployment descriptor of the Java EE application Veries that the contents of the EAR le are well formed and comply with the Java EE specication Deploys (installs) the Java EE application EAR le into the Java EE server

18

OVERVIEW

Java EE 5 APIsFigure 17 illustrates the availability of the Java EE 5 platform APIs in each Java EE container type. The following sections give a brief summary of the technologies required by the Java EE platform, and the APIs used in Java EE applications.Applet Container AppletJAX-RPC JAXR JAX-WS

HTTP SSL

Web Container JSPWS Metadata Web Services JACC

EJB Container EJBWS Metadata Web Services JACC StAX Java Persistence JTA Connectors JMS Management JAX-RPC JAXR JAX-WS Java Mail JAF Java Mail JAF

ServletJTSL JavaServer Faces StAX Java Persistence JTA Connectors JMS Management

J2SE Application Client Container Application ClientWS Metadata Web Services JMS StAX Java Persistence Management JAX-RPC JAXR JAX-WS

HTTP SSL

SAAJ

SAAJ

J2SE

J2SE

SAAJ

J2SENew in Java EE 5

Database

Figure 17 Java EE Platform APIs

Enterprise JavaBeans TechnologyAn Enterprise JavaBeans (EJB) component, or enterprise bean, is a body of code having elds 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 Java EE server. There are two kinds of enterprise beans: session beans and message-driven beans. A session bean represents a transient conversation with a client. When the client nishes executing, the session bean and its data are gone. A messagedriven bean combines features of a session bean and a message listener, allowing a business component to receive messages asynchronously. Commonly, these are Java Message Service (JMS) messages.

JAVA EE 5 APIS

19

In Java EE 5, entity beans have been replaced by Java persistence API entities. An entity represents persistent data stored in one row of a database table. If the client terminates, or if the server shuts down, the persistence manager ensures that the entity data is saved.

Java Servlet TechnologyJava servlet technology lets you dene HTTP-specic 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 TechnologyJavaServer 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.

JavaServer Pages Standard Tag LibraryThe 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 ow control, tags for manipulating XML documents, internationalization tags, tags for accessing databases using SQL, and commonly used functions.

20

OVERVIEW

JavaServer FacesJavaServer 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 exible 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 st