The Java™ Web
Services Tutorial
For Java Web Services Developer’s Pack, v2.0
February 17, 2006
Copyright © 2006 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, Enterprise JavaBeans, Java Naming
and Directory Interface, EJB, 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, FAQs, 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 © 2006 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 Microsystems, Inc., ainsi qu aux dis-
positions 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, Enterprise JavaBeans, Java Naming and
Directory Interface, EJB, 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.
iii
About This Tutorial. . . . . . . . . . . . . . . . . . . . . . . . . . . .ix
Who Should Use This Tutorial ix
Prerequisites ix
How to Use This Tutorial x
About the Examples x
Required Software xi
Building the Examples xi
How to Print This Tutorial xiii
Typographical Conventions xiii
Feedback xiv
Chapter 1: Building Web Services with JAX-WS. . . . . . . . . . . . xv
Setting the Port xvi
Creating a Simple Web Service and Client with JAX-WS xvi
Requirements of a JAX-WS Endpoint xviii
Coding the Service Endpoint Implementation Class xix
Building the Service xix
Packaging and Deploying the Service xx
A Simple JAX-WS Client xxi
Types Supported by JAX-WS xxiii
Web Services Interoperability and JAX-WS xxiii
Further Information xxiv
Chapter 2: Binding between XML Schema and Java Classes . 1
JAXB Architecture 1
Architectural Overview 2
The JAXB Binding Process 3
More About Unmarshalling 4
More About Marshalling 4
Contents
iv CONTENTS
More About Validation 4
Representing XML Content 5
Java Representation of XML Schema 5
Binding XML Schemas 5
Simple Type Definitions 5
Default Data Type Bindings 6
Customizing JAXB Bindings 8
Schema-to-Java 8
Java-to-Schema 9
Chapter 3: Using JAXB. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11
General Usage Instructions 12
Description 12
Using the Examples 15
Configuring and Running the Samples 15
JAXB Compiler Options 16
JAXB Schema Generator Options 18
About the Schema-to-Java Bindings 19
Schema-Derived JAXB Classes 22
Basic Examples 29
Unmarshal Read Example 29
Modify Marshal Example 31
Unmarshal Validate Example 33
Customizing JAXB Bindings 35
Why Customize? 35
Customization Overview 36
Customize Inline Example 49
Datatype Converter Example 55
External Customize Example 56
Fix Collides Example 59
Bind Choice Example 64
Java-toSchema Examples 66
j2s-create-marshal Example 66
j2s-xmlAccessorOrder Example 66
j2s-xmlAdapter-field Example 69
j2s-xmlAttribute-field Example 72
j2s-xmlRootElement Example 73
j2s-xmlSchemaType-class Example 73
j2s-xmlType Example 74
CONTENTS v
Chapter 4: Streaming API for XML . . . . . . . . . . . . . . . . . . . . . . . 77
Why StAX? 77
Streaming Versus DOM 78
Pull Parsing Versus Push Parsing 79
StAX Use Cases 79
Comparing StAX to Other JAXP APIs 80
StAX API 81
Cursor API 81
Iterator API 82
Choosing Between Cursor and Iterator APIs 87
Using StAX 89
StAX Factory Classes 89
Resources, Namespaces, and Errors 91
Reading XML Streams 92
Writing XML Streams 95
Sun’s Streaming Parser Implementation 97
Reporting CDATA Events 97
SJSXP Factories Implementation 98
Sample Code 99
Sample Code Organization 99
Configuring Your Environment for Running the Samples 100
Running the Samples 101
Sample XML Document 102
cursor Sample – CursorParse.java 103
cursor2event Sample – CursorApproachEventObject.java 105
event Sample – EventParse.java 106
filter Sample – MyStreamFilter.java 109
readnwrite Sample – EventProducerConsumer.java 111
writer Sample – CursorWriter.java 114
Further Information 116
Chapter 5: SOAP with Attachments API for Java . . . . . . . . . . 117
Overview of SAAJ 118
Messages 118
Connections 122
Tutorial 123
Creating and Sending a Simple Message 124
Adding Content to the Header 133
Adding Content to the SOAPPart Object 134
Adding a Document to the SOAP Body 136
