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

  <properties>
    <title>The Source Code Generator - Command line interface</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 Source Code Generator from a Java command
       line.
    </abstract>
    <status>Draft</status>
  </properties>

  <body>

    <title>Using the Source Code Generator from a Java command line</title>

    <section title="First steps">

      <code-panel top-caption="Example:">
java org.exolab.castor.builder.SourceGeneratorMain -i foo-schema.xsd \
    -package com.xyz
      </code-panel>

      <p>
        This will generate a set of source files from the the XML Schema
        <tt>foo-schema.xsd</tt> and place them in the package
        <tt>com.xyz</tt>.
      </p>

      <p>
        To compile the generated classes, simply run javac or your favorite
        compiler:
      </p>

      <code-panel>javac com/xyz/*.java</code-panel>

      <p>
        Created class will have marshal and unmarshal methods which are used to
        go back and forth between XML and an Object instance.
      </p>

    </section>

    <section title="Source Generator - command line options">

      <p>
        The source code generator has a number of different options which may
        be set. Some of these are done using the command line and others are
        done using a properties file located by default at
        <tt>"org/exolab/castor/builder/castorbuilder.properties"</tt>.
      </p>

      <section title="Specifying the input source">

        <p>
          There's more than one way of specifying the input for the Castor code 
          generator. <b>At least one</b> input source must be specified. 
        </p>

        <ctable border="1" cellspacing="0">
          <cheader>
            <th align="center">Option</th>
            <th>Args</th>
            <th>Description</th>
            <th>Version</th>
          </cheader>
          <crow>
            <td align="center">i</td>
            <td><i>filename</i></td>
            <td>The input XML Schema file</td>
            <td> - </td>
          </crow>
          <crow>
            <td align="center">is</td>
            <td><i>URL</i></td>
            <td>URL of an XML Schema</td>
            <td><font color="red">1.2 and newer</font></td>
          </crow>
        </ctable>
        
      </section>
      
      <section title="Other command Line Options">

        <ctable border="1" cellspacing="0">
          <cheader>
            <th align="center">Option</th>
            <th>Args</th>
            <th>Description</th>
            <th>Optional?</th>
          </cheader>
<!--           
          <crow>
            <td align="center">i</td>
            <td><i>filename</i></td>
            <td>The input XML Schema file</td>
            <td>At least one of the 'i' or 'is' attributes must be set</td>
          </crow>
          <crow>
            <td align="center">is</td>
            <td><i>input source as URL</i></td>
            <td>URL of an XML Schema</td>
            <td>At least one of the 'i' or 'is' attributes must be set</td>
          </crow>
 -->          
          <crow>
            <td align="center">package</td>
            <td><i>package-name</i></td>
            <td>The package for the generated source</td>
            <td>Optional</td>
          </crow>
          <crow>
            <td align="center">dest</td>
            <td><i>path</i></td>
            <td>
              The destination directory in which to create the generated source
            </td>
            <td>Optional</td>
          </crow>
          <crow>
            <td align="center">line-separator</td>
            <td><i>unix | mac | win</i></td>
            <td>
              Sets the line separator style for the desired platform. This is
              useful if you are generating source on one platform, but will
              be compiling/modifying on another platform.
            </td>
            <td>Optional</td>
          </crow>
          <crow>
            <td align="center">types</td>
            <td><i>type-factory</i></td>
            <td>
              Sets which type factory to use. This is useful if you want JDK
              1.2 collections instead of JDK 1.1 or if you want to pass in your
              own FieldInfoFactory (see <a href="#Collection-Types">Collection
              types</a>).
            </td>
            <td>Optional</td>
          </crow>
          <crow>
            <td align="center">h</td>
            <td><br/></td>
            <td>Shows the help/usage information.</td>
            <td>Optional</td>
          </crow>
          <crow>
            <td align="center">f</td>
            <td><br/></td>
            <td>
              Forces the source generator to suppress all non-fatal errors,
              such as overwriting pre-existing files.</td>
            <td>Optional</td>
          </crow>
          <crow>
            <td align="center">nodesc</td>
            <td><br/></td>
            <td>Do not generate the class descriptors</td>
            <td>Optional</td>
          </crow>
          <crow>
            <td align="center">gen-mapping</td>
            <td><br/></td>
            <td>(Additionally) Generate a mapping file.</td>
            <td>Optional</td>
          </crow>
          <crow>
            <td align="center">nomarshall</td>
            <td><br/></td>
            <td>
              Do not generate the marshaling framework methods (marshal,
              unmarshal, validate)</td>
            <td>Optional</td>
          </crow>
          <crow>
            <td align="center">testable</td>
            <td><br/></td>
            <td>
              Generate the extra methods used by the CTF (Castor Testing
              Framework)
            </td>
            <td>Optional</td>
          </crow>
          <crow>
            <td align="center">sax1</td>
            <td><br/></td>
            <td>
              Generate marshaling methods that use the SAX1 framework
              (default is false).
            </td>
            <td>Optional</td>
          </crow>
          <crow>
            <td align="center">binding-file</td>
            <td>The binding file name.</td>
            <td>
              Configures the use of a Binding File to allow finely-grained
              control of the generated classes
            </td>
            <td>Optional</td>
          </crow>
          <crow>
            <td align="center">generateImportedSchemas</td>
            <td><br/></td>
            <td>
              Generates sources for imported XML Schemas in addition to the
              schema provided on the command line (default is false).
            </td>
            <td>Optional</td>
          </crow>
          <crow>
            <td align="center">case-insensitive</td>
            <td><br/></td>
            <td>
              The generated classes will use a case insensitive method for
              looking up enumerated type values.
            </td>
            <td>Optional</td>
          </crow>
          <crow>
            <td align="center">verbose</td>
            <td><br/></td>
            <td>Enables extra diagnostic output from the source generator</td>
            <td>Optional</td>
          </crow>
          <crow>
            <td align="center">nameConflictStrategy</td>
            <td>Name conflict strategy.</td>
            <td>Sets the name conflict strategy to use during XML code generation</td>
            <td>Optional</td>
          </crow>
          <crow>
            <td align="center">fail</td>
            <td><br/></td>
            <td>
              Instructs the source generator to fail on the first error. When
              you are trying to figure out what is failing during source
              generation, this option will help.
            </td>
            <td>Optional</td>
          </crow>
          <crow>
            <td align="center">jclassPrintingType</td>
            <td>JClass printing mode.</td>
            <td>Specifies the JClass printing mode to use during XML code generation; possible
                values are<tt>standard</tt> (default) and <tt>velocity</tt>; if no value
                is specified, the default mode is <tt>standard</tt>.</td>
            <td>Optional</td>
          </crow>
        </ctable>

        <section title="Collection Types">

          <p>
            The source code generator has the ability to use the following
            types of collections when generating source code:
          </p>

          <ctable>
            <crow>
              <th>Type</th>
              <th>Value</th>
              <th>Default</th>
            </crow>
            <crow>
              <td>Java 1.1</td>
              <td><i>default</i></td>
              <td><tt>java.util.Vector</tt></td>
            </crow>
            <crow>
              <td>Java 1.2</td>
              <td><tt>-type j2</tt></td>
              <td><tt>java.util.Collection</tt></td>
            </crow>
            <crow>
              <td>ODMG 3.0</td>
              <td><tt>-types odmg</tt></td>
              <td><tt>odmg.DArray</tt></td>
            </crow>
          </ctable>

          <p>
            You can also write your own FieldInfoFactory to handle specific
            collection types. All you have to do is to pass in the fully
            qualified name of that FieldInfoFactory as follows:
          </p>

          <code-panel>-types com.personal.MyCoolFactory</code-panel>

        </section>

      </section>

      <tip>
        For additional information about the Source Generator and its options,
        you can download the <a href="./SourceGeneratorUser.pdf">Source
        Generator User Document (PDF).</a> Please note that the use of a
        binding file is not dicussed in that document.
      </tip>

    </section>

  </body>

</document>
