XML has certainly taken the programming world by storm over the last several years. However, the complexity of XML applications, which started out high, has not diminished much in the recent past. Developers still have to spend weeks, if not months, learning the complicated semantics of XML, as well as APIs to manipulate XML, such as SAX and DOM. However, in just the last six to 12 months a new class of XML API, called Quick, has become increasingly popular as a simpler alternative to these more complex APIs.

Data binding allows you to directly map between the Java objects and XML, without having to deal with XML attributes and elements. Additionally, it allows Java developers to work with XML without having to spend hours boning up on XML specifications. Quick is one such data binding API -- a project that's geared toward business use in Java applications.

Installation and setup

Before diving into the details of using Quick, you'll need to download and install the project. Visit Quick's Web site (see Resources ), and select Download. You can then download a .zip file for the project; as of this writing, the latest version available was Quick 4.3.1, accessed through the Quick4.3.1.zip file.

Expand the .zip file to create the Quick distribution. The directory hierarchy is shown in Listing 1:

Quick4
  |
  +-- JARs
  +-- BATs
  +-- Doc
  +-- dtdParserSrc
  +-- DTDs
  +-- examples
  +-- JARs
  +-- QDMLs
  +-- QJMLs
  +-- quickSrc
  +-- UTILs
  +-- utilSrc
  +-- XSLs

The two directories of most interest to developers are Quick4/BATs, which should be added to your PATH environment variable, and Quick4/JARs, which contains jar files that should be added to your CLASSPATH environment variable. Specifically, you need to add dtdparser115.jar, Quick4rt.jar, and Quick4util.jar to your current class path. You'll also need a SAX parser implementation, such as the Apache project's Xerces-J (see Resources ). Add xerces.jar, or your own favorite parser, to your class path as well.

Back to top

Java classes and XML documents

Data binding centers around XML and Java, so let's take a look at how these XML documents and Java classes relate to Quick. To illustrate these points, I look at several simple Java classes, and a simple XML document.

A simple XML document

First, Listing 2 shows a small XML document. I've kept things simple so that you don't miss out on the concepts by wading through 10 or 15 Java classes.

<?xml version="1.0"?>
<!DOCTYPE person SYSTEM "person.dtd">
<person>
  <firstName>Gary</firstName>
  <lastName>Greathouse</lastName>
  <address type="home">
    <street>10012 Townhouse Drive</street>
    <city>Waco</city>
    <state>TX</state>
    <zipCode>76713</zipCode>
  </address>
  <phoneNumber>
    <type>home</type>
    <number>2545550287</number>
  </phoneNumber>
  <phoneNumber>
    <type>work</type>
    <number>2545556127</number>
  </phoneNumber>
</person>

Listing 2, while not a prime example of how to write XML, brings out several Quick points that are worth noting. You'll also want to take a look at the DTD for the document, shown in Listing 3.

<!ELEMENT person (firstName, lastName, address+, phoneNumber+)>

<!ELEMENT firstName (#PCDATA)>
<!ELEMENT lastName (#PCDATA)>

<!ELEMENT address (street, city, state, zipCode)>
<!ATTLIST address
          type    (home | work | other)    "home"
>

<!ELEMENT street (#PCDATA)>
<!ELEMENT city (#PCDATA)>
<!ELEMENT state (#PCDATA)>
<!ELEMENT zipCode (#PCDATA)>

<!ELEMENT phoneNumber (type, number)>
<!ELEMENT type (#PCDATA)>
<!ELEMENT number (#PCDATA)>

The Java classes

In many data binding implementations, you would now need to generate Java source files to represent this type of XML document. That sort of implementation assumes, generally falsely, that you lack the Java business objects you want to use. More commonly, you have a set of Java classes that you want to begin persisting to XML. This use case is exactly what Quick helps to solve. In light of that, then, Listings 4, 5, and 6 are three Java source files that represent a person.

import java.util.LinkedList;
import java.util.List;

public class Person {

    /** The first name of the person */
    private String firstName;
    
    /** The last name of the person */
    private String lastName;
    
    /** The addresses of the person */
    private List addressList;
    
    /** The phone numbers of the person */
    private List phoneNumberList;
    
    public Person() {
        addressList = new LinkedList();
        phoneNumberList = new LinkedList();
    }
    
    public Person(String firstName, String lastName,
        List addressList, List phoneNumberList) {
            
        this.firstName = firstName;
        this.lastName = lastName;
        this.addressList = addressList;
        this.phoneNumberList = phoneNumberList;
    }
    
    public String getFirstName() {
        return firstName;
    }
    
    public void setFirstName(String firstName) {
        this.firstName = firstName;
    }
    
    public String getLastName() {
        return lastName;
    }
    
    public void setLastName(String lastName) {
        this.lastName = lastName;
    }
    
    public List getAddressList() {
        return addressList;
    }
    
    public void setAddressList(List addressList) {
        this.addressList = addressList;
    }
    
    public void addAddress(Address address) {
        addressList.add(address);
    }
    
    public List getPhoneNumberList() {
        return phoneNumberList;
    }
    
    public void setPhoneNumberList(List phoneNumberList) {
        this.phoneNumberList = phoneNumberList;
    }
    
    public void addPhoneNumber(PhoneNumber phoneNumber) {
        phoneNumberList.add(phoneNumber);
    }
}

public class Address {

    /** The type of address */
    private String type;
    
    /** The street address */
    private String street;
    
    /** The city */
    private String city;
    
    /** The state */
    private String state;
    
    /** The zip code */
    private String zipCode;
    
    public Address() { }
    
    public Address(String type, String street, String city, 
        String state, String zipCode) {
        
        this.type = type;
        this.street = street;
        this.city = city;
        this.state = state;
        this.zipCode = zipCode;
    }
    
    public String getType() {
        return type;
    }
    
    public void setType(String type) {
        this.type = type;
    }
    
    public String getStreet() {
        return street;
    }
    
    public void setStreet(String street) {
        this.street = street;
    }
    
    public String getCity() {
        return city;
    }
    
    public void setCity(String city) {
        this.city = city;
    }
    
    public String getState() {
        return state;
    }
    
    public void setState(String state) {
        this.state = state;
    }
    
    public String getZipCode() {
        return zipCode;
    }
    
    public void setZipCode(String zipCode) {
        this.zipCode = zipCode;
    }
}

public class PhoneNumber {

    /** The number itself */
    private String number;
    
    /** The type of number */
    private String type;
    
    public PhoneNumber() { }
    
    public PhoneNumber(String type, String number) {
        this.type = type;
        this.number = number;
    }
    
    public String getNumber() {
        return number;
    }
    
    public void setNumber(String number) {
        this.number = number;
    }
    
    public String getType() {
        return type;
    }
    
    public void setType(String type) {
        this.type = type;
    }
}

These classes should be fairly self-explanatory. They are the analogs of the XML structure you saw back in Listing 2. Presumably, you will want to convert XML documents to instances of these Java objects, and back again. Quick makes these conversions a piece of cake.

Back to top

Initialization

Once you have your XML document (or documents), your DTD, and your Java classes, you need to tell the Quick framework how to map data from one format to the other. This is a multi-step process:

1. Create a QDML file from the XML document's DTD
2. Create a QJML file from the QDML document
3. Create a QIML file from the QJML document
4. Use the QIML to map Java to XML and back again

I'll show you how to accomplish each step in turn in the next several sections. While this may seem like a lot of steps to get Quick going, you should note that each of these only needs to occur one time so this is an up-front cost for using the Quick framework. Once you have taken care of these steps, you can use Quick in your applications as many times as you want, without this process overhead.

Creating QDML

The first thing you need to do in getting Quick ready to roll is create a QDML file. QDML (Quick Document Markup Language) is essentially Quick's version of a DTD, and defines the XML document's structure for the Quick framework. At this point, you aren't providing any mapping information; you're just defining your document in a format that Quick can understand. Of course, this is accomplished through a Quick tool, which makes life easier for developers.

First, make sure that your class path is set up as indicated in Installation and setup. You can then use the cfgDtd2Qdml script, located in the Quick distribution's BATs directory. For Windows users, you would use cfgDtd2Qdml.bat; for Unix users, use cfgDtd2Qdml.sh. (The examples in this article are all in Unix format, but you can easily accomplish the tasks on Windows.)

Issue the following command:

sh cfgDtd2Qdml.sh -in=person.dtd -out=person.qdml

You won't see much exciting in terms of output, but you should get a new file, called person.qdml. With your DTD in a format that's more easily understood by Quick, you're almost ready to move to the next step.

Before moving on, you need to let Quick (and the QDML file it uses) know the root element of your XML document. In this case, it's the person element. To do this, use another Quick utility:

sh cfgSetQdmlRoot.sh -in=person.qdml -out=person.qdml -root=person

Creating QJML

You now need to create a QJML file for Quick to use. QJML is the Quick Java Markup Language, and is the equivalent of a binding schema, for those of you familiar with JAXB or other data binding implementations. Quick uses QJML to convert the constructs in your XML file to their Java counterparts, and vice versa.

It's possible to create a QJML file from scratch; however, Quick supplies a tool for generating one automatically, and you generally only need to make minimal changes. For that reason, this is the recommended approach. Use either the cfgQdml2Qjml.bat or cfgQdml2Qjml.sh script to accomplish this, supplying your newly-generated QDML file as input (Quick reads the QDML to determine the constructs to map; see why you needed that file now?):

sh cfgQdml2Qjml.sh -in=person.qdml -out=person.qjml

You should now have a new file, person.qjml.

As I've said, you will need to make some changes to this file, since Quick makes some problematic assumptions about Java variable names. Open up your file, and add the property elements for each item (highlighted in bold) so it resembles Listing 7.

<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
<!DOCTYPE qjml SYSTEM "classpath:///qjml.dtd">
<qjml root="person">
    <bean tag="person">
        <targetClass>Person</targetClass>
        <elements>
            <item coin="firstName">
                <property name="firstName"/>
            </item>
            <item coin="lastName">
                <property name="lastName"/>
            </item>
            <item coin="address" repeating="True">
                <property kind="list" name="addressList"/>
            </item>
            <item coin="phoneNumber" repeating="True">
                <property kind="list" name="phoneNumberList"/>
            </item>
        </elements>
    </bean>
    <text tag="firstName"/>
    <text tag="lastName"/>
    <bean tag="address">
        <targetClass>Address</targetClass>
        <attributes>
            <item coin="address.type" optional="True" value="home">
                <property initializer="home" name="type"/>
            </item>
        </attributes>
        <elements>
            <item coin="street">
                <property name="street"/>
            </item>
            <item coin="city">
                <property name="city"/>
            </item>
            <item coin="state">
                <property name="state"/>
            </item>
            <item coin="zipCode">
                <property name="zipCode"/>
            </item>
        </elements>
    </bean>
    <text label="address.type" tag="type">
        <enum value="home"/>
        <enum value="work"/>
        <enum value="other"/>
    </text>
    <text tag="street"/>
    <text tag="city"/>
    <text tag="state"/>
    <text tag="zipCode"/>
    <bean tag="phoneNumber">
        <targetClass>PhoneNumber</targetClass>
        <elements>
            <item coin="type">
                <property name="type"/>
            </item>
            <item coin="number">
                <property name="number"/>
            </item>
        </elements>
    </bean>
    <text tag="type"/>
    <text tag="number"/>
</qjml>

These changes should be pretty obvious when you compare the original file to the one shown in Listing 7; they all involve mapping the XML property to the correct Java property name, as defined in the source code (see Listings 4, 5, and 6 for a refresher on these).

Creating QIML

You're almost done with the setup work; you still need to perform one final step. Quick performs much better with a QIML file -- the Quick Internal Markup Language. As the name implies, Quick uses this internal format to avoid runtime compilation, conversion, and processing of QJML files. Perform the following simple step to put your QJML into a format that Quick can use more handily:

sh cfgQjml2Qiml.sh -in=person.qjml -out=person.qiml

Finally, to improve performance even further, turn this text-based format into a Java source file that you can compile (binary objects are always better to work with than non-compiled textual file formats):

sh cfgQiml2Java.sh -in=person.qiml -out=PersonSchema.java 
-class=PersonSchema -key=person.qjml

You really don't need to worry too much about what is happening here; it's all Quick-specific, and the utilities take care of things. You should now compile this created source (and the rest of your Java source if you haven't already), and make sure everything is added to your classpath. With all these steps complete, you're ready to do some data binding.

Back to top

Data binding

With all the setup work done, it is now trivial to use the Quick framework to convert your XML document into Java bytecode and then back again. I'm going to keep the example for this simple; once you've got the basics down, the uses of data binding become limitless, and rather than assume I know your use-case, I'll just let you use the information you need from the sample code and take off! Take a look at Listing 8, and then I'll explain the main concepts.

import java.util.Iterator;

// Quick imports
import com.jxml.quick.QDoc;
import com.jxml.quick.Quick;

public class PersonTest {

  public static void main(String[] args) {
    try {
      if (args.length != 2) {
        System.err.println("Usage: java PersonTest [input file] [output file]");
        return;
      }

      // Initialize Quick
      QDoc schema = PersonSchema.createSchema();

      // Convert input XML to Java
      QDoc doc = Quick.parse(schema, args[0]);

      // Get the result
      Person person = (Person)Quick.getRoot(doc);

      // Output block
      System.out.println(" --------------- Person ------------------ ");
      System.out.println(" First Name: " + person.getFirstName());
      System.out.println(" Last Name : " + person.getLastName());
      for (Iterator i = person.getAddressList().iterator(); i.hasNext(); ) {
        Address address = (Address)i.next();
        System.out.println(" Address (" + address.getType() + "):");
        System.out.println("   " + address.getStreet());
        System.out.println("   " + address.getCity() + ", " + address.getState() +
           " " + address.getZipCode());
      }
      for (Iterator i = person.getPhoneNumberList().iterator(); i.hasNext(); ) {
        PhoneNumber number = (PhoneNumber)i.next();
        System.out.println(" Phone Number (" + number.getType() + "):");
        System.out.println("   " + number.getNumber());
      }

      // Add a new address
      Address address = 
        new Address("work", "357 West Magnolia Lane", "Waco", "TX", "76710");
      person.getAddressList().add(address);

      // Change a phone number
      PhoneNumber number = (PhoneNumber)person.getPhoneNumberList().get(1);
      number.setNumber("2547176547");

      // Write out modified XML
      Quick.express(doc, args[1]);
    } catch (Exception e) {
       e.printStackTrace();
    }
  }
}

The portion of this code that deals with Quick turns out to be only about four lines! You first must load the QIML (compiled as Java bytecode) so Quick knows which XML elements and attributes become which Java classes and properties. Do this through the createSchema() method (which is static) of the generated PersonSchema class. Once that schema is loaded, it and the input file are handed off to the Quick.parse() method, which does the conversion. From there, you simply have to grab the root element of the resulting QDoc and work with it as you would any other Java object. Quick enters the picture again in the last bit of the code where the express() method outputs a modified version of the XML. Pretty easy, isn't it?

Note: Do not supply the same filename for both input and output, as you will overwrite your original data, and can cause all sorts of unexpected things to happen.

Back to top

Conclusion

Ideally, you've seen some really intriguing functionality here. First, data binding in general can greatly simplify programming tasks, especially when you need to persist data to some type of static storage (like a file, as shown in this article). Additionally, Quick provides a fast, simple way to achieve this in your own projects. Take a spin around the block with Quick, and see how you like it. Enjoy, and I'll see you online!

Back to top

Download

Information about download methods

Resources

• Get the source code for this article, as well as the Quick-generated files and code .
  
  
• Download Quick from The Quick Project Home Page which includes additional downloads and documentation.
  
  
• Check out the The Apache XML Project XML which offers several parsers and processors, all free for use.
  
  
• Visit The Apache Xalan XSLT processor home page, where XSLT processors can be examined and downloaded.
  
  
• Find more XML resources on the developerWorks XML technology zone.
  
  
• Check out Rational Application Developer for WebSphere Software, an easy-to-use, integrated development environment for building, testing, and deploying J2EE applications, including generating XML documents from DTDs and schemas.
  
  
• Find out how you can become an IBM Certified Developer in XML and related technologies.
  
  

About the author

Brett McLaughlin has been working in computers since the Logo days (Remember the little triangle?). He currently specializes in building application infrastructure using Java and Java-related technologies. He has spent the last several years implementing these infrastructures at Nextel Communications and Allegiance Telecom, Inc. Brett is one of the co-founders of the Java Apache project Turbine, which builds a reusable component architecture for Web application development using Java servlets. He is also a contributor to the EJBoss project, an open source EJB application server, and Cocoon, an open source XML Web-publishing engine.

Rate this article

Comments

Back to top

Table of contents

• Installation and setup
• Java classes and XML documents
• Initialization
• Data binding
• Conclusion
• Download
• Resources
• About the author
• Comments

Next steps from IBM

Rational Application Developer features provide the comprehensive Integrated Development Environment (IDE) used to develop J2EE applications requiring Servlets and JavaServer Pages (JSPs).

---

• Try: Try the free Rational Application Developer, which helps developers quickly design, develop, test, analyze, and deploy high-quality Java, Javaserver pages, and J2EE applications.
• Article: Learn how you can deliver accurate, higher-quality J2EE apps with Rational Application Developer, open source JUnit and JUnitEE test frameworks.
• Tutorial: Build a Facebook application using PHP, the Spring framework, and J2EE.
• Demo: This demo shows how to use the new Java EE 5 Java Persistence API (JPA) framework.
• Buy: Rational Application Developer

Dig deeper into XML on developerWorks

Try IBM PureSystems. No charge.

Experience today!

---

Get started with the cloud-based trial and pattern development kit.

Special offers