<?xml version="1.0" encoding="ISO-8859-1"?>
<document url="http://castor.codehaus.org/srcgen-anttask.xml">

  <properties>
    <title>The Ant Task for the Castor XML Code Generator</title>
    <author email="keith AT kvisco DOT com">Keith Visco</author>
    <author email="blandin@intalio.com">Arnaud Blandin</author>
    <abstract>
       Describes how to use the Ant task for the Castor XML Code Generator and
       what is currently supported.
    </abstract>
    <status>Draft</status>
  </properties>

  <body>

    <title>Using the Ant task for the Castor XML Code Generator</title>
    
    <header>
      <p>API Reference: <api package="org.exolab.castor.builder">The Source Builder API</api></p>
    </header>

    <section title="Castor source generator Ant task">

      <p>
        An alternative to using the command line as shown in the previous section,
        the Castor Source Generator Ant Task can be used to call the source
        generator for class generation. The only requirement is that the
        castor-&lt;version&gt;-codegen-antask.jar must be on the CLASSPATH.
      </p>

      <section title="Specifying the source for generation">

        <p>
          As shown in the subsequent table, there's multiple ways of specifying the input
          for the Castor code generator. <b>At least one</b> input source
          has to be specified. 
        </p>
      
        <ctable>
          <cheader>
            <th>Attribute</th>
            <th>Description</th>
            <th>Required</th>
            <th>Since</th>
          </cheader>
          <crow>
            <td><b>file</b></td>
            <td>The XML schema, to be used as input for the source code generator.</td>
            <td>No.</td>
            <td> - </td>
          </crow>
          <crow>
            <td><b>dir</b></td>
            <td>Sets a directory such that all XML schemas in this directory will have 
                code generated for them.</td>
            <td>No</td>
            <td> - </td>
          </crow>
          <crow>
            <td><b>schemaURL</b></td>
            <td>URL to an XML schema, to be used as input for the source code generator.</td>
            <td>No.</td>
            <td><font color="red">1.2</font></td>
          </crow>
        </ctable>     
        
        <p>
            In addition, a nested <b>&lt;fileset&gt;</b> can be specified as the source of input. 
            Please refer to the samples shown below.
        </p>
      </section>
      
      <section title="Parameters">

        <p>
          Please find below the complete list of parameters that can be set on the Castor
          source generator to fine-tune the execution behavior.
        </p>

        <ctable>
          <cheader>
            <th>Attribute</th>
            <th>Description</th>
            <th>Required</th>
            <th>Since</th>
          </cheader>
          <crow>
            <td><b>package</b></td>
            <td>The default package to be used during source code generation.</td>
            <td>No; if not given, all classes will be placed in the root package.</td>
            <td>-</td>
          </crow>
          <crow>
            <td><b>todir</b></td>
            <td>The destination directory to be used during source code generation. In
                this directory all generated Java classes will be placed.</td>
            <td>No</td>
            <td>-</td>
          </crow>
          <crow>
            <td><b>bindingfile</b></td>
            <td>A Castor source generator binding file, as detailed <a href="">here</a>.</td>
            <td>No</td>
            <td>-</td>
          </crow>
          <crow>
            <td><b>lineseparator</b></td>
            <td>Defines whether to use Unix- or Windows- or Mac-style line separators during source code generation. Possible values are: 'unix', 'win' or 'mac'.</td>
            <td>No; if not set, system property 'line.separator' is used instead.</td>
            <td>-</td>
          </crow>
          <crow>
            <td><b>types</b></td>
            <td>Defines what collection types to use (Java 1 vs. Java 2). Possible values: 'vector', 'arraylist' (aka 'j2') or 'odmg'.</td>
            <td>No; if not set, the default collection used will be Java 1 type</td>
            <td>-</td>
          </crow>
          <crow>
            <td><b>verbose</b></td>
            <td>Whether to output any logging messages as emitted by the source generator</td>
            <td>No</td>
            <td>-</td>
          </crow>
          <crow>
            <td><b>warnings</b></td>
            <td>Whether to suppress any warnings as otherwise emitted by the source generator</td>
            <td>No</td>
            <td>-</td>
          </crow>
          <crow>
            <td><b>nodesc</b></td>
            <td>If used, instructs the source generator not to generate *Descriptor classes.</td>
            <td>No</td>
            <td>-</td>
          </crow>
          <crow>
            <td><b>generateMapping</b></td>
            <td>If used, instructs the source generator to (additionally) generate a mapping
                file.</td>
            <td>No</td>
            <td>-</td>
          </crow>
          <crow>
            <td><b>nomarshal</b></td>
            <td>If specified, instructs the source generator not to create (un)marshalling
                methods within the Java classes generated.</td>
            <td>No</td>
            <td>-</td>
          </crow>
          <crow>
            <td><b>caseInsensitive</b></td>
            <td>If used, instructs the source generator to generate code for enumerated type
                lookup in a case insensitive manner.</td>
            <td>No</td>
            <td>-</td>
          </crow>
          <crow>
            <td><b>sax1</b></td>
            <td>If used, instructs the source generator to generate SAX-1 compliant code.</td>
            <td>No</td>
            <td>-</td>
          </crow>
          <crow>
            <td><b>generateImportedSchemas</b></td>
            <td>If used, instructs the source generator to generate code for imported
                schemas as well.</td>
            <td>No</td>
            <td>-</td>
          </crow>
          <crow>
            <td><b>nameConflictStrategy</b></td>
            <td>If used, sets the name conflict strategy to use during XML code generation; 
                possible values are '<tt>warnViaConsoleDialog</tt>' and 
                '<tt>informViaLog</tt>'.</td>
            <td>No</td>
            <td>-</td>
          </crow>
          <crow>
            <td><b>properties</b></td>
            <td>Location of file defining a set of properties to be used during source code
                generation. This overrides the default mechanisms of configuring the source
                generator through a <tt>castorbuilder.properties</tt> (that has to be
                placed on the CLASSPATH)</td>
            <td>No</td>
            <td>-</td>
          </crow>
          <crow>
            <td><b>automaticConflictStrategy</b></td>
            <td>If used, sets the name conflict resolution strategy used during XML 
                code generation; possible values are '<tt>type</tt>' and '<tt>xpath</tt>'
                (default being '<tt>xpath</tt>').</td>
            <td>No</td>
            <td>-</td>
          </crow>
          <crow>
            <td><b>jclassPrinterType</b></td>
            <td>Sets the mode for printing JClass instances during XML 
                code generation; possible values are '<tt>standard</tt>' and '<tt>velocity</tt>'
                (default being '<tt>standard</tt>').</td>
            <td>No</td>
            <td><font color="red">1.2.1</font></td>
          </crow>
          <crow>
            <td><b>generateJdoDescriptors</b></td>
            <td>If used, instructs the source generator to generate JDO class
                descriptors as well; default is false.</td>
            <td>No</td>
            <td><font color="red">1.2.1</font></td>
          </crow>
        </ctable>

      </section>

      <section title="Examples">
      
        <section title="Using a file">

            <p>
              Below is an example of how to use this task from within an Ant target
              definition named 'castor:gen:src':
            </p>

            <code-panel>
