JavaTM Architecture for XML Binding
Sample Apps Readme

Specification Version: 2.0
Reference Implementation (RI) Version: 2.0.2 fcs
This page summarizes basic use-cases for Java-2-Schema, Schema-2-Java, and lists all of the sample applications that ship with JAXB.

Using the Runtime Binding Framework

Schema-2-Java

Schema-2-Java is the process of compiling one or more schema files into generated Java classes. Here are some of the basic steps for developing an app:

  1. Develop/locate your schema
  2. Annotate the schema with binding customizations if necessary (or place them in an external bindings file)
  3. Compile the schema with the XJC binding compiler
  4. Develop your JAXB client application using the Java content classes generated by the XJC binding compiler along with the javax.xml.bind runtime framework
  5. Set your CLASSPATH to include all of the JAR files
  6. Compile all of your Java sources with javac
  7. Run it!

Java-2-Schema

  

Java-2-Schema is the process of augmenting existing Java classes with the annotations defined in the javax.xml.bind.annotation package so that the JAXB runtime binding framework is capable of performing the un/marshal operations. Here are the basic steps for developing an app:

  1. Develop your data model in Java
  2. Apply the javax.xml.bind.annotation annotations to control the binding process
  3. Set your CLASSPATH to include all of the JAR files
  4. Compile your data model with javac (Important! make sure that you classpath includes jaxb-xjc.jar before running javac)
  5. The resulting class files will contain your annotations as well other default annotations needed by the JAXB runtime binding framework
  6. Develop your client application that uses the data model and develop the code that uses the JAXB runtime binding framework to persist your data model using the un/marshal operations.
  7. Compile and run your client application!

For more information about this process, see the the Java WSDP Tutorial and the extensive sample application documentation.

Building and Running the Sample Apps with Ant

To run the sample applications using the supplied Ant build.xml files, follow these steps:

For Solaris/Linux:
  1. % <your JWSDP2.0 installation directory>/apache-ant/bin/ant -emacs
  2. repeat for each sample app
For WindowsNT/2000/XP:
  1. > <your JWSDP2.0 installation directory>\apache-ant\bin\ant -emacs
  2. repeat for each sample app

A few sample applications do not use Ant. For those samples, refer to the included readme.txt files for instructions.

List of Sample Apps

catalog resolver
This example demonstrates how to use the "-catalog" compiler switch to handle references to schemas in external web sites.
character-escape
This example shows how you can use the new JAXB RI Marshaller property "com.sun.xml.bind.characterEscapeHandler" to change the default character escaping behavior.
create-marshal (formerly SampleApp3)
This sample application demonstrates how to use the ObjectFactory class to create a Java content tree from scratch and marshal it to XML data. It also demonstrates how to add content to a JAXB List property.
datatypeconverter (formerly SampleApp7)
This sample application is very similar to the inline-customize sample application (formerly SampleApp6), but illustrates an easier, but not as robust, <jaxb:javaType> customization.
dtd
This sample application illustrate some of the DTD support available in the JAXB RI's extension mode. Please refer to the <a href="vendor.html> Vendor Extensions</a> page for more detail.
element-substitution
This sample application illustrates how W3C XML Schema substitution groups are supported in JAXB RI's extension mode. Please refer to the <a href="vendor.html">Vendor Extensions</a> page for more detail.
external-customize (formerly SampleApp8)
This sample application is identical to the datatypeconverter sample application (formerly SampleApp7) except that the binding customizations are contained in an external binding file.
fix-collides (formerly part of SampleApp9)
Another binding customization example that illustrates how to resolve name conflicts. Running this sample without the binding file will result in name collisions (see readme.txt) . Running "ant" will use the binding customizations to resolve the name conflicts while compiling the schema.
inline-customize (formerly SampleApp6)
This sample application demonstrates how to customize the default binding produced by the XJC binding compiler.
Java to Schema Binding
This sample application demonstrates marshalling, unmarshalling and unmarshal validation with existing Java classes annotated with JAXB annotations.
Ordering Properties and Fieldes in Java to Schema Bindings
This sample application demonstrates the use of mapping annotations @XmlAccessorOrder and @XmlType.propOrder in Java classes for ordering properties and fields in Java to schema bindings.
Adapters for custom marshaling/unmarshaling XML content
This sample application demonstrates the use of interface XmlAdapter and annotation XmlJavaTypeAdapter for custom marshaling/unmarshaling XML content into/out of a Java type.
@XmlAttribute used to define properties and fields as XML Attributes
This sample application demonstrates the use of annotation @XmlAttribute for defining Java properties and fields as XML attributes.
Defining XML elements via @XmlRootElement
This sample application demonstrates the use of annotation @XmlRootElement to define a class to be an XML element.
Annotation @XmlSchemaType is used to customize the mapping of a property or field to an XML built-in type.
This sample application demonstrates the use of annotation @XmlSchemaType to customize the mapping of a property or field to an XML built-in type.
Ordering Properties and Fieldes in Java to Schema Bindings
This sample application demonstrates the use of mapping annotations @XmlAccessorOrder and @XmlType.propOrder in Java classes for ordering properties and fields in Java to schema bindings.
locator-support
This sample shows how to use the new non-standard locator support. By following the instructions in the readme.txt file, you can cause all of the generated impl classes to implement a new interface that provides more information about error locations. When a ValidationEvent happens on your content tree, simply retrieve the object and cast it down to <tt>com.sun.xml.bind.extra.Locatable</tt>.
Universal Business Language (UBL)
This project processes a UBL (Universal Business Language) order instance and prints a report to the screen.
modify-marshal (formerly SampleApp2)
This sample application demonstrates how to modify a java content tree and marshal it back to XML data.
namespace-prefix
This sample application demonstrates how to use the new JAXB RI Marshaller property "com.sun.xml.bind.namespacePrefixMapper" to customize the namespace prefixes generated during marshalling.
partial-unmarshalling
In this example, the input document will be unmarshalled a small chunk at a time, instead of unmarshalling the whole document at once.
pull parser based unmarshalling
This sample app demonstrates how a pull-parser can be used with JAXB to increase the flexibility of processing.
Generating synchronized methods
This sample shows how to use the new non-standard synchronized method support. By following the instructions in the readme.txt, you can cause all of the generated impl class methods signatures to contain the "synchronized" keyword.
Type substitutoin support
This sample app demonstrates type substitution using the W3C XML Schema Part 0: Primer international purchase order schema.
Using unmarshaller (formerly SampleApp1)
This sample application demonstrates how to unmarshal an instance document into a Java content tree and access data contained within it.
validating unmarshaller (formerly SampleApp4)
This sample application demonstrates how to enable validation during the unmarshal operations.
Updateable Partial Binding using Binder
This sample application demonstrates how to partially map a DOM tree to JAXB (using JAXP 1.3 XPath), modify JAXB mapped instance and then update modifications back to the DOM tree.
RI-specific customizations
This example demonstrates how to use <xjc:superClass> vendor extensions provided by Sun's JAXB RI, as well as <jaxb:serializable> customization.
XML message passing via socket
This example demonstrates how one can use one communication channel (such as a socket) to send multiple XML messages, and how it can be combined with JAXB.
Marshalling output customization
A common customization need for the marshalling output is about introducing extra processing instruction and/or DOCTYPE declaration. This example demonstrates how such modification can be done easily.