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

    DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

    Copyright (c) 2012-2017 Oracle and/or its affiliates. All rights reserved.

    The contents of this file are subject to the terms of either the GNU
    General Public License Version 2 only ("GPL") or the Common Development
    and Distribution License("CDDL") (collectively, the "License").  You
    may not use this file except in compliance with the License.  You can
    obtain a copy of the License at
    https://oss.oracle.com/licenses/CDDL+GPL-1.1
    or LICENSE.txt.  See the License for the specific
    language governing permissions and limitations under the License.

    When distributing the software, include this License Header Notice in each
    file and include the License file at LICENSE.txt.

    GPL Classpath Exception:
    Oracle designates this particular file as subject to the "Classpath"
    exception as provided by Oracle in the GPL Version 2 section of the License
    file that accompanied this code.

    Modifications:
    If applicable, add the following below the License Header, with the fields
    enclosed by brackets [] replaced by your own identifying information:
    "Portions Copyright [year] [name of copyright owner]"

    Contributor(s):
    If you wish your version of this file to be governed by only the CDDL or
    only the GPL Version 2, indicate your decision by adding "[Contributor]
    elects to include this software in this distribution under the [CDDL or GPL
    Version 2] license."  If you don't indicate a single choice of license, a
    recipient has the option to distribute your version of this file under
    either the CDDL, the GPL Version 2 or to extend the choice of license to
    its licensees as provided above.  However, if you add GPL Version 2 code
    and therefore, elected the GPL Version 2 license, then the option applies
    only if the new code is made subject to such option by the copyright
    holder.

-->

<!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>