&lt;target name="castor:gen:src" depends="init"
         description="Generate Java source files from XSD.">

    &lt;taskdef name="castor-srcgen"
             classname="org.castor.anttask.CastorCodeGenTask"
             classpathref="castor.class.path" />
    &lt;mkdir dir="generated" />
    &lt;castor-srcgen <font color="red"><b>file=</b>"src/schema/sample.xsd"</font>
                   todir="generated-source"
                   package="org.castor.example.schema"
                   types="j2"
                   warnings="true" />
&lt;/target>
            </code-panel>

        </section>

        <section title="Using an URL">

            <p>
              Below is the same sample as above, this time using the <b>url</b> attribute
              as the source of input instead:
            </p>

            <code-panel>
&lt;target name="castor:gen:src" depends="init"
         description="Generate Java source files from XSD.">

    &lt;taskdef name="castor-srcgen"
             classname="org.castor.anttask.CastorCodeGenTask"
             classpathref="castor.class.path" />
    &lt;mkdir dir="generated" />
    &lt;castor-srcgen <font color="red"><b>schemaURL</b>="http://some.domain/some/path/sample.xsd"</font>
                   todir="generated-source"
                   package="org.castor.example.schema"
                   types="j2"
                   warnings="true" />
&lt;/target>
            </code-panel>

        </section>

        <section title="Using a nested &lt;fileset&gt;">

            <p>
              Below is the same sample as above, this time using the <b>url</b> attribute
              as the source of input instead:
            </p>

            <code-panel>
&lt;target name="castor:gen:src" depends="init"
         description="Generate Java source files from XSD.">

    &lt;taskdef name="castor-srcgen"
             classname="org.castor.anttask.CastorCodeGenTask"
             classpathref="castor.class.path" />
    &lt;mkdir dir="generated" />
    &lt;castor-srcgen todir="generated-source"
                   package="org.castor.example.schema"
                   types="j2"
                   warnings="true" >
       <font color="red"><b>&lt;fileset dir="${basedir}/src/schema">
          &lt;include name="**/*.xsd"/>
       &lt;/fileset></b></font>
    &lt;/castor-srcgen>
&lt;/target>
            </code-panel>

        </section>
        
      </section>

    </section>

  </body>

</document>
