The Java™ Web Services Tutorial

The Java™ Web Services Tutorial Eric Armstrong Stephanie Bodoff Debbie Carson Maydene Fisher Dale Green Kim Haase February 4, 2002iii Copyright © 2002 by Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California 94303 U.S.A. All rights reserved. RESTRICTED RIGHTS LEGEND: Use, duplication, or disclosure by the United States Government is subject to the restrictions set forth in DFARS 252.227-7013(c)(1)(iii) and FAR 52.227-19. The release described in this book may be protected by one or more U.S. patents, foreign patents, or pending applica- tions. Sun, Sun Microsystems, Sun Microsystems Computer Corporation, the Sun logo, the Sun Microsystems Computer Corporation logo, Java, JavaSoft, Java Software, JavaScript, JDBC, JDBC Compliant, JavaOS, JavaBeans, Enterprise JavaBeans, JavaServer, JavaServer Pages, J2EE, J2SE, JavaMail, Java Naming and Directory Interface, EJB, and JSP ®are trademarks or registered trademarks of Sun Microsystems, Inc. UNIX is a registered trademark in the United States and other countries, exclusively licensed through X/Open Company, Ltd. All other product names mentioned herein are the trademarks of their respective owners. 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.ivContents Preface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv Who Should Use This Tutorial xvi About the Examples xvi Prerequisites for the Examples xvi Running the Examples xvi Related Information xix How to Print This Tutorial xx Typographical Conventions xx Chapter 1: Introduction to Web Services . . . . . . . . . . . . . . . . . . . . 1 The Role of XML and the Java™ Platform 2 What Is XML? 4 What Makes XML Portable? 5 Overview of the Java APIs for XML 6 JAXP 7 The SAX API 8 The DOM API 10 The XSLT API 13 JAX-RPC 16 Using JAX-RPC 16 JAXM 17 Getting a Connection 19 Creating a Message 21 Populating a Message 21 Sending a Message 24 JAXR 24 Using JAXR 25 Sample Scenario 27 Scenario 28 iiiiv Conclusion 29 Chapter 2: Understanding XML . . . . . . . . . . . . . . . . . . . . . . . . . . .31 Introduction to XML 31 What Is XML? 32 Why Is XML Important? 37 How Can You Use XML? 39 XML and Related Specs: Digesting the Alphabet Soup 42 Basic Standards 43 Schema Standards 45 Linking and Presentation Standards 48 Knowledge Standards 49 Standards That Build on XML 50 Summary 52 Designing an XML Data Structure 53 Saving Yourself Some Work 53 Attributes and Elements 53 Normalizing Data 56 Normalizing DTDs 57 Chapter 3: Getting Started With Tomcat . . . . . . . . . . . . . . . . . . . .59 Setting Up 60 Getting the Example Code 60 Checking the Environment Variables 61 Creating the Getting Started Application 61 The Converter Class 61 The Web Client 62 Building and Deploying the Getting Started Application Using Ant 64 Setting the CLASSPATH 64 Creating the Build File for Ant 64 Compiling the Source Files 66 Deploying the Application 66 Running the Getting Started Application 67 Starting Tomcat 67 Running the Web Client 67 Shutting Down Tomcat 68 Modifying the Application 68 Modifying a Class File 69 Modifying the Web Client 69v Reloading the Application 69 Common Problems and Their Solutions 70 Compilation Errors 70 Deployment Errors 71 Chapter 4: Java™ API for XML Processing. . . . . . . . . . . . . . . . . . 73 The JAXP APIs 74 An Overview of the Packages 74 The Simple API for XML (SAX) APIs 75 The SAX Packages 78 The Document Object Model (DOM) APIs 78 The DOM Packages 80 The XML Stylesheet Language for Transformation (XSLT) APIs 81 The XSLT Packages 82 Where Do You Go from Here? 82 Chapter 5: Simple API for XML. . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 Writing a Simple XML File 86 Creating the File 87 Writing the Declaration 87 Adding a Comment 87 Adding Nested Elements 89 Adding HTML-Style Text 89 Adding an Empty Element 90 The Finished Product 91 Echoing an XML File with the SAX Parser 91 Creating the Skeleton 92 Importing Classes 93 Setting up for I/O 93 Implementing the ContentHandler Interface 94 Setting up the Parser 95 Writing the Output 96 Spacing the Output 97 Handling Content Events 97 Compiling and Running the Program 100 Command Scripts 100 Checking the Output 101 Identifying the Events 101 Compressing the Output 103vi Inspecting the Output 105 Documents and Data 106 Adding Additional Event Handlers 107 Identifying the Document’s Location 107 Handling Processing Instructions 108 Summary 110 Handling Errors with the Nonvalidating Parser 111 Substituting and Inserting Text 120 Handling Special Characters 120 Using an Entity Reference in an XML Document 121 Handling Text with XML-Style Syntax 122 Handling CDATA and Other Characters 124 Creating a Document Type Definition (DTD) 124 Basic DTD Definitions 124 Defining Text and Nested Elements 126 Limitations of DTDs 127 Special Element Values in the DTD 128 Referencing the DTD 128 DTD’s Effect on the Nonvalidating Parser 129 Tracking Ignorable Whitespace 130 Cleanup 132 Documents and Data 132 Empty Elements, Revisited 133 Defining Attributes and Entities in the DTD 133 Defining Attributes in the DTD 133 Defining Entities in the DTD 135 Echoing the Entity References 137 Additional Useful Entities 138 Referencing External Entities 138 Echoing the External Entity 139 Summarizing Entities 140 Referencing Binary Entities 140 Using a MIME Data Type 140 The Alternative: Using Entity References 142 Using the Validating Parser 142 Configuring the Factory 142 Changing the Environment Variable 143 Experimenting with Validation Errors 143 Error Handling in the Validating Parser 145 Defining Parameter Entities and Conditional Sections 146 Creating and Referencing a Parameter Entity 146vii Conditional Sections 148 Parsing the Parameterized DTD 149 DTD Warnings 151 Handling Lexical Events 152 How the LexicalHandler Works 153 Working with a LexicalHandler 153 Using the DTDHandler and EntityResolver 159 The DTDHandler API 159 The EntityResolver API 161 Chapter 6: Document Object Model . . . . . . . . . . . . . . . . . . . . . 163 Reading XML Data into a DOM 164 Creating the Program 164 Additional Information 168 Looking Ahead 171 Displaying a DOM Hierarchy 171 Echoing Tree Nodes 171 Convert DomEcho to a GUI App 171 Create Adapters to Display the DOM in a JTree 177 Finishing Up 187 Examining the Structure of a DOM 187 Displaying A Simple Tree 187 Displaying a More Complex Tree 190 Finishing Up 194 Constructing a User-Friendly JTree from a DOM 195 Compressing the Tree View 195 Acting on Tree Selections 200 Handling Modifications 209 Finishing Up 209 Creating and Manipulating a DOM 209 Obtaining a DOM from the Factory 209 Normalizing the DOM 213 Other Operations 214 Finishing Up 215 Using Namespaces 215 Defining a Namespace 216 Referencing a Namespace 217 Defining a Namespace Prefix 217viii Chapter 7: XML Stylesheet Language for Transformations . . . .221 Introducing XSLT and XPath 222 The XSLT Packages 222 How XPath Works 223 Summary 232 Writing Out a DOM as an XML File 232 Reading the XML 232 Creating a Transformer 234 Writing the XML 236 Writing Out a Subtree of the DOM 237 Summary 238 Generating XML from an Arbitrary Data Structure 238 Creating a Simple File 239 Creating a Simple Parser 241 Modifying the Parser to Generate SAX Events 244 Using the Parser as a SAXSource 250 Doing the Conversion 252 Transforming XML Data with XSLT 252 Defining an Ultra-Simple article Document Type 253 Creating a Test Document 255 Writing an XSLT Transform 256 Processing the Basic Structure Elements 257 Writing the Basic Program 261 Trimming the Whitespace 263 Processing the Remaining Structure Elements 266 Process Inline (Content) Elements 271 Printing the HTML 275 What Else Can XSLT Do? 275 Concatenating XSLT Transformations with a Filter Chain 278 Writing the Program 278 Understanding How it Works 281 Testing the Program 283 Conclusion 285 Chapter 8: Java™ API for XML Messaging . . . . . . . . . . . . . . . . .287 Overview of JAXM 288 Messages 288 Connections 291 Messaging Providers 293 Running the Samples 295