| <?xml version="1.0" encoding="UTF-8"?> |
| <!-- |
| |
| Copyright (c) 2012, 2020 Oracle and/or its affiliates. All rights reserved. |
| |
| This program and the accompanying materials are made available under the |
| terms of the Eclipse Distribution License v. 1.0, which is available at |
| http://www.eclipse.org/org/documents/edl-v10.php. |
| |
| SPDX-License-Identifier: BSD-3-Clause |
| |
| --> |
| |
| <!DOCTYPE book [ |
| <!ENTITY % ents SYSTEM "docbook.ent"> |
| %ents; |
| ]> |
| <section version="5.0" xml:id="jaxb-2-0-sample-apps" xml:lang="en" |
| xmlns="http://docbook.org/ns/docbook" |
| xmlns:xlink="http://www.w3.org/1999/xlink" |
| xmlns:ns5="http://www.w3.org/1999/xhtml" |
| xmlns:ns3="http://www.w3.org/2000/svg" |
| xmlns:ns="http://docbook.org/ns/docbook" |
| xmlns:m="http://www.w3.org/1998/Math/MathML"> |
| <title>Sample Apps</title> |
| |
| <para>This page summarizes basic use-cases for Java-2-Schema, |
| Schema-2-Java, and lists all of the sample applications that ship with |
| JAXB.</para> |
| |
| <section xml:id="section-3589085759105448"> |
| <title>Using the Runtime Binding Framework</title> |
| |
| <section xml:id="section-527832527889161"> |
| <title>Schema-2-Java</title> |
| |
| <para>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:</para> |
| |
| <orderedlist> |
| <listitem> |
| <para>Develop/locate your schema</para> |
| </listitem> |
| |
| <listitem> |
| <para>Annotate the schema with binding customizations if |
| necessary (or place them in an external bindings |
| file)</para> |
| </listitem> |
| |
| <listitem> |
| <para>Compile the schema with the XJC binding |
| compiler</para> |
| </listitem> |
| |
| <listitem> |
| <para>Develop your JAXB client application using the Java |
| content classes generated by the XJC binding compiler |
| along with the <literal>jakarta.xml.bind</literal> runtime |
| framework</para> |
| </listitem> |
| |
| <listitem> |
| <para>Set your <literal>CLASSPATH</literal> to include all |
| of the <xref linkend="jars" |
| xrefstyle="select:title" /></para> |
| </listitem> |
| |
| <listitem> |
| <para>Compile all of your Java sources with |
| <literal>javac</literal></para> |
| </listitem> |
| |
| <listitem> |
| <para>Run it!</para> |
| </listitem> |
| </orderedlist> |
| </section> |
| |
| <section xml:id="section-308004238994006"> |
| <title>Java-2-Schema</title> |
| |
| <para>Java-2-Schema is the process of augmenting existing Java |
| classes with the annotations defined in the |
| <literal>jakarta.xml.bind.annotation</literal> 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:</para> |
| |
| <orderedlist> |
| <listitem> |
| <para>Develop your data model in Java</para> |
| </listitem> |
| |
| <listitem> |
| <para>Apply the <literal>jakarta.xml.bind.annotation</literal> |
| annotations to control the binding process</para> |
| </listitem> |
| |
| <listitem> |
| <para>Set your <literal>CLASSPATH</literal> to include all |
| of the <xref linkend="jars" |
| xrefstyle="select:title" /></para> |
| </listitem> |
| |
| <listitem> |
| <para>Compile your data model with |
| <literal>javac</literal></para> |
| |
| <important> |
| <para>Make sure that you <literal>CLASSPATH</literal> |
| includes <filename>jaxb-xjc.jar</filename> before |
| running <command>javac</command>.</para> |
| </important> |
| </listitem> |
| |
| <listitem> |
| <para>The resulting class files will contain your |
| annotations as well other default annotations needed by |
| the JAXB runtime binding framework</para> |
| </listitem> |
| |
| <listitem> |
| <para>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.</para> |
| </listitem> |
| |
| <listitem> |
| <para>Compile and run your client application!</para> |
| </listitem> |
| </orderedlist> |
| |
| <para>For more information about this process, see the the <link |
| xlink:href="http://docs.oracle.com/javaee/6/tutorial/doc/gijti.html">Java |
| WSDP Tutorial</link> and the extensive <xref |
| linkend="jaxb-2-0-sample-apps" xrefstyle="select:title" /> |
| documentation.</para> |
| </section> |
| |
| <section xml:id="section-3999932384958513"> |
| <title>Building and Running the Sample Apps with Ant</title> |
| |
| <para>To run the sample applications, add jaxb dependencies |
| to classpath at jaxb.home property, and run <command>ant</command> |
| without any option into each sample directory.</para> |
| |
| <para>A few sample applications do <emphasis>not</emphasis> use |
| Ant. For those samples, refer to the included |
| <filename>readme.txt</filename> files for instructions.</para> |
| </section> |
| |
| <section xml:id="samples"> |
| <title>List of Sample Apps</title> |
| |
| <variablelist> |
| <varlistentry> |
| <term><literal>samples/catalog-resolver</literal></term> |
| |
| <listitem> |
| <para>This example demonstrates how to use the |
| <option>-catalog</option> compiler switch to handle |
| references to schemas in external web sites.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>samples/character-escape</literal></term> |
| |
| <listitem> |
| <para>This example shows how you can use the new JAXB |
| RI <literal>Marshaller</literal> property |
| <literal>org.glassfish.jaxb.characterEscapeHandler</literal> |
| to change the default character escaping |
| behavior.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>samples/class-resolver</literal></term> |
| |
| <listitem> |
| <para>This little DI-container-by-JAXB example |
| demonstrates how one can avoid passing in a list of |
| classes upfront, and instead load classes |
| lazily.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>samples/create-marshal</literal></term> |
| |
| <listitem> |
| <para>This sample application demonstrates how to use |
| the <literal>ObjectFactory</literal> 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.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>samples/cycle-recovery</literal></term> |
| |
| <listitem> |
| <para>&binding.impl.name;'s vendor extension |
| <literal>CycleRecoverable</literal> provides |
| application a hook to handle cycles in the object |
| graph. Advanced.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>samples/datatypeconverter</literal></term> |
| |
| <listitem> |
| <para>This sample application is very similar to the |
| inline-customize sample application (formerly |
| <application>SampleApp6</application>), but |
| illustrates an easier, but not as robust, |
| <literal><jaxb:javaType></literal> |
| customization.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>samples/dtd</literal></term> |
| |
| <listitem> |
| <para>This sample application illustrate some of the |
| DTD support available in the &binding.impl.name;'s extension mode. |
| Please refer to the <xref linkend="jaxb-ri-extensions" |
| xrefstyle="select:title" /> page for more |
| detail.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>samples/element-substitution</literal></term> |
| |
| <listitem> |
| <para>This sample application illustrates how W3C XML |
| Schema substitution groups are supported in &binding.impl.name;'s |
| extension mode. Please refer to the <xref |
| linkend="jaxb-ri-extensions" |
| xrefstyle="select:title" /> page for more |
| detail.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>samples/external-customize</literal></term> |
| |
| <listitem> |
| <para>This sample application is identical to the |
| <application>datatypeconverter</application> sample |
| application (formerly |
| <application>SampleApp7</application>) except that the |
| binding customizations are contained in an external |
| binding file.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>samples/fix-collides</literal></term> |
| |
| <listitem> |
| <para>Another binding customization example that |
| illustrates how to resolve name conflicts. Running |
| this sample without the binding file will result in |
| name collisions (see <filename>readme.txt</filename>) |
| . Running <application>ant</application> will use the |
| binding customizations to resolve the name conflicts |
| while compiling the schema.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>samples/inline-customize</literal></term> |
| |
| <listitem> |
| <para>This sample application demonstrates how to |
| customize the default binding produced by the XJC |
| binding compiler.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>samples/j2s-crete-marshal</literal></term> |
| |
| <listitem> |
| <para>This sample application demonstrates |
| marshalling, unmarshalling and unmarshal validation |
| with existing Java classes annotated with JAXB |
| annotations.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>samples/j2s-xmlAccessorOrder</literal></term> |
| |
| <listitem> |
| <para>This sample application demonstrates the use of |
| mapping annotations |
| <literal>@XmlAccessorOrder</literal> and |
| <literal>@XmlType.propOrder</literal> in Java classes |
| for ordering properties and fields in Java to schema |
| bindings.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>samples/j2s-xmlAdapter</literal></term> |
| |
| <listitem> |
| <para>This sample application demonstrates the use of |
| interface <literal>XmlAdapter</literal> and annotation |
| <literal>XmlJavaTypeAdapter</literal> for custom |
| marshaling/unmarshaling XML content into/out of a Java |
| type.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>samples/j2s-xmlAttribute</literal></term> |
| |
| <listitem> |
| <para>This sample application demonstrates the use of |
| annotation <literal>@XmlAttribute</literal> for |
| defining Java properties and fields as XML |
| attributes.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>samples/j2s-xmlRootElement</literal></term> |
| |
| <listitem> |
| <para>This sample application demonstrates the use of |
| annotation <literal>@XmlRootElement</literal> to |
| define a class to be an XML element.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>samples/j2s-xmlSchematType</literal></term> |
| |
| <listitem> |
| <para>This sample application demonstrates the use of |
| annotation <literal>@XmlSchemaType</literal> to |
| customize the mapping of a property or field to an XML |
| built-in type.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>samples/j2s-xmlType</literal></term> |
| |
| <listitem> |
| <para>This sample application demonstrates the use of |
| mapping annotations |
| <literal>@XmlAccessorOrder</literal> and |
| <literal>@XmlType.propOrder</literal> in Java classes |
| for ordering properties and fields in Java to schema |
| bindings.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>samples/locator-support</literal></term> |
| |
| <listitem> |
| <para>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 <literal>ValidationEvent</literal> |
| happens on your content tree, simply retrieve the |
| object and cast it down to |
| <literal>com.sun.xml.bind.extra.Locatable</literal>.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>samples/modify-marshal</literal></term> |
| |
| <listitem> |
| <para>This sample application demonstrates how to |
| modify a java content tree and marshal it back to XML |
| data.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>samples/namespace-prefix</literal></term> |
| |
| <listitem> |
| <para>This sample application demonstrates how to use |
| the new &binding.impl.name; Marshaller property |
| <literal>org.glassfish.jaxb.namespacePrefixMapper</literal> |
| to customize the namespace prefixes generated during |
| marshalling.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>samples/partial-unmarshalling</literal></term> |
| |
| <listitem> |
| <para>In this example, the input document will be |
| unmarshalled a small chunk at a time, instead of |
| unmarshalling the whole document at once.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>samples/pull-parser</literal></term> |
| |
| <listitem> |
| <para>This sample app demonstrates how a pull-parser |
| can be used with JAXB to increase the flexibility of |
| processing.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>samples/streaming-unmarshalling</literal></term> |
| |
| <listitem> |
| <para>This example illustrates a different approach to |
| the streaming unmarshalling, which is suitable for |
| processing a large document.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>samples/synchronized-methods</literal></term> |
| |
| <listitem> |
| <para>This sample shows how to use the new |
| non-standard synchronized method support. By following |
| the instructions in the |
| <filename>readme.txt</filename>, you can cause all of |
| the generated impl class methods signatures to contain |
| the <literal>synchronized</literal> keyword.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>samples/type-substitution</literal></term> |
| |
| <listitem> |
| <para>This sample app demonstrates type substitution |
| using the W3C XML Schema Part 0: Primer international |
| purchase order schema.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>samples/ubl</literal></term> |
| |
| <listitem> |
| <para>This project processes a UBL (Universal Business |
| Language) order instance and prints a report to the |
| screen.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>samples/unmarshal-read</literal></term> |
| |
| <listitem> |
| <para>This sample application demonstrates how to |
| unmarshal an instance document into a Java content |
| tree and access data contained within it.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>samples/unmarshal-validate</literal></term> |
| |
| <listitem> |
| <para>This sample application demonstrates how to |
| enable validation during the unmarshal |
| operations.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>samples/updateablePartialBind</literal></term> |
| |
| <listitem> |
| <para>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.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>samples/vendor-extensions</literal></term> |
| |
| <listitem> |
| <para>This example demonstrates how to use |
| <literal><xjc:superClass></literal> vendor |
| extensions provided by &binding.impl.name;'s, as well as |
| <literal><jaxb:serializable></literal> |
| customization.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>samples/xml-channel</literal></term> |
| |
| <listitem> |
| <para>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.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>samples/xml-stylesheet</literal></term> |
| |
| <listitem> |
| <para>A common customization need for the marshalling |
| output is about introducing extra processing |
| instruction and/or <literal>DOCTYPE</literal> |
| declaration. This example demonstrates how such |
| modification can be done easily.</para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| </section> |
| </section> |
| </section> |
