The Java™ Web Services Tutorial

The Java™ Web Services Tutorial Eric Armstrong Stephanie Bodoff Debbie Carson Maydene Fisher Scott Fordin Dale Green Kim Haase Eric Jendrock February 20, 2003Copyright © 2003 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, U.S.A. All rights reserved.U.S. Government Rights - Commercial software. Government users are subject to the Sun Microsystems, Inc. standard license agreement and applicable provisions of the FAR and its supple- ments. This distribution may include materials developed by third parties. Sun, Sun Microsystems, the Sun logo, Java, J2EE, JavaServer Pages, Java Naming and Directory Inter- face, JSP, J2EE, J2SE 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, Fads, sam- ples) is provided under this License. Products covered by and information contained in this service manual are controlled by U.S. Export Con- trol laws and may be subject to the export or import laws in other countries. Nuclear, missile, chemical biological weapons or nuclear maritime end uses or end users, whether direct or indirect, are strictly pro- hibited. Export or reexport to countries subject to U.S. embargo or to entities identified on U.S. export exclusion lists, including, but not limited to, the denied persons and specially designated nationals lists is strictly prohibited. DOCUMENTATION IS PROVIDED "AS IS" AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MER- CHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID. Copyright © 2003 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, États- Unis. Tous droits réservés. Droits du gouvernement américain, utlisateurs gouvernmentaux - logiciel commercial. Les utilisateurs gouvernmentaux sont soumis au contrat de licence standard de Sun Micro- systems, 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, JavaServer Pages, Java Naming and Directory Interface, JSP, J2EE, J2SE et le logo Java Coffee Cup sont des marques de fabrique ou des marques déposées de Sun Microsystems, Inc. aux États-Unis et dans d’autres pays. A moins qu’autrement autorisé, le code de logiciel en tous les matériaux techniques dans le présent (arti- cles y compris, FAQs, échantillons) est fourni sous ce permis. Les produits qui font l’objet de ce manuel d’entretien et les informations qu’il contient sont régis par la législation américaine en matière de contrôle des exportations et peuvent être soumis au droit d’autres pays dans le domaine des exportations et importations. Les utilisations finales, ou utilisateurs finaux, pour des armes nucléaires, des missiles, des armes biologiques et chimiques ou du nucléaire maritime, directe- ment ou indirectement, sont strictement interdites. Les exportations ou réexportations vers des pays sous embargo des États-Unis, ou vers des entités figurant sur les listes d’exclusion d’exportation américaines, y compris, mais de manière non exclusive, la liste de personnes qui font objet d’un ordre de ne pas partic- iper, d’une façon directe ou indirecte, aux exportations des produits ou des services qui sont régi par la législation américaine en matière de contrôle des exportations ("U .S. Commerce Department’s Table of Denial Orders "et la liste de ressortissants spécifiquement désignés ("U.S. Treasury Department of Spe- cially Designated Nationals and Blocked Persons "),, sont rigoureusement interdites. LA DOCUMENTATION EST FOURNIE "EN L’ÉTAT" ET TOUTES AUTRES CONDITIONS, DEC- LARATIONS ET GARANTIES EXPRESSES OU TACITES SONT FORMELLEMENT EXCLUES, DANS LA MESURE AUTORISEE PAR LA LOI APPLICABLE, Y COMPRIS NOTAMMENT TOUTE GARANTIE IMPLICITE RELATIVE A LA QUALITE MARCHANDE, A L’APTITUDE A UNE UTILISATION PARTICULIERE OU A L’ABSENCE DE CONTREFAÇON.Contents About This Tutorial. . . . . . . . . . . . . . . . . . . . . . . . . . . .xi Who Should Use This Tutorial xi How to Read This Tutorial xi About the Examples xiii How to Print This Tutorial xiv Typographical Conventions xv Chapter 1: Introduction to Web Services . . . . . . . . . . . . . . . . . . 1 The Role of XML and the Java™ Platform 2 What Is XML? 3 Overview of the Java APIs for XML 6 JAXP 7 JAXB 15 JAX-RPC 20 JAXM 27 JAXR 34 Sample Scenario 37 Chapter 2: Understanding XML . . . . . . . . . . . . . . . . . . . . . . . . . 41 Introduction to XML 41 XML and Related Specs: Digesting the Alphabet Soup 51 Designing an XML Data Structure 63 Chapter 3: Getting Started With Tomcat . . . . . . . . . . . . . . . . . . 69 Setting Up 69 Quick Overview 72 Creating the Getting Started Application 73 Building the Getting Started Application Using Ant 77 iiiiv CONTENTS Deploying the Application 80 Running the Getting Started Application 82 Using admintool 83 Modifying the Application 85 Common Problems and Their Solutions 87 Further Information 91 Chapter 4: Web Applications . . . . . . . . . . . . . . . . . . . . . . . . . . .93 Web Application Life Cycle 94 Web Application Archives 96 Configuring Web Applications 98 Installing Web A 102 Deploying Web Applications 103 Listing Installed and Deployed Web Applications 104 Running Web Applications 105 Updating Web A 105 Removing Web Applications 107 Undeploying Web A 107 Internationalizing and Localizing Web Applications 108 Accessing Databases from Web Applications 109 Further Information 113 Chapter 5: Java API for XML Processing . . . . . . . . . . . . . . . . .115 The JAXP APIs 115 An Overview of the Packages 116 The Simple API for XML (SAX) APIs 117 The Document Object Model (DOM) APIs 120 The XML Stylesheet Language for Transformation (XSLT) APIs 122 Compiling and Running the Programs 123 Where Do You Go from Here? 123 Chapter 6: Simple API for XML . . . . . . . . . . . . . . . . . . . . . . . . .125 When to Use SAX 126 Writing a Simple XML File 127 Echoing an XML File with the SAX Parser 132 Adding Additional Event Handlers 151 Handling Errors with the Nonvalidating Parser 155 Substituting and Inserting Text 163 Creating a Document Type Definition (DTD) 168CONTENTS v DTD’s Effect on the Nonvalidating Parser 173 Defining Attributes and Entities in the DTD 177 Referencing Binary Entities 184 Choosing your Parser Implementation 186 Using the Validating Parser 187 Defining Parameter Entities and Conditional Sections 193 Parsing the Parameterized DTD 197 Handling Lexical Events 200 Using the DTDHandler and EntityResolver 207 Further Information 209 Chapter 7: Document Object Model . . . . . . . . . . . . . . . . . . . 211 When to Use DOM 212 Reading XML Data into a DOM 218 Displaying a DOM Hierarchy 225 Examining the Structure of a DOM 241 Constructing a User-Friendly JTree from a DOM 252 Creating and Manipulating a DOM 268 Using Namespaces 277 Validating with XML Schema 280 Further Information 286 Chapter 8: XML Stylesheet Language for Transformations . . 289 Introducing XSLT and XPath 290 Choosing the Transformation Engine 291 How XPath Works 294 Writing Out a DOM as an XML File 305 Generating XML from an Arbitrary Data Structure 312 Transforming XML Data with XSLT 327 Transforming from the Command Line 351 Concatenating Transformations with a Filter Chain 354 Further Information 361 Chapter 9: Binding XML Schema to Java Classes with JAXB 363 JAXB Architecture 364 XML Schemas 376 Representing XML Content 380 Binding XML Schemas 381 Customizing JAXB Bindings 384vi CONTENTS What is Not Supported 386 JAXB APIs and Tools 386 Chapter 10: Using JAXB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .387 General Usage Instructions 388 Basic Sample Applications 409 Customizing JAXB Bindings 422 Chapter 11: Building Web Services With JAX-RPC . . . . . . . . . .455 A Simple Example: HelloWorld 456 Types Supported By JAX-RPC 467 A Dynamic Proxy Client Example 470 A Dynamic Invocation Interface (DII) Client Example 471 The wscompile Tool 474 The wsdeploy Tool 477 Advanced Topics for wscompile and wsdeploy 480 Further Information 481 Chapter 12: Web Services Messaging with JAXM . . . . . . . . . .483 The Structure of the JAXM API 484 Overview of JAXM 485 Running the Samples 495 Tutorial 499 Code Examples 521 Further Information 535 Chapter 13: Publishing and Discovering Web Services with JAXR 537 Overview of JAXR 538 Implementing a JAXR Client 541 Running the Client Examples 562 Further Information 570 Chapter 14: Java Servlet Technology . . . . . . . . . . . . . . . . . . . .571 What is a Servlet? 571 The Example Servlets 572 Servlet Life Cycle 574CONTENTS vii Sharing Information 577 Initializing a Servlet 581 Writing Service Methods 582 Filtering Requests and Responses 587 Invoking Other Web Resources 594 Accessing the Web Context 598 Maintaining Client State 599 Finalizing a Servlet 602 Further Information 605 Chapter 15: JavaServer Pages Technology . . . . . . . . . . . . . . . 607 What Is a JSP Page? 607 The Example JSP Pages 610 The Life Cycle of a JSP Page 612 Initializing and Finalizing a JSP Page 615 Creating Static Content 615 Creating Dynamic Content 616 Including Content in a JSP Page 622 Transferring Control to Another Web Component 624 Including an Applet 624 JavaBeans Components in JSP Pages 627 Extending the JSP Language 635 Further Information 636 Chapter 16: Custom Tags in JSP Pages . . . . . . . . . . . . . . . . . . . 637 What Is a Custom Tag? 638 The Example JSP Pages 638 Using Tags 641 Defining Tags 645 Examples 661 Chapter 17: JavaServer Pages Standard Tag Library . . . . . . . 673 The Example JSP Pages 674 Using JSTL 674 Expression Language Support 677 Core Tags 683 XML Tags 689 Internationalizatio