The Java Web Services Tutorial - Oracle

About This TutorialTHE Java Web Services Tutorial is a guide to developing Web applicationswith the Java Web Services Developer Pack (Java WSDP). The Java WSDP is anall-in-one download containing key technologies to simplify building of Webservices using the Java 2 Platform. This tutorial requires a full installation (Typical, not Custom) of the Java WSDP, v1.6 with the Sun Java System ApplicationServer Platform Edition 8.1 2005Q2 UR2 (hereafter called the ApplicationServer). Here we cover all the things you need to know to make the best use ofthis tutorial.Who Should Use This TutorialThis tutorial is intended for programmers who are interested in developing anddeploying Web services and Web applications on the Sun Java System Application Server Platform Edition 8.1.PrerequisitesBefore proceeding with this tutorial you should have a good knowledge of theJava programming language. A good way to get to that point is to work throughall the basic and some of the specialized trails in The Java Tutorial, MaryCampione et al., (Addison-Wesley, 2000). In particular, you should be familiarxi

xiiABOUT THIS TUTORIALwith relational database and security features described in the trails listed inTable 1.Table 1 Prerequisite Trails in The Java ks/tutorial/security1.2How to Use This TutorialThe Java Web Services Tutorial is an adjunct to the J2EE 1.4 Tutorial, whichyou can download from the following l#tutorialThe Java Web Services Tutorial addresses the following technology areas, whichare not covered in the J2EE 1.4 Tutorial: The Java Architecture for XML Binding (JAXB)The StAX APIs and the Sun Java Streaming XML Parser implementationXML and Web Services Security (XWS Security)XML Digital SignatureService RegistryAll of the examples for this tutorial are installed with the Java WSDP 1.6 bundleand can be found in the subdirectories of the JWSDP HOME / technology /samples directory, where JWSDP HOME is the directory where you installedthe Java WSDP 1.6 bundle.The J2EE 1.4 Tutorial opens with three introductory chapters that you shouldread before proceeding to any specific technology area. Java WSDP users shouldlook at Chapters 2 and 3, which cover XML basics and getting started with Webapplications.

ABOUT THIS TUTORIALWhen you have digested the basics, you can delve into one or more of the following main XML technology areas: The Java XML chapters cover the technologies for developing applicationsthat process XML documents and implement Web services components: The Java API for XML Processing (JAXP) The Java API for XML-based RPC (JAX-RPC) SOAP with Attachments API for Java (SAAJ) The Java API for XML Registries (JAXR) The Web-tier technology chapters cover the components used in developing the presentation layer of a J2EE or stand-alone Web application: Java Servlet JavaServer Pages (JSP) JavaServer Pages Standard Tag Library (JSTL) JavaServer Faces Web application internationalization and localization The platform services chapters cover system services used by all the J2EEcomponent technologies. Java WSDP users should look at the Web-tiersection of the Security chapter.After you have become familiar with some of the technology areas, you areready to tackle a case study, which ties together several of the technologies discussed in the tutorial. The Coffee Break Application (Chapter 35) describes anapplication that uses the Web application and Web services APIs.Finally, the following appendixes contain auxiliary information helpful to theWeb Services application developer: Java encoding schemes (Appendix A) XML Standards (Appendix B) HTTP overview (Appendix C)About the ExamplesThis section tells you everything you need to know to install, build, and run theexamples.xiii

xivABOUT THIS TUTORIALRequired SoftwareJava WSDP 1.6 BundleThe example source for the technologies in this tutorial is contained in the JavaWSDP 1.6 bundle. If you are viewing this online, you need to download the JavaWSDP 1.6 bundle ervicespack.htmlAfter you have installed the Java WSDP 1.6 bundle, the example source code isin the subdirectories of the JWSDP HOME / technology /samples/ directory.For example, the examples for JAXB are included in the Java WSDP in the subdirectories of the JWSDP HOME /jaxb/samples directory.Application ServerSun Java System Application Server Platform Edition 8.1 2005Q2 UR2 is thebuild and runtime environment for the tutorial examples. To build, deploy, andrun the examples, you need a copy of the Application Server and the Java 2 Software Development Kit, Standard Edition (J2SE SDK) 1.4.2 or higher (J2SE 5.0is recommended). The Application Server and J2SE SDK are contained in theJ2EE 1.4 SDK. If you already have a copy of the J2SE SDK, you can downloadthe Application Server kYou can also download the J2EE 1.4 SDK—which contains the ApplicationServer and the J2SE SDK—from the same site.Building the ExamplesMost of the examples in the Java WSDP are distributed with a build file for Ant,a portable build tool contained in the Java WSDP. For information about Ant,visit http://ant.apache.org/. Directions for building the examples are provided in each chapter. Most of the tutorial examples in the J2EE 1.4 Tutorial aredistributed with a configuration file for asant, a portable build tool contained inthe Application Server. This tool is an extension of the Ant tool developed by theApache Software Foundation (http://ant.apache.org). The asant utility

