The Java Web Services Tutorial

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

About This Tutorial. . . . . . . . . . . . . . . . . . . . . . . . . . xxiii
Who Should Use This Tutorial xxiii
How to Read This Tutorial xxiii
About the Examples xxv
Prerequisites for the Examples xxv
How to Print This Tutorial xxvii
Typographical Conventions xxviii
Chapter 1: Introduction to Web Services . . . . . . . . . . . . . . . . . . 1
The Role of XML and the Java Platform 2
What Is XML? 3
What Makes XML Portable? 5
Overview of the Java APIs for XML 6
JAXP 7
The SAX API 7
The DOM API 10
The XSLT API 12
JAXB 15
JAXB Binding Process 16
Validation 17
Representing XML Content 17
Customizing JAXB Bindings 17
Example 18
JAX-RPC 20
Overview of JAX-RPC 21
Using JAX-RPC 23
Creating a Web Service 23
Coding a Client 26
Invoking a Remote Method 27
SAAJ 27
Getting a Connection 28
Creating a Message 28
Populating a Message 29
Sending a Message 31
JAXR 31
Using JAXR 32
Sample Scenario 34
Scenario 34
Conclusion 36
Chapter 2: Introduction to Interactive Web Application Technologies
37
Interactive Web Application Architectures 39
Java Servlet Technology 40
JavaServer Pages Technology 41
JavaServer Pages Standard Tag Library 43
JavaServer Faces Technology 44
Chapter 3: Getting Started With Tomcat . . . . . . . . . . . . . . . . . .49
Setting Up 49
Getting the Example Code 49
Setting the PATH Variable 52
Modifying the Build Properties File 52
Running the Application 53
Creating a Simple Web Application 54
Creating the JavaBeans Component 54
Creating a Web Client 55
Creating the Build Properties File 57
Creating the Build File 57
Creating the Deployment Descriptor 59
Building the Example Application 60
Installing the Web Application 62
Running the Getting Started Application 63
Modifying the Application 65
Modifying a JavaBeans Component 66
Modifying the Web Client 66
Common Problems and Their Solutions 66
Errors Starting Tomcat 67
Compilation Errors 67
Installation and Deployment Errors 69
Chapter 4: Getting Started with Web Applications . . . . . . . . . 73
Web Application Life Cycle 74
Web Applications 76
Packaging Web Applications 77
Installing Web Applications 78
Deploying Web Applications 80
Listing Installed and Deployed Web Applications 81
Updating Web Applications 82
Reloading Web Applications 82
Redeploying Web Applications 82
Debugging Web Applications 83
Using the Server Log 83
Using a Debugger 84
Removing Web Applications 84
Undeploying Web Applications 84
Configuring Web Applications 85
Prolog 85
Mapping URLs to Web Components 85
Declaring Welcome Files 86
Setting Initialization Parameters 87
Specifying Error Mappings 88
Declaring References to Environment Entries, Resource Environment
Entries, or Resources 88
Duke’s Bookstore Examples 88
Accessing Databases from Web Applications 89
Installing and Starting the PointBase Database Server 90
Populating the Example Database 91
Defining a Data Source in Tomcat 92
Configuring the Web Application to Reference a Resource 93
Mapping the Web Application Resource Reference to a Data Source 94
Further Information 94
Chapter 5: Understanding XML . . . . . . . . . . . . . . . . . . . . . . . . . 95
Introduction to XML 95
What Is XML? 95
Why Is XML Impotant? 100
How Can You Use XML? 103
XML and Related Specs: Digesting the Alphabet Soup 105
Basic Standards 106
Schema Standards 110
Linking and Presentation Standards 112
Knowledge Standards 113
Standards That Build on XML 115
Summary 117
Generating XML Data 117
Writing a Simple XML File 117
Defining the Root Element 119
Writing Processing Instructions 122
Introducing an Error 124
Substituting and Inserting Text 125
Creating a Document Type Definition 128
Documents and Data 133
Defining Attributes and Entities in the DTD 134
Referencing Binary Entities 140
Defining Parameter Entities and Conditional Sections 142
Resolving A Naming Conflict 146
Using Namespaces 147
Designing an XML Data Structure 150
Saving Yourself Some Work 150
Attributes and Elements 151
Normalizing Data 153
Normalizing DTDs 154
Summary 155
Chapter 6: Java API for XML Processing . . . . . . . . . . . . . . . . .157
The JAXP APIs 157
An Overview of the Packages 158
The Simple API for XML (SAX) APIs 159
The SAX Packages 162
The Document Object Model (DOM) APIs 162
The DOM Packages 164
The XML Stylesheet Language for Transformation (XSLT) APIs 165
The XSLT Packages 166
Compiling and Running the Programs 166
Where Do You Go from Here? 166
Chapter 7: Simple API for XML . . . . . . . . . . . . . . . . . . . . . . . . . 169
When to Use SAX 170
Echoing an XML File with the SAX Parser 171
Creating the Skeleton 171
Imorting Classes 172
Setting up for I/O 172
Implementing the ContentHandler Interface 173
Setting up the Parser 174
Writing the Output 175
Spacing the Output 176
Handling Content Events 176
Compiling and Running the Program 181
Checking the Output 182
Identifying the Events 183
Compressing the Output 185
Inspecting the Output 187
Documents and Data 188
Adding Additional Event Handlers 189
Identifying the Document’s Location 189
Handling Processing Instructions 191
Summary 192
Handling Errors with the Nonvalidating Parser 192
Displaying Special Characters and CDATA 200
Handling Special Characters 200
Handling Text with XML-Style Syntax 201
Handling CDATA and Other Characters 202
Parsing with a DTD 203
DTD’s Effect on the Nonvalidating Parser 203
Tracking Ignorable Whitespace 204
Cleanup 206
Empty Elements, Revisited 206
Echoing Entity References 206
Echoing the External Entity 207
Summarizing Entities 208
Choosing your Parser Implementation 208
Using the Validating Parser 208
Configuring the Factory 209
Validating with XML Schema 209
Experimenting with Validation Errors 212
Error Handling in the Validating Parser 215
Parsing a Parameterized DTD 215
DTD Warnings 216
Handling Lexical Events 217
How the LexicalHandler Works 218
Working with a LexicalHandler 218
Using the DTDHandler and EntityResolver 224
The DTDHandler API 224
The EntityResolver API 226
Further Information 226
Chapter 8: Document Object Model . . . . . . . . . . . . . . . . . . . .227
When to Use DOM 228
Documents Versus Data 228
Mixed Content Model 229
A Simpler Model 230
Increasing the Complexity 231
Choosing Your Model 233
Reading XML Data into a DOM 234
Creating the Program 234
Additional Information 239
Looking Ahead 241
Displaying a DOM Hierarchy 241
Echoing Tree Nodes 241
Convert DomEcho to a GUI App 241
Create Adapters to Display the DOM in a JTree 247
Finishing Up 257
Examining the Structure of a DOM 257
Displaying A Simple Tree 258
Displaying a More Complex Tree 260
Finishing Up 267
Constructing a User-Friendly JTree from a DOM 267
Compressing the Tree View 267
Acting on Tree Selections 273
Handling Modifications 283
Finishing Up 283
Creating and Manipulating a DOM 283
Obtaining a DOM from the Factory 283
Normalizing the DOM 287
Other Operations 289
Finishing Up 292
Validating with XML Schema 292
Overview of the Validation Process 293
Configuring the DocumentBuilder Factory 293
Validating with Multiple Namespaces 295
Further Information 298
Chapter 9: XML Stylesheet Language for Transformations . . 301
Introducing XSLT and XPath 301
The JAXP Transformation Packages 302
How XPath Works 303
XPATH Expressions 303
The XSLT/XPath Data Model 304
Templates and Contexts 305
Basic XPath Addressing 305
Basic XPath Expressions 306
Combining Index Addresses 307
Wildcards 307
Extended-Path Addressing 308
XPath Data Types and Operators 309
String-Value of an Element 309
XPath Functions 310
Summary 313
Writing Out a DOM as an XML File 313
Reading the XML 314
Creating a Transformer 315
Writing the XML 318
Writing Out a Subtree of the DOM 318
Summary 320
Generating XML from an Arbitrary Data Structure 320
Creating a Simple File 321
Creating a Simple Parser 323
Modifying the Parser to Generate SAX Events 325
Using the Parser as a SAXSource 332
Doing the Conversion 334
Transforming XML Data with XSLT 335
Defining a Simple

