XML Reference Guide

These days, many programmers are used to programming with objects; they're familiar with concepts such as classes, methods, parameters, and so on. In some cases, this familiarity can lead to resistance on the part of the programmer to use XML, because it doesn't seem to readily adapt itself to the thought processes involved in creating an object-oriented application. Data binding is the process of making data act like an object so that it can be manipulated like an object. Consider, for example, our sample order file:

<?xml version="1.0"?>
<order orderid="THX1138" customerNumber="3263827">
    <lineitem itemid="C33">
       <item>3/4" Hex Bolt</item>
       <quantity>36</quantity>
       <unitprice currency="dollars">.35</unitprice>
    </lineitem>
    <lineitem itemid="M48">
       <item>Condenser</item>
       <quantity>1</quantity>
       <unitprice currency="dollars">2200</unitprice>
    </lineitem>
</order>

If the order were an object, it might be an object of type Order, with properties such as orderid and customerNumber, both of which might be string objects, and a lineitem property that might consist of a group of Lineitem objects. The Lineitem class would define properties such as itemid, item, quantity, and unitprice.

If you were designing the Order class, you'd probably have methods such as:

public java.lang.String getOrderid();
public void setOrderid(java.lang.String orderid);

public java.lang.String getCustomerNumber();
public void setCustomerNumber(java.lang.String customerNumber);

public Lineitem[] getLineitem();
public Lineitem getLineitem(int index);
public int getLineitemCount();
public void setLineitem(Lineitem[] lineitemArray);
public void setLineitem(int index, Lineitem vLineitem);
public void addLineitem(Lineitem vLineitem);
public void removeAllLineitem();

With these methods, you could control the information stored in the object.

The existance of XML Data Binding tools means that this way of working doesn't have to be mutually exclusive with XML. Instead, you can use a tool that analyzes a DTD or XML Schema and uses the information to automatically generate the necessary classes and the methods necessary for obtaining and manipulating the data.

More than that, though, these tools include the ability to marshal and unmarshal XML data. Marshalling is the process if taking data that's stored in an object and saving it back out as XML. Unmarshalling is the process of reading in the XML file and using it to populate the object. For example, we can create a simple program that creates an order and adds a line item to it:

import java.io.FileWriter;

public class TakeAnOrder {

  public static void main (String args[]){
     try{
        Order order = new Order();
        order.setOrderid("THX1138");
        order.setCustomerNumber("3263827"); 

        Lineitem lineitem = new Lineitem();
        lineitem.setItem("3/4\" Hex Bolt");
        lineitem.setItemid("C33");
        lineitem.setQuantity("36");

        Unitprice unitprice = new Unitprice();
        unitprice.setContent(".35");
        unitprice.setCurrency("dollars");

        lineitem.setUnitprice(unitprice);

        order.addLineitem(lineitem);

        FileWriter writer = new FileWriter("neworder.xml");
        order.marshal(writer);

     } catch (Exception e){
         e.printStackTrace();
     }
  }

}

(I'm using Java here, but data binding tools exist for most programming languages.)

Here we create the new Order object (from a class automatically generated with a tool such as Castor), and then set the orderid and customerNumber properties. We can then create a new Lineitem (again automatically generated, along with its methods), populate it, and add it to the Order. Once it's been created and populated, we can marshal, or save, the data out to a file.

Now, notice that all of this deals with the content of the XML file, but not its structure. This process is designed to be completely independant of the structure of the original file. In fact, running the application as-is resulted in the following output:

<?xml version="1.0" encoding="UTF-8"?>
<order lineitem-count="1" valid="true">
   <lineitem valid="true">
      <unitprice valid="true">
         <currency>dollars</currency>
         <content>.35</content>
      </unitprice>
      <item>3/4" Hex Bolt</item>
      <itemid>C33</itemid>
      <quantity>36</quantity>
   </lineitem>
   <customer-number>3263827</customer-number>
   <orderid>THX1138</orderid>
</order>

Now, I've cleaned it up a little bit so you can see the data, but it's obvious that while all of the data is there, it's barely recognizable from our original document. That's where mapping comes in.

Mapping enables you to tell the application how to handle the information stored in the object. For example, the mapping file:

<?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="Order">
                <map-to xml="order"/>

                <field name="orderid"
                       type="java.lang.String">
                        <bind-xml name="orderid" node="attribute"/>
                </field>

                <field name="customerNumber"
                       type="java.lang.String">
                        <bind-xml name="customerNumber" node="attribute"/>
                </field>

                <field name="lineitem"
                       type="Lineitem">
                        <bind-xml name="lineitem" node="element"/>
                </field>
        </class>

        <class name="Lineitem">
            <map-to xml="lineitem"/>
                <field name="itemid"
                       type="java.lang.String">
                        <bind-xml name="itemid" node="attribute"/>
                </field>

                <field name="item"
                       type="java.lang.String">
                        <bind-xml name="item" node="element"/>
                </field>

                <field name="quantity"
                       type="java.lang.String">
                        <bind-xml name="quantity" node="element"/>
                </field>

                <field name="unitprice"
                       type="Unitprice">
                        <bind-xml name="unitprice" node="element"/>
                </field>
        </class>

        <class name="Unitprice">
               <map-to xml="unitprice"/>

                <field name="currency"
                       type="java.lang.String">
                        <bind-xml name="currency" node="attribute"/>
                </field>

                <field name="content"
                       type="java.lang.String">
                        <bind-xml node="text"/>
                </field>
        </class>

</mapping>

tells the application that properties such as itemid and currency should be treated as attributes rather than element children, and that the content of the unitprice is actually the text, and not a property named content.

By using a mapping file, you can create an application that is completely independent of the structure of the actual XML data. The only difference is that instead of marshalling the data directly from the order object, you can use a Marshaller object that can read the mapping and use it appropriately:

...
        lineitem.setUnitprice(unitprice);

        order.addLineitem(lineitem);

        FileWriter writer = new FileWriter("neworder.xml");

        Mapping mapping = new Mapping();
        mapping.loadMapping("mapping.xml");

        Marshaller marshaller = new Marshaller(writer);
        marshaller.setMapping(mapping);
        marshaller.marshal( order );
  
     } catch (Exception e){
         e.printStackTrace();
     }
  }

}

Overall, the idea of XML data binding is that of working with XML data as though it's an object. Here we're just creating an object from scratch, but you can also build applications that unmarshal the data, or read it from a file, and then update it and put it back.