The popularity of data binding

In XML newsgroups, mailing lists, and discussion forums of the Web site (you can find links for many of these in Resources), one of the most common themes is data binding. Java and XML developers are clamoring for an easy way to convert between Java objects and XML documents, and then back into Java objects.

Sun has held the place of dominance in this realm with their JAXB, the Java Architecture for XML Binding (If you've seen the JAXB acronym used for something else, that's OK; Sun seems to change what JAXB stands for every year or so). However, the JAXB API (or architecture, if you like) has some deficiencies, and doesn't get updated very often. It also doesn't handle mapping to relational databases, a common request.

Enter Castor

It's at this point that Castor enters the picture. Castor is an open source framework that picks up in many cases where JAXB leaves off. It's been around for a while, and predates the JAXB code base and Sun's specifications on data binding. In fact, Castor was updated to work with the JAXB approach to data binding so that programmers unhappy with JAXB could move their code over with a minimal amount of fuss.

A few advantages

Before getting into the details of installing and using Castor, it's worth pointing out a few reasons you should at least try out Castor, and consider switching over from JAXB.

• First, Castor is an almost-drop-in replacement for JAXB. In other words, you can change all of your JAXB code to Castor with very little trouble. (It's not an exact replacement, but it's close enough to make the task simple for even newbie programmers.)
• Second, Castor offers quite a bit more in the data binding area, allows you to convert between Java and XML without a schema, an easier-to-use binding schema than JAXB, and the ability to marshal and unmarshal from a relational database, as well as XML documents.
• Castor also provides JDO capabilities. JDO stands for Java Data Objects, and it's the underlying technology that drives the Java-to-RDBMS marshalling and unmarshalling. JDO isn't quite as popular as it was a few years ago, but it's still a nice feature to have. Additionally, because JDO is another Sun specification, you won't write code to an obscure API.

Back to top

Download Castor

The installation of Castor is a straightforward procedure. First, visit the Castor Web site (see links in Resources) and click Download in the left menu. Select the latest milestone release, and scroll down to Download sets. While you can download the Castor JARs, DTDs, docs, dependencies, and so forth all in pieces, it's easiest to use one of the pre-packaged download sets (see Figure 1).

For this article, you'll use version 1.1.2.1. I selected the The Castor JARs, docs, DTDs, command line tools, and examples download set, in ZIP form. You'll get an archive you can expand, which contains a number of JAR files, docs, and sample programs (see Figure 2).

Back to top

Getting things in the right place

Next, you need to get all of Castor's files in the right places on your system, so your Java environment can access them.

A common place for Java libraries

I strongly recommend you decide on a common place for all of your third party Java libraries. It's possible to leave them all over your system, but it becomes a nightmare for several reasons:

1. It's hard to find things, in the most general sense.
2. You'll have a tough time figuring out what library version you use, as you'll often end up with multiple versions in different places on your system.
3. Your class path will become a long, convoluted nightmare.

I place all of my libraries in /usr/local/java/, each in their own subdirectory (usually with a version number). So move your Castor archive—expanded—into your common library location. In my case, the complete path to Castor then is: /usr/local/java/castor-1.1.2.1.

Bookmark the Castor JavaDoc

Another step in setting up any Java library on your system is to locate and link to the documentation. You'll come back to this time and time again, and most Java libraries ship with local copies of their documentation (including JavaDoc) in HTML format. In the Castor case, this is in castor-1.1.2.1/doc/. So on my system, I added a bookmark to /usr/local/java/castor-1.1.2.1/doc/index.html. Figure 3 shows what the Castor docs look like, loaded locally, for version 1.1.2.1.

Two big reasons why this is worth taking up time and space, both in this article and your programming life, are:

1. The documentation is local. Ever programmed on a plane? Lost your network connection? Couldn't get logged into the Starbucks WiFi? Local documentation is a life saver in these cases, in addition to being faster to access.
2. The documentation is always for your version. As Castor evolves, you might not always download the newest release. Using online documentation means you're probably using docs for the very latest version, which won't always match your system. When you use local documentation, you'll always work with documentation for the exact version of the library that you use. That will reduce confusion and frustration from trying to use a feature improperly, or even one that doesn't exist in your version of the library.

Back to top

Download Castor dependencies

Castor has a lot of dependencies:

• Apache Ant
• Jakarta Commons
• JDBC 2.0 Standard Extensions
• Log4J logging utilities
• Apache Xerces XML parser

That's actually a shortened set that works for most Castor operations. If you want to build Castor from source, run their examples, use their tests, or go further into Castor, you'll need even more. You will need these dependencies in your class path before you can use Castor.

The hard way

The brute force approach to getting things going is to visit Castor's download page and write down the version of each dependency that you need. Then you can hop over to each dependency Web site, find that version, download it, and add it to your class path. This takes a long time, although it's great for control freaks. Additionally, if you already have most of these libraries setup and working, this might be a viable option.

The easy way

Thankfully, there's a better approach. Go back to the Castor download page, find the stable releases, and locate another download set. This one is called Full SVN snapshot: All sources, docs, and 3rd party libraries (big). It's marked "big", but it's only 10 MB (in a DSL or cable world, that's nothing). Pull this file down, and expand it (it will look like Figure 4).

Now you can go into the lib/ directory, which has lots of JAR files. These are the libraries that Castor needs.

A place for more libraries

Create a new directory—either in your original Castor distribution or alongside it—and move all the JAR files you just downloaded into that directory. For example:

[bmclaugh:~] cd /usr/local/java
[bmclaugh:/usr/local/java] ls
castor-1.1.2.1  xalan-j_2_7_0
[bmclaugh:/usr/local/java] cd castor-1.1.2.1/
[bmclaugh:/usr/local/java/castor-1.1.2.1] ls
CHANGELOG                       castor-1.1.2.1.jar
castor-1.1.2.1-anttasks.jar     doc
castor-1.1.2.1-codegen.jar      jdbc-se2.0.jar
castor-1.1.2.1-ddlgen.jar       jta1.0.1.jar
castor-1.1.2.1-jdo.jar          schema
castor-1.1.2.1-xml.jar
[bmclaugh:/usr/local/java/castor-1.1.2.1] mkdir lib
[bmclaugh:/usr/local/java/castor-1.1.2.1] cd lib
[bmclaugh:/usr/local/java/castor-1.1.2.1/lib] cp ~/downloads/castor-1.1.2.1/lib/*.jar .
[bmclaugh:/usr/local/java/castor-1.1.2.1/lib]

Here, I created a lib/ directory in my Castor distribution, moved all the JAR files into it, and have Castor ready to use.

Back to top

Getting your class path set up

Now you need to get everything in your class path setup. I use a .profile file in my Mac OS X configuration to handle all of these issues. You might want to set your profile like this, or in Windows, set a system environment variable. In any case, you want to add the following JARs to your classpath:

• castor-1.1.2.1.jar (in the main Castor directory)
• castor-1.1.2.1-xml.jar (in the main Castor directory)
• xerces-J-1.4.0.jar (wherever you put your Castor dependency libraries)
• commons-logging-1.1.jar (wherever you put your Castor dependency libraries)

For reference, here is my .profile, so you can see how I have this setup:

export JAVA_BASE=/usr/local/java
export JAVA_HOME=/Library/Java/Home
export XERCES_HOME=$JAVA_BASE/xerces-2_6_2
export XALAN_HOME=$JAVA_BASE/xalan-j_2_7_0
export CASTOR_HOME=$JAVA_BASE/castor-1.1.2.1
export EDITOR=vi

export CASTOR_CLASSES=$CASTOR_HOME/castor-1.1.2.1.jar:
                      $CASTOR_HOME/castor-1.1.2.1-xml.jar:
                      $CASTOR_HOME/lib/xerces-J_1.4.0.jar:
                      $CASTOR_HOME/lib/commons-logging-1.1.jar



export CVS_RSH=ssh

export PS1="[`whoami`:\w] "



export CLASSPATH=$XALAN_HOME/xalan.jar:$XALAN_HOME/xml-apis.jar:
                 $XALAN_HOME/xercesImpl.jar:

                 ~/lib/mclaughlin-xml.jar:$CASTOR_CLASSES:.

Make sure you've got all of this in your class path, and you're ready to do a quick test.

Back to top

Testing your installation

Let's build a very simple class, and then a utility to convert it to XML and back to Java. This is not a demonstration of Castor's full features, but instead just a very basic test. Listing 1 shows a CD class we'll use. Type this source code in and save it as CD.java (or download the code from Resources).

                
package ibm.xml.castor;

import java.util.ArrayList;
import java.util.List;

/** A class to represent CDs */
public class CD implements java.io.Serializable {

  /** The name of the CD */
  private String name = null;

  /** The artist of the CD */
  private String artist = null;

  /** Track listings */
  private List tracks = null;

  /** Required no-args constructor */
  public CD() {
    super();
  }

  /** Create a new CD */
  public CD(String name, String artist) {
    super();
    this.name = name;
    this.artist = artist;
  }

  public void setName(String name) {
    this.name = name;
  }

  public String getName() {
    return name;
  }

  public void setArtist(String artist) {
    this.artist = artist;
  }

  public String getArtist() {
    return artist;
  }

  public void setTracks(List tracks) {
    this.tracks = tracks;
  }

  public List getTracks() {
    return tracks;
  }

  public void addTrack(String trackName) {
    if (tracks == null) {
      tracks = new ArrayList();
    }
    tracks.add(trackName);
  }
}

Now you need a class to handle marshalling. That's shown in Listing 2.

                
package ibm.xml.castor;

import java.io.FileWriter;

import org.exolab.castor.xml.Marshaller;

public class MarshalTester {

  public static void main(String[] args) {
    try {
      CD sessions = new CD("Sessions for Robert J", "Eric Clapton");
      sessions.addTrack("Little Queen of Spades");
      sessions.addTrack("Terraplane Blues");

      FileWriter writer = new FileWriter("cds.xml");
      Marshaller.marshal(sessions, writer);
    } catch (Exception e) {
      System.err.println(e.getMessage());
      e.printStackTrace(System.err);
    }
  }
}

And, last but not least, Listing 3 is a class for unmarshalling.

                
package ibm.xml.castor;

import java.io.FileReader;
import java.util.Iterator;
import java.util.List;

import org.exolab.castor.xml.Unmarshaller;

public class UnmarshalTester {

  public static void main(String[] args) {
    try {
      FileReader reader = new FileReader("cds.xml");
      CD cd = (CD)Unmarshaller.unmarshal(CD.class, reader);
      System.out.println("CD title: " + cd.getName());
      System.out.println("CD artist: " + cd.getArtist());
      List tracks = cd.getTracks();
      if (tracks == null) {
        System.out.println("No tracks.");
      } else {
        for (Iterator i = tracks.iterator(); i.hasNext(); ) {
          System.out.println("Track: " + i.next());
        }
      }
    } catch (Exception e) {
      System.err.println(e.getMessage());
      e.printStackTrace(System.err);
    }
  }
}

Compile these classes like this:

[bmclaugh:~/Documents/developerworks/castor] javac -d . *.java
Note: CD.java uses unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.

The warning is if you're using Java 5 or greater, because you don't use parameterized types in CD.java. Don't worry about this, it's not a problem. Now, you need to run your marshaller testing class.

[bmclaugh:~/Documents/developerworks/castor] java ibm.xml.castor.MarshalTester

You should be able to locate and open up cds.xml now. It should look like this:

<?xml version="1.0" encoding="UTF-8"?>
<CD>
  <artist>Eric Clapton</artist>
  <name>Sessions for Robert J</name>
  <tracks xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
     xsi:type="java:java.lang.String">Little Queen of Spades</tracks>
  <tracks xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
     xsi:type="java:java.lang.String">Terraplane Blues</tracks>
</CD>

This isn't overly readable, but you should see all the information in the CD that you created in the MarshalTester class in this XML document.

Now you need to make sure you can convert back from that XML document into Java. Run the unmarshalling tester:

[bmclaugh:~/Documents/developerworks/castor] java ibm.xml.castor.UnmarshalTester 
CD title: Sessions for Robert J
CD artist: Eric Clapton
Track: Little Queen of Spades
Track: Terraplane Blues

This is pretty self-explanatory. If you get this output, you have Castor pulling open your XML file and turning it back into a Java class.

At this point—assuming that you got the same cds.xml and output from UnmarshalTester —you have a working installation. While you haven't done anything particularly complicated with Castor, you have done enough to make sure that Castor is working, your JAR files are set up properly, and Castor can do what it needs to do.