ABOUT THIS TUTORIALcontains additional tasks that invoke the Application Server administration utility asadmin. Directions for building the examples are provided in each chapter.In order to run the Ant scripts, you must configure your environment and properties files as follows: Add the bin directory of your J2SE SDK installation to the front of yourpath. Add JWSDP HOME /jwsdp-shared/bin to the front of your path so theJava WSDP 1.6 scripts that are shared by multiple components overrideother installations. Add JWSDP HOME /apache-ant/bin to the front of your path so that theJava WSDP 1.6 Ant script overrides other installations.Further InformationThis tutorial includes the basic information that you need to deploy applicationson and administer the Application Server.For reference information on the tools distributed with the Application Server,see the man pages at http://docs.sun.com/db/doc/819-0082.See the Sun Java System Application Server Platform Edition 8.1 2005Q1Developer’s Guide at http://docs.sun.com/db/doc/819-0079 for information about developer features of the Application Server.See the Sun Java System Application Server Platform Edition 8.1 2005Q1Administration Guide at http://docs.sun.com/db/doc/819-0076 for information about administering the Application Server.For information about the PointBase database included with the ApplicationServer, see the PointBase Web site at www.pointbase.com.How to Print This TutorialTo print this tutorial, follow these steps:1. Ensure that Adobe Acrobat Reader is installed on your system.2. Open the PDF version of this book.3. Click the printer icon in Adobe Acrobat Reader.xv

xviABOUT THIS TUTORIALTypographical ConventionsTable 2 lists the typographical conventions used in this tutorial.Table 2 Typographical ConventionsFont StyleUsesitalicEmphasis, titles, first occurrence of termsmonospaceURLs, code examples, file names, path names, tool names,application names, programming language keywords, tag,interface, class, method, and field names, propertiesitalic monospaceVariables in code, file paths, and URLs italic monospace User-selected file path componentsFeedbackPlease send comments, broken link reports, errors, suggestions, and questionsabout this tutorial to the tutorial team at users@jwsdp.dev.java.net.

1Binding XML Schemato Java Classes withJAXBTHE Java Architecture for XML Binding (JAXB) provides a fast and convenient way to bind XML schemas to Java representations, making it easy for Javadevelopers to incorporate XML data and processing functions in Java applications. As part of this process, JAXB provides methods for unmarshalling XMLinstance documents into Java content trees, and then marshalling Java contenttrees back into XML instance documents.What this all means is that you can leverage the flexibility of platform-neutralXML data in Java applications without having to deal with or even know XMLprogramming techniques. Moreover, you can take advantage of XML strengthswithout having to rely on heavyweight, complex XML processing models likeSAX or DOM. JAXB hides the details and gets rid of the extraneous relationships in SAX and DOM—generated JAXB classes describe only the relationships actually defined in the source schemas. The result is highly portable XMLdata joined with highly portable Java code that can be used to create flexible,lightweight applications and Web services.This chapter describes the JAXB architecture, functions, and core concepts. Youshould read this chapter before proceeding to Chapter 2, which provides samplecode and step-by-step procedures for using JAXB.1

2BINDING XML SCHEMA TO JAVA CLASSES WITH JAXBJAXB ArchitectureThis section describes the components and interactions in the JAXB processingmodel. After providing a general overview, this section goes into more detailabout core JAXB features. The topics in this section include: Architectural OverviewThe JAXB Binding ProcessJAXB Binding FrameworkMore About javax.xml.bindMore About UnmarshallingMore About MarshallingMore About ValidationArchitectural OverviewFigure 1–1 shows the components that make up a JAXB implementation.Figure 1–1 JAXB Architectural Overview

ARCHITECTURAL OVERVIEWAs shown in Figure 1–1, a JAXB implementation comprises the following eightcore components.Table 1–1 Core Components in a JAXB ImplementationComponentDescriptionXML SchemaAn XML schema uses XML syntax to describe the relationships amongelements, attributes and entities in an XML document. The purpose of anXML schema is to define a class of XML documents that must adhere toa particular set of structural rules and data constraints. For example, youmay want to define separate schemas for chapter-oriented books, for anonline purchase order system, or for a personnel database. In the contextof JAXB, an XML document containing data that is constrained by anXML schema is referred to as a document instance, and the structure anddata within a document instance is referred to as a content tree.BindingCustomizationsBy default, the JAXB binding compiler binds Java classes and packagesto a source XML schema based on rules defined in Section 5, “BindingXML Schema to Java Representations,” in the JAXB Specification. Inmost cases, the default binding rules are sufficient to generate a robustset of schema-derived classes from a wide range of schemas. There maybe times, however, when the default binding rules are not sufficient foryour needs. JAXB supports customizations and overrides to the defaultbinding rules by means of binding customizations made either inline asannotations in a source schema, or as statements in an external bindingcustomization file that is passed to the JAXB binding compiler. Note thatcustom JAXB binding customizations also allow you to customize yourgenerated JAXB classes beyond the XML-specific constraints in anXML schema to include Java-specific refinements such as class andpackage name mappings.BindingCompilerThe JAXB binding compiler is the core of the JAXB processing model.Its function is to transform, or bind, a source XML schema to a set ofJAXB content classes in the Java programming language. Basically, yourun the JAXB binding compiler using an XML schema (optionally withcustom binding declarations) as input, and the binding compiler generates Java classes that map to constraints in the source XML schema.ImplementationofThe JAXB binding framework implementation is a runtime API that provides interfaces for unmarshalling, marshalling, and validating XMLcontent in a Java application. The binding framework comprises interfaces in the javax.xml.bind package.javax.xml.bindSchema-DerivedClassesThese are the schema-derived classes generated by the binding JAXBcompiler. The specific classes will vary depending on the input schema.3

4BINDING XML SCHEMA TO JAVA CLASSES WITH JAXBTable 1–1 Core Components in a JAXB Implementation (Continued)ComponentDescriptionJavaApplicationIn the context of JAXB, a Java application is a client application that usesthe JAXB binding framework to unmarshal XML data, validate and modify Java content objects, and marshal Java content back to XML data.Typically, the JAXB binding framework is wrapped in a larger Javaapplication that may provide UI features, XML transformation functions,data processing, or whatever else is desired.XML InputDocumentsXML content that is unmarshalled as input to the JAXB binding framework -- that is, an XML instance document, from which a Java representation in the form of a content tree is generated. In practice, the term“document” may not have the conventional meaning, as an XMLinstance document does not have to be a completely formed, selfstandingdocument file; it can instead take the form of streams of data passedbetween applications, or of sets of database fields, or of XML infosets, inwhich blocks of information contain just enough information to describewhere they fit in the schema structure.In JAXB, the unmarshalling process supports validation of the XMLinput document against the constraints defined in the source schema.This validation process is optional, however, and there may be cases inwhich you know by other means that an input document is valid and soyou may choose for performance reasons to skip validation duringunmarshalling. In any case, validation before (by means of a third-partyapplication) or during unmarshalling is important, because it assures thatan XML document generated during marshalling will also be valid withrespect to the source schema. Validation is discussed more later in thischapter.XML OutputDocumentsXML content that is marshalled out to an XML document. In JAXB,marshalling involves parsing an XML content object tree and writing outan XML document that is an accurate representation of the original XMLdocument, and is valid with respect the source schema. JAXB can marshal XML data to XML documents, SAX content handlers, and DOMnodes.

THE JAXB BINDING PROCESSThe JAXB Binding ProcessFigure 1–2 shows what occurs during the JAXB binding process.Figure 1–2 Steps in the JAXB Binding ProcessThe general steps in the JAXB data binding process are:1. Generate classes. An XML schema is used as input to the JAXB bindingcompiler to generate JAXB classes based on that schema.2. Compile classes. All of the generated classes, source files, and applicationcode must be compiled.3. Unmarshal. XML documents written according to the constraints in thesource schema are unmarshalled by the JAXB binding framework. Notethat JAXB also supports unmarshalling XML data from sources other thanfiles/documents, such as DOM nodes, string buffers, SAX Sources, and soforth.4. Generate content tree. The unmarshalling process generates a content treeof data objects instantiated from the generated JAXB classes; this contenttree represents the structure and content of the source XML documents.5

6BINDING XML SCHEMA TO JAVA CLASSES WITH JAXB5. Validate (optional). The unmarshalling process optionally involves validation of the source XML documents before generating the content tree.Note that if you modify the content tree in Step 6, below, you can also usethe JAXB Validate operation to validate the changes before marshalling thecontent back to an XML document.6. Process content. The client application can modify the XML data represented by the Java content tree by means of interfaces generated by thebinding compiler.7. Marshal. The processed content tree is marshalled out to one or more XMLoutput documents. The content may be validated before marshalling.To summarize, using JAXB involves two discrete sets of activities: Generate and compile JAXB classes from a source schema, and build anapplication that implements these classes Run the application to unmarshal, process, validate, and marshal XMLcontent through the JAXB binding frameworkThese two steps are usually performed at separate times in two distinct phases.Typically, for example, there is an application development phase in whichJAXB classes are generated and compiled, and a binding implementation is built,followed by a deployment phase in which the generated JAXB classes are usedto process XML content in an ongoing “live” production setting.Note: Unmarshalling is not the only means by which a content tree may be created.Schema-derived content classes also support the programmatic construction of content trees by direct invocation of the appropriate factory methods. Once created, acontent tree may be revalidated, either in whole or in part, at any time. See CreateMarshal Example (page 47) for an example of using the ObjectFactory class todirectly add content to a content tree.JAXB Binding FrameworkThe JAXB binding framework is implemented in three Java packages: The javax.xml.bind package defines abstract classes and interfaces thatare used directly with content classes.The javax.xml.bind package defines the Unmarshaller, Validator,and Marshaller classes, which are auxiliary objects for providing theirrespective operations.

MORE ABOUT JAVAX.XML.BINDThe JAXBCon

CursorParse.java 112 CursorApproachEventObject.java 114 EventParse.java 115 CursorWriter.java 118 MyStreamFilter.java 119 EventProducerConsumer.java 122 Further Information 125 Chapter 4: Introduction to XML and Web Services Security. 127 Overview 128 Does XWS-Security Implement Any Spe