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

  <properties>
    <title>Castor XML Schema Support</title>
    <author email="blandin@intalio.com">Arnaud Blandin</author>
    <author email="edward.kuns@aspect.com">Edward Kuns</author>
    <abstract>
       Describe the features of the W3C XML Schema Recommendation supported by
       the Castor Source Code Generator.
    </abstract>
    <status>Updated to the W3C XML Schema 1.0, Second Edition Recommendation</status>
  </properties>

  <body>

    <title>Castor Source Generator XML Schema Support</title>
    <header>
        <p></p>
    </header>

    <section title="Introduction">

      <p>
        Castor XML supports the <a href="http://www.w3.org/TR/xmlschema-1/">W3C
        XML Schema 1.0 Second Edition Recommendation document (10/28/2004).</a>
        The Schema Object Model (located in the package
        <api package="org.exolab.castor.xml.schema">org.exolab.castor.xml.schema</api>)
        provides an in-memory representation of a given XML schema whereas the
        <a href="./sourcegen.xml">Source Generator</a> provides a binding
        between XML schema datatypes and structures into the corresponding ones
        in Java.
      </p>

      <p>
        The Castor Schema Object Model can read
        (<api package="org.exolab.castor.xml.schema.reader">org.exolab.castor.xml.schema.reader</api>)
        and write
        (<api package="org.exolab.castor.xml.schema.writer">org.exolab.castor.xml.schema.writer</api>)
        an XML Schema as defined by the W3C recommandation. It allows you to
        create and manipulate an in-memory view of an XML Schema.
      </p>

      <p>
        The Castor Schema Object Model supports the W3C XML Schema
        recommendation with no limitation. However the Source Generator does
        currently not offer a one to one mapping from an XML Schema component
        to a Java component for every XML Schema components; some limitations
        exist. The aim of the following sections is to provide a list of
        supported features in the Source Generator. Please keep in mind that
        the Castor Schema Object Model again can handle any XML Schema without
        limitations.
      </p>

      <p>
        Some Schema types do not have a corresponding type in Java.  Thus the
        Source Generator uses Castor implementation of these specific types
        (located in the <api package="org.exolab.castor.types"> types package</api>).
        For instance the <tt>duration</tt> type is implemented directly in
        Castor. Remember that the representation of XML Schema datatypes does
        not try to fit the W3C XML Schema specifications exactly. The aim is to
        map an XML Schema type to the Java type that is the best fit to the XML
        Schema type.
      </p>

      <p>
        You will find next a list of the supported XML Schema datatypes and
        structures in the Source Code Generator. For a more detailed support of
        XML Schema structure and more information on the Schema Object Model,
        please refer to  <a href="./SourceGeneratorUser.pdf">Source Generator
        User Document (PDF).</a>
      </p>

    </section>

    <section title="Supported XML Schema Built-in Datatypes">

      <p>
        The following is a list of the supported datatypes with the
        corresponding facets and the Java mapping type.
      </p>

      <section title="Primitive Datatypes">

        <ctable>
          <crow>
            <th align="left">XML Schema Type</th>
            <th align="left">Supported Facets</th>
            <th align="left">Java mapping type</th>
          </crow>

          <crow>
            <td valign="top">anyURI</td>
            <td>
              enumeration<br/>
            </td>
            <td valign="top"><tt>java.lang.String</tt></td>
          </crow>

          <crow>
            <td valign="top">base64Binary</td>
            <td>&#160;</td>
            <td valign="top">primitive <tt>byte[]</tt></td>
          </crow>

          <crow>
            <td valign="top">boolean</td>
            <td>
              pattern<br/>
            </td>
            <td valign="top">
              primitive <tt>boolean</tt> or <tt>java.lang.Boolean</tt><a href="#sup-2"><sup>2</sup></a>
            </td>
          </crow>

          <crow>
            <td valign="top">date</td>
            <td>
              enumeration<br/>
              maxInclusive<br/>
              maxExclusive<br/>
              minInclusive<br/>
              minExclusive<br/>
              pattern<br/>
              whitespace<a href="#sup-1"><sup>1</sup></a><!-- Only legal value is "collapse" -->
            </td>
            <td valign="top"><tt>org.exolab.castor.types.Date</tt></td>
          </crow>

          <crow>
            <td valign="top">dateTime</td>
            <td>
              enumeration<br/>
              maxInclusive<br/>
              maxExclusive<br/>
              minInclusive<br/>
              minExclusive<br/>
              pattern<br/>
              whitespace<a href="#sup-1"><sup>1</sup></a><!-- Only legal value is "collapse" -->
            </td>
            <td valign="top"><tt>java.util.Date</tt></td>
          </crow>

          <crow>
            <td valign="top">decimal</td>
            <td>
              totalDigits<br/>
              fractionDigits<br/>
              pattern<br/>
              whiteSpace<br/>
              enumeration<br/>
              maxInclusive<br/>
              maxExclusive<br/>
              minInclusive<br/>
              minExclusive<br/>
              whitespace<a href="#sup-1"><sup>1</sup></a><!-- Only legal value is "collapse" -->
            </td>
            <td valign="top"><tt>java.math.BigDecimal</tt></td>
          </crow>

          <crow>
            <td valign="top">double</td>
            <td>
              pattern<br/>
              enumeration<br/>
              maxInclusive<br/>
              maxExclusive<br/>
              minInclusive<br/>
              minExclusive<br/>
              whitespace<a href="#sup-1"><sup>1</sup></a><!-- Only legal value is "collapse" -->
            </td>
            <td valign="top">
              primitive <tt>double</tt> or <tt>java.lang.Double</tt><a href="#sup-2"><sup>2</sup></a>
            </td>
          </crow>

          <crow>
            <td valign="top">duration</td>
            <td>
              pattern<br/>
              enumeration<br/>
              maxInclusive<br/>
              maxExclusive<br/>
              minInclusive<br/>
              minExclusive<br/>
              whitespace<sup>1</sup><!-- Only legal value is "collapse" -->
            </td>
            <td valign="top"><tt>org.exolab.castor.types.Duration</tt></td>
          </crow>

          <crow>
            <td valign="top">float</td>
            <td>
              pattern<br/>
              enumeration<br/>
              maxInclusive<br/>
              maxExclusive<br/>
              minInclusive<br/>
              minExclusive<br/>
              whitespace<a href="#sup-1"><sup>1</sup></a><!-- Only legal value is "collapse" -->
            </td>
            <td valign="top">
              primitive <tt>float</tt> or <tt>java.lang.Float</tt><a href="#sup-2"><sup>2</sup></a>
            </td>
          </crow>

          <crow>
            <td valign="top">gDay</td>
            <td>
              pattern<br/>
              enumeration<br/>
              maxInclusive<br/>
              maxExclusive<br/>
              minInclusive<br/>
              minExclusive<br/>
              whitespace<a href="#sup-1"><sup>1</sup></a><!-- Only legal value is "collapse" -->
            </td>
            <td valign="top"><tt>org.exolab.castor.types.GDay</tt></td>
          </crow>

          <crow>
            <td valign="top">gMonth</td>
            <td>
              pattern<br/>
              enumeration<br/>
              maxInclusive<br/>
              maxExclusive<br/>
              minInclusive<br/>
              minExclusive<br/>
              whitespace<a href="#sup-1"><sup>1</sup></a><!-- Only legal value is "collapse" -->
            </td>
            <td valign="top"><tt>org.exolab.castor.types.GMonth</tt></td>
          </crow>

          <crow>
            <td valign="top">gMonthDay</td>
            <td>
              pattern<br/>
              enumeration<br/>
              maxInclusive<br/>
              maxExclusive<br/>
              minInclusive<br/>
              minExclusive<br/>
              whitespace<a href="#sup-1"><sup>1</sup></a><!-- Only legal value is "collapse" -->
            </td>
            <td valign="top"><tt>org.exolab.castor.types.GMonthDay</tt></td>
          </crow>

          <crow>
            <td valign="top">gYear</td>
            <td>
              pattern<br/>
              enumeration<br/>
              maxInclusive<br/>
              maxExclusive<br/>
              minInclusive<br/>
              minExclusive<br/>
              whitespace<a href="#sup-1"><sup>1</sup></a><!-- Only legal value is "collapse" -->
            </td>
            <td valign="top"><tt>org.exolab.castor.types.GYear</tt></td>
          </crow>

          <crow>
            <td valign="top">gYearMonth</td>
            <td>
              pattern<br/>
              enumeration<br/>
              maxInclusive<br/>
              maxExclusive<br/>
              minInclusive<br/>
              minExclusive<br/>
              whitespace<a href="#sup-1"><sup>1</sup></a><!-- Only legal value is "collapse" -->
            </td>
            <td valign="top"><tt>org.exolab.castor.types.GYearMonth</tt></td>
          </crow>

          <crow>
            <td valign="top">hexBinary</td>
            <td>&#160;</td>
            <td valign="top">primitive <tt>byte[]</tt></td>
          </crow>

          <crow>
            <td valign="top">QName</td>
            <td>
               length<br/>
               minLength<br/>
               maxLength<br/>
               pattern<br/>
               enumeration<br/>
            </td>
            <td valign="top"><tt>java.lang.String</tt></td>
          </crow>

          <crow>
            <td valign="top">string</td>
            <td>
              length<br/>
              minLength<br/>
              maxLength<br/>
              pattern<br/>
              enumeration<br/>
              whiteSpace<br/>
            </td>
            <td valign="top"><tt>java.lang.String</tt></td>
          </crow>

          <crow>
            <td valign="top">time</td>
            <td>
              pattern<br/>
              enumeration<br/>
              maxInclusive<br/>
              maxExclusive<br/>
              minInclusive<br/>
              minExclusive<br/>
              whitespace<a href="#sup-1"><sup>1</sup></a><!-- Only legal value is "collapse" -->
            </td>
            <td valign="top"><tt>org.exolab.castor.types.Time</tt></td>
          </crow>
        </ctable>
      </section>

      <section title="Derived Datatypes">
      
        <ctable border="1">
          <crow>
            <th align="left">Type</th>
            <th align="left">Supported Facets</th>
            <th align="left">Java mapping type</th>
          </crow>

          <crow>
            <td valign="top">byte</td>
            <td>
              totalDigits<br/>
              fractionDigits<a href="#sup-4"><sup>4</sup></a><br/>
              pattern<br/>
              enumeration<br/>
              maxInclusive<br/>
              maxExclusive<br/>
              minInclusive<br/>
              minExclusive<br/>
              whitespace<a href="#sup-1"><sup>1</sup></a><!-- Only legal value is "collapse" -->
            </td>
            <td valign="top">
              primitive <tt>byte</tt> or <tt>java.lang.Byte</tt><a href="#sup-2"><sup>2</sup></a>
            </td>
          </crow>

          <crow>
            <td valign="top">ENTITY</td>
            <td>&#160;</td>
            <td valign="top"><i>Not implemented</i></td>
          </crow>

          <crow>
            <td valign="top">ENTITIES</td>
            <td>&#160;</td>
            <td valign="top"><i>Not implemented</i></td>
          </crow>

          <crow>
            <td valign="top">ID</td>
            <td>
              enumeration<br/>
            </td>
            <td valign="top"><tt>java.lang.String</tt></td>
          </crow>

          <crow>
            <td valign="top">IDREF</td>
            <td>&#160;</td>
            <td valign="top"><tt>java.lang.Object</tt></td>
          </crow>

          <crow>
            <td valign="top">IDREFS</td>
            <td>&#160;</td>
            <td valign="top"><tt>java.util.Vector</tt> of <tt>java.lang.Object</tt></td>
          </crow>

          <crow>
            <td valign="top">int</td>
            <td>
              totalDigits<br/>
              fractionDigits<a href="#sup-4"><sup>4</sup></a><br/>
              pattern<br/>
              enumeration<br/>
              maxInclusive<br/>
              maxExclusive<br/>
              minInclusive<br/>
              minExclusive<br/>
              whitespace<a href="#sup-1"><sup>1</sup></a><!-- Only legal value is "collapse" -->
            </td>
            <td valign="top">
              primitive <tt>int</tt> or <tt>java.lang.Integer</tt><a href="#sup-2"><sup>2</sup></a>
            </td>
          </crow>

          <crow>
            <td valign="top">integer</td>
            <td>
              totalDigits<br/>
              fractionDigits<a href="#sup-4"><sup>4</sup></a><br/>
              pattern<br/>
              enumeration<br/>
              maxInclusive<br/>
              maxExclusive<br/>
              minInclusive<br/>
              minExclusive<br/>
              whitespace<a href="#sup-1"><sup>1</sup></a><!-- Only legal value is "collapse" -->
            </td>
            <td valign="top">
              primitive <tt>long</tt> or <tt>java.lang.Long</tt><a href="#sup-2"><sup>2</sup></a>
            </td>
          </crow>

          <crow>
            <td valign="top">language</td>
            <td>
              length<br/>
              minLength<br/>
              maxLength<br/>
              pattern<br/>
              enumeration<br/>
              whiteSpace<br/>
            </td>
            <td valign="top">
              treated as a <tt>xsd:string</tt><a href="#sup-3"><sup>3</sup></a>
            </td>
          </crow>

          <crow>
            <td valign="top">long</td>
            <td>
              totalDigits<br/>
              fractionDigits<a href="#sup-4"><sup>4</sup></a><br/>
              pattern<br/>
              enumeration<br/>
              maxInclusive<br/>
              maxExclusive<br/>
              minInclusive<br/>
              minExclusive<br/>
              whitespace<a href="#sup-1"><sup>1</sup></a><!-- Only legal value is "collapse" -->
            </td>
            <td valign="top">
              primitive <tt>long</tt> or <tt>java.lang.Long</tt><a href="#sup-2"><sup>2</sup></a>
            </td>
          </crow>

          <crow>
            <td valign="top">Name</td>
            <td>&#160;</td>
            <td valign="top"><i>Not implemented</i></td>
          </crow>

          <crow>
            <td valign="top">NCName</td>
            <td>
               enumeration<br/>
            </td>
            <td valign="top"><tt>java.lang.String</tt></td>
          </crow>

          <crow>
            <td valign="top">negativeInteger</td>
            <td>
              totalDigits<br/>
              fractionDigits<a href="#sup-4"><sup>4</sup></a><br/>
              pattern<br/>
              enumeration<br/>
              maxInclusive<br/>
              maxExclusive<br/>
              minInclusive<br/>
              minExclusive<br/>
              whitespace<a href="#sup-1"><sup>1</sup></a><!-- Only legal value is "collapse" -->
            </td>
            <td valign="top">
              primitive <tt>long</tt> or <tt>java.lang.Long</tt><a href="#sup-2"><sup>2</sup></a>
            </td>
          </crow>

          <crow>
            <td valign="top">NMTOKEN</td>
            <td>
               enumeration<br/>
               length<br/>
               maxlength<br/>
               minlength<br/>
            </td>
            <td valign="top"><tt>java.lang.String</tt></td>
          </crow>

          <crow>
            <td valign="top">NMTOKENS</td>
            <td>&#160;</td>
            <td valign="top"><tt>java.util.Vector</tt> of <tt>java.lang.String</tt></td>
          </crow>

          <crow>
            <td valign="top">NOTATION</td>
            <td>&#160;</td>
            <td valign="top"><i>Not implemented</i></td>
          </crow>

          <crow>
            <td valign="top">nonNegativeInteger</td>
            <td>
              totalDigits<br/>
              fractionDigits<a href="#sup-4"><sup>4</sup></a><br/>
              pattern<br/>
              enumeration<br/>
              maxInclusive<br/>
              maxExclusive<br/>
              minInclusive<br/>
              minExclusive<br/>
              whitespace<a href="#sup-1"><sup>1</sup></a><!-- Only legal value is "collapse" -->
            </td>
            <td valign="top">
              primitive <tt>long</tt> or <tt>java.lang.Long</tt><a href="#sup-2"><sup>2</sup></a>
            </td>
          </crow>

          <crow>
            <td valign="top">nonPositiveInteger</td>
            <td>
              totalDigits<br/>
              fractionDigits<a href="#sup-4"><sup>4</sup></a><br/>
              pattern<br/>
              enumeration<br/>
              maxInclusive<br/>
              maxExclusive<br/>
              minInclusive<br/>
              minExclusive<br/>
              whitespace<a href="#sup-1"><sup>1</sup></a><!-- Only legal value is "collapse" -->
            </td>
            <td valign="top">
              primitive <tt>long</tt> or <tt>java.lang.Long</tt><a href="#sup-2"><sup>2</sup></a>
            </td>
          </crow>

          <crow>
            <td valign="top">normalizedString</td>
            <td>
               enumeration<br/>
               length<br/>
               minLength<br/>
               maxLength<br/>
               pattern<br/>
            </td>
            <td valign="top"><tt>java.lang.String</tt></td>
          </crow>

          <crow>
            <td valign="top">positiveInteger</td>
            <td>
              totalDigits<br/>
              fractionDigits<a href="#sup-4"><sup>4</sup></a><br/>
              pattern<br/>
              enumeration<br/>
              maxInclusive<br/>
              maxExclusive<br/>
              minInclusive<br/>
              minExclusive<br/>
              whitespace<a href="#sup-1"><sup>1</sup></a><!-- Only legal value is "collapse" -->
            </td>
            <td valign="top">
              primitive <tt>long</tt> or <tt>java.lang.Long</tt><a href="#sup-2"><sup>2</sup></a>
            </td>
          </crow>

          <crow>
            <td valign="top">short</td>
            <td>
              totalDigits<br/>
              fractionDigits<a href="#sup-4"><sup>4</sup></a><br/>
              pattern<br/>
              enumeration<br/>
              maxInclusive<br/>
              maxExclusive<br/>
              minInclusive<br/>
              minExclusive<br/>
              whitespace<a href="#sup-1"><sup>1</sup></a><!-- Only legal value is "collapse" -->
            </td>
            <td valign="top">
              primitive <tt>short</tt> or <tt>java.lang.Short</tt><a href="#sup-2"><sup>2</sup></a>
            </td>
          </crow>

          <crow>
            <td valign="top">token</td>
            <td>
              length<br/>
              minLength<br/>
              maxLength<br/>
              pattern<br/>
              enumeration<br/>
              whiteSpace<br/>
            </td>
            <td valign="top">
              treated as a <tt>xsd:string</tt><a href="#sup-3"><sup>3</sup></a>
            </td>
          </crow>

          <crow>
            <td valign="top">unsignedByte</td>
            <td>
              totalDigits<br/>
              fractionDigits<a href="#sup-4"><sup>4</sup></a><br/>
              maxExclusive<br/>
              minExclusive<br/>
              maxInclusive<br/>
              minInclusive<br/>
              pattern<br/>
              whitespace<a href="#sup-1"><sup>1</sup></a><!-- Only legal value is "collapse" -->
            </td>
            <td valign="top">
              primitive <tt>short</tt> or <tt>java.lang.Short</tt><a href="#sup-2"><sup>2</sup></a>
            </td>
          </crow>

          <crow>
            <td valign="top">unsignedInt</td>
            <td>
              totalDigits<br/>
              fractionDigits<a href="#sup-4"><sup>4</sup></a><br/>
              maxExclusive<br/>
              minExclusive<br/>
              maxInclusive<br/>
              minInclusive<br/>
              pattern<br/>
              whitespace<a href="#sup-1"><sup>1</sup></a><!-- Only legal value is "collapse" -->
            </td>
            <td valign="top">
              primitive <tt>long</tt> or <tt>java.lang.Long</tt><a href="#sup-2"><sup>2</sup></a>
            </td>
          </crow>

          <crow>
            <td valign="top">unsignedLong</td>
            <td>
              totalDigits<br/>
              fractionDigits<a href="#sup-4"><sup>4</sup></a><br/>
              pattern<br/>
              enumeration<br/>
              maxInclusive<br/>
              maxExclusive<br/>
              minInclusive<br/>
              minExclusive<br/>
              whitespace<a href="#sup-1"><sup>1</sup></a><!-- Only legal value is "collapse" -->
            </td>
            <td valign="top"><tt>java.math.BigInteger</tt></td>
          </crow>

          <crow>
            <td valign="top">unsignedShort</td>
            <td>
              totalDigits<br/>
              fractionDigits<a href="#sup-4"><sup>4</sup></a><br/>
              pattern<br/>
              enumeration<br/>
              maxInclusive<br/>
              maxExclusive<br/>
              minInclusive<br/>
              minExclusive<br/>
              whitespace<a href="#sup-1"><sup>1</sup></a><!-- Only legal value is "collapse" -->
            </td>
            <td valign="top">
              primitive <tt>int</tt> or <tt>java.lang.Integer</tt><a href="#sup-2"><sup>2</sup></a>
            </td>
          </crow>
        </ctable>

        <p>
          Notes:
        </p>

        <p>
          <a name="sup-1"><sup>1</sup></a> For the date/time and numeric types,
          the only supported value for whitespace is "collapse".
        </p>

        <p>
          <a name="sup-2"><sup>2</sup></a> For the various numerical types, the
          default behavior is to generate primitive types.  However, if the
          use of wrappers is enabled by the following line in the
          <tt>castorbuilder.properties</tt> file:
          <code>org.exolab.castor.builder.primitivetowrapper=true</code> then
          the <tt>java.lang.*</tt> wrapper objects (as specified above) will be
          used instead.
        </p>

        <p>
          <a name="sup-3"><sup>3</sup></a> Currently, xsd:language and xsd:token
          are treated as if they were xsd:string.
        </p>

        <p>
          <a name="sup-4"><sup>4</sup></a> For the integral types, the only
          allowed value for fractionDigits is 0.
        </p>
      </section>
    </section>

    <section title="Supported XML Schema Structures">

      <p>
        Supporting XML schema structures is a constant work. The main
        structures are already supported with some limitations. The
        following will give you a rough list of the supported structures. For a
        more detailed support of XML Schema structure in the Source Generator or
        in the Schema Object Model, please refer to
        <a href="./SourceGeneratorUser.pdf">Source Generator User Document
        (PDF).</a>
      </p>

      <p>Supported schema components:</p>

      <ul>
        <li>Attribute Declaration (<tt>&lt;attribute&gt;</tt>)</li>
        <li>Element Declaration (<tt>&lt;element&gt;</tt>)</li>
        <li>ComplexType Definition (<tt>&lt;complexType&gt;</tt>)</li>
        <li>AttributeGroup Definition (<tt>&lt;attributeGroup&gt;</tt>)</li>
        <li>ModelGroup Definition (<tt>&lt;group&gt;</tt>)</li>
        <li>ModelGroup (<tt>&lt;all&gt;</tt>, <tt>&lt;choice&gt;</tt>, <tt>&lt;sequence&gt;</tt>)</li>
        <li>Annotation (<tt>&lt;annotation&gt;</tt>)</li>
        <li>Wildcard (<tt>&lt;any&gt;</tt>)</li>
        <li>SimpleType Definition (<tt>&lt;simpleType&gt;</tt>)</li>
      </ul>

      <section title="Groups">

        <p>
          Grouping support covers both Model Group Definitions
          (<tt>&lt;group&gt;</tt>) and Model Groups (<tt>&lt;all&gt;</tt>,
          <tt>&lt;choice&gt;</tt>, <tt>&lt;sequence&gt;</tt>). In this section
          we will label as a 'nested group' any Model Group whose first parent
          is another Model Group.
        </p>

        <ul>
          <li>
            For each top-level Model Group Definition, a class is generated
            either when using the 'element' mapping property or the 'type' one.
          </li>

          <li>
            If a group -- nested or not -- appears to have maxOccurs > 1 then a
            class is generated to represent the items contained in the group.
          </li>

          <li>
            For each nested group, a class is generated. The name of the
            generated class will follow this naming convention:
            <tt>Name,Compositor+,Counter?</tt> where
            <ul>
              <li>
                'Name' is name of the top-level component (element, complexType or group).
              </li>
              <li>
                'Compositor' is the compositor of the nested group.  For
                instance, if a 'choice' is nested inside a sequence, the value
                of Compositor will be <tt>SequenceChoice</tt> ('Sequence'+'Choice').
                Note: if the 'choice' is inside a Model Group and that Model
                Group <b>parent</b> is a Model Group Definition or a
                complexType then the value of'Compositor' will be only 'Choice'.
              </li>
              <li>'Counter' is a number that prevents naming collision.</li>
            </ul>
          </li>
        </ul>
      </section>

      <section title="Wildcard">
        <p>
           <tt>&lt;any&gt;</tt> is supported in the Source Generator and will
           map to an AnyNode. However full namespace validation is not yet
           implemented even though an AnyNode structure is fully namespace aware.
        </p>

        <p>
           <tt>&lt;anyAttribute&gt;</tt> is currently not supported. It is a
           work in progress.
        </p>

      </section>
    </section>

  </body>

</document>
