Developer.com content and product recommendations are editorially independent. We may make money when you click on links to our partners. Learn More.
Castor oil was once billed as a miracle cure. Even today, there are many Web sites that extol the amazing healing properties of Castor oil. Whether this was the inspiration for the name for Exolab’s open source data binding framework or not remains a mystery. In fact, Exolab goes out of their way in the documentation to hide the origin of the name.
No matter what the inspiration, Castor is a valuable tool that every Java developer should be familiar with. Castor is a data-binding framework. It provides a simple API that can be used by developers to convert Java objects to XML files and to bind Java objects to database tables. Castor implements most of the functionality of Sun’s JAXB (Java XML Binding) and JDO (Java Data Objects) specifications although it is not fully compliant with either of them.
Java XML Binding
Converting Java objects to XML files usually involves writing a lot of custom code using the SAX (Simple API for XML) or DOM (Document Object Model) API. Writing this code involves creating a custom parser that converts a Java object to and from an XML file. This is a very tedious process and is hard to maintain.
Castor eliminates the need to write any custom code by providing methods that can introspect a Java object and using a set of rules convert it to and from an XML file. The process Castor uses is very similar to serialization. The Castor XML API provides two main classes for Java to XML binding: Marshaller and Unmarshaller. Marshaller is the main class used to convert a Java object to an XML file. The Unmarshaller class is used to convert an XML file to a Java object.
In order for Castor to do this automatic conversion, the Java objects must implement a Java bean interface that has setter and getter methods for all its member variables.
Consider the following classes that are used to represent directory and file nodes in a file system. The UML diagram for these classes is shown in Figure 1. There are four classes. The FileSystemNode is the base class for all nodes in a file system. It contains the properties that are common to both file and directory nodes. Two classes extend the FileSystemNode class, DirectoryNode and FileNode, and implement methods that are specific to the file and directory nodes. The NodeTypeConst class is used to encapsulate storing and comparing of the different node types. The full source code for these classes and all examples in this article can be downloaded here.
Figure 1: UML diagram of File System classes
To demonstrate how Castor can be used to convert Java objects to and from an XML file, let’s create a set of file and directory nodes and save them to an XML file. The code snippet below shows the creation of the various objects. The top level of the hierarchy is:
// Create a few nodes of a file system
DirectoryNode rootNode = new DirectoryNode("Root");
DirectoryNode srcDir = new DirectoryNode("src");
DirectoryNode classDir = new DirectoryNode("classes");
FileNode srcFile = new FileNode("XMLConverter.java", 5);
FileNode xmlFile = new FileNode("rootNode.xml", 1);
FileNode classFile = new FileNode("XMLConverter.class", 3);
classFile.setLock(true);
classDir.addChild(classFile);
srcDir.addChild(srcFile);
srcDir.addChild(xmlFile);
rootNode.addChild(srcDir);
rootNode.addChild(classDir);
a “Root” node that contains two sub directories “src” and “classes”. The src directory contains two files: “XMLConverter.java and “rootNode.xml”. The class’s directory contains one file: “XMLConverter.class”.
To save the root node and all its descendants, you would use the Marshaller class as follows:
// Create a File to marshal to
FileWriter writer = new FileWriter("rootNode.xml");
// Create a marshaller
Marshaller marshaller = new Marshaller(writer);
// marshal the object to an xml file
marshaller.marshal(rootNode);
That’s all there is to it. Castor introspects the rootNode object and all its associated classes and creates an XML file. The important thing to remember is that the rootNode object and all the associated classes need getter methods for each member variable. If a member variable does not have a getter method, it will not be save to the XML file.
The resultant XML file from the marshal operation is shown below. As you can see, it contains all the information contained in the rootNode object including its descendants.
<directory-node node-type-int="1">
<node-type node-type="1"/>
<name>Root</name>
<child-list node-type-int="1" xsi_type="java:DirectoryNode"
xmlns_xsi="http://www.w3.org/2001/XMLSchema-instance">
<node-type node-type="1"/>
<name>src</name>
<child-list locked="false" lock="false" filesize="5"
node-type-int="0" xsi_type="java:FileNode">
<name>XMLConverter.java</name>
<node-type node-type="0"/>
</child-list>
<child-list locked="false" lock="false" filesize="1"
node-type-int="0" xsi_type="java:FileNode">
<name>rootNode.xml</name>
<node-type node-type="0"/>
</child-list>
</child-list>
<child-list node-type-int="1" xsi_type="java:DirectoryNode"
xmlns_xsi="http://www.w3.org/2001/XMLSchema-instance">
<node-type node-type="1"/>
<name>classes</name>
<child-list locked="true" lock="true" filesize="3"
node-type-int="0" xsi_type="java:FileNode">
<name>XMLConverter.class</name>
<node-type node-type="0"/>
</child-list>
</child-list>
</directory-node>
To convert an XML file to a Java object, you would use Castor’s Unmarshaller class, as shown in the following code snippet .
// Create a Reader to the file to unmarshal from
FileReader reader = new FileReader("rootNode.xml");
// Create the unmarshaller
Unmarshaller unmarshaller = new Unmarshaller
(FileSystemNode.class);
// Unmarshal the object
FileSystemNode rootNode = (FileSystemNode)
unmarshaller.unmarshal(reader);
Again, it’s a simple operation. Castor parses the XML file and creates all the objects defined in the file. For the unmarshalling to work correctly, each associated class has to have setter methods for each of the attributes and/or nodes in the XML file. Also, each class must have a zero argument constructor. If a class has a member variable that is a collection, such as the FileSystemNode’s m_childList, it also helps to have an add method that is used to add individual members to the collection.
It’s important to point out that Castor uses a naming convention to find the correct getter and setter methods for the member variables. If there are problems with the marshalling and unmarshalling, they are usually caused by improperly named setter and getter methods.
If you want more control over the format and content of the XML file, you can use a mapping file to better control the conversion between the object and XML file. The mapping file is an XML file that has elements for each class. These elements are used to map the class to a specific XML tag . The class elements contain field elements that are used to define the individual properties of each of the member variables of the class. Each field element contains a bind-xml element, which is used to define the field to XML mapping.
The mapping file for our file system classes is shown below.
<mapping>
<class name="FileSystemNode" auto-complete="false">
<description>Default mapping for class
FileSystemNode</description>
<map-to xml="FileSystemNode"/>
<field name="type" type="NodeTypeConst" required="false"
direct="false" transient="false"
get-method="getNodeType">
<bind-xml name="node-type" node="element"/>
</field>
<field name="name" type="string" required="false"
direct="false" transient="false">
<bind-xml name="name" node="element"/>
</field>
</class>
<class name="DirectoryNode" auto-complete="false">
<description>Default mapping for class
DirectoryNode</description>
<map-to xml="directory-node"/>
<field name="type" type="NodeTypeConst" required="false"
direct="false" transient="false"
get-method="getNodeType">
<bind-xml name="node-type" node="element"/>
</field>
<field name="name" type="string" required="false"
direct="false" transient="false">
<bind-xml name="name" node="element"/>
</field>
<field name="ChildList" type="FileSystemNode"
required="false" direct="false"
transient="false" collection="vector">
<bind-xml name="child-list" node="element"/>
</field>
</class>
<class name="FileNode" auto-complete="false">
<description>Default mapping for class FileNode</description>
<map-to xml="file-node"/>
<field name="type" type="NodeTypeConst" required="false"
direct="false" transient="false"
get-method="getNodeType">
<bind-xml name="node-type" node="element"/>
</field>
<field name="name" type="string" required="false"
direct="false" transient="false">
<bind-xml name="name" node="element"/>
</field>
<field name="locked" type="boolean" required="false"
direct="false" transient="false">
<bind-xml name="locked" node="element" get-method="getLock"/>
</field>
<field name="filesize" type="integer" required="false"
direct="false" transient="false">
<bind-xml name="filesize" node="attribute"/>
</field>
</class>
<class name="NodeTypeConst" auto-complete="false">
<description>Default mapping for class
NodeTypeConst</description>
<map-to xml="lock-info"/>
<field name="nodeType" type="integer" required="false"
direct="false" transient="false">>
<bind-xml name="type" node="attribute"/>
</field>
</class>
</mapping>
As you can see, there are entries for each of our four classes and each class has a field and bind-xml element for each of the member variables. Field elements can reference other classes in the mapping file so that a class definition can be a combination of other classes. For classes that have member variables that are collections, a field element must be used to specify the type of collection. For a complete explanation of all the tags in the mapping file, see the Castor documentation.
To save an object to an XML file using the mapping file, you would use the Mashaller class as before, with one minor change, as shown below.
// Create a File to marshal to
FileWriter writer = new FileWriter("rootNodeUsingMap.xml");
//Create and load mapping file
Mapping xmlMap = new Mapping();
xmlMap.loadMapping("FileSystemMap.xml");
//Create Marshaller
Marshaller marshaller = new Marshaller(writer);
//Set the mapping file
marshaller.setMapping(xmlMap);
//Save the object to the xml file
marshaller.marshal(rootNode);
To unmarshall data from an XML file to a Java object using a mapping file, you would use the Unmarshaller class as before, with one minor change.
//Create and load mapping file
Mapping mapping = new Mapping();
mapping.loadMapping("FileSystemMap.xml");
// Create unmarshaller and read xml file
Unmarshaller unmar = new Unmarshaller(mapping);
Object obj = unmar.unmarshal(new InputSource
(new FileReader(fileName)));
Although there are a number of nuances associated with Castor’s Marshaller and Unmarshaller class, once you use them a few times they become easy to use and will save a lot of time and coding.
Java SQL Binding
Castor’s other main API is used to persist Java object to database tables. This API is very similar to JDO. In fact, the main class used to do conversion between object and database table is the JDO class. Before we can start using this class, however, we first have to determine how to map each of our Java objects to a specific database table. Of course, object-relational mapping is a fairly complex subject in itself that can not be covered properly in this article. For a more detailed discussion of object-relation mapping, see the resources at the end of the article.
To keep our example simple, we are going to use the same classes that we used for the XML example (DirectoryNode and FileNode). To map these objects to a database, we must first create a table that corresponds to each object. The FileNodes table contains entries for the name of the file, the size of the file, whether the file is locked or not, and a parent field that is used to link the file to its parent directory. The DirNodes table contains entries for name of the directory and a parent field, which can be used to link this directory to its parent.
Figure 2: Database tables for the File and Directory Node objects
Now that we have the tables and objects defined, we need to create a mapping file that Castor will use to transfer the objects to/from the database. Unlike Castor XML, Castor JDO requires a mapping file to be used.
<mapping>
<class name="DirectoryNode" identity="name">
<description>Default mapping for class
DirectoryNode</description>
<map-to table="dirnodes"/>
<field name="name" type="string" required="false"
direct="false" transient="false">
<sql name="name" type="varchar"/>
</field>
<field name="parentName" type="string">
<sql name="parent" type="varchar"/>
</field>
<field name="childList" type="FileNode" required="false"
collection="vector"
get-method="getChildList"
set-method="setChildList">
<sql many-key="parent"/>
</field>
</class>
<class name="FileNode" identity="name">
<description>Default mapping for class FileNode</description>
<map-to table="filenodes"/>
<field name="name" type="string">
<sql name="name" type="varchar"/>
</field>
<field name="locked" type="boolean" get-method="getLock"
set-method="setLock">
<sql name="locked" type="bit"/>
</field>
<field name="filesize" type="integer">
<sql name="size" type="integer"/>
</field>
<field name="parentName" type="string">
<sql name="parent" type="varchar"/>
</field>
</class>
</mapping>
The mapping file for mapping objects to a database is very similar to the mapping file Castor uses for XML mapping. In fact, the two mapping files can be combined into one file, if desired.
There are elements for classes and fields just like the XML mapping file. The main difference for the class element is a new attribute called “identity”. This attribute is used to designate the field in this class, which will uniquely identify an instance of this class. Another way to look at this is that the identity field will be the primary key for the table that contains these objects. For our example, the identity for file and directory nodes is just the name of the node. This is the simplest type of identity, but the identity field can also be a complex type made up of multiple fields.
Inside the class element is a “map-to table” element that is used to associate the class to a table in the database. Inside the field element is an sql element that is used to associate a member variable with a column in the database table. It’s important to make sure that the Java type for the field and the database type for sql element are compatible. For example, in the name field in the FileNode class, the type is String for the field element and varchar for the sql element. Likewise, for the locked field in the FileNodes class is type boolean for the field element and bit for the sql element. As long as the types are compatible, Castor will do the conversions correctly.
Besides defining how member variables for each object maps to each table, the mapping file is also used to define how the objects are connected. The sql element can either contain a many-key attribute to define a one to many relationship or a many-table attribute to define a many to many relationship.
For our example, the DirectoryNode contains a field element named childList, which is used map the DirectoryNode’s childList vector to a set of FileNode entries in the FileNodes table. The sql element within the field tag uses the many-key attribute to map the DirectorNode’s identity field to the FileNode’s parent field thus establishing the one to may relationship between directory and file nodes (in other words, each file node will contain the name of its one parent in its parent field).
One thing to note is that the mapping defines the relationship between objects in a fairly rigid way. Even though a directory node can have children that are file or directory nodes, our mapping has limited the directory node children to be only file nodes. This was just the result of our database design. If a more complex relationship is needed between the objects, the database has to be changed accordingly. The problem is that Java objects can use inheritance and polymorphism in their design but these properties are hard to map to a database. Although there are some other tags and attributes in the mapping file that may help map these relationships, the database design is critical to allow easy conversion between objects and the database.
Now that we have the mapping file set up, we can write the code to bind the objects to the database. The first thing that needs to be created is the JDO object.
m_JDO = new JDO();
m_JDO.setDatabaseName("test");
m_JDO.setConfiguration("my_database.xml);
The JDO object requires two things to be set before it can be used: the database name and a configuration file. The configuration file contains information about how to connect the database as well as what mapping file to use. For more information on the configuration file, see the Castor documentation. The documentation contains a lists of databases supported along with some sample configuration files.
Once the JDO object is created and configured, it then can be used to create, read, update, or delete objects defined in the mapping file. The class that is used to do these operations is the Database class, which can be gotten from the JDO class by using the JDO.getDatabase() method. The Database class represents a connection to the database and contains most of the methods needed to interact with the database. All database operations must be performed in the context of a transaction using the Database.begin() and Database.commit() methods.
To create a new object and persist it to the database, you first need to create the object, and then call the Database.create() method to persist it to the database, as shown in the code below.
DirectoryNode srcDir = new DirectoryNode("src");
FileNode srcFile = new FileNode("XMLConverter.java", 5);
FileNode xmlFile = new FileNode("rootNode.xml", 1);
srcFile.setParentName(srcDir.getName());
srcDir.addChild(srcFile);
xmlFile.setParentName(srcDir.getName());
srcDir.addChild(xmlFile);
Database db = m_JDO.getDatabase();
//Set auto store to true so that child nodes are also created
db.setAutoStore(true);
db.begin();
db.create(srcDir);
db.commit();
This code snippet shows some of the nice features of Castor. Even though there are three objects created, the directory node and two file nodes, you only need to call the db.create() method once for the directory node to persist all three objects to the database. This is because when AutoStore is set to true, the create() operation will create the specified object and all other related objects. You also can get this same behavior if you specify the FileNode class to be dependant on the DirectoryNode class in the mapping file. However, if do this, you cannot access the file nodes directly, but only through directory nodes. See the Castor documentation for a full explanation of this behavior.
Castor gives you a couple of ways to get objects from the database. If you know the exact object you want, you can use the load() method to get the specific object as shown in the code below.
db.begin();
dirNode = (DirectoryNode) db.load(DirectoryNode.class, "src");
db.commit();
The load() method shown here takes two arguments. The first argument is the class of the object you are looking for. The second argument is the value of the identity field for this class that will uniquely identify the object.
If you want to get a group of objects from the database, you can use Castor’s OQL (Object Query Language) to query the objects in the database and get back a result set. An OQL query is very similar to the sql query language except you query objects, not the underlying database tables. The query is executed as shown below. For details on OQL, see the Castor documentation.
db.begin();
OQLQuery oql = db.getOQLQuery("SELECT s FROM DirectoryNode s
WHERE s.name = "src"");
QueryResults results = oql.execute();
while(results.hasMore())
{
dirNode = (DirectoryNode) results.next();
//do something with directory node
}
db.commit()
Castor caches the objects it retrieves from the database, so if the object is retrieved multiple times by different calls it only reads the object from the database once. This minimizes calls to the database and makes the process more efficient.
Updates are also easy to do. Simply make the changes to the object and call the update() method:
DirNode.setParent("root");
db.begin();
db.update(dirNode);
db.commit();
Updates will throw an ObjectModifiedException if the object in the database has been modified since the object was last retrieved from the database. Castor calls this dirty checking. For dirty checking to work, each object class must implement the TimeStampable interface. This interface has two methods used to set and get the timestamp when the object is retrieved or updated.
This dirty checking is useful if multiple clients are updating the same object in the database. For example, let’s say one client gets an object from the database just before a second client performs an update to that object. When the first client goes to do an update, it will get an ObjectModifiedException that it can catch and then use the load() method to get a fresh version of the object from the database before doing the update. This will prevent clients from overwriting each other’s changes. Castor’s Database class also provides a lock method, so a client can lock an object in the database so that it can’t be modified by anyone else.
Objects are deleted from the database with the remove method.
db.begin(); db.remove(dirNode); db.commit();
The remove method only removes the specified object and not any related objects unless the related objects have specified a dependency on the object being deleted in the mapping file.
Conclusion
There is a lot more to the Castor API than what I have shown here in these simple examples. Castor is very well documented and provides a lot of information, not only on the API but on the philosophy behind it as well as the best way to use it. I encourage you to check out the Castor Web site and explore the API on your own. Hopefully, these examples have demonstrated the usefulness of the Castor API and will give you another tool to use when mapping Java objects to XML files or databases.
Links and References
- Source code for all examples in this article: click here to download.
- Castor Web site: http://castor.exolab.org
- For more information on object-relational mapping, see Scott Ambler’s “Mapping Objects to Relational Databases” article.
Author’s Bio
Thomas Hammell is a senior developer at Hewlett-Packard and is part of the Open Call Business Unit that develops telecom networks infrastruture software. He has over 17 years of experience in developing software. Tom has published a number of articles on Java topics ranging from Swing development to Unit testing and speaks frequently on Java topics. Tom holds a Bachelor of Science in Electrical Engineering and Master of Computer Science from Steven’s Institute of Technology. He may be reached at thomas_hammell@hp.com.