Back to top

What's next?

At this point, you have a working Castor environment. You should even have a basic idea of how Castor works, based on Listings 1, 2, and 3. See if you can play around with marshalling and unmarshalling on your own. In the next article, you'll look more closely at Castor's XML features, and how to use mapping files. Until then, enjoy playing around.

Back to top

Downloads

Information about download methods

Resources

Learn

• Data binding with Castor, Part 2: Marshall and unmarshall XML (Brett McLaughlin, developerWorks, December 2007): Convert your Java classes to XML and transform that XML back into Java code, as well as learn how Castor works and to design your classes to function well with the API.
  
  
• Data binding with Castor, Part 3: Map between schemas (Brett McLaughlin, developerWorks, January 2008): Convert data in an unwieldy or inconvenient XML document to your custom Java objects using Castor. You'll no longer be constrained by the names of elements in your XML document, or by the member variable names in your Java classes.
  
  
• Data binding with Castor, Part 4: Bind your Java objects to SQL databases (Brett McLaughlin, developerworks, April 2008): With Castor, turn Java objects into rows within your SQL database. Learn what syntax is the same, what's different, and how you can add SQL to your data binding arsenal.
  
  
• The Castor Web site: Visit the online hub for all things Castor.
  
  
• Castor classes: Read the JavaDoc.
  
  
• xml.com: If you're completely new to XML, try these easy online resources for everything XML.
  
  
• Castor's JDO capabilities (Bruce Snyder, developerWorks, August 2002): Read this older article on developerWorks. Some of the language specifics of this article are out of date, but the concepts are still right on.
  
  
• Practical Data Binding (Brett McLaughlin, developerWorks, May 2004): Start with the introductory article of a multi-part series for more on Sun's data binding API, JAXB.
  
  
• IBM XML certification: Find out how you can become an IBM-Certified Developer in XML and related technologies.
  
  
• XML technical library: See the developerWorks XML Zone for a wide range of technical articles and tips, tutorials, standards, and IBM Redbooks.
  
  
• developerWorks technical events and webcasts: Stay current with technology in these sessions.
  
  
• The technology bookstore: Browse for books on these and other technical topics.
  
  

Get products and technologies

• Java and XML, Third Edition (Brett McLaughlin and Justin Edelson, O'Reilly Media, Inc.): Cover XML from start to finish, including extensive information on data binding and mapping.
  
  
• Java and XML Data Binding (Brett McLaughlin, O'Reilly Media, Inc.): In this older book, find details on Castor and the concepts involved in data binding.
  
  
• Castor Professional Services: Hunting for paid support or help with Castor? Look into Castor's professional services.
  
  
• IBM trial software: Build your next development project with trial software available for download directly from developerWorks.
  
  

Discuss

• Participate in the discussion forum.
  
  
• XML zone discussion forums: Participate in any of several XML-related discussions.
  
  
• developerWorks XML zone: Share your thoughts: After you read this article, post your comments and thoughts in this forum. The XML zone editors moderate the forum and welcome your input.
  
  
• developerWorks blogs: Check out these blogs and get involved in the developerWorks community.
  
  

About the author

Brett McLaughlin has worked in computers since the Logo days. (Remember the little triangle?) In recent years, he's become one of the most well-known authors and programmers in the Java and XML communities. He's worked for Nextel Communications, implementing complex enterprise systems; at Lutris Technologies, actually writing application servers; and most recently at O'Reilly Media, Inc., where he continues to write and edit books that matter. Brett's upcoming book, Head Rush Ajax, brings the award-winning and innovative Head First approach to Ajax. His last book, Java 1.5 Tiger: A Developer's Notebook, was the first book available on the newest version of Java technology. And his classic Java and XML remains one of the definitive works on using XML technologies in the Java language.

Rate this article

Comments

Back to top

Table of contents

• The popularity of data binding
• Download Castor
• Getting things in the right place
• Download Castor dependencies
• Getting your class path set up
• Testing your installation
• What's next?
• Downloads
• Resources
• About the author
• Comments

Dig deeper into Java on developerWorks

IBM SmartCloud trial. No charge.

Unleash the power of hybrid cloud computing today!

---

Public and private solutions in one trial.

Special offers