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

DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

Copyright (c) 2012 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
http://glassfish.java.net/public/CDDL+GPL_1_1.html
or packager/legal/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 packager/legal/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="tools-schemagen-ant-task" 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>SchemaGen Ant Task</title>

    <section>
        <title><command>schemagen</command> Task Overview</title>

        <para>The <literal>jaxb-xjc.jar</literal> file contains the
        <literal>SchemaGenTask.class</literal> file, which allows the schema
        generator to be invoked from the <link
        xlink:href="http://jakarta.apache.org/ant">Ant</link> build tool. To
        use <literal>SchemaGenTask</literal>, include the following statement
        in your <literal>build.xml</literal> file:</para>

        <informalexample>
            <programlisting language="xml"><![CDATA[<taskdef name="schemagen"
         classname="com.sun.tools.jxc.SchemaGenTask">
    <classpath>
        <fileset dir="path/to/jaxb/lib" includes="*.jar"/>
    </classpath>
</taskdef>]]></programlisting>
        </informalexample>

        <para>This maps <literal>SchemaGenTask</literal> to an Ant task named
        <literal>schemagen</literal>. For detailed examples of using this
        task, refer to the <literal>build.xml</literal> files used by the java to
        schema <xref linkend="jaxb-2-0-sample-apps"
        xrefstyle="select:title" />.</para>
    </section>

    <section xml:id="section-417846742205862">
        <title><command>schemagen</command> Task Attributes</title>

        <section xml:id="section-077165761436022">
            <title>Environment Variables</title>

            <itemizedlist>
                <listitem>
                    <para><link
                    xlink:href="http://wiki.apache.org/ant/TheElementsOfAntStyle">ANT_OPTS</link>
                    - command-line arguments that should be passed to the JVM.
                    For example, you can define system properties or set the
                    maximum Java heap size here.</para>
                </listitem>
            </itemizedlist>
        </section>

        <section xml:id="section-914482811856355">
            <title>Parameter Attributes</title>

            <para><literal>schemagen</literal> supports most of the attributes
            defined by <link
            xlink:href="http://ant.apache.org/manual/CoreTasks/javac.html">the
            javac task</link>, plus the following parameter attributes.</para>

            <informaltable frame="all">
                <tgroup cols="3" colsep="1" rowsep="1">
                    <thead>
                        <row>
                            <entry><emphasis
                            role="bold">Attribute</emphasis></entry>

                            <entry><emphasis
                            role="bold">Description</emphasis></entry>

                            <entry><emphasis
                            role="bold">Required</emphasis></entry>
                        </row>
                    </thead>

                    <tbody>
                        <row>
                            <entry><para><literal>destdir</literal></para></entry>

                            <entry><para>Base directory to place the generated
                            schema files</para></entry>

                            <entry><para>No</para></entry>
                        </row>

                        <row>
                            <entry><para><literal>classpath</literal></para></entry>

                            <entry><para>Works just like the nested
                            &lt;classpath&gt; element</para></entry>

                            <entry><para>No</para></entry>
                        </row>

                        <row>
                            <entry><para><literal>episode</literal></para></entry>

                            <entry><para>If specified, generate an episode file
                            in the specified name. For more about the episode
                            file, see <xref linkend="episode"
                            xrefstyle="select:title" />.</para></entry>

                            <entry><para>No</para></entry>
                        </row>
                    </tbody>
                </tgroup>
            </informaltable>
        </section>

        <section xml:id="section-107210544982149">
            <title>Nested Elements</title>

            <para><literal>xjc</literal> supports all the nested elements
            defined by <link
            xlink:href="http://ant.apache.org/manual/CoreTasks/javac.html">the
            javac task</link>, the following nested element parameters.</para>

            <section xml:id="section-1989087498722346">
                <title><literal>schema</literal></title>

                <para>Control the file name of the generated schema. This
                element takes a mandatory <literal>namespace</literal> attribute and
                a mandaotry <literal>file</literal> attribute. When this element is
                present, the schema document generated for the specified
                namespace will be placed in the specified file name.</para>

                <para>The file name is interpreted as relative to the destdir
                attribute. In the absence of the destdir attribute, file names
                are relative to the project base directory. This element can
                be specified multiple times.</para>
            </section>

            <section xml:id="section-652997891191299">
                <title><literal>classpath</literal></title>

                <para>A <link
                xlink:href="http://ant.apache.org/manual/using.html#path">path-like
                structure</link> that represents the classpath. If your Java
                sources/classes depend on other libraries, they need to be
                available in the classpath.</para>
            </section>
        </section>
    </section>

    <section xml:id="section-9298229576523986">
        <title><command>schemagen</command> Examples</title>

        <para>Generate schema files from source files in the <literal>src</literal>
        dir and place them in the <filename>build/schemas</filename> directory.</para>

        <informalexample>
            <programlisting language="xml"><![CDATA[<schemagen srcdir="src" destdir="build/schemas">]]></programlisting>
        </informalexample>

        <para>Compile a portion of the source tree.</para>

        <informalexample>
            <programlisting language="xml"><![CDATA[<schemagen destdir="build/schemas">
    <src path="src"/>
    <exclude name="Main.java"/>
</schemagen>]]></programlisting>
        </informalexample>

        <para>Set schema file names.</para>

        <informalexample>
            <programlisting language="xml"><![CDATA[<schemagen srcdir="src" destdir="build/schemas">
    <schema namespace="http://myschema.acme.org/common"
            file="myschema-common.xsd"/>
    <schema namespace="http://myschema.acme.org/onion"
            file="myschema-onion.xsd"/>
</schemagen>]]></programlisting>
        </informalexample>
    </section>
</section>