Document Type 335
Creating a Test Document 337
Writing an XSLT Transform 338
Processing the Basic Structure Elements 339
Writing the Basic Program 343
Trimming the Whitespace 345
Processing the Remaining Structure Elements 348
Process Inline (Content) Elements 352
Printing the HTML 356
What Else Can XSLT Do? 357
Transforming from the Command Line with Xalan 358
Concatenating Transformations with a Filter Chain 359
Writing the Program 359
Understanding How the Filter Chain Works 362
Testing the Program 363
Conclusion 366
Further Information 366
Chapter 10: Binding XML Schema to Java Classes with JAXB 367
JAXB Architecture 368
Architectural Overview 368
The JAXB Binding Process 371
JAXB Binding Framework 372
More About javax.xml.bind 373
More About Unmarshalling 374
More About Marshalling 375
More About Validation 377
XML Schemas 379
Representing XML Content 383
Binding XML Names to Java Identifiers 383
Java Representation of XML Schema 383
Binding XML Schemas 384
Simple Type Definitions 384
Default Data Type Bindings 385
Default Binding Rules Summary 386
Customizing JAXB Bindings 387
Scope 388
Scope Inheritance 388
What is Not Supported 389
JAXB APIs and Tools 389
Chapter 11: Using JAXB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .391
General Usage Instructions 392
Description 392
Using the Examples 394
Configuring and Running the Examples Manually 394
Configuring and Running the Samples With Ant 396
JAXB Compiler Options 398
About the Schema-to-Java Bindings 400
Schema-Derived JAXB Classes 403
Basic Examples 411
Unmarshal Read Example 411
Modify Marshal Example 413
Create Marshal Example 415
Unmarshal Validate Example 420
Validate-On-Demand Example 421
Customizing JAXB Bindings 423
Why Customize? 424
Customization Overview 425
Customize Inline Example 438
Datatype Converter Example 443
External Customize Example 444
Fix Collides Example 448
Bind Choice Example 452
Chapter 12: Building Web Services With JAX-RPC . . . . . . . . . . 455
Types Supported By JAX-RPC 456
J2SE SDK Classes 456
Primitives 457
Arrays 457
Value Types 458
JavaBeans Components 458
Setting the Port 458
Creating a Web Service with JAX-RPC 459
Coding the Service Endpoint Interface and Implementation Class 460
Building the Service 461
Deploying the Service 464
Creating Web Service Clients with JAX-RPC 465
Static Stub Client Example 465
Dynamic Proxy Client Example 468
Dynamic Invocation Interface (DII) Client Example 471
More JAX-RPC Client Examples 475
Web Services Interoperability (WS-I) and JAX-RPC 475
Advanced JAX-RPC Examples 476
SOAP Message Handlers Example 476
Advanced Static Stub Example 486
Advanced Dynamic Proxy Example 503
Advanced DII Client Example 507
Further Information 513
Chapter 13: SOAP with Attachments API for Java . . . . . . . . . .515
Overview of SAAJ 516
Messages 516
Connections 520
Tutorial 521
Creating and Sending a Simple Message 522
Adding Content to the Header 530
Adding Content to the SOAP Body 531
Adding Content to the SOAPPart Object 532
Adding a Document to the SOAP Body 534
Manipulating Message Content Using SAAJ or DOM APIs 534
Adding Attachments 535
Adding Attributes 537
Using SOAP Faults 543
Code Examples 547
Request.java 548
MyUddiPing.java 549
HeaderExample.java 556
DOMExample.java and DomSrcExample.java 558
Attachments.java 562
SOAPFaultTest.java 564
Further Information 565
Chapter 14: Java API for XML Registries . . . . . . . . . . . . . . . . . .567
Overview of JAXR 567
What Is a Registry? 568
What Is JAXR? 568
JAXR Architecture 569
Implementing a JAXR Client 571
Establishing a Connection 572
Querying a Registry 577
Managing Registry Data 581
Using Taxonomies in JAXR Clients 590
Running the Client Examples 595
Before You Compile the Examples 596
Compiling the Examples 598
Running the Examples 598
.Further Information 604
Chapter 15: Java Servlet Technology . . . . . . . . . . . . . . . . . . . . 605
What is a Servlet? 605
The Example Servlets 606
Troubleshooting 608
Servlet Life Cycle 608
Handling Servlet Life Cycle Events 609
Handling Errors 611
Sharing Information 612
Using Scope Objects 612
Controlling Concurrent Access to Shared Resources 613
Accessing Databases 614
Initializing a Servlet 615
Writing Service Methods 616
Getting Information from Requests 617
Constructing Responses 619
Filtering Requests and Responses 621
Programming Filters 622
Programming Customized Requests and Responses 624
Specifying Filter Mappings 626
Invoking Other Web Resources 629
Including Other Resources in the Response 630
Transferring Control to Another Web Component 631
Accessing the Web Context 632
Maintaining Client State 633
Accessing a Session 633
Associating Attributes with a Session 633
Session Management 634
Session Tracking 635
Finalizing a Servlet 636
Tracking Service Requests 637
Notifying Methods to Shut Down 638
Creating Polite Long-Running Methods 639
Further Information 639
Chapter 16: JavaServer Pages Technology . . . . . . . . . . . . . . .641
What Is a JSP Page? 641
Example 642
The Example JSP Pages 645
The Life Cycle of a JSP Page 650
Translation and Compilation 650
Execution 651
Creating Static Content 653
Response and Page Encoding 653
Creating Dynamic Content 654
Using Objects within JSP Pages 654
Expression Language 655
Deactivating Expression Evaluation 656
Using Expressions 657
Variables 658
Implicit Objects 659
Literals 660
Operators 660
Reserved Words 661
Examples 661
Functions 662
JavaBeans Components 663
JavaBeans Component Design Conventions 664
Creating and Using a JavaBeans Component 665
Setting JavaBeans Component Properties 666
Retrieving JavaBeans Component Properties 669
Using Custom Tags 669
Declaring Tag Libraries 670
Including the Tag Library Implementation 671
Reusing Content in JSP Pages 672
Transferring Control to Another Web Component 673
jsp:param Element 674
Including an Applet 674
Setting Properties for Groups of JSP Pages 677
Further Information 680
Chapter 17: JavaServer Pages Standard Tag Library . . . . . . . .681
The Example JSP Pages 681
Using JSTL 682
Tag Collaboration 684
Core Tags 685
Variable Support Tags 685
Flow Control Tags 686
URL Tags 689
Miscellaneous Tags 690
XML Tags 691
Core Tags 693
Flow Control Tags 694
Transformation Tags 695
Internationalization Tags 695
Setting the Locale 696
Messaging Tags 697
Formatting Tags 697
SQL Tags 698
query Tag Result Interface 700
Functions 703
Further Information 704
Chapter 18: Custom Tags in JSP Pages . . . . . . . . . . . . . . . . . . . 705
What Is a Custom Tag? 706
The Example JSP Pages 706
Types of Tags 709
Tags with Attributes 709
Tags with Bodies 712
Tags That Define Variables 713
Communication Between Tags 713
Encapsulating Reusable Content using Tag Files 714
Tag File Location 715
Tag File Directives 715
Evaluating Fragments Passed to Tag Files 724
Examples 724
Tag Library Descriptors 728
Declaring Tag Files 730
Declaring Tag Handlers 733
Declaring Tag Attributes for Tag Handlers 735
Declaring Tag Variables for Tag Handlers 736
Programming Simple Tag Handlers 738
Basic Tags 739
Tags with Attributes 740
Tags with Bodies 742
Tags That Define Variables 743
Cooperating Tags 746
Examples 748
Chapter 19: Scripting in JSP Pages . . . . . . . . . . . . . . . . . . . . . .757
The Example JSP Pages 758
Using Scripting 758
Disabling Scripting 759
Declarations 759
Initializing and Finalizing a JSP Page 760
Scriptlets 760
Expressions 761
Programming Tags That Accept Scripting Elements 762
TLD Elements 762
Tag Handlers 763
Tags with Bodies 765
Cooperating Tags 767
Tags That Define Variables 769
Chapter 20: JavaServer Faces Technology. . . . . . . . . . . . . . . .771
JavaServer Faces Technology Benefits 772
What is a JavaServer Faces Application? 773
Framework Roles 774
A Simple JavaServer Faces Application 775
Steps in the Development Process 775
Creating the Pages 776
Define Page Navigation 778
Develop the Beans 780
Adding Managed Bean Declarations 781
The Lifecycle of a JavaServer Faces Page 783
Request Processing Lifecycle Scenarios 784
Standard Request Processing Lifecycle 785
User Interface Component Model 790
The User-Interface Component Classes 790
The Component Rendering Model 792
Conversion Model 796
Event and Listener Model 797
Validation Model 797
Navigation Model 798
Backing Bean Management 799
Application Configuration 801
About the Examples 802
Running the Examples on the Java WSDP Container 802
Building and Running the Sample Applications Manually 803
The cardemo Example 803
Basic Requirements of a JavaServer Faces Application 805
Writing the web.xml File 806
Including the Required JAR Files 808
Including the Classes, Pages, and Other Resources 809
Setting Up The Application Configuration File 810
Chapter 21: Using JavaServer Faces Technology . . . . . . . . . . 813
Using the JavaServer Faces Tag Libraries 813
Requirements For Using the Tags on The Page 814
Using the Core Tags 815
Using the HTML Tags 817
Working With Backing Beans 838
Writing Component Properties 838
Writing Backing-Bean Methods 846
Configuring Beans 849
Binding Component Values and Instances to External Data Sources 858
Referencing a Backing Bean Method 863
Performing Validation 864
Displaying Validation Error Messages 865
Requiring a Value 866
Using the Standard Validators 866
Creating a Custom Validator 868
Performing Data Conversions 878
Using the Standard Converters 879
Creating and Using a Custom Converter 884
Handling Events 887
Implementing an Event Listener 888
Registering Listeners on Components 890
Handling Events With A Backing Bean Method 892
Navigating Between Pages 894
What is Navigation? 895
How Navigation Works 896
Configuring Navigation Rules in faces-config.xml 897
Referencing an Action Method 899
Using an Action Method With a Navigation Rule 900
Performing Localization 901
Localizing Static Data 901
Localizing Dynamic Data 903
Localizing Messages 904
Chapter 22: Creating Custom UI Components . . . . . . . . . . . . .905
Determining if You Need a Custom Component or Renderer 906
When to Use a Custom Component 906
When to Use a Custom Renderer 907
Component, Renderer, and Tag Combinations 908
Understanding the Image Map Example 909
Why Use JavaServer Faces Technology to Implement an Image Map?
909
Understanding the Rendered HTML 910
Understanding the JSP Page 911
Simplifying the JSP Page 912
Summary of the Application Classes 914
Steps for Creating a Custom Component 915
Creating the Component Tag Handler 916
Defining the Custom Component Tag in a Tag Library Descriptor 921
Creating Custom Component Classes 922
Performing Encoding 925
Performing Decoding 927
Defining Properties for the Component’s Values 928
Saving and Restoring State 929
Delegating Rendering to a Renderer 930
Create the Renderer Class 931
Register the Renderer with a Render Kit 933
Identify the Renderer Type 934
Register the Component 934
Handling Events for Custom Components 935
Using the Custom Component in the Page 937
Further Information 939
Chapter 23: Internationalizing and Localizing Web Applications .
941
Java Platform Localization Classes 941
Providing Localized Messages and Labels 942
Date and Number Formatting 943
Character Sets and Encodings 944
Character Sets 944
Character Encoding 945
Further Information 948
Chapter 24: Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 949
Security in the Web-Tier 949
Realms, Users, Groups, and Roles 952
Setting up Security Roles 952
Managing Roles and Users 954
Specifying Security Constraints 955
Specifying a Secure Connection 956
Using Login Authentication 958
Example: Using Form-Based Authentication 959
Using Programmatic Security in the Web Tier 968
Declaring and Linking Role References 968
Installing and Configuring SSL Support 969
What is Secure Socket Layer Technology? 969
Setting Up Digital Certificates 970
Configuring the SSL Connector 976
XML and Web Services Security 980
Transport-Level Security 980
Example: Basic Authentication with JAX-RPC 981
Example: Client-Certificate Authentication over HTTP/SSL with JAXRPC
986
Message-Level Security 994
Chapter 25: The Coffee Break Application. . . . . . . . . . . . . . . 1001
Coffee Break Overview 1001
Common Code 1003
JAX-RPC Distributor Service 1003
Service Interface 1003
Service Implementation 1004
Publishing the Service in the Registry 1005
Deleting the Service From the Registry 1009
SAAJ Distributor Service 1011
SAAJ Client 1013
SAAJ Service 1020
Coffee Break Server 1026
JSP Pages 1027
JavaBeans Components 1028
RetailPriceListServlet 1030
JavaServer Faces Version of Coffee Break Server 1030
JSP Pages 1031
JavaBeans Components 1034
Resource Configuration 1035
Building, Packaging, Installing, and Running the Application 1036
Setting the Port 1036
Building the Common Classes 1037
Building and Installing the JAX-RPC Service 1037
Building and Installing the SAAJ Service 1038
Building and Installing the Coffee Break Server 1038
Building and Installing the JavaServer Faces Technology Version of the
Coffee Break Server 1039
Running the Coffee Break Client 1039
Removing the Coffee Break Application 1041
Appendix A: Tomcat Web Server Administration Tool . . . . . . .1043
Running admintool 1043
Configuring Tomcat 1046
Setting Server Properties 1046
Configuring Services 1047
Configuring Connector Elements 1048
Configuring Host Elements 1054
Configuring Logger Elements 1062
Configuring Realm Elements 1065
Configuring Valve Elements 1072
Configuring Resources 1076
Configuring Data Sources 1077
Configuring Environment Entries 1079
Configuring User Databases 1080
Administering Roles, Groups, and Users 1081
Managing Roles 1081
Managing Users 1082
Further Information 1083
Appendix B: Tomcat Web Application Manager . . . . . . . . . . 1085
Running the Web Application Manager 1085
Running Manager Commands Using Ant Tasks 1087
Appendix C: The Java WSDP Registry Server . . . . . . . . . . . . . . 1089
Starting the Registry Server 1090
Changing the Port for the Registry Server 1090
Using JAXR to Access the Registry Server 1091
Adding and Deleting Users 1092
Adding a New User to the Registry 1092
Deleting a User from the Registry 1093
Further Information 1093
Appendix D: Registry Browser . . . . . . . . . . . . . . . . . . . . . . . . . . 1095
Starting the Browser 1095
Querying a Registry 1097
Querying by Name 1097
Querying by Classification 1097
Managing Registry Data 1098
Adding an Organization 1098
Adding Services to an Organization 1099
Adding Service Bindings to a Service 1099
Adding and Removing Classifications 1100
Submitting the Data 1101
Deleting an Organization 1101
Stopping the Browser 1101
Appendix E: HTTP Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 1103
HTTP Requests 1104
HTTP Responses 1104
Appendix F: Java Encoding Schemes. . . . . . . . . . . . . . . . . . . 1105
Further Information 1106
Glossary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1107
About the Authors . . . . . . . . . . . . . . . . . . . . . . . . 1135

Another Java Books
Another Web Programming Books
Download