<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html><head><title>Using Castor XML</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><p><span class="bodyGrey">Reference: <a href="api/org/exolab/castor/xml/package-summary.html"><api package="org.exolab.castor.xml">The XML Framework API</api></a></span></p><p><span class="bodyGrey">Note: This documentation is not yet finished</span></p><span class="bodyGrey"><a href="#Introduction">Introduction</a><br></span><span class="bodyGrey"><a href="#The-Marshalling-Framework">The Marshalling Framework</a><br></span><span class="bodyGrey"><a href="#Using-Existing-Classes/Objects">Using Existing Classes/Objects</a><br></span><span class="bodyGrey"><a href="#Class-Descriptors">Class Descriptors</a><br></span><span class="bodyGrey"> <a href="#Compile-Time-Descriptors">Compile-Time Descriptors</a><br></span><span class="bodyGrey"> <a href="#Run-Time-Descriptors">Run-Time Descriptors</a><br></span><br><a name="Introduction"><h2>Introduction</h2></a> <p><span class="bodyGrey"> Castor XML is an XML databinding framework. Unlike the two main XML APIs, DOM (Document Object Model) and SAX (Simple API for XML) which deal with the structure of an XML document, Castor enables one to deal with the data defined in an XML document through an object model which represents that data. </span></p> <p><span class="bodyGrey"> Castor XML can marshal almost any "bean-like" Java Object to and from XML. In most cases the marshalling framework uses a set of ClassDescriptors and FieldDescriptors to describe how an Object should be marshalled and unmarshalled from XML. </span></p> <p><span class="bodyGrey"> For those not familiar with the terms "marshal" and "unmarshal", it's simply the act of converting a stream (sequence of bytes) of data to and from an Object. The act of "marshalling" consists of converting an Object to a stream, and "unmarshalling" from a stream to an Object. </span></p> <a name="The-Marshalling-Framework"><h2>The Marshalling Framework</h2></a> <p><span class="bodyGrey"> The marshalling framework, as it's name implies, is responsible for doing the conversion between Java and XML. The framework consists of two main classes, <a href="api/org/exolab/castor/xml/Marshaller.html"><api>org.exolab.castor.xml.Marshaller</api></a> and <a href="api/org/exolab/castor/xml/Unmarshaller.html"><api>org.exolab.castor.xml.Unmarshaller</api></a>. </span></p> <p><span class="bodyGrey"> Lets walk through a very simple example. Assume we have a simple Person class as follows: <span class="bodyBlack"><pre>
import java.util.Date;
<span class="bodyGrey"><font color="red">/**
* An simple person class
*/</font></span>
public class Person implements java.io.Serializable {
<span class="bodyGrey"><font color="red">/**
* The name of the person
*/</font></span>
private String name = null;
<span class="bodyGrey"><font color="red">/**
* The Date of birth
*/</font></span>
private Date dob = null;
<span class="bodyGrey"><font color="red">/**
* Creates a Person with no name
*/</font></span>
public Person() {
super();
}
<span class="bodyGrey"><font color="red">/**
* Creates a Person with the given name
*/</font></span>
public Person(String name) {
this.name = name;
}
<span class="bodyGrey"><font color="red">/**
* @return date of birth of the person
*/</font></span>
public Date getDateOfBirth() {
return dob;
}
<span class="bodyGrey"><font color="red">/**
* @return name of the person
*/</font></span>
public String getName() {
return name;
}
<span class="bodyGrey"><font color="red">/**
* Sets the date of birth of the person
* @param name the name of the person
*/</font></span>
public void setDateOfBirth(Date dob) {
this.dob = dob;
}
<span class="bodyGrey"><font color="red">/**
* Sets the name of the person
* @param name the name of the person
*/</font></span>
public void setName(String name) {
this.name = name;
}
}
</pre></span> To marshal an instance of the person class you simply call the Marshaller as follows: <span class="bodyBlack"><pre>
<span class="bodyGrey"><font color="red">// Create a new Person</font></span>
Person person = new Person("Ryan 'Mad Dog' Madden");
person.setDateOfBirth(new Date(1955, 8, 15));
<span class="bodyGrey"><font color="red">// Create a File to marshal to</font></span>
writer = new FileWriter("test.xml");
<span class="bodyGrey"><font color="red">// Marshal the person object</font></span>
Marshaller.marshal(person, writer);
</pre></span> To unmarshal an instance of the person class you simply call the Unmarshaller as follows: <span class="bodyBlack"><pre>
<span class="bodyGrey"><font color="red">// Create a Reader to the file to unmarshal from</font></span>
reader = new FileReader("test.xml");
<span class="bodyGrey"><font color="red">// Marshal the person object</font></span>
Person person = (Person)Unmarshaller.unmarshal(Person.class, reader);
</pre></span> </span></p> <b><i>Marshalling and Unmarshalling is basically that simple!</i></b> <p><span class="bodyGrey"></span></p> <b> Note: A common mistake when using a Mapping file is to call the Marshaller or Unmarshaller as in the above example. This won't work because the mapping will be ignored. The above example uses the <i>static</i> methods of the marshalling framework. If you are using a mapping file simply call the Marshaller or Unmarshaller as follows: </b> <p><span class="bodyGrey"> <span class="bodyBlack"><pre>
<span class="bodyGrey"><font color="red">// Load Mapping</font></span>
Mapping mapping = new Mapping();
mapping.loadMapping("mapping.xml");
<span class="bodyGrey"><font color="red">// Create a Reader to the file to unmarshal from</font></span>
reader = new FileReader("test.xml");
<span class="bodyGrey"><font color="red">// Create a new Unmarshaller</font></span>
Unmarshaller unmarshaller = new Unmarshaller(Person.class);
unmarshaller.setMapping(mapping);
<span class="bodyGrey"><font color="red">// Unmarshal the person object</font></span>
Person person = (Person)unmarshaller.unmarshal(reader);
</pre></span> </span></p> <a name="Using-Existing-Classes/Objects"><h2>Using Existing Classes/Objects</h2></a> <p><span class="bodyGrey"> Castor can marshal "almost" any arbitrary Object to and from XML. When descriptors are not available for a specfic Class, the marshalling framework uses reflection to gain information about the object. <hr size="1" noshadow><span class="bodyGrey"> Actually an in memory set of descriptors are created for the object and we will soon have a way for saving these descriptors as Java source, so that they may be modified and compiled with little effort. <hr size="1" noshadow></span> </span></p> <p><span class="bodyGrey">If a set of descriptors exist for the classes, then Castor will use those to gain information about how to handle the marshalling. See <a href="#Class Descriptors">Class Descriptors</a> for more information. </span></p> <p><span class="bodyGrey"> There is one main restrictions to marshalling objects. These classes must have have a public default constructor (ie. a constructor with no arguments) and adequete "getter" and "setter" methods to be properly be marshalled and unmarshalled. </span></p> <p><span class="bodyGrey"> The example illustrated in the previous section <a href="#The Marshalling Framework">The Marshalling Framework</a> demonstrates how to use the framework with existing classes. </span></p> <a name="Class-Descriptors"><h2>Class Descriptors</h2></a> <p><span class="bodyGrey"> Class descriptors provide the "Castor Framework" with necessary information so that the Class can be marshalled properly. The class descriptors can be shared between the JDO and XML frameworks. </span></p> <p><span class="bodyGrey"> Class descriptors contain a set of <a href="#Field Descriptors">Field Descriptors</a> </span></p> <p><span class="bodyGrey"> XML Class descriptors provide the marshalling framework with the information it needs about a class in order to be marshalled to and from XML. The XMLClassDescriptor <a href="api/org/exolab/castor/xml/XMLClassDescriptor.html"><api>org.exolab.castor.xml.XMLClassDescriptor</api></a>. </span></p> <p><span class="bodyGrey"> XML Class Descriptors are created four main ways. Two of these are basically run-time, and the other two are compile time. <a name="Compile-Time-Descriptors"><h4>Compile-Time Descriptors</h4></a> <p><span class="bodyGrey"> To use "compile-time" class descriptors, one can either implement the <a href="api/org/exolab/castor/xml/XMLClassDescriptor.html"><api>org.exolab.castor.xml.XMLClassDescriptor</api></a> interface for each class which needs to be "described", or have the <a href="sourcegen.html">Source Code Generator</a> create the proper descriptors. </span></p> <p><span class="bodyGrey"> The main advantage of compile-time descriptors is that they are faster than the run-time approach. </span></p> <a name="Run-Time-Descriptors"><h4>Run-Time Descriptors</h4></a> <p><span class="bodyGrey"> To use "run-time" class descriptors, one can either simply let Castor introspect the classes, a mapping file can be provided, or a combination of both "default introspection" and a specified mapping file may be used. </span></p> <p><span class="bodyGrey"> For "default introspection" to work the class being introspected must have adequete setter/getter methods for each field of the class that should be marshalled and unmarshalled. If no getter/setter methods exist, Castor can handle direct field access to public fields. It does not do both at the same time. So if the respective class has any getter/setter methods at all, then no direct field access will take place. </span></p> <p><span class="bodyGrey"> There is nothing to do to enable "default introspection". If a descriptor cannot be found for a class, introspection occurs automatically. </span></p> <p><span class="bodyGrey"> Some behavior of the introspector may be controlled by setting the appropriate properties in the <i>castor.properties</i> file. Such behavior consists of changing the naming conventions, and whether primitive types are treated as attributes or elements. See <i>castor.properties</i> file for more information. </span></p> <p><span class="bodyGrey"> A mapping file may also be used to "describe" the classes which are to be marshalled. The mapping is loaded before any marshalling/unmarshalling takes place. See <a href="api/org/exolab/castor/mapping/Mapping.html"><api>org.exolab.castor.mapping.Mapping</api></a> </span></p> <p><span class="bodyGrey"> The main advantage of run-time descriptors is that it takes very little effort to get something working. </span></p> </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>
