<?xml version="1.0" encoding="UTF-8"?>
<!--

    Copyright (c) 2012, 2021 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>javax.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>javax.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>javax.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, just go into each sample
            directory, and run <command>ant</command> without any
            option.</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>com.sun.xml.bind.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>JAXB RI'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>&lt;jaxb:javaType&gt;</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 JAXB RI'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 JAXB RI'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 JAXB RI Marshaller property
                        <literal>com.sun.xml.bind.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>&lt;xjc:superClass&gt;</literal> vendor
                        extensions provided by Sun's JAXB RI, as well as
                        <literal>&lt;jaxb:serializable&gt;</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>
