<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html><head><title>Castor XML Mapping</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">Castor XML Mapping</span><br><br><span class="bodyGrey"><a href="#1-Introduction">1 Introduction</a><br></span><span class="bodyGrey"><a href="#2-Overview">2 Overview</a><br></span><span class="bodyGrey"><a href="#2.1-Marshalling-Behavior">2.1 Marshalling Behavior</a><br></span><span class="bodyGrey"><a href="#2.2-Unmarshalling-Behavior">2.2 Unmarshalling Behavior</a><br></span><span class="bodyGrey"><a href="#3.-The-Mapping-File">3. The Mapping File</a><br></span><span class="bodyGrey"><a href="#3.1-The-<mapping>-element">3.1 The <mapping> element</a><br></span><span class="bodyGrey"><a href="#3.2-The-<class>-element--">3.2 The <class> element </a><br></span><span class="bodyGrey"><a href="#3.3-The-<map-to>-element">3.3 The <map-to> element</a><br></span><span class="bodyGrey"><a href="#3.4-The-<field>-element">3.4 The <field> element</a><br></span><span class="bodyGrey"><a href="#3.5-The-<bind-xml>-element">3.5 The <bind-xml> element</a><br></span><span class="bodyGrey"><a href="#4.-Usage-Pattern">4. Usage Pattern</a><br></span><span class="bodyGrey"><a href="#5.-xsi:type">5. xsi:type</a><br></span><span class="bodyGrey"><a href="#6.-Location-attribute">6. Location attribute</a><br></span><span class="bodyGrey"><a href="#7.-Tips">7. Tips</a><br></span><span class="bodyGrey"><a href="#7.1-Automatically-create-a-mapping-file">7.1 Automatically create a mapping file</a><br></span><span class="bodyGrey"><a href="#7.2-Create-your-own-FieldHandler">7.2 Create your own FieldHandler</a><br></span><span class="bodyGrey"><a href="#7.3-Mapping-constructor-arguments">7.3 Mapping constructor arguments</a><br></span><br><a name="1-Introduction"><h2>1 Introduction</h2></a> <p><span class="bodyGrey">Castor XML mapping is a way to simplify the binding of java classes to XML document. It allows to transform the data contained in a java object model into/from an XML document.</span></p> <p><span class="bodyGrey">Although it is possible to rely on Castor's default behavior to marshal and unmarshal Java objects into an XML document, it might be necessary to have more control over this behavior. For example, if a Java object model already exists, Castor XML Mapping can be used as a bridge between the XML document and that Java object model.</span></p> <p><span class="bodyGrey">Castor allows one to specify some of its marshalling/unmarshalling behavior using a mapping file. This file gives explicit information to Castor on how a given XML document and a given set of Java objects relate to each other.</span></p> <p><span class="bodyGrey">A Castor mapping file is a good way to dissociate the changes in the structure of a Java object model from the changes in the corresponding XML document format.</span></p> <a name="2-Overview"><h2>2 Overview</h2></a> <p><span class="bodyGrey">The mapping information is specified by an XML document. This document is written from the point of view of the Java object and describes how the properties of the object have to be translated into XML. One constraint for the mapping file is that Castor should be able to infer unambiguously from it how a given XML element/attribute has to be translated into the object model during unmarshalling.</span></p> <p><span class="bodyGrey">The mapping file describes for each object how each of its fields have to be mapped into XML. A field is an abstraction for a property of an object. It can correspond directly to a public class variable or indirectly to a property via some accessor methods (setters and getters).</span></p> <p><span class="bodyGrey">It is possible to use the mapping and Castor default behavior in conjunction: when Castor has to handle an object or an XML data but can't find information about it in the mapping file, it will rely on its default behavior. Castor will use the Java Reflection API to introspect the Java objects to determine what to do.</span></p> <p><span class="bodyGrey"><b>Note:</b> Castor can't handle all possible mappings. In some complex cases, it may be necessary to rely on an XSL transformation in conjunction with Castor to adapt the XML document to a more friendly format.</span></p> <a name="2.1-Marshalling-Behavior"><h3>2.1 Marshalling Behavior</h3></a> <p><span class="bodyGrey">For Castor, a Java class has to map into an XML element. When Castor marshals an object, it will:</span></p> <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">use the mapping information, if any, to find the name of the element to create</span></td></tr> </span></table> <p><span class="bodyGrey">or</span></p> <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">by default, create a name using the name of the class</span></td></tr> </span></table> <p><span class="bodyGrey">It will then use the fields information from the mapping file to determine how a given property of the object has to be translated into one and only one of the following:</span></p> <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">an attribute</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey">an element</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey">text content</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey">nothing, as we can choose to ignore a particular field</span></td></tr> </span></table> <p><span class="bodyGrey">This process will be recursive: if Castor finds a property that has a class type specified elsewhere in the mapping file, it will use this information to marshal the object.</span></p> <p><span class="bodyGrey">By default, if Castor finds no information for a given class in the mapping file, it will introspect the class and apply a set of default rules to guess the fields and marshal them. The default rules are as follows:</span></p> <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">All primitive types, including the primitive type wrappers (Boolean, Short, etc...) are marshalled as attributes.</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey">All other objects are marshalled as elements with either text content or element content.</span></td></tr> </span></table> <a name="2.2-Unmarshalling-Behavior"><h3>2.2 Unmarshalling Behavior</h3></a> <p><span class="bodyGrey">When Castor finds an element while unmarshalling a document, it will try to use the mapping information to determine which object to instantiate. If no mapping information is present, Castor will use the name of the element to try to guess the name of a class to instantiate (for example, for an element named 'test-element', Castor will try to instantiate a class named 'TestElement' if no information is given in the mapping file). Castor will then use the field information of the mapping file to handle the content of the element.</span></p> <p><span class="bodyGrey">If the class is not described in the mapping file, Castor will instrospect the class using the Java Reflection API to determine if there is any function of the form getXxxYyy()/setXxxYyy(<type> x). This accessor will be associated with XML element/attribute named 'xxx-yyy'. In the future, we will provide a way to override this default behavior.</span></p> <p><span class="bodyGrey">Castor will introspect object variables and use direct access _only_ if no get/set methods have been found in the class. In this case, Castor will look for public variables of the form:</span></p> <span class="bodyBlack"><pre>
public <type> xxxYYY;
</pre></span> <p><span class="bodyGrey">and expect an element/attribute named 'xxx-yyy'. The only handled collections for <type> are java.lang.Vector and array. (up to version 0.8.10)</span></p> <p><span class="bodyGrey">For primitive <type>, Castor will look for an attribute first and then an element. If <type> is not a primitive type, Castor will look for an element first and then an attribute.</span></p> <a name="3.-The-Mapping-File"><h2>3. The Mapping File</h2></a> <a name="3.1-The-<mapping>-element"><h3>3.1 The <mapping> element</h3></a> <span class="bodyBlack"><pre>
<!ELEMENT mapping ( description?, include*, class*, key-generator* )>
</pre></span> <p><span class="bodyGrey">The <mapping> element is the root element of a mapping file. It contains:</span></p> <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">an optional description</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey">zero or more <include> which facilitates reusing mapping files</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey">zero or more <class> descriptions: one for each class we intend to give mapping information</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey">zero or more <key-generator>: not used for XML mapping</span></td></tr> </span></table> <p><span class="bodyGrey">A mapping file look like this:</span></p> <span class="bodyBlack"><pre>
<?xml version="1.0"?>
<!DOCTYPE mapping PUBLIC "-//EXOLAB/Castor Object Mapping DTD Version 1.0//EN"
"http://castor.exolab.org/mapping.dtd">
<mapping>
<description>Description of the mapping</description>
<include href="other_mapping_file.xml"/>
<class name="A">
.........
</class>
<class name="B">
.........
</class>
</mapping>
</pre></span> <a name="3.2-The-<class>-element--"><h3>3.2 The <class> element </h3></a> <span class="bodyBlack"><pre>
<!ELEMENT class ( description?, cache-type?, map-to?, field+ )>
<!ATTLIST class
name ID #REQUIRED
extends IDREF #IMPLIED
depends IDREF #IMPLIED
auto-complete ( true |false ) "false"
identity CDATA #IMPLIED
access ( read-only | shared | exclusive | db-locked ) "shared"
key-generator IDREF #IMPLIED >
</pre></span> <p><span class="bodyGrey">The <class> element contains all the information used to map a Java class into an XML document. The content of <class> is mainly used to describe the fields that will be mapped.</span></p> <p><span class="bodyGrey">Description of the attributes:</span></p> <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 Java class that we want to map to. It should look like 'mypackage.myclass'</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>extends:</b> should be used _only_ if this class extends another class for which mapping information is provided. It should _not_ be used if the extended class is not used in the mapping file.</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>depends:</b> for more information on this fields see JDO documentation.</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>auto-complete:</b> if true, the class will be introspected to determine its field and the fields specified in the mapping file will be used to overide the field found during the introspection.</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>identity:</b> for more information on this fields see JDO documentation</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>access:</b> for more information on this fields see JDO documentation</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>key-generator</b>: for more information on this fields see JDO documentation</span></td></tr> </span></table> <p><span class="bodyGrey">The auto-complete attributes is interesting as it allow a fine degree of control of the introspector: it is possible to specifiy only the fields whose Castor default behavior does not suite our needs. These feature should simplify the handling of complexe class containing many fields.</span></p> <p><span class="bodyGrey">Description of the content:</span></p> <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>description</b>: an optional <description></span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>cache-type:</b> for more information on this field see JDO documentation</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>an optional <map-to></b>. Used if the name of the element is not the name of the class. By default, Castor will infer the name of the element to be mapped from the name of the class: a Java class named 'XxxYyy' will be transformed in 'xxx-yyy'. If you don't want Castor to generate the name, you need to use <map-to> to specify the name you want to use. <map-to> is only used for the root element.</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>field:</b> zero or more <field> which are used to describe properties of the Java objects.</span></td></tr> </span></table> <p><span class="bodyGrey">If you want to map the following class into the element '<data>':</span></p> <span class="bodyBlack"><pre>
package mypackage
public class myclass {
...
public int foo;
...
public String getBar()
...
public void setBar(String bar)
...
}
</pre></span> <p><span class="bodyGrey">Into an XML document like:</span></p> <span class="bodyBlack"><pre>
<data foo-like="12">
<something>
...
</something>
</data>
</pre></span> <p><span class="bodyGrey">You might use the following mapping file:</span></p> <span class="bodyBlack"><pre>
<mapping>
...
<class name="mypackage.myclass">
<map-to xml="data"/>
<field name="foo"
direct="true"
....
>
<bind-xml name="foo-like" node="attribute"/>
</field>
</field name="bar"
....
>
<bind-xml name="something" node="element"/>
</field>
</class>
...
</mapping>
</pre></span> <a name="3.3-The-<map-to>-element"><h3>3.3 The <map-to> element</h3></a> <span class="bodyBlack"><pre>
<!ELEMENT map-to EMPTY>
<!ATTLIST map-to
table NMTOKEN #IMPLIED
xml NMTOKEN #IMPLIED
ns-uri NMTOKEN #IMPLIED
ns-prefix NMTOKEN #IMPLIED
ldap-dn NMTOKEN #IMPLIED
ldap-oc NMTOKEN #IMPLIED>
</pre></span> <p><span class="bodyGrey"><map-to> is used to specify the name of the element that should be associated with the given class.<map-to> is only used for the root class. If this information is not present, Castor will:</span></p> <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">for marshalling, infer the name of the element to be mapped from the name of the class: a Java class named 'XxxYyy' will be transformed into 'xxx-yyy'.</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey">for unmarshalling, infer the name of the class from the name of the element : for an element named 'test-element' Castor will try to use a class named 'TestElement'</span></td></tr> </span></table> <p><span class="bodyGrey">Description of the attributes:</span></p> <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>xml:</b> name of the element that the class is associated to.</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>ns-uri</b>: namespace URI</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>ns-prefix:</b> desired namespace</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>ldap-dn:</b> not used for XML</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>ldap-oc:</b> not used for XML</span></td></tr> </span></table> <a name="3.4-The-<field>-element"><h3>3.4 The <field> element</h3></a> <span class="bodyBlack"><pre>
<!ELEMENT field ( description?, sql?, xml?, ldap? )>
<!ATTLIST field
name NMTOKEN #REQUIRED
type NMTOKEN #IMPLIED
handler NMTOKEN #IMPLIED
required ( true | false ) "false"
direct ( true | false ) "false"
lazy ( true | false ) "false"
transient ( true | false ) "false"
get-method NMTOKEN #IMPLIED
set-method NMTOKEN #IMPLIED
create-method NMTOKEN #IMPLIED
collection ( array | vector | hashtable | collection | set | map ) #IMPLIED>
</pre></span> <p><span class="bodyGrey"><field> is used to describe a property of a Java object we want to marshal/unmarshal. It gives:</span></p> <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">its identity ('name')</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey">its type (infered from 'type' and 'collection')</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey">its access method (infered from 'direct', 'get-method', 'set-method')</span></td></tr> </span></table> <p><span class="bodyGrey">From this information, Castor is able to access a given property in the Java class.</span></p> <p><span class="bodyGrey">In order to determine the signature that Castor expects, there are two easy rules to apply.</span></p> <p><span class="bodyGrey"><b>1. Determine <type>.</b></span></p> <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"><p><span class="bodyGrey"><b>If there is no 'collection' attribute</b>, the <type> is just the Java type specified in <type_attribute> (the value of the 'type' attribute in the XML document). The value of <type_attribute> can be a fully qualified Java object like 'java.lang.String' or one of the allowed short name:</span></p> <table border="1" cellpadding="4"> <tr><th>short name</th><th>Primitive type?</th><th>Java Class</th></tr> <tr><td><span class="bodyGrey">other</span></td><td><span class="bodyGrey">N</span></td><td><span class="bodyGrey">java.lang.Object</span></td></tr> <tr><td><span class="bodyGrey">string</span></td><td><span class="bodyGrey">N</span></td><td><span class="bodyGrey">java.lang.String</span></td></tr> <tr><td><span class="bodyGrey">integer</span></td><td><span class="bodyGrey">Y</span></td><td><span class="bodyGrey">java.lang.Integer.TYPE</span></td></tr> <tr><td><span class="bodyGrey">long</span></td><td><span class="bodyGrey">Y</span></td><td><span class="bodyGrey">java.lang.Long.TYPE</span></td></tr> <tr><td><span class="bodyGrey">boolean</span></td><td><span class="bodyGrey">Y</span></td><td><span class="bodyGrey">java.lang.Boolean.TYPE</span></td></tr> <tr><td><span class="bodyGrey">double</span></td><td><span class="bodyGrey">Y</span></td><td><span class="bodyGrey">java.lang.Double.TYPE</span></td></tr> <tr><td><span class="bodyGrey">float</span></td><td><span class="bodyGrey">Y</span></td><td><span class="bodyGrey">java.lang.Float.TYPE</span></td></tr> <tr><td><span class="bodyGrey">big-decimal</span></td><td><span class="bodyGrey">N</span></td><td><span class="bodyGrey">java.math.BigDecimal</span></td></tr> <tr><td><span class="bodyGrey">byte</span></td><td><span class="bodyGrey">Y</span></td><td><span class="bodyGrey">java.lang.Byte.TYPE</span></td></tr> <tr><td><span class="bodyGrey">date</span></td><td><span class="bodyGrey">N</span></td><td><span class="bodyGrey">java.util.Date</span></td></tr> <tr><td><span class="bodyGrey">short</span></td><td><span class="bodyGrey">Y</span></td><td><span class="bodyGrey">java.lang.Short.TYPE</span></td></tr> <tr><td><span class="bodyGrey">char</span></td><td><span class="bodyGrey">Y</span></td><td><span class="bodyGrey">java.lang.Character.TYPE</span></td></tr> <tr><td><span class="bodyGrey">bytes</span></td><td><span class="bodyGrey">N</span></td><td><span class="bodyGrey">byte[]</span></td></tr> <tr><td><span class="bodyGrey">chars</span></td><td><span class="bodyGrey">N</span></td><td><span class="bodyGrey">char[]</span></td></tr> <tr><td><span class="bodyGrey">strings</span></td><td><span class="bodyGrey">N</span></td><td><span class="bodyGrey">String[]</span></td></tr> <tr><td><span class="bodyGrey">locale</span></td><td><span class="bodyGrey">N</span></td><td><span class="bodyGrey">java.util.Locale</span></td></tr> </table> <p><span class="bodyGrey">Castor will try to cast the data in the XML file in the proper Java type.</span></p></span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>If there is a collection attribute</b>, you can use the following table: <table border="1" cellpadding="4"> <tr><th>name</th><th><type></th><th>default implementation</th></tr> <tr><td><span class="bodyGrey">array</span></td><td><span class="bodyGrey"><type_attribute>[]</span></td><td><span class="bodyGrey"><type_attribute>[]</span></td></tr> <tr><td><span class="bodyGrey">arraylist</span></td><td><span class="bodyGrey">java.util.ArrayList</span></td><td><span class="bodyGrey">java.util.Arraylist </span></td></tr> <tr><td><span class="bodyGrey">vector</span></td><td><span class="bodyGrey">java.util.Vector</span></td><td><span class="bodyGrey">java.util.Vector</span></td></tr> <tr><td><span class="bodyGrey">hashtable</span></td><td><span class="bodyGrey">java.util.Hashtable</span></td><td><span class="bodyGrey">java.util.Hashtable</span></td></tr> <tr><td><span class="bodyGrey">collection</span></td><td><span class="bodyGrey">java.util.Collection</span></td><td><span class="bodyGrey">java.util.Arraylist </span></td></tr> <tr><td><span class="bodyGrey">set</span></td><td><span class="bodyGrey">java.util.Set</span></td><td><span class="bodyGrey">java.util.Hashset</span></td></tr> <tr><td><span class="bodyGrey">map</span></td><td><span class="bodyGrey">java.util.Map</span></td><td><span class="bodyGrey">java.util.Hashmap</span></td></tr> </table> <p><span class="bodyGrey">The type of the object inside the collection is <type_attribute>. The 'default implementation' is the type used if the object holding the collection is found to be null and need to be instantiated.</span></p> <p><span class="bodyGrey">For hashtable and map, Castor will add an object with put(object, object): the object is both the key and the value. This will be improved in the future.</span></p></span></td></tr> </span></table> <p><span class="bodyGrey">It is necessary to use a collection when the content model of the element expects more than one element of the specified type.</span></p> <p><span class="bodyGrey"><b>2. Determine the signature of the function</b></span></p> <li> <p><span class="bodyGrey"><b>If 'direct' is set to true</b>, Castor expects to find a class variable with the given signature:</span></p> <span class="bodyBlack"><pre>
public <type> <name>;
</pre></span> <li><p><span class="bodyGrey"><b>If 'direct' is set to false or omitted</b>, Castor will access the property though accessor methods. Castor determines the signature of the accessors as follow: If the 'get-method' or 'set-method' attributes are supplied, it will try to find a function with the following signature:</span></p> <span class="bodyBlack"><pre>
public <type> <get-method>();
</pre></span> or <span class="bodyBlack"><pre>
public void <set-method>(<type> value);
</pre></span> <p><span class="bodyGrey">If 'get-method' and 'set-method' attributes are not provided, Castor will try to find the following function:</span></p> <span class="bodyBlack"><pre>
public <type> get<capitalized-name>();
</pre></span> or <span class="bodyBlack"><pre>
public void set<capitalized-name>(<type> value);
</pre></span> <p><span class="bodyGrey"><capitalized-name> means that Castor takes the <name> attribute and put its first letter in uppercase without modifying the other letters.</span></p> <p><span class="bodyGrey">The content of <field> will contain the information on how to map this given field to SQL, XML, ...</span></p> <p><span class="bodyGrey">Description of the attributes: </span></p> <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 field 'name' is required even if no such field exists in the class. If 'direct' access is used, 'name' should be the name of a public variable in the object we are mapping (The field must be public, not static and not transient). If no direct access and no 'get-/set-method' is specified, this name will be used to infer the name of the accessors methods.</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>type:</b> the Java type of the field. It is used to access the field. Castor will use this information to cast the XML information (like string into integer). It is also used to define the signature of the accessors method. If a collection is specified, this is used to specify the type of the object inside the collection. See description above for more details.</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>required:</b> the field can the optional or required</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>transient:</b> if true, this field will be ignored during the marshalling. This is usefull in when used with the auto-complete option.</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>direct:</b> if true, Castor will expect a public variable in the object and will modify it directly</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>collection:</b> if a parent expects more than one occurrence of one of its element, it is necessary to specify which collection Castor will use to handle them. The type specified is used to define the type of the content inside the collection.</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>get-method:</b> optional name of the get method Castor should use. If this attribute is not set and the set-method attribute is not set, then Castor will try to guess the name with the algorithm described above.</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>set-method:</b> optional name of the set method Castor should use. If this attribute is not set and the get-method attribute is not set, then Castor will try to guess the name with the algorithm described above. <p><span class="bodyGrey"> <a name="constructor-args"></a> <b>*Now supported (since 0.9.5) for <i>attribute</i> mapped fields, you may map a constructor field using the set-method attribute.</b> </span></p> <p><span class="bodyGrey"> To specify a constructor argument use "%1" - "%9" as the value of the set-method attribute. </span></p> <p><span class="bodyGrey"> For example:<br> <span class="bodyBlack"><pre>
<field name="foo" set-method="%1" get-method="getFoo" type="string">
<bind-xml node="attribute"/>
</field>
</pre></span> Note that because the set-method is specified, the get-method also must be specified...a bit of an annoyance, but at least there is now a way to handle this feature. </span></p> </span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>create-method:</b> Factory method for instantiation of FieldHandler</span></td></tr> </span></table> <p><span class="bodyGrey">Description of the content:</span></p> <p><span class="bodyGrey">In the case of XML mapping, the content of a field element should be one and only one <xml> element describing how this given field will be mapped into the XML document.</span></p> <a name="3.5-The-<bind-xml>-element"><h3>3.5 The <bind-xml> element</h3></a> <span class="bodyBlack"><pre>
<!ELEMENT bind-xml EMPTY>
<!ATTLIST bind-xml
name NMTOKEN #IMPLIED
type NMTOKEN #IMPLIED
location CDATA #IMPLIED
matches NMTOKENS #IMPLIED
QName-prefix NMTOKEN #IMPLIED
reference ( true | false ) "false"
node ( attribute | element | text ) #IMPLIED
auto-naming ( deriveByClass | deriveByField ) #IMPLIED
transient ( true | false ) "false">
</pre></span> <p><span class="bodyGrey"><bind-xml> is used to describe how a given Java field should appear in an XML document. It is used both for marshalling and unmarshalling.</span></p> <p><span class="bodyGrey">Description of the attributes:</span></p> <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 element or attribute</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>auto-naming:</b> if no name is specified this attribute controls how castor will automatically create a name for the field. Normally the name is created using the field name, however many times it is necessary to create the name by using the class type instead (such as heterogenenous collections). </span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>type:</b>XML Schema type (of the value of this field) that requires specific handling in the Castor Marshalling Framework (such as 'QName' for instance). </span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>location:</b> (since 0.9.4.4) allows the user to specify the "sub-path" for which the value should be marshalled to and from. This is useful for "wrapping" values in elements or for mapping values that appear on sub-elements to the current "element" represented by the class mapping. For more information see the <a href="#6.-Location-attribute">Location attribute</a> below. </span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>QName-prefix:</b> When using a QName value, you can provide a default prefix that is used when marshalling value of type QName. More information on the use of 'QName-prefix' can be found in the <a href="./SourceGeneratorUser.pdf">SourceGenerator Documentation</a></span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>reference:</b> Indicates if this field has to be treated as a reference by the unmarshaller. In order to work properly, you must specify the node type to 'attribute' for both the 'id' and the 'reference'.</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>matches:</b> Allows overriding the matches rules for the name of the element. It is a standard regular expression and will be used instead of the 'name' field. A '*' will match any xml name, however it will only be matched if no other field exists that matches the xml name. </span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>node:</b> indicates if the name corresponds to an attribute, an element, or text content. By default, primitive types are assumed to be an attribute otherwise the node is assumed to be an element</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>transient:</b> Allows for making this field transient for XML. The default value is inherited from the <field> element. </span></td></tr> </span></table> <a name="4.-Usage-Pattern"><h2>4. Usage Pattern</h2></a> <p><span class="bodyGrey">Here is an example of how Castor Mapping can be used. We want to map an XML document like the following one (called 'order.xml'). model.</span></p> <table border="1" cellpadding="4"> <tr><td bgcolor="#CCCCCC"><span class="bodyGrey" bgcolor="#CCCCCC"> <span class="bodyBlack"><pre>
<Order reference="12343-AHSHE-314159">
<Client>
<Name>Jean Smith</Name>
<Address>2000, Alameda de las Pulgas, San Mateo, CA 94403</Address>
</Client>
<Item reference="RF-0001">
<Description>Stuffed Penguin</Description>
<Quantity>10</Quantity>
<UnitPrice>8.95</UnitPrice>
</Item>
<Item reference="RF-0034">
<Description>Chocolate</Description>
<Quantity>5</Quantity>
<UnitPrice>28.50</UnitPrice>
</Item>
<Item reference="RF-3341">
<Description>Cookie</Description>
<Quantity>30</Quantity>
<UnitPrice>0.85</UnitPrice>
</Item>
</Order>
</pre></span> </span></td></tr> </table> <p><span class="bodyGrey">Into the following object model composed of 3 classes:</span></p> <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>MyOrder:</b> represent an order</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>Client:</b> used to store information on the client</span></td></tr> <tr><td align="left" valign="top" width="10">-</td><td align="left" valign="top"><span class="bodyGrey"><b>Item:</b> used to store item in an order</span></td></tr> </span></table> <p><span class="bodyGrey">The sources of these classes follow.</span></p> <table border="1" cellpadding="4"> <tr> <th> MyOrder.java </th> </tr> <tr> <td bgcolor="#CCCCCC"><span class="bodyGrey" bgcolor="#CCCCCC"> <span class="bodyBlack"><pre>
import java.util.Vector;
import java.util.Enumeration;
public class MyOrder {
private String _ref;
private ClientData _client;
private Vector _items;
private float _total;
public void setReference(String ref) {
_ref = ref;
}
public String getReference() {
return _ref;
}
public void setClientData(ClientData client) {
_client = client;
}
public ClientData getClientData() {
return _client;
}
public void setItemsList(Vector items) {
_items = items;
}
public Vector getItemsList() {
return _items;
}
public void setTotal(float total) {
_total = total;
}
public float getTotal() {
return _total;
}
// Do some processing on the data
public float getTotalPrice() {
float total = 0.0f;
for (Enumeration e = _items.elements() ; e.hasMoreElements() ;) {
Item item = (Item) e.nextElement();
total += item._quantity * item._unitPrice;
}
return total;
}
}
</pre></span> </span></td> </tr> </table> <table border="1" cellpadding="4"> <tr> <th> ClientData.java </th> </tr> <tr> <td bgcolor="#CCCCCC"><span class="bodyGrey" bgcolor="#CCCCCC"> <span class="bodyBlack"><pre>
public class ClientData {
private String _name;
private String _address;
public void setName(String name) {
_name = name;
}
public String getName() {
return _name;
}
public void setAddress(String address) {
_address = address;
}
public String getAddress() {
return _address;
}
}
</pre></span> </span></td> </tr> </table> <table border="1" cellpadding="4"> <tr> <th> Item.java </th> </tr> <tr> <td bgcolor="#CCCCCC"><span class="bodyGrey" bgcolor="#CCCCCC"> <span class="bodyBlack"><pre>
public class Item {
public String _reference;
public int _quantity;
public float _unitPrice;
public String _description;
}
</pre></span> </span></td> </tr> </table> <p><span class="bodyGrey">The XML document and the java object model can be connected by using the following mapping file:</span></p> <table border="1" cellpadding="4"> <tr> <th> mapping.xml </th> </tr> <tr> <td bgcolor="#CCCCCC"><span class="bodyGrey" bgcolor="#CCCCCC"> <span class="bodyBlack"><pre>
<?xml version="1.0"?>
<!DOCTYPE mapping PUBLIC "-//EXOLAB/Castor Object Mapping DTD Version 1.0//EN"
"http://castor.exolab.org/mapping.dtd">
<mapping>
<class name="MyOrder">
<map-to xml="Order"/>
<field name="Reference"
type="java.lang.String">
<bind-xml name="reference" node="attribute"/>
</field>
<field name="Total"
type="float">
<bind-xml name="total-price" node="attribute"/>
</field>
<field name="ClientData"
type="ClientData">
<bind-xml name="Client"/>
</field>
<field name="ItemsList"
type="Item"
collection="vector">
<bind-xml name="Item"/>
</field>
</class>
<class name="ClientData">
<field name="Name"
type="java.lang.String">
<bind-xml name="Name" node="element"/>
</field>
<field name="Address"
type="java.lang.String">
<bind-xml name="Address" node="element"/>
</field>
</class>
<class name="Item">
<field name="_reference"
type="java.lang.String"
direct="true">
<bind-xml name="reference" node="attribute"/>
</field>
<field name="_quantity"
type="integer"
direct="true">
<bind-xml name="Quantity" node="element"/>
</field>
<field name="_unitPrice"
type="float"
direct="true">
<bind-xml name="UnitPrice" node="element"/>
</field>
<field name="_description"
type="string"
direct="true">
<bind-xml name="Description" node="element"/>
</field>
</class>
</mapping>
</pre></span> </span></td> </tr> </table> <p><span class="bodyGrey">The following class is an example of how to use Castor XML Mapping to manipulate the file 'order.xml'. It unmarshals the document 'order.xml', computes the total price, sets the total price in the java object and marshals the object model back into XML with the calculated price.</span></p> <table border="1" cellpadding="4"> <tr> <th> main.java </th> </tr> <tr> <td bgcolor="#CCCCCC"><span class="bodyGrey" bgcolor="#CCCCCC"> <span class="bodyBlack"><pre>
import org.exolab.castor.mapping.Mapping;
import org.exolab.castor.mapping.MappingException;
import org.exolab.castor.xml.Unmarshaller;
import org.exolab.castor.xml.Marshaller;
import java.io.IOException;
import java.io.FileReader;
import java.io.OutputStreamWriter;
import org.xml.sax.InputSource;
public class main {
public static void main(String args[]) {
Mapping mapping = new Mapping();
try {
<span class="bodyGrey"><font color="red">// 1. Load the mapping information from the file</font></span>
mapping.loadMapping( "mapping.xml" );
<span class="bodyGrey"><font color="red">// 2. Unmarshal the data</font></span>
Unmarshaller unmar = new Unmarshaller(mapping);
MyOrder order = (MyOrder)unmar.unmarshal(new InputSource(new FileReader("order.xml")));
<span class="bodyGrey"><font color="red">// 3. Do some processing on the data</font></span>
float total = order.getTotalPrice();
System.out.println("Order total price = " + total);
order.setTotal(total);
<span class="bodyGrey"><font color="red">// 4. marshal the data with the total price back and print the XML in the console</font></span>
Marshaller marshaller = new Marshaller(new OutputStreamWriter(System.out));
marshaller.setMapping(mapping);
marshaller.marshal(order);
} catch (Exception e) {
System.out.println(e);
return;
}
}
}
</pre></span> </span></td> </tr> </table> <a name="5.-xsi:type"><h2>5. xsi:type</h2></a> <p><span class="bodyGrey">Ordinarily, a mapping will only reference types that are concrete classes (i.e. not interfaces nor abstract classes). The reason is that to unmarshal a type requires instantiating it and one cannot instantiate an interface. However, in many real situations, object models depend on the use of interfaces. Many class properties are defined to have interface types to support the ability to swap implementations. This is often the case in frameworks.</span></p> <p><span class="bodyGrey">The problem is that a different mapping must be used each time the same model is to be used to marshal/unmarshal an implementation that uses different concrete types. This is not convenient. The mapping should represent the model and the specific concrete type used to unmarshal a document is a configuration parameter; it should be specified in the instance document to be unmarshalled, not the mapping.</span></p> <p><span class="bodyGrey">For example, assume a very simple object model of an engine that has one property that is a processor:</span></p> <span class="bodyBlack"><pre>
public interface IProcessor
{
public void process();
}
..
public class Engine
{
private IProcessor processor;
public IProcessor getProcessor()
{
return processor;
}
public void setProcessor(IProcessor processor)
{
this.processor = processor;
}
}
</pre></span> <p><span class="bodyGrey">A typical mapping file for such a design may be:</span></p> <span class="bodyBlack"><pre>
<mapping>
<class name="Engine">
<map-to xml="engine" />
<field name="processor" type="IProcessor" required="true">
<bind-xml name="processor" node="element" />
</field>
</class>
</mapping>
</pre></span> <p><span class="bodyGrey">It is possible to use such a mapping and still have the marshal/unmarshal process work by specifying the concrete implementation of IProcessor in the document to be unmarshalled, using the xsi:type attribute, as follows:</span></p> <span class="bodyBlack"><pre>
<engine>
<processor xsi:type="java:com.abc.MyProcessor" />
</engine>
</pre></span> <p><span class="bodyGrey">In this manner, one is still able to maintain only a single mapping, but vary the manner in which the document is unmarshalled from one instance document to the next. This flexibility is powerful because it enables the support of polymorphism within the castor xml marshalling framework.</span></p> <p><span class="bodyGrey">Suppose we wanted the following XML instead:</span></p> <span class="bodyBlack"><pre>
<engine>
<myProcessor/>
</engine>
</pre></span> <p><span class="bodyGrey">In the above output our XML name changed to match the type of the class used instead of relying on the xsi:type attribute. This can be achieved by modifying the mapping file as such: </span></p> <span class="bodyBlack"><pre>
<mapping>
<class name="Engine">
<map-to xml="engine" />
<field name="processor" type="IProcessor" required="true">
<bind-xml auto-naming="deriveByClass" node="element" />
</field>
</class>
<class name="MyProcessor">
<map-to xml="myProcessor" />
</class>
</mapping>
</pre></span> <a name="6.-Location-attribute"><h2>6. Location attribute</h2></a> <p><span class="bodyGrey">Since 0.9.5</span></p> <p><span class="bodyGrey"> The location attribute allows the user to map fields from nested elements or specify a wrapper element for a given field. Wrapper elements are simply elements which appear in the XML instance, but do not have a direct mapping to an object or field within the object model. </span></p> <p><span class="bodyGrey"> For example to map an instance of the following class: <span class="bodyBlack"><pre>
public class Foo {
private Bar bar = null;
public Foo();
public getBar() {
return bar;
}
public void setBar(Bar bar) {
this.bar = bar;
}
}
</pre></span> into the following XML instance: <span class="bodyBlack"><pre>
<?xml version="1.0"?>
<foo>
<abc>
<bar>...</bar>
</abc>
</foo>
</pre></span> <i>(notice that an 'abc' field doesn't exist in the Bar class)</i> <p><span class="bodyGrey"></span></p> One would use the following mapping: <span class="bodyBlack"><pre>
<?xml version="1.0"?>
<mapping>
...
<class name="Foo">
<field name="bar" type="Bar">
<bind-xml name="bar" location="abc"/>
</field>
</class>
...
</mapping>
</pre></span> Note the "location" attribute. The value of this attribute is the name of the wrapper element. To use more than one wrapper element, the name is separated by a forward-slash as such: <span class="bodyBlack"><pre>
<bind-xml name="bar" location="abc/xyz"/>
</pre></span> Note that the name of the element is not part of the location itself and that the location is always relative to the class in which the field is being defined. This works for attributes also: <span class="bodyBlack"><pre>
<bind-xml name="bar" location="abc" node="attribute"/>
</pre></span> will produce the following: <span class="bodyBlack"><pre>
<?xml version="1.0"?>
<foo>
<abc bar="..."/>
</foo>
</pre></span> </span></p> <a name="7.-Tips"><h2>7. Tips</h2></a> <p><span class="bodyGrey">Some helpful hints...</span></p> <a name="7.1-Automatically-create-a-mapping-file"><h3>7.1 Automatically create a mapping file</h3></a> <p><span class="bodyGrey"> Castor comes with a tool that can automatically create a mapping from class files. Please see the <a href="xml-faq.html">XML FAQ</a> for more information. </span></p> <a name="7.2-Create-your-own-FieldHandler"><h3>7.2 Create your own FieldHandler</h3></a> <p><span class="bodyGrey"> Sometimes to handle complex situations you'll need to create your own FieldHandler. Normally a FieldHandler deals with a specific class and field, however generic, reusable FieldHandlers can also be created by extending org.exolab.castor.mapping.GeneralizedFieldHandler or org.exolab.castor.mapping.AbstractFieldHandler. The FieldHandler can be specified on the <field> element. </span></p> <a name="7.3-Mapping-constructor-arguments"><h3>7.3 Mapping constructor arguments</h3></a> Since: 0.9.5 <p><span class="bodyGrey"> You may map any attributes to constructor arguments. Mapping elements to constructor arguments is not yet supported. For more information on how to map constructor arguments see the information available in the section on <a href="#constructor-args">set-method</a> above. </span></p> </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>
