<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html><head><title>Using the Source Code Generator</title><link rel="stylesheet" href="default.css"></head><body bgcolor="#ffffff" link="#6763a9" vlink="#6763a9" topmargin="0" bottommargin="0" leftmargin="0" marginheight="0" marginwidth="0"><a name="top"></a><table border="0" cellpadding="0" cellspacing="0" height="400"><tr><td width="10" valign="top" align="left" bgcolor="#7270c2"><img src="images/dotTrans.gif" width="1" height="1" border="0"></td><td width="115" valign="top" align="left" bgcolor="#7270c2"><img src="images/dotTrans.gif" width="1" height="1" border="0"></td><td width="7" valign="top" align="left"><img src="images/dotTrans.gif" border="0" width="1" height="1"></td><td width="70" valign="top" align="left"><img src="images/dotTrans.gif" width="70" height="6" border="0"></td><td width="400" valign="top" align="left"><img src="images/top_2.gif" width="400" height="6" border="0"></td><td width="120" valign="top" align="left"><img src="images/line_purple.gif" width="120" height="6" border="0"></td></tr><tr><td width="10" bgcolor="#7270c2" valign="top" align="left"><img src="images/dotTrans.gif" border="0" width="1" height="1"></td><td width="115" bgcolor="#7270c2" valign="top" align="left"><img src="images/dotTrans.gif" border="0" width="1" height="1"></td><td width="7" bgcolor="#ffffff" valign="top" align="left"></td><td width="70" valign="top" align="left"><img src="images/dotTrans.gif" width="1" height="1" border="0"></td><td width="400" valign="middle" align="left"><a href="http://www.exolab.org"><span class="menuTopOff">ExoLab</span></a> <a href="http://openejb.sf.net"><span class="menuTopOff">OpenEJB</span></a> <a href="http://openjms.sf.net"><span class="menuTopOff">OpenJMS</span></a> <a href="http://openorb.sf.net"><span class="menuTopOff">OpenORB</span></a> <a href="http://castor.exolab.org"><span class="menuTopOn">Castor</span></a> <a href="http://tyrex.sf.net"><span class="menuTopOff">Tyrex</span></a> <br><img src="images/dotTrans.gif" width="1" height="2" border="0"></td><td width="120" height="20" valign="top" align="left"> </td></tr><tr><td width="10" bgcolor="#7270c2" valign="top" align="left"><img src="images/dotTrans.gif" width="10" height="3" border="0"></td><td width="115" bgcolor="#7270c2" valign="top" align="right"><img src="images/line_sm.gif" width="105" height="3" border="0"></td><td width="7" bgcolor="#a9a5de" valign="top" align="left"><img src="images/line_sm.gif" width="7" height="3" border="0"></td><td width="70" valign="top" align="left"><img src="images/line_light.gif" width="70" height="3" border="0"></td><td width="400" valign="top" align="left"><img src="images/line_light.gif" width="400" height="3" border="0"></td><td width="120" valign="top" align="left"><img src="images/dotTrans.gif" border="0" width="1" height="1"></td></tr><tr><td bgcolor="#7270c2" valign="top" align="left"><img src="images/dotTrans.gif" width="10" height="10" border="0"></td><td width="115" bgcolor="#7270c2" valign="top" align="left"><img src="images/dotTrans.gif" width="1" height="2" border="0"><br><table border="0" cellpadding="0" cellspacing="0"><tr><td valign="top" align="left"><span class="subMenuOn">Main</span></td></tr><tr><td valign="top" align="left"> <a href="index.html"><span class="subMenuOff">Home</span></a></td></tr><tr><td valign="top" align="left"> <a href="download.html"><span class="subMenuOff">Download</span></a></td></tr><tr><td valign="top" align="left"> <a href="api/overview-summary.html"><span class="subMenuOff">API</span></a></td></tr><tr><td valign="top" align="left"> <a href="schema.html"><span class="subMenuOff">Schema</span></a></td></tr><tr><td valign="top" align="left"> <a href="lists.html"><span class="subMenuOff">Mailing Lists</span></a></td></tr><tr><td valign="top" align="left"> <a href="cvs.html"><span class="subMenuOff">CVS / Bugzilla</span></a></td></tr><tr><td valign="top" align="left"> <a href="support.html"><span class="subMenuOff">Support</span></a></td></tr></table><br><table border="0" cellpadding="0" cellspacing="0"><tr><td valign="top" align="left"><span class="subMenuOn">XML</span></td></tr><tr><td valign="top" align="left"> <a href="xml-framework.html"><span class="subMenuOff">Using XML</span></a></td></tr><tr><td valign="top" align="left"> <a href="sourcegen.html"><span class="subMenuOff">Source Generator</span></a></td></tr><tr><td valign="top" align="left"> <a href="xmlschema.html"><span class="subMenuOff">Schema Support</span></a></td></tr><tr><td valign="top" align="left"> <a href="xml-mapping.html"><span class="subMenuOff">XML Mapping</span></a></td></tr><tr><td valign="top" align="left"> <a href="xml-faq.html"><span class="subMenuOff">XML FAQ</span></a></td></tr></table><br><table border="0" cellpadding="0" cellspacing="0"><tr><td valign="top" align="left"><span class="subMenuOn">JDO</span></td></tr><tr><td valign="top" align="left"> <a href="jdo.html"><span class="subMenuOff">Using JDO</span></a></td></tr><tr><td valign="top" align="left"> <a href="database-conf.html"><span class="subMenuOff">JDO Config</span></a></td></tr><tr><td valign="top" align="left"> <a href="types.html"><span class="subMenuOff">Types</span></a></td></tr><tr><td valign="top" align="left"> <a href="jdo-mapping.html"><span class="subMenuOff">JDO Mapping</span></a></td></tr><tr><td valign="top" align="left"> <a href="jdo-faq.html"><span class="subMenuOff">JDO FAQ</span></a></td></tr><tr><td valign="top" align="left"> <a href="castor-one.html"><span class="subMenuOff">Other Features</span></a></td></tr></table><br><table border="0" cellpadding="0" cellspacing="0"><tr><td valign="top" align="left"><span class="subMenuOn">Advanced JDO</span></td></tr><tr><td valign="top" align="left"> <a href="oql.html"><span class="subMenuOff">OQL</span></a></td></tr><tr><td valign="top" align="left"> <a href="locking.html"><span class="subMenuOff">Trans. & Locks</span></a></td></tr><tr><td valign="top" align="left"> <a href="design-persist.html"><span class="subMenuOff">Design</span></a></td></tr><tr><td valign="top" align="left"> <a href="key-generator.html"><span class="subMenuOff">KeyGen</span></a></td></tr><tr><td valign="top" align="left"> <a href="long-transact.html"><span class="subMenuOff">Long Trans.</span></a></td></tr><tr><td valign="top" align="left"> <a href="nested-attr.html"><span class="subMenuOff">Nested Attrs.</span></a></td></tr><tr><td valign="top" align="left"> <a href="pooling.html"><span class="subMenuOff">Pooling Examples</span></a></td></tr><tr><td valign="top" align="left"> <a href="postgresql-blobs.html"><span class="subMenuOff">Blobs and PostgreSQL</span></a></td></tr></table><br><table border="0" cellpadding="0" cellspacing="0"><tr><td valign="top" align="left"><span class="subMenuOn">More</span></td></tr><tr><td valign="top" align="left"> <a href="presentations.html"><span class="subMenuOff">Presentations</span></a></td></tr><tr><td valign="top" align="left"> <a href="examples.html"><span class="subMenuOff">The Examples</span></a></td></tr><tr><td valign="top" align="left"> <a href="extras.html"><span class="subMenuOff">Extras and 3rd Party Tools</span></a></td></tr><tr><td valign="top" align="left"> <a href="test-framework.html"><span class="subMenuOff">Test Framework -- JDO</span></a></td></tr><tr><td valign="top" align="left"> <a href="ctf.html"><span class="subMenuOff">Test Framework -- XML</span></a></td></tr><tr><td valign="top" align="left"> <a href="conf-lib.html"><span class="subMenuOff">Configuration</span></a></td></tr><tr><td valign="top" align="left"> <a href="tips-tricks.html"><span class="subMenuOff">Tips & Tricks</span></a></td></tr><tr><td valign="top" align="left"> <a href="javadoc/overview-summary.html"><span class="subMenuOff">Full JavaDoc</span></a></td></tr></table><br><table border="0" cellpadding="0" cellspacing="0"><tr><td valign="top" align="left"><span class="subMenuOn">About</span></td></tr><tr><td valign="top" align="left"> <a href="license.html"><span class="subMenuOff">License</span></a></td></tr><tr><td valign="top" align="left"> <a href="contributors.html"><span class="subMenuOff">Contributors</span></a></td></tr><tr><td valign="top" align="left"> <a href="status.html"><span class="subMenuOff">Status, Todo</span></a></td></tr><tr><td valign="top" align="left"> <a href="changelog.html"><span class="subMenuOff">Changelog</span></a></td></tr><tr><td valign="top" align="left"> <a href="library.html"><span class="subMenuOff">Library</span></a></td></tr><tr><td valign="top" align="left"> <a href="contacts.html"><span class="subMenuOff">Contact</span></a></td></tr></table><br></td><td width="7" bgcolor="#a9a5de" valign="top" align="left"> </td><td width="70" valign="top" align="left"> </td><td rowspan="4" width="400" valign="top"><table cols="2" rows="2" border="0" cellpadding="0" cellspacing="0" width="400"><tr><td valign="top" align="left"><br><img border="0" height="34" hspace="0" src="images/castor.gif" vspace="0" width="115"><br><img border="0" height="10" hspace="0" src="images/dotTrans.gif"></td><td width="120" height="5" valign="top" align="right"><a href="http://www.exolab.org"><img src="images/logo_exolab.gif" hspace="0" vspace="10" width="77" height="20" border="0"></a></td></tr></table><p></p><p></p><br><span class="header">The Source Code Generator</span><br><br><p><span class="bodyGrey">Reference: <a href="api/org/exolab/castor/builder/package-summary.html"><api package="org.exolab.castor.builder">The Source Builder API</api></a></span></p><p><span class="bodyGrey">For a more detailed version of the Source Generator documentation, please download the <a href="./SourceGeneratorUser.pdf">Source Generator User Document(PDF).</a></span></p><span class="bodyGrey"><a href="#Introduction">Introduction</a><br></span><span class="bodyGrey"><a href="#Source-Generator-Options">Source Generator Options</a><br></span><span class="bodyGrey"><a href="#Command-Line-Options">Command Line Options</a><br></span><span class="bodyGrey"> <a href="#Collection-Types">Collection Types</a><br></span><span class="bodyGrey"><a href="#Advanced-Options">Advanced Options</a><br></span><span class="bodyGrey"> <a href="#Bound-Properties">Bound Properties</a><br></span><span class="bodyGrey"> <a href="#Class-Creation/Mapping">Class Creation/Mapping</a><br></span><span class="bodyGrey"> <a href="#The-'element'-method">The 'element' method</a><br></span><span class="bodyGrey"> <a href="#The-'type'-method">The 'type' method</a><br></span><span class="bodyGrey"> <a href="#Setting-a-super-class">Setting a super class</a><br></span><span class="bodyGrey"> <a href="#Map-XML-namespaces-to-Java-packages">Map XML namespaces to Java packages</a><br></span><span class="bodyGrey"> <a href="#Generate-equals()-method">Generate equals() method</a><br></span><span class="bodyGrey"> <a href="#Maps-java-primitive-types-to-wrapper-object">Maps java primitive types to wrapper object</a><br></span><span class="bodyGrey"><a href="#Binding-File">Binding File</a><br></span><span class="bodyGrey"><a href="#<binding>-element"><binding> element</a><br></span><span class="bodyGrey"><a href="#<include>-element"><include> element</a><br></span><span class="bodyGrey"><a href="#<package>-element"><package> element</a><br></span><span class="bodyGrey"><a href="#<namingXML>-element"><namingXML> element</a><br></span><span class="bodyGrey"><a href="#<componentBinding>-element"><componentBinding> element</a><br></span><span class="bodyGrey"><a href="#<java-class>-element"><java-class> element</a><br></span><span class="bodyGrey"><a href="#<interface>-element"><interface> element</a><br></span><span class="bodyGrey"><a href="#<member>-element"><member> element</a><br></span><span class="bodyGrey"><a href="#todo">todo</a><br></span><span class="bodyGrey"><a href="#XML-Schema">XML Schema</a><br></span><span class="bodyGrey"></span><br><a name="Introduction"><h2>Introduction</h2></a> <p><span class="bodyGrey">Castor's Source Code Generator creates a set of Java classes which represent an object model for an XML Schema (W3C XML Schema, 20010502 Recommendation)<sup>1</sup>, as well as the necessary Class Descriptors used by the <a href="xml-framework.html">marshalling framework</a> to obtain information about the generated classes. <note> Currently the generated source files will need to be compiled. We will be adding an Ant taskdef eventually to handle this automatically. </note> </span></p> <p><span class="bodyGrey">Example: <span class="bodyGrey"><pre>java org.exolab.castor.builder.SourceGenerator -i foo-schema.xsd -package com.xyz</pre></span></span></p> <p><span class="bodyGrey">This will generate a set of source files from the the XML Schema, foo-schema.xsd, and place them in the com/xyz/* package.</span></p> <p><span class="bodyGrey">To compile the generated classes simply run javac, or your favorite compiler: <span class="bodyGrey"><pre>javac com/xyz/*.java</pre></span></span></p> <p><span class="bodyGrey">Created class will have marshal and unmarshal methods which are used to go back and forth between XML and an Object instance.</span></p> <a name="Source-Generator-Options"><h2>Source Generator Options</h2></a> <p><span class="bodyGrey"> 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 at <span class="bodyGrey"><pre>"org/exolab/castor/builder/castorbuilder.properties"</pre></span>. </span></p> <a name="Command-Line-Options"><h3>Command Line Options</h3></a> <table border="1" cellspacing="0"> <tr> <th align="center">Option</th><th>Args</th><th>Description</th><th>Optional?</th> </tr> <tr> <td align="center"><span class="bodyGrey" align="center">i</span></td><td><span class="bodyGrey"><i>filename</i></span></td> <td><span class="bodyGrey">The input XML Schema file</span></td> <td><span class="bodyGrey">Required</span></td> </tr> <tr> <td align="center"><span class="bodyGrey" align="center">package</span></td><td><span class="bodyGrey"><i>package-name</i></span></td> <td><span class="bodyGrey">The package for the generated source</span></td> <td><span class="bodyGrey">Optional</span></td> </tr> <tr> <td align="center"><span class="bodyGrey" align="center">dest</span></td><td><span class="bodyGrey"><i>path</i></span></td> <td><span class="bodyGrey">The destination in which to put the generated source</span></td> <td><span class="bodyGrey">Optional</span></td> </tr> <tr> <td align="center"><span class="bodyGrey" align="center">line-separator</span></td><td><span class="bodyGrey"><i>unix | mac | win</i></span></td> <td><span class="bodyGrey"> 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. </span></td> <td><span class="bodyGrey">Optional</span></td> </tr> <tr> <td align="center"><span class="bodyGrey" align="center">types</span></td><td><span class="bodyGrey"><i>type-factory</i></span></td> <td><span class="bodyGrey">Sets which type factory to use. This is useful if you 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>) </span></td> <td><span class="bodyGrey">Optional</span></td> </tr> <tr> <td align="center"><span class="bodyGrey" align="center">h</span></td><td><span class="bodyGrey"><br></span></td> <td><span class="bodyGrey">Shows the help/usage screen</span></td> <td><span class="bodyGrey">Optional</span></td> </tr> <tr> <td align="center"><span class="bodyGrey" align="center">f</span></td><td><span class="bodyGrey"><br></span></td> <td><span class="bodyGrey"> Forces the source generator to supress all non-fatal errors, such as overwriting of pre-existing files. </span></td> <td><span class="bodyGrey">Optional</span></td> </tr> <tr> <td align="center"><span class="bodyGrey" align="center">nodesc</span></td><td><span class="bodyGrey"><br></span></td> <td><span class="bodyGrey"> Do not generate the class descriptors </span></td> <td><span class="bodyGrey">Optional</span></td> </tr> <tr> <td align="center"><span class="bodyGrey" align="center">nomarshall</span></td><td><span class="bodyGrey"><br></span></td> <td><span class="bodyGrey"> Do not generate the marshalling framework methods (marshall, unmarshall, validate) </span></td> <td><span class="bodyGrey">Optional</span></td> </tr> <tr> <td align="center"><span class="bodyGrey" align="center">testable</span></td><td><span class="bodyGrey"><br></span></td> <td><span class="bodyGrey"> Generate the specific methods used by the Castor Marshalling Framework </span></td> <td><span class="bodyGrey">Optional</span></td> </tr> <tr> <td align="center"><span class="bodyGrey" align="center">sax1</span></td><td><span class="bodyGrey"><br></span></td> <td><span class="bodyGrey"> Generate marshalling methods that are using SAX1 framework (default is false). </span></td> <td><span class="bodyGrey">Optional</span></td> </tr> <tr> <td align="center"><span class="bodyGrey" align="center">binding-file</span></td><td><span class="bodyGrey">The binding file name.</span></td> <td><span class="bodyGrey"> Allows the setting of a Binding File to allow a fine-grained control the classes generated </span></td> <td><span class="bodyGrey">Optional</span></td> </tr> </table> <a name="Collection-Types"><h4>Collection Types</h4></a> <p><span class="bodyGrey"> The source code generator has the ability to use the following types of collections when generating source code: <table border="0" cellpadding="2" cellspacing="2"><tr><td colspan="2" height="5"></td></tr><span class="bodyGrey"> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey">Java 1.1 (default): java.util.Vector</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey">Java 1.2: use the option <tt>-types j2</tt>, collection type is java.util.Collection</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey">ODMG 3.0: use the option <tt>-types odmg</tt>, collection tyoe is odmg.DArray</span></td></tr> </span></table> 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: <tt>-types com.personal.MyCoolFactory</tt> </span></p> <a name="Advanced-Options"><h3>Advanced Options</h3></a> <a name="Bound-Properties"><h4>Bound Properties</h4></a> <p><span class="bodyGrey">Since version: 0.8.9</span></p> <p><span class="bodyGrey"> Bound properties are "properties" of a class, which when updated the class will send out a java.beans.PropertyChangeEvent to all registered java.beans.PropertyChangeListeners. </span></p> <p><span class="bodyGrey">To enable bound properties uncomment the appropriate line in the "org/exolab/castor/builder/castorbuilder.properties" file: <span class="bodyBlack"><pre>
# To enable bound properties uncomment the following line. Please
# note that currently *all* fields will be treated as bound properties
# when enabled. This will change in the future when we introduce
# fine grained control over each class and it's properties.
#
#org.exolab.castor.builder.boundproperties=true
</pre></span> <p><span class="bodyGrey"> When enabled, <b>all</b> properties will be treated as bound properties. For each class that is generated a <b>setPropertyChangeListener</b> method is created as follows: <span class="bodyBlack"><pre>
<span class="bodyGrey"><font color="red">
/**
* Registers a PropertyChangeListener with this class.
* @param pcl The PropertyChangeListener to register.
**/
</font></span>
public void addPropertyChangeListener(java.beans.PropertyChangeListener pcl)
{
propertyChangeListeners.addElement(pcl);
} //-- void addPropertyChangeListener(java.beans.PropertyChangeListener)
</pre></span> Whenever a property of the class is changed, a <b>PropertyChangeEvent</b> will be sent to all registered listeners. The property name, the old value, and the new value will be set in the <b>PropertyChangeEvent</b>. <p><span class="bodyGrey"> <b> Note: To prevent unnecessary overhead, if the property is a collection, the old value will be <i>null</i>. </b> </span></p> </span></p> </span></p> <a name="Class-Creation/Mapping"><h4>Class Creation/Mapping</h4></a> <p><span class="bodyGrey">Since version: 0.8.9</span></p> <p><span class="bodyGrey"> The source generator can treat the XML Schema structures such as complexType and element in two main ways. The first, and currently default method is called the "element" method. The other is called the "type" method. </span></p> <a name="The-'element'-method"><h5>The 'element' method</h5></a> <p><span class="bodyGrey"> The "element" method creates classes for all elements whose type is a complexType. Abstract classes are created for all top-level complexTypes. Any elements whose type is a top-level type will have a new class create that extends the abstract class which was generated for that top-level complexType. </span></p> <p><span class="bodyGrey"> Classes are not created for elements whose type is a simpleType. </span></p> <a name="The-'type'-method"><h5>The 'type' method</h5></a> <p><span class="bodyGrey"> The "type" method creates classes for all top-level complexTypes, or elements that contain an "anonymous" (in-lined) complexType. </span></p> <p><span class="bodyGrey"> Classes will not be generated for elements whose type is a top-level type. </span></p> <p><span class="bodyGrey"> More information on this is forth coming. </span></p> <p><span class="bodyGrey"> To change the "method" of class creation simple edit the <b>castorbuilder.properties</b> file: <span class="bodyBlack"><pre>
# Java class mapping of <xsd:element>'s and <xsd:complexType>'s
#
#org.exolab.castor.builder.javaclassmapping=element
</pre></span> </span></p> <a name="Setting-a-super-class"><h4>Setting a super class</h4></a> <p><span class="bodyGrey">Since version: 0.8.10</span></p> <p><span class="bodyGrey"> The source generator enables the user to set a super class to <b>all</b> the generated classes (of course class descriptors are not concerned by this option) </span></p> <p><span class="bodyGrey"> To set up the super class, edit the castorbuilder.properties file : <span class="bodyBlack"><pre>
# This property allows one to specify the super class of *all*
# generated classes
#
#org.exolab.castor.builder.superclass=com.xyz.BaseObject
</pre></span> </span></p> <a name="Map-XML-namespaces-to-Java-packages"><h4>Map XML namespaces to Java packages</h4></a> <p><span class="bodyGrey">Since version: 0.9.0</span></p> <p><span class="bodyGrey"> An XML Schema grammar is identified by a namespace. For data-binding purpose it may be convenient to map namespaces to Java packages. </span></p> <p><span class="bodyGrey"> To allow the mapping between namespaces and Java packages , edit the castorbuilder.properties file : <span class="bodyBlack"><pre>
# XML namespace mapping to Java packages
#
#org.exolab.castor.builder.nspackages=\
http://www.xyz.com/schemas/project=com.xyz.schemas.project,\
http://www.xyz.com/schemas/person=com.xyz.schemas.person
</pre></span> </span></p> <a name="Generate-equals()-method"><h4>Generate equals() method</h4></a> <p><span class="bodyGrey">Since version: 0.9.1</span></p> <p><span class="bodyGrey"> The Source Generator can override the 'equals()' method for the generated objects. </span></p> <p><span class="bodyGrey">Note: hashcode() is not currently overriden.</span></p> <p><span class="bodyGrey"> To generate the equals() method , edit the castorbuilder.properties file : <span class="bodyBlack"><pre>
# Set to true if you want to generate the equals method
# for each generated class.
# false by default
#org.exolab.castor.builder.equalsmethod=true
</pre></span> </span></p> <a name="Maps-java-primitive-types-to-wrapper-object"><h4>Maps java primitive types to wrapper object</h4></a> <p><span class="bodyGrey">Since version 0.9.4</span></p> <p><span class="bodyGrey"> It may be convenient to use java objects instead of primitives, the Source Generator provides a way to do it. Thus the following mapping can be used: <table border="0" cellpadding="2" cellspacing="2"><tr><td colspan="2" height="5"></td></tr><span class="bodyGrey"> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey">boolean to java.lang.Boolean</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey">byte to java.lang.Byte</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey">double to java.lang.Double</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey">float to java.lang.Float</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey">int and integer to java.lang.Integer</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey">long to java.lang.Long</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey">short to java.lang.Short</span></td></tr> </span></table> </span></p> <p><span class="bodyGrey">To enable this property, edit the castor builder.properties file: <span class="bodyBlack"><pre>
# Set to true if you want to use Object Wrappers instead
# of primitives (e.g Float instead of float).
# false by default.
#org.exolab.castor.builder.primitivetowrapper=false
</pre></span> </span></p> <a name="Binding-File"><h2>Binding File</h2></a> <p><span class="bodyGrey">It may appear that the default binding used to generate the Java Object Model from an XML schema doesn't meet one's expectation. For instance, the default binding won't deal with naming collision problems that can appear since XML Schema allows an element declaration and a complexType definition to both share the same name. From a Java standpoint, it will result in the creation of two classes with the same qualified name: the second class generated will simply overwrite the first one. Another example is when one user wants to change the default datatype binding provided by Castor or to add validation rules by implementing his own validator and passing it to the SourceGenerator.</span></p> <p><span class="bodyGrey">The Binding declaration is an XML based language that allows the user to define such control on the generated classes. The aim of this section is to provide an overview of the binding file as well as a definition of the several XML components used to define this binding file. A more in-depth presentation will be available soon in the <a href="./SourceGeneratorUser.pdf">Source Generator User Document(PDF).</a></span></p> <a name="<binding>-element"><h3><binding> element</h3></a> <table> <tr> <span class="bodyBlack"><pre>
<binding
defaultBindingType = (element|type)>
(include*,package*,namingXML?,elementBinding*, attributeBinding, complexTypeBinding, groupBinding
</binding>
</pre></span> </tr> </table> <p><span class="bodyGrey">The binding element is the root element and contains the binding information. The attribute <span class="bodyBlack"><pre>defaultBindingType</pre></span> controls the <a href="#Class-Creation/Mapping">Class creation type</a></span></p> <a name="<include>-element"><h3><include> element</h3></a> <table> <tr> <span class="bodyBlack"><pre>
<include
URI = xsd:anyURI/>
</pre></span> </tr> </table> <table border="0" cellpadding="2" cellspacing="2"><tr><td colspan="2" height="5"></td></tr><span class="bodyGrey"> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>URI:</b>The URI of the binding file to include.</span></td></tr> </span></table> <p><span class="bodyGrey">This element allows one to include the binding declaration defined in another file. This allows re-usability of Binding files defined for various XML Schemas.</span></p> <a name="<package>-element"><h3><package> element</h3></a> <table> <tr> <span class="bodyBlack"><pre>
<package>
name = xsd:string
(namespace|schemaLocation) = xsd:string>
</package>
</pre></span> </tr> </table> <table border="0" cellpadding="2" cellspacing="2"><tr><td colspan="2" height="5"></td></tr><span class="bodyGrey"> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>name:</b>A fully qualified java package name.</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>namespace:</b>An XML namespace that will be mapped to the package name defined by the <i>name</i> element.</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>schemaLocation:</b>A URL that locates the schema to be mapped to the package name defined by the <i>name</i> element.</span></td></tr> </span></table> <p><span class="bodyGrey">The <i>targetNamespace</i> attribute of an XML Schema identifies the namespace in which the XML language is defined. Such language namespace is defined in the java language as package declaration. The <package/> element allows you to define the mapping between an XML namespace and a Java package. Moreover XML Schema allows you to factorize the definition of an XML Schema identified by a unique namespace by including several XML Schemas to build one XML Schema using the <xsd:include/> element (Please make sure you understand the difference between <xsd:include/> and <xsd:import/>). <xsd:include/> relies on the URI of the included XML schema and it can be needed to keep the structure hierarchy defined in XML Schema in the Java package generated. Thus the binding file allows to define the mapping between a schemaLocation attribute and a Java package.</span></p> <a name="<namingXML>-element"><h3><namingXML> element</h3></a> <table> <tr> <span class="bodyBlack"><pre>
<namingXML>
(elementName,complexTypeName,modelGroupName)
</namingXML>
<elementName|complexTypeName|modelGroupName>
(prefix?, suffix?) = xsd:string
</elementName|complexTypeName|modelGroupName>
</pre></span> </tr> </table> <table border="0" cellpadding="2" cellspacing="2"><tr><td colspan="2" height="5"></td></tr><span class="bodyGrey"> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>prefix:</b>The prefix to add to the names of the generated classes.</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>suffix:</b>The suffix to append to the the names of the generated classes</span></td></tr> </span></table> <p><span class="bodyGrey">One of the aim of the binding file is to avoid naming collisions. Indeed XML Schema allows elements and complexTypes to share the same name which results in name collisions when generated the sources. Defining a binding for every element and complexType that share the same name is sometimes not a convenient solution (for instance the BPML XML Schema or the UDDI v2.0 XML Schema use the same names for top-level complexTypes and top-level elements). The aim of the <naming/> XML element is to define a prefix and a suffix for the names of the classes generated for an element, a complexType or a model group definition.<br> <b>Note:</b>It is not possible to control the names of the classes generated to represent nested model groups (all, choice, sequence).</span></p> <a name="<componentBinding>-element"><h3><componentBinding> element</h3></a> <table> <tr> <span class="bodyBlack"><pre>
<elementBinding|attributeBinding|complexTypeBinding|groupBinding
name = xsd:string>
((java-class|interface|member), elementBinding*, attributeBinding*, complexTypeBinding*, groupBinding*)
</elementBinding|attributeBinding|complexTypeBinding|groupBinding>
</pre></span> </tr> </table> <table border="0" cellpadding="2" cellspacing="2"><tr><td colspan="2" height="5"></td></tr><span class="bodyGrey"> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>name:</b>The name of the XML schema component for which we are defining a binding.</span></td></tr> </span></table> <p><span class="bodyGrey">These elements are the tenets of the binding file since they contain the binding definition for an XML Schema element, attribute, complexType and modelGroup definition. The first child element (<java-class/>, <interface> or <member>) will determine the type of binding one is defining. Please note that defining a <java-class> binding on an XML Schema attribute will have absolutely no <b>effect</b>.</span></p> <p><span class="bodyGrey">The binding file being written from an XML Schema point of view; there are two distinct ways to define the XML Schema component for which we are defining a binding. First we can define it throught the <tt>name</tt> attribute.</span></p> <p><span class="bodyGrey">The value of the name attribute uniquely identifies the XML Schema Component. It can refer to the top-level component using the NCName of that component or it can use a location language based on <a href="http://www.w3.org/TR/xpath">XPath</a><sup>3</sup>. The grammar of that language can be defined by the following BNF:</span></p> <span class="bodyGrey"><pre>
[1]Path ::= LocationPath('/'LocationPath)*
[2]LocationPath ::= (Complex|ModelGroup|Attribute|Element)
[3]Complex ::= 'complexType:'<a href="http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/datatypes.html#NCName">NCName</a>
[4]ModelGroup ::= 'group:'<a href="http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/datatypes.html#NCName">NCName</a>
[5]Attribute ::= '@'<a href="http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/datatypes.html#NCName">NCName</a>
[6]Element ::= <a href="http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/datatypes.html#NCName">NCName</a>
</pre></span> <p><span class="bodyGrey">The second option to identify a XML Schema Component is to embed its binding definition inside its parent binding definition.</span></p> <p><span class="bodyGrey">For instance, the following binding definition will be equivalent and will identify the element 'foo' defined in the top-level complexType 'fooType'.</span></p> <span class="bodyGrey"><pre>
<elementBinding name="complexType:fooType/foo>
<member name="MyFoo" handler="mypackage.myHandler"/>
</elementBinding>
</pre></span> <span class="bodyGrey"><pre>
<complexTypeBinding name="fooType">
<elementBinding name="foo>
<member name="MyFoo" handler="mypackage.myHandler"/>
</elementBinding>
<complexTypeBinding>
</pre></span> <a name="<java-class>-element"><h3><java-class> element</h3></a> <table> <tr> <span class="bodyBlack"><pre>
<java-class
name? = xsd:string
package? = xsd:string
final? = xsd:boolean
abstract? = xsd:boolean
equals? = xsd:boolean
bound? = xsd:boolean >
(implements*,extends?)
</java-class>
</pre></span> </tr> </table> <table border="0" cellpadding="2" cellspacing="2"><tr><td colspan="2" height="5"></td></tr><span class="bodyGrey"> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>name:</b>The name of the class that will be generated.</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>package:</b>The package of the class to be generated. if set, this option overrides the mapping defined in the <package/> element.</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>final:</b>If true, the generated class will be final.</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>abstract:</b>If true, the generated class will be abstract.</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>equals:</b>If true, the generated class will implement the equals method.</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>bound:</b>If true, the generated class will implement the bound properties.</span></td></tr> </span></table> <p><span class="bodyGrey">This element defines all the options for the class to be generated.</span></p> <a name="<interface>-element"><h3><interface> element</h3></a> <table> <tr> <span class="bodyBlack"><pre>
<interface>
name = xsd:string
</interface>
</pre></span> </tr> </table> <table border="0" cellpadding="2" cellspacing="2"><tr><td colspan="2" height="5"></td></tr><span class="bodyGrey"> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>name:</b>The name of the interface that will be generated.</span></td></tr> </span></table> <p><span class="bodyGrey">This element specifies the name of the interface to be generated for an XML schema component.</span></p> <p><span class="bodyGrey"><b>NOTE: this element is not yet implemented.</b></span></p> <a name="<member>-element"><h3><member> element</h3></a> <table> <tr> <span class="bodyBlack"><pre>
<member
name? = xsd:string
java-type? = xsd:string
wrapper? = xsd:boolean
handler? = xsd:string
collection? = (array|vector|arraylist|hashtable|collection|odmg|set|map)
validator? = xsd:string/>
</pre></span> </tr> </table> <table border="0" cellpadding="2" cellspacing="2"><tr><td colspan="2" height="5"></td></tr><span class="bodyGrey"> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>name:</b>The name of the class member that will be generated.</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>java-type:</b>the fully qualified name of the java type.</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>wrapper:</b>If true, a wrapper object will be generated in case the java type is a java primitive.</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>handler:</b>The fully qualified name of the FieldHandler to use.</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>collection:</b>If the schema component can occur more than once then this attribute allows to specify the collection to use to represent the component in Java.</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>validator:</b>The fully qualified name of the FieldValidator to use.</span></td></tr> </span></table> <p><span class="bodyGrey">This element represents the binding for class member. It allows the definition of its name and java type as well as an implementation of FieldHandler to help the Marshalling framework in handling that member. Defining a validator is also possible. The names given for the validator and the fieldHandler must be fully qualified.</span></p> <a name="todo"><h3>todo</h3></a> <table border="0" cellpadding="2" cellspacing="2"><tr><td colspan="2" height="5"></td></tr><span class="bodyGrey"> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"> <table> <tr> <span class="bodyBlack"><pre>
<enumBinding>
(enumClassName|enumMemberName)
</enumBinding>
</pre></span> </tr> </table> <p><span class="bodyGrey">This element will allow more control on the type safe enumerations generated to represent an XML Schema simpleType enumeration</span></p> </span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"> <table> <tr> <span class="bodyBlack"><pre><javadoc/></pre></span> </tr> </table> <p><span class="bodyGrey">the javadoc element will allow one to enter the necessary javadoc that represents the generated classes or members.</span></p> </span></td></tr> </span></table> <a name="XML-Schema"><h2>XML Schema</h2></a> <p><span class="bodyGrey"> The input file to the source code generator is an XML Schema<sup>2</sup>. The current supported version is the <b>W3C XML Schema Recommendation</b><sup>1</sup>. For more information about XML Schema Support, check the <a href="xmlschema.html">XML Schema page</a> </span></p> <a name><h2></h2></a> <hr size="1" noshadow><span class="bodyGrey"><sup>1</sup>Castor 0.9.4.1 uses <a href="http://www.w3.org/TR/XMLschema-1"> XML Schema Recommendation 20010502</a><hr size="1" noshadow></span> <hr size="1" noshadow><span class="bodyGrey"> <sup>2</sup>XML Schema is a <a href="http://www.w3.org">W3C</a> Recommendation <hr size="1" noshadow></span> <hr size="1" noshadow><span class="bodyGrey"> <sup>3</sup>XPath is a <a href="http://www.w3.org">W3C</a> Recommendation <hr size="1" noshadow></span> </td></tr><tr height="5"><td width="10" height="5" bgcolor="#7270c2" valign="top" align="left"> </td><td width="115" height="5" bgcolor="#7270c2" valign="top"><img src="images/dotTrans.gif" width="1" height="15" border="0"><br><img src="images/line_sm.gif" width="105" height="3" border="0" align="right"></td><td width="7" height="5" bgcolor="#a9a5de" valign="top" align="left"> </td><td width="70" height="5" valign="top" align="left"> </td><td width="120" height="5" valign="top" align="left"> </td></tr><tr><td width="10" height="5" bgcolor="#7270c2" valign="top" align="left"> </td><td width="115" bgcolor="#7270c2" valign="top" align="left"></td><td width="7" bgcolor="#a9a5de" valign="top" align="left"><img src="images/dotTrans.gif" width="1" height="25" border="0"></td><td width="70" valign="top" align="left"><img src="images/dotTrans.gif" width="1" height="25" border="0"></td><td width="120" valign="top" align="left"> </td></tr><tr height="5"><td width="10" rowspan="2" height="100%" bgcolor="#7270c2" valign="bottom" align="left"><img src="images/stripes1.gif" width="10" height="125" border="0"></td><td width="115" rowspan="2" height="100%" bgcolor="#7270c2" valign="bottom" align="left"><img src="images/stripe105.gif" width="105" height="125" border="0"></td><td width="7" rowspan="2" height="100%" bgcolor="#a9a5de" valign="top" align="left"> </td><td width="70" height="100%" valign="top" align="left"> </td><td width="120" height="100%" valign="top" align="left"> </td></tr><tr height="5"><td width="70" height="25" valign="top" align="left"> </td><td width="400" height="25" valign="bottom" align="left"><br><br><img src="images/line_light.gif" border="0" width="400" height="3"><br><p></p><span class="bodyGrey"><small><notice> Copyright ) 1999-2003 <a href="http://www.exolab.org">ExoLab Group</a>. All rights reserved. </notice><br> <br></small><small><notice> Java, EJB, JDBC, JNDI, JTA, Sun, Sun Microsystems are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and in other countries. XML, XML Schema, XSLT and related standards are trademarks or registered trademarks of MIT, INRIA, Keio or others, and a product of the World Wide Web Consortium. All other product names mentioned herein are trademarks of their respective owners. </notice><br> <br></small></span><p></p> </td><td width="120" height="25" valign="top" align="left"> </td></tr></table></body></html>
