Castor XML is an XML data binding 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 you to deal with the data defined in an XML document through an object model which represents that data.

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.

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.

The XML data binding framework, as it's name implies, is responsible for doing the conversion between Java and XML. The framework consists of two worker classes, org/exolab/castor/xml/Marshaller and org.exolab.castor.xml.Unmarshaller respectively, and a bootstrap class org.exolab.castor.xml.XMLContext used for configuration of the XML data binding framework and instantiation of the two worker objects.

Lets walk through a very simple example. Assume we have a simple Person class as follows:

import java.util.Date;

/** An simple person class */ 
public class Person implements java.io.Serializable {

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

   /** The Date of birth */ 
   private Date dob = null;

   /** Creates a Person with no name */ 
   public Person() {
      super(); 
   }

   /** Creates a Person with the given name */ 
   public Person(String name) { this.name = name; }

   /** 
     * @return date of birth of the person 
     */ 
   public Date getDateOfBirth() { return dob; }

   /** 
     * @return name of the person 
     */ 
   public String getName() { return name; }

   /** 
     * Sets the date of birth of the person 
     * @param name the name of the person 
     */ 
   public void setDateOfBirth(Date dob) { this.dob = dob; }

   /** 
     * Sets the name of the person 
     * @param name the name of the person 
     */ 
   public void setName(String name) { this.name = name; } 
}
		

To (un-)marshal data to and from XML, Castor XML can be used in one of three modes:

The following sections discuss each of these modes at a high level.

1.1.2.1. Introspection mode

The introspection mode is the simplest mode to use from a user perspective, as it does not require any configuration from the user. As such, the user does not have to provide any mapping file(s), nor point Castor to any generated descriptor classes (as discussed in the 'descriptor mode' section).

In this mode, the user makes use of static methods on the org.exolab.castor.xml.Marshaller and org.exolab.castor.xml.Unmarshaller classes, providing all required data as parameters on these method calls.

To marshal an instance of the person class you simply call the org.exolab.castor.xml.Marshaller as follows:

// Create a new Person
Person person = new Person("Ryan 'Mad Dog' Madden");
person.setDateOfBirth(new Date(1955, 8, 15));

// Create a File to marshal to
writer = new FileWriter("test.xml");

// Marshal the person object
Marshaller.marshal(person, writer);
			

This produces the XML shown in Example 1.1, “XML produced in introspection mode”

Example 1.1. XML produced in introspection mode

XML to written
				

To unmarshal an instance of the person class from XML, you simply call the org.exolab.castor.xml.Unmarshaller as follows:

// Create a Reader to the file to unmarshal from
reader = new FileReader("test.xml");

// Marshal the person object
Person person = (Person)
Unmarshaller.unmarshal(Person.class, reader);
			

Marshalling and unmarshalling is basically that simple.

	Note
	Note: The above example uses the static methods of the marshalling framework, and as such no Marshaller and/or Unmarshaller instances need to be created. A common mistake in this context when using a mapping file is to call the org.exolab.castor.xml.Marshaller or org.exolab.castor.xml.Unmarshaller as in the above example. This won't work, as the mapping will be ignored.

In introspection mode , Castor XML uses Java reflection to establish the binding between the Java classes (and their properties) and the XML, following a set of (default) naming rules. Whilst it is possible to change to a different set of naming rules, there's no way to override this (default) naming for individual artifacts. In such a case, a mapping file should be used.

import org.exolab.castor.xml.XMLContext; import
org.exolab.castor.mapping.Mapping; import
org.exolab.castor.xml.Unmarshaller;

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


	// initialize and configure XMLContext

XMLContext context = new XMLContext();
context.addMapping(mapping);


	// Create a Reader to the file to unmarshal from

reader = new FileReader("test.xml");

// Create a new Unmarshaller
Unmarshaller unmarshaller =
context.createUnmarshaller();
unmarshaller.setClass(Person.class);

// Unmarshal the person object
Person person = (Person)
unmarshaller.unmarshal(reader);
				

import org.exolab.castor.xml.Marshaller;

// create a Writer to the file to marshal to
Writer writer = new FileWriter("out.xml");

// create a new Marshaller
Marshaller marshaller = context.createMarshaller();
marshaller.setWriter(writer);

// marshal the person object
marshaller.marshal(person);
				

Castor supports multiple sources and destinations from which objects can be marshalled and unmarshalled.

Castor 1.3.2 and 1.3.3 introduced support for the STaX API for both for marshalling and unmarshalling. The framework fully supports the STaX cursor and iterator API.

An example of marshalling using STaX:

// marshalling using STaX
StringWriter writer = new StringWriter();
XMLOutputFactory outputFactory = XMLOutputFactory.newInstance();
XMLStreamWriter xmlStreamWriter = outputFactory.createXMLStreamWriter(writer);

marshaller.setXmlStreamWriter(xmlStreamWriter);
marshaller.marshal(object);
    		

Also beginning from version 1.3.3, the framework has been modified to support Source and Result interfaces. Now it is possible to use SAXSource, DOMSource and StreamSource for unmarshalling and corresponding classes for marshalling.

Below an example of marshalling into Result:

// instance of object to be marshalled
Object obj = ...

// marshalling into DOM node
XMLContext xmlContext = ... // creates the xml context

// creates marshaller
Marshaller marshaller = xmlContext.createMarshaller();

// creates DOM factory
DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
DocumentBuilder builder = factory.newDocumentBuilder();

// creates document
Document document = builder.newDocument();

// sets the DOM result for the marshaller
marshaller.setResult(new DOMResult(document));

// marshalls object
marshaller.marshall(obj);
		  

Another example of unmarshalling from Source:

// unmarshalling from SAX InputSource
XMLContext xmlContext = ... // creates the xml context

// creates unmarshaller
Unmarshaller unmarshaller = xmlContext.createUnmarshaller();

// creates SAX input source
InputSource inputSource = new InputSource(new StringReader(xml));

// creates instance of SAXSource
SAXSource saxSource = new SAXSource(inputSource);

// unmarshalls object
Object result = unmarshaller.unmarshal(saxSource);
    		

With Castor 1.1.2, the org.exolab.castor.xml.XMLContext class has been added to the Castor marshalling framework. This new class provides a bootstrap mechanism for Castor XML, and allows easy (and efficient) instantiation of org.exolab.castor.xml.Marshaller and org.exolab.castor.xml.Unmarshaller instances as needed.

As shown above, the org.exolab.castor.xml.XMLContext class offers various factory methods to obtain a new org.exolab.castor.xml.Marshaller, org.exolab.castor.xml.Unmarshaller.

When you need more than one org.exolab.castor.xml.Unmarshaller instance in your application, please call org.exolab.castor.xml.XMLContext.createUnmarshaller() as required. As all Unmarshaller instances are created from the very same XMLContext instance, overhead will be minimal. Please note, though, that use of one Unmarshaller instance is not thread-safe.

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.

	Note
	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.

If a set of descriptors exist for the classes, then Castor will use those to gain information about how to handle the marshalling. See Section 1.1.6, “Class Descriptors” for more information.

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.

The example illustrated in the previous section Section 1.1.2, “Castor XML - The XML data binding framework” demonstrates how to use the framework with existing classes.

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.

Class descriptors contain a set of ???

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 org.exolab.castor.xml.XMLClassDescriptor.

XML Class Descriptors are created in four main ways. Two of these are basically run-time, and the other two are compile time.

Castor XML mapping is a way to simplify the binding of java classes to XML document. It allows to transform the data contained in a java object model into/from an XML document.

Although it is possible to rely on Castor's default behavior to marshal and unmarshal Java objects into an XML document, it might be necessary to have more control over this behavior. For example, if a Java object model already exists, Castor XML Mapping can be used as a bridge between the XML document and that Java object model.

Castor allows one to specify some of its marshalling/unmarshalling behavior using a mapping file. This file gives explicit information to Castor on how a given XML document and a given set of Java objects relate to each other.

A Castor mapping file is a good way to dissociate the changes in the structure of a Java object model from the changes in the corresponding XML document format.

The mapping information is specified by an XML document. This document is written from the point of view of the Java object and describes how the properties of the object have to be translated into XML. One constraint for the mapping file is that Castor should be able to infer unambiguously from it how a given XML element/attribute has to be translated into the object model during unmarshalling.

The mapping file describes for each object how each of its fields have to be mapped into XML. A field is an abstraction for a property of an object. It can correspond directly to a public class variable or indirectly to a property via some accessor methods (setters and getters).

It is possible to use the mapping and Castor default behavior in conjunction: when Castor has to handle an object or an XML data but can't find information about it in the mapping file, it will rely on its default behavior. Castor will use the Java Reflection API to introspect the Java objects to determine what to do.

Note: Castor can't handle all possible mappings. In some complex cases, it may be necessary to rely on an XSL transformation in conjunction with Castor to adapt the XML document to a more friendly format.

public <type> xxxYYY;
        

The following sections define the syntax for each of the mapping file artefacts and their semantical meaning.

public class Order {

    private List orderItems;
    private String orderNumber;
    
    public List getOrderItems() {
        return orderItems;
    }
    public void setOrderItems(List orderItems) {
        this.orderItems = orderItems;
    }
    public String getOrderNumber() {
        return orderNumber;
    }
    public void setOrderNumber(String orderNumber) {
        this.orderNumber = orderNumber;
    }
}

public class OrderItem {
    
    private String id;
    private Integer orderQuantity;
    
    public String getId() {
        return id;
    }
    public void setId(String id) {
        this.id = id;
    }
    public Integer getOrderQuantity() {
        return orderQuantity;
    }
    public void setOrderQuantity(Integer orderQuantity) {
        this.orderQuantity = orderQuantity;
    }
}

<!ELEMENT mapping ( description?, include*, field-handler*, class*, key-generator* )>
        

<?xml version="1.0"?>

<!DOCTYPE mapping PUBLIC "-//EXOLAB/Castor Mapping DTD Version 1.0//EN"
      castor.org
                         "http://castor.org/mapping.dtd">

<mapping>
	<description>Description of the mapping</description>
	
	<include href="other_mapping_file.xml"/>
	
	<!-- mapping for class 'A' -->
	<class name="A">
	        .........
	</class>
	
	<!-- mapping for class 'B' -->
	<class name="B">
	        .........
	</class>

</mapping>

<!ELEMENT class ( description?, cache-type?, map-to?, field+ )>
<!ATTLIST class
          name            ID       #REQUIRED
          extends         IDREF    #IMPLIED
          depends         IDREF    #IMPLIED
          auto-complete   ( true |false ) "false"
          identity        CDATA    #IMPLIED
          access          ( read-only | shared | exclusive | db-locked )  "shared"
          key-generator   IDREF    #IMPLIED >

<class name="mypackage.OrderItem>
           
   <map-to xml="item"/>

   <field name="id" type="string">
      <bind-xml name="identity" node="attribute"/>
   </field>

   </field name="orderQuantity" type="integer">
      <bind-xml name="quantity" node="element"/>
   </field>

</class>

<?xml version="1.0" ?>        
<item identity="12">
   <quantity>100</quantity>
</item>

<class name="mypackage.OrderItem auto-complete="true">
           
   <map-to xml="item"/>

   <field name="id" type="string">
      <bind-xml name="identity" node="attribute"/>
   </field>

</class>

<?xml version="1.0" ?>        
<item identity="12">
   <order-quantity>100</order-quantity>
</item>

<class name="mypackage.OrderItem auto-complete="true">
           
   <field name="id" type="string">
      <bind-xml name="identity" node="attribute"/>
   </field>

</class>

<?xml version="1.0" ?>        
<order-item identity="12">
   <order-quantity>100</order-quantity>
</order-item>

<!ELEMENT map-to EMPTY>
<!ATTLIST map-to
          table               NMTOKEN  #IMPLIED
          xml                 NMTOKEN  #IMPLIED
          ns-uri              NMTOKEN  #IMPLIED
          ns-prefix           NMTOKEN  #IMPLIED
          ldap-dn             NMTOKEN  #IMPLIED
          element-definition  (true|false) "false"     NEW as of 1.0M3
          ldap-oc             NMTOKEN  #IMPLIED>

<class name="myPackage.OrderItem">
   ...
   <map-to xml="item" />
   ...
</class>

<class name="myPackage.OrderItem">
   ...
   <map-to xml="item" ns-uri="http://castor.org/sample/mapping/"
           ns-prefix="castor"/>
   ...
</class>

<?xml version="1.0" ?>        
<castor:order-item xmlns:castor="http://castor.org/sample/mapping/" identity="12">
   <castor:order-quantity>100</castor:order-quantity>
</castor:order-item>

<!ELEMENT field ( description?, sql?, bind-xml?, ldap? )>
<!ATTLIST field
    name           NMTOKEN  #REQUIRED
    type           NMTOKEN  #IMPLIED
    handler        NMTOKEN  #IMPLIED
    required       ( true | false )  "false"
    direct         ( true | false )  "false"
    lazy           ( true | false )  "false"
    transient      ( true | false )  "false"
    nillable       ( true | false )  "false"
    container      ( true | false )  "false"
    get-method     NMTOKEN  #IMPLIED
    set-method     NMTOKEN  #IMPLIED
    create-method  NMTOKEN  #IMPLIED
    collection     ( array | vector | hashtable | collection | set | map )  #IMPLIED>
        

<field name="foo" set-method="%1" get-method="getFoo" type="string">
   <bind-xml node="attribute"/>
</field>

<class name="org.some.package.Root">
   <field name="member" type="string" handler="org.some.package.CustomFieldHandlerImpl"/>
</class>

<field-handler name="myHandler" class="org.some.package.CustomFieldHandlerImpl">
   <param name="date-format" value="yyyyMMddHHmmss"/>
</field-handler>

<class name="org.some.package.Root">
   <field name="member" type="string" handler="myHandler"/>
</class>

<class name="some.example.Order">
            
   ...
   <field name="item" type="some.example.Item" >
      <bind-xml> name="item" node="element" />
   </field>
   ...
</class>

<class name="some.example.Item">
   <field name="id" type="long" />
   <field name="description" type="string" />
</class>

<order>
    ...
    <item>
        <id>100</id>
        <description>...</description>
    </item>
</order>

<field name="item" type="some.example.Item" container="false" >
   <bind-xml> name="item" node="element" />
</field>

<order>
    ...
    <id>100</id>
    <description>...</description>
</order>

1.2.3.7. The <bind-xml> element

1.2.3.7.1. Grammar

<!ELEMENT bind-xml (class?, property*)>
<!ATTLIST bind-xml
          name     NMTOKEN     #IMPLIED
          type     NMTOKEN     #IMPLIED
          location CDATA       #IMPLIED
          matches  NMTOKENS    #IMPLIED
          QName-prefix NMTOKEN #IMPLIED
          reference   ( true | false ) "false"
          node        ( attribute | element | text )    #IMPLIED
          auto-naming ( deriveByClass | deriveByField ) #IMPLIED
          transient   ( true | false ) "false">

1.2.3.7.1.1. Definiton

The <bind-xml> element is used to describe how a given Java field should appear in an XML document. It is used both for marshalling and unmarshalling.

Table 1.11. Description of the attributes

name	The name of the element or attribute. Note The name is a QName, and a namespace prefix may be used to indicate the element or attribute belongs to a certain namespace. Note the prefix is not preserved or used during marshalling, it's simply used for qualification of which namespace the element or attribute belongs.
auto-naming	If no name is specified, this attribute controls how castor will automatically create a name for the field. Normally, the name is created using the field name, however many times it is necessary to create the name by using the class type instead (such as heterogenenous collections).
type	XML Schema type (of the value of this field) that requires specific handling in the Castor Marshalling Framework (such as 'QName' for instance).
location (since 0.9.4.4)	Allows the user to specify the "sub-path" for which the value should be marshalled to and from. This is useful for "wrapping" values in elements or for mapping values that appear on sub-elements to the current "element" represented by the class mapping. For more information, see the Location attribute below.
QName-prefix	When the field represents a QName value, a prefix can be provided that is used when marshalling value of type QName. More information on the use of 'QName-prefix' can be found in the SourceGenerator Documentation
reference	Indicates if this field has to be treated as a reference by the unmarshaller. In order to work properly, you must specify the node type to 'attribute' for both the 'id' and the 'reference'. In newer versions of Castor, 'element' node for reference is allowed. Remember to make sure that an identity field is specified on the <class> mapping for the object type being referenced so that Castor knows what the object's identity is.
matches	Allows overriding the matches rules for the name of the element. It is a standard regular expression and will be used instead of the 'name' field. A '*' will match any xml name, however it will only be matched if no other field exists that matches the xml name.
node	Indicates if the name corresponds to an attribute, an element, or text content. By default, primitive types are assumed to be an attribute, otherwise the node is assumed to be an elemen
transient	Allows for making this field transient for XML. The default value is inherited from the <field> element.

1.2.3.7.2. Nested class mapping

Since 0.9.5.3, the bind-xml element supports a nested class mapping, which is often useful when needing to specify more than one mapping for a particular class. A good example of this is when mapping Hashtable/HashMap/Map.

<bind-xml ...>
   <class name="org.exolab.castor.mapping.MapItem">
      <field name="key" type="java.lang.String">
        <bind-xml name="id"/>
      </field>
      <field name="value" type="com.acme.Foo"/>
   </class>
</bind-xml>

Here is an example of how Castor Mapping can be used. We want to map an XML document like the following one (called 'order.xml'). model.

<Order reference="12343-AHSHE-314159">
  <Client>
    <Name>Jean Smith</Name>
    <Address>2000, Alameda de las Pulgas, San Mateo, CA 94403</Address>
  </Client>

  <Item reference="RF-0001">
    <Description>Stuffed Penguin</Description>
    <Quantity>10</Quantity>
    <UnitPrice>8.95</UnitPrice>
  </Item>

  <Item reference="RF-0034">
    <Description>Chocolate</Description>
    <Quantity5</Quantity>
    <UnitPrice>28.50</UnitPrice>
  </Item>

  <Item reference="RF-3341">
     <Description>Cookie</Description>
     <Quantity>30</Quantity>
     <UnitPrice>0.85</UnitPrice>
  </Item>
</Order>

Into the following object model composed of 3 classes:

The sources of these classes follow.

import java.util.Vector;
import java.util.Enumeration;

public class MyOrder {

    private String _ref;
    private ClientData _client;
    private Vector _items;
    private float _total;

    public void setReference(String ref) {
        _ref = ref;
    }

    public String getReference() {
        return _ref;
    }

    public void setClientData(ClientData client) {
        _client = client;
    }

    public ClientData getClientData() {
        return _client;
    }

    public void setItemsList(Vector items) {
        _items = items;
    }

    public Vector getItemsList() {
        return _items;
    }


    public void setTotal(float total) {
        _total = total;
    }

    public float getTotal() {
        return _total;
    }

    // Do some processing on the data
    public float getTotalPrice() {
        float total = 0.0f;

        for (Enumeration e = _items.elements() ; e.hasMoreElements() ;) {
            Item item = (Item) e.nextElement();
            total += item._quantity * item._unitPrice;
        }

        return total;
    }
}

public class ClientData {

    private String _name;
    private String _address;

    public void setName(String name) {
        _name = name;
    }

    public String getName() {
        return _name;
    }

    public void setAddress(String address) {
        _address = address;
    }

    public String getAddress() {
        return _address;
    }
}

public class Item {
    public String _reference;
    public int    _quantity;
    public float  _unitPrice;
    public String _description;
}

The XML document and the java object model can be connected by using the following mapping file:

<?xml version="1.0"?>
<!DOCTYPE mapping PUBLIC "-//EXOLAB/Castor Mapping DTD Version 1.0//EN"
                         "http://castor.org/mapping.dtd">

<mapping>
  <class name="MyOrder">
    <map-to xml="Order"/>

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

    <field name="Total"
           type="float">
      <bind-xml name="total-price" node="attribute"/>
    </field>

    <field name="ClientData"
           type="ClientData">
      <bind-xml name="Client"/>
    </field>

    <field name="ItemsList"
           type="Item"
              collection="vector">
      <bind-xml name="Item"/>
    </field>
  </class>

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

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

  <class name="Item">
    <field name="_reference"
           type="java.lang.String"
           direct="true">
      <bind-xml name="reference" node="attribute"/>
    </field>

    <field name="_quantity"
           type="integer"
           direct="true">
      <bind-xml name="Quantity" node="element"/>
    </field>

    <field name="_unitPrice"
           type="float"
           direct="true">
      <bind-xml name="UnitPrice" node="element"/>
    </field>

    <field name="_description"
           type="string"
           direct="true">
      <bind-xml name="Description" node="element"/>
    </field>
  </class>

</mapping>

The following class is an example of how to use Castor XML Mapping to manipulate the file 'order.xml'. It unmarshals the document 'order.xml', computes the total price, sets the total price in the java object and marshals the object model back into XML with the calculated price.

import org.exolab.castor.mapping.Mapping;
import org.exolab.castor.mapping.MappingException;

import org.exolab.castor.xml.Unmarshaller;
import org.exolab.castor.xml.Marshaller;

import java.io.IOException;
import java.io.FileReader;
import java.io.OutputStreamWriter;

import org.xml.sax.InputSource;

public class main {

    public static void main(String args[]) {

        Mapping      mapping = new Mapping();

        try {
            // 1. Load the mapping information from the file
            mapping.loadMapping( "mapping.xml" );

            // 2. Unmarshal the data
            Unmarshaller unmar = new Unmarshaller(mapping);
            MyOrder order = (MyOrder)unmar.unmarshal(new InputSource(new FileReader("order.xml")));

            // 3. Do some processing on the data
            float total = order.getTotalPrice();
            System.out.println("Order total price = " + total);
            order.setTotal(total);

            // 4. marshal the data with the total price back and print the XML in the console
            Marshaller marshaller = new Marshaller(new OutputStreamWriter(System.out));
            marshaller.setMapping(mapping);
            marshaller.marshal(order);

        } catch (Exception e) {
            System.out.println(e);
            return;
        }
    }
}
       

Ordinarily, a mapping will only reference types that are concrete classes (i.e. not interfaces nor abstract classes). The reason is that to unmarshal a type requires instantiating it and one cannot instantiate an interface. However, in many real situations, object models depend on the use of interfaces. Many class properties are defined to have interface types to support the ability to swap implementations. This is often the case in frameworks.

The problem is that a different mapping must be used each time the same model is to be used to marshal/unmarshal an implementation that uses different concrete types. This is not convenient. The mapping should represent the model and the specific concrete type used to unmarshal a document is a configuration parameter; it should be specified in the instance document to be unmarshalled, not the mapping.

For example, assume a very simple object model of an engine that has one property that is a processor:

public interface IProcessor {
    public void process();
}

public class Engine {
    private IProcessor processor;
    public IProcessor getProcessor() {
        return processor;
    }
    public void setProcessor(IProcessor processor) {
        this.processor = processor;
    }
}
            

A typical mapping file for such a design may be:

  
<mapping>
    <class name="Engine">
        <map-to xml="engine" />

        <field name="processor" type="IProcessor" required="true">
           <bind-xml name="processor" node="element" />
        </field>

     </class>
  </mapping>

It is possible to use such a mapping and still have the marshal/unmarshal process work by specifying the concrete implementation of IProcessor in the document to be unmarshalled, using the xsi:type attribute, as follows:

  <engine>
     <processor xsi:type="java:com.abc.MyProcessor" />
  </engine>
            

In this manner, one is still able to maintain only a single mapping, but vary the manner in which the document is unmarshalled from one instance document to the next. This flexibility is powerful because it enables the support of polymorphism within the castor xml marshalling framework.

Suppose we wanted the following XML instead:

  <engine>
     <myProcessor/>
  </engine>

In the above output our XML name changed to match the type of the class used instead of relying on the xsi:type attribute. This can be achieved by modifying the mapping file as such:

  <mapping>
     <class name="Engine">
        <map-to xml="engine" />
        <field name="processor" type="IProcessor" required="true">
           <bind-xml auto-naming="deriveByClass" node="element" />
        </field>
     </class>

     <class name="MyProcessor">
        <map-to xml="myProcessor" />
     </class>

  </mapping>

Since 0.9.5

The location attribute allows the user to map fields from nested elements or specify a wrapper element for a given field. Wrapper elements are simply elements which appear in the XML instance, but do not have a direct mapping to an object or field within the object model.

For example to map an instance of the following class:

public class Foo {

    private Bar bar = null;

    public Foo();

    public getBar() {
        return bar;
    }

    public void setBar(Bar bar) {
        this.bar = bar;
    }
}

into the following XML instance:

<?xml version="1.0"?>
<foo>;
   <abc>
      <bar>...</bar>
   </abc>
</foo>

(notice that an 'abc' field doesn't exist in the Bar class) One would use the following mapping:

<?xml version="1.0"?>
   ...
   <class name="Foo">
      <field name="bar" type="Bar">
         <bind-xml name="bar" location="abc"/>
      </field>
   </class>
   ...
</mapping>

Note the "location" attribute. The value of this attribute is the name of the wrapper element. To use more than one wrapper element, the name is separated by a forward-slash as such:

<bind-xml name="bar" location="abc/xyz" />

Note that the name of the element is not part of the location itself and that the location is always relative to the class in which the field is being defined. This works for attributes also:

<bind-xml name="bar" location="abc" node="attribute" />

will produce the following:

<?xml version="1.0"?>
<foo>
   <abc bar="..."/>;
</foo>

Some helpful hints...

To be defined ...

Before using the Marshaller class for marshalling Java objects to XML, the Marshaller can be fine-tuned according to your needs by calling a variety of set-methods on this class. This section enlists the available properties and provides you with information about their meaning, possible values and the default value.

Before using the Unmarshaller class for unmarshalling Java objects from XML, the Unmarshaller can be fine-tuned according to your needs by calling a variety of set-methods on this class. This section enlists the available properties and provides you with information about their meaning, possible values and the default value.

Being an XML data binding framework by definition, Castor XML relies on the availability of an XML parser at run-time. In Java, an XML parser is by default accessed though either the DOM or the SAX APIs: that implies that the XML Parser used needs to comply with either (or both) of these APIs.

With the creation of the JAXP API (and its addition to the Java language definition as of Java 5.0), Castor internally has been enabled to allow usage of the JAXP interfaces to interface to XML parsers. As such, Castor XML allows the use of a JAXP-compliant XML parser as well.

By default, Castor ships with Apache Xerces 2.6.2. You may, of course, upgrade to a newer version of Apache Xerces at your convenience, or switch to any other XML parser as long as it is JAXP compliant or implements a particular SAX interface. Please note that users of Java 5.0 and above do not need to have Xerces available at run-time, as JAXP and Xerces have both been integrated into the run-time library of Java.

For marshalling, Castor XML can equally use any JAXP complaint XML parser (or interact with an XML parser that implements the SAX API), with the exception of the following special case: when using 'pretty printing' during marshalling (by setting the corresponding property in castor.properties to true) with Java 1.4 or below, Apache Xerces has to be on the classpath, as Castor XML internally uses Xerces' XMLSerializer to implement this feature.

The following table enlists the requirements relative to the Java version used in your environment.

As of Castor 1.3.2, Castor XML can be used with a StAX-compliant parser to unmarshal from XML. Please see Example 1.1, “XML produced in introspection mode” for StAX-specific unmarshal methods added to org.exolab.castor.xml.Unmarshaller.

Castor uses a configuration file for environmental properties that are shared across all the Castor sub systems. The configuration file is specified as a Java properties file with the name castor.properties.

By definition, a default configuration file is included with the Castor XML JAR. Custom properties can be supplied using one of the following methods. Please note that the custom properties specified will override the default configuration.

Please note that Castor XML - upon startup - will try the methods given above in exactly the sequence as stated above; if it managed to find a custom property file using any of the given methods, it will cancel its search.

When running the provided examples, Castor will use the configuration file located in the examples directory which specifies additional debugging information as well as pretty printing of all produced XML documents.

The following properties are currently supported in the configuration file:

	Note
	As of Castor 1.3.3, the default values for org.exolab.castor.sax.features and org.exolab.castor.sax.features-to-disable have changed to include/disable selected features.

As of Castor 1.1, it is possible to read and set the value of properties programmatically using the getProperty(String) and setProperty(String,String) on the following classes:

Whilst using the setter methods on the first two classes will change the settings of the respective instances only, using the setProperty() method on the org.exolab.castor.xml.XMLContext class will change the configuration globally, and affect all org.exolab.castor.xml.Unmarshaller and org.exolab.castor.xml.Marshaller instances created thereafter using the org.exolab.castor.xml.XMLContext.createUnmarshaller() and org.exolab.castor.xml.XMLContext.createMarshaller() methods.

When developing using Castor, we recommend that you use the various setLogWriter methods to get detailed information and error messages.

Using a logger with org.exolab.castor.mapping.Mapping will provide detailed information about mapping decisions made by Castor and will show the SQL statements being used.

Using a logger with org.exolab.castor.jdo.JDO will provide trace messages that show when Castor is loading, storing, creating and deleting objects. All database operations will appear in the log; if an object is retrieved from the cache or is not modified, there will be no trace of load/store operations.

Using a logger with org.exolab.castor.xml.Unmarshaller will provide trace messages that show conflicts between the XML document and loaded objects.

A simple trace logger can be obtained from org.exolab.castor.util.Logger. This logger uses the standard output stream, but prefixes each line with a short message that indicates who generated it. It can also print the time and date of each message. Since logging is used for warning messages and simple tracing, Castor does not require a sophisticated logging mechanism.

Interested in integratating Castor's logging with Log4J? Then see this question in the JDO FAQ.

By default the marshaler writes XML documents without indentation. When developing using Castor or when debugging an application that uses Castor, it might be desireable to use indentation to make the XML documents human-readable. To turn indentation on, modify the Castor properties file, or create a new properties file in the classpath (named castor.properties) with the following content:

org.exolab.castor.indent=true
      

Indentation inflates the size of the generated XML documents, and also consumes more CPU. It is recommended not to use indentation in a production environment.

It is possible to disable the validation in the marshaling framework by modifying the Castor properties file or by creating a new properties file in the classpath (named castor.properties) with the following content:

 org.exolab.castor.marshalling.validation=false
        

Check your CLASSPATH, check it often, there is no reason not to!

	Note
	This only works with Castor-XML.

To save time when writing your mappings, try using the auto-complete attribute of class. When using auto-complete, Castor will introspect your class and automatically fill in any missing fields.

Example:

<class name="com.acme.Foo" auto-complete="true"/>
          

This is also compatible with generated descriptor files. You can use a mapping file to override some of the behavior of a compiled descriptor by using auto-complete.

	Note
	Be careful to make sure you use the exact field name as specified in the generated descriptor file in order to modify the behavior of the field descriptor! Otherwise, you'll probably end up with two fields being marshaled!

Castor requires that classes have a public, no-argument constructor in order to provide the ability to marshal & unmarshal objects of that type.

create-method is an optional attribute to the <field> mapping element that can be used to overcome this restriction in cases where you have an existing object model that consists of, say, singleton classes where public, no-argument constructors must not be present by definition.

Assume for example that a class "A" that you want to be able to unmarshal uses a singleton class as one of its properties. When attempting to unmarshal class "A", you should get an exception because the singleton property has no public no-arg constructor. Assuming that a reference to the singleton can be obtained via a static getInstance() method, you can add a "create method" to class A like this:

 public MySingleton getSingletonProperty() {
    return MySingleton.getInstance();
 }
      

and in the mapping file for class A, you can define the singleton property like this:

 <field name="mySingletonProperty"
       type="com.u2d.MySingleton"
       create-method="getSingletonProperty">
    <bind-xml name="my-singleton-property" node="element" />
 </field>

This illustrates how the create-method attribute is quite a useful mechanism for dealing with exceptional situations where you might want to take advantage of marshaling even when some classes do not have no-argument public constructors.

	Note
	As of this writing, the specified create-method must exist as a method in the current class (i.e. the class being described by the current <class> element). In the future it may be possible to use external static factory methods.

Castor allows control on the object being marshaled or unmarshaled by a set of two listener interfaces: MarshalListener and UnmarshalListener.

The MarshalListener interface located in org.exolab.castor.xml listens to two different events that are intercepted by the following methods:

The UnmarshalListener located also in org.castor.xml listens to four different events that are intercepted by the following methods:

Note: The UnmarshalListener had been part of org.exolab.castor.xml but as an extention of this interface had been required a new interface in org.castor.xml was introduced. Currently the org.exolab.castor.xml.UnmarshalListener interface can still be used but is deprecated.

Sometimes we need to deal with a data format that Castor doesn't support out-of-the-box, such as an unsupported Date/Time representation, or we want to wrap and unwrap fields in Wrapper objects to get the desired XML output without changing our object model. To handle these cases Castor allows specifying a custom org.exolab.castor.mapping.FieldHandler which can do these varying conversions during calls to the fields setter and getter methods.

	Note
	The FieldHandler is the basic interface used by the Castor Framework when accessing field values or setting them. By specifying a custom FieldHandler in the mapping file we can basically intercept the calls to retrieve or set a field's value and do whatever conversions are necessary.

When a writing a FieldHandler handler we need to provide implementations of the various methods specified in the FieldHandler interface. The main two methods are the getValue and setValue methods which will basically handle all our conversion code. The other methods provide ways to create a new instance of the field's value or reset the field value.

	Tip
	It's actually even easier to write custom field handlers if we use a GeneralizedFieldHandler. See more details in Section 1.7.3, “Writing a GeneralizedFieldHandler”

Let's take a look at how to convert a date in the format YYYY-MM-DD using a custom FieldHandler. We want to marshal the following XML input file text.xml:

<?xml version="1.0"?>
<root>2004-05-10</root>

The class we'll be marshalling from and unmarshalling to looks as follows:

import java.util.Date;

public class Root {

    private Date _date;

    public Root() {
        super();
    }

    public Date getDate() {
        return _date;
    }


    public void setDate(final Date date) {
        _date = date;
    }
         

So we need to write a custom FieldHandler that takes the input String and converts it into the proper java.util.Date instance:

import org.exolab.castor.mapping.FieldHandler;
import org.exolab.castor.mapping.FieldDescriptor;
import org.exolab.castor.mapping.ValidityException;

import java.text.ParseException;
import java.text.SimpleDateFormat;
import java.util.Date;

/**
 * The FieldHandler for the Date class
 *
 */
public class MyDateHandler implements FieldHandler
{

    private static final String FORMAT = "yyyy-MM-dd";

    /**
     * Creates a new MyDateHandler instance
     */
    public MyDateHandler() {
        super();
    }

    /**
     * Returns the value of the field from the object.
     *
     * @param object The object
     * @return The value of the field
     * @throws IllegalStateException The Java object has changed and
     *  is no longer supported by this handler, or the handler is not
     *  compatible with the Java object
     */
    public Object getValue(final Object object) throws IllegalStateException {
        Root root = (Root)object;
        Date value = root.getDate();
        if (value == null) return null;
        SimpleDateFormat formatter = new SimpleDateFormat(FORMAT);
        Date date = (Date)value;
        return formatter.format(date);
    }


    /**
     * Sets the value of the field on the object.
     *
     * @param object The object
     * @param value The new value
     * @throws IllegalStateException The Java object has changed and
     *  is no longer supported by this handler, or the handler is not
     *  compatible with the Java object
     * @throws IllegalArgumentException The value passed is not of
     *  a supported type
     */
    public void setValue(Object object, Object value) 
       throws IllegalStateException, IllegalArgumentException {
       
        Root root = (Root)object;
        SimpleDateFormat formatter = new SimpleDateFormat(FORMAT);
        Date date = null;
        try {
            date = formatter.parse((String)value);
        }
        catch(ParseException px) {
            throw new IllegalArgumentException(px.getMessage());
        }
        root.setDate(date);
    }


    /**
     * Creates a new instance of the object described by this field.
     *
     * @param parent The object for which the field is created
     * @return A new instance of the field's value
     * @throws IllegalStateException This field is a simple type and
     *  cannot be instantiated
     */
    public Object newInstance(Object parent) throws IllegalStateException {
        //-- Since it's marked as a string...just return null,
        //-- it's not needed.
        return null;
    }


    /**
     * Sets the value of the field to a default value.
     *
     * Reference fields are set to null, primitive fields are set to
     * their default value, collection fields are emptied of all
     * elements.
     *
     * @param object The object
     * @throws IllegalStateException The Java object has changed and
     *  is no longer supported by this handler, or the handler is not
     *  compatible with the Java object
     */
    public void resetValue(Object object) throws IllegalStateException, IllegalArgumentException {
        ((Root)object).setDate(null);
    }
}
       

	Tip
	The newInstance method should return null for immutable types.

	Note
	There is also an org.exolab.castor.mapping.AbstractFieldHandler that we can extend instead of implementing FieldHandler directly. Not only do we not have to implement deprecated methods, but we can also gain access to the FieldDescriptor used by Castor.

In order to tell Castor that we want to use our Custom FieldHandler we must specify it in the mapping file mapping.xml:

<?xml version="1.0"?>
<mapping>
  <class name="Root">
     <field name="date" type="string" handler="MyDateHandler">
        <bind-xml node="text"/>
     </field>
  </class>
</mapping>

        

We can now use a simple Test class to unmarshal our XML document:

import java.io.*;
import org.exolab.castor.xml.*;
import org.exolab.castor.mapping.*;

public class Test {

    public static void main(String[] args) {
	    try {

	       //--load mapping
	       Mapping mapping = new Mapping();
	       mapping.loadMapping("mapping.xml");

           System.out.println("unmarshalling root instance:");
           System.out.println();

           Reader reader = new FileReader("test.xml");
           Unmarshaller unmarshaller = new Unmarshaller(Root.class);
           unmarshaller.setMapping(mapping);
           Root root = (Root) unmarshaller.unmarshal(reader);
           reader.close();

           System.out.println("Root#getDate : " + root.getDate());
	    }
	    catch (Exception e) {
	        e.printStackTrace();
	    }
    }
}

         

Now simply compile the code and run!

% java Test
unmarshalling root instance:

Root#getDate : Mon May 10 00:00:00 CDT 2004
         

After running our test program we can see that Castor invoked our custom FieldHandler and we got our properly formatted date in our Root.class.

A org.exolab.castor.mapping.GeneralizedFieldHandler is an extension of FieldHandler interface where we simply write the conversion methods and Castor will automatically handle the underlying get/set operations. This allows us to re-use the same FieldHandler for fields from different classes that require the same conversion.

	Note
	Note: Currently the GeneralizedFieldHandler cannot be used from a binding-file for use with the SourceGenerator, an enhancement patch will be checked into SVN for this feature, shortly after 0.9.6 final is released.

The same FieldHandler we used above can be written as a GeneralizedFieldHandler as such:

import org.exolab.castor.mapping.GeneralizedFieldHandler;
import org.exolab.castor.mapping.FieldDescriptor;

import java.text.ParseException;
import java.text.SimpleDateFormat;
import java.util.Date;

/**
 * The FieldHandler for the Date class
 *
 */
public class MyDateHandler extends GeneralizedFieldHandler {

    private static final String FORMAT = "yyyy-MM-dd";

    /**
     * Creates a new MyDateHandler instance
     */
    public MyDateHandler() {
        super();
    }

    /**
     * This method is used to convert the value when the
     * getValue method is called. The getValue method will
     * obtain the actual field value from given 'parent' object.
     * This convert method is then invoked with the field's
     * value. The value returned from this method will be
     * the actual value returned by getValue method.
     *
     * @param value the object value to convert after
     *  performing a get operation
     * @return the converted value.
     */
    public Object convertUponGet(Object value) {
        if (value == null) return null;
        SimpleDateFormat formatter = new SimpleDateFormat(FORMAT);
        Date date = (Date)value;
        return formatter.format(date);
    }


    /**
     * This method is used to convert the value when the
     * setValue method is called. The setValue method will
     * call this method to obtain the converted value.
     * The converted value will then be used as the value to
     * set for the field.
     *
     * @param value the object value to convert before
     *  performing a set operation
     * @return the converted value.
     */
    public Object convertUponSet(Object value) {
        SimpleDateFormat formatter = new SimpleDateFormat(FORMAT);
        Date date = null;
        try {
            date = formatter.parse((String)value);
        }
        catch(ParseException px) {
            throw new IllegalArgumentException(px.getMessage());
        }
        return date;
    }

    /**
     * Returns the class type for the field that this
     * GeneralizedFieldHandler converts to and from. This
     * should be the type that is used in the
     * object model.
     *
     * @return the class type of of the field
     */
    public Class getFieldType() {
        return Date.class;
    }

    /**
     * Creates a new instance of the object described by
     * this field.
     *
     * @param parent The object for which the field is created
     * @return A new instance of the field's value
     * @throws IllegalStateException This field is a simple
     *  type and cannot be instantiated
     */
    public Object newInstance(Object parent) throws IllegalStateException
    {
        //-- Since it's marked as a string...just return null,
        //-- it's not needed.
        return null;
    }

}

        

Everything else is the same. So we can re-run our test case using this GeneralizedFieldHandler and we'll get the same result. The main difference is that we implement the convertUponGet and convertUponSet methods.

Notice that we never reference the Root class in our GeneralizedFieldHandler. This allows us to use the same exact FieldHandler for any field that requires this type of conversion.

In some situations, the GeneralizedFieldHandler might not provide sufficient flexibility. Suppose your XML document uses more than one date format. You could solve this by creating a GeneralizedFieldHandler subclass per date format, but that would lead to code duplication, which in itself is not desirable.

A ConfigurableFieldHandler is a FieldHandler that can be configured in the mapping file with any kind and any number of parameters. You can simply configure two (or more) instances of the same ConfigurableFieldHandler class with different date format patterns. Here's a mapping file that uses a ConfigurableFieldHandler to marshal and unmarshal the date field, similar to the preceding examples:

<?xml version="1.0"?>
<mapping>
   
   <field-handler name="myHandler" class="FieldHandlerImpl">
      <param name="date-format" value="yyyyMMddHHmmss"/>
   </field-handler>
   
   <class name="Root">
      <field name="date" type="string" handler="myHandler"/>
   </class>

</mapping>
         	

The field-handler element defines the ConfigurableFieldHandler. The class must be an implementation of the org.exolab.castor.mapping.ConfigurableFieldHandler interface. This instance is configured with a date format. However, each implementation can decide which, and how many parameters to use.

The field handler instance is referenced by the field element, using the handler attribute.

Here's the ConfigurableFieldHandler implementation:

import java.text.ParseException;
import java.text.SimpleDateFormat;
import java.util.Date;

import java.text.ParseException;
import java.text.SimpleDateFormat;
import java.text.DateFormat;
import java.util.Date;
import java.util.Properties;

import org.exolab.castor.mapping.ConfigurableFieldHandler;
import org.exolab.castor.mapping.FieldHandler;
import org.exolab.castor.mapping.GeneralizedFieldHandler;
import org.exolab.castor.mapping.ValidityException;

public class FieldHandlerImpl implements FieldHandler, ConfigurableFieldHandler {

    private DateFormat formatter;

    public void setConfiguration(final Properties config) throws ValidityException {
    	String pattern = config.getProperty("date-format");
    	if (pattern == null) {
    		throw new ValidityException("Required parameter \"date-format\" is missing for FieldHandlerImpl.");
    	}
    	try {
    		formatter = new SimpleDateFormat(pattern);
    	} catch (IllegalArgumentException e) {
    		throw new ValidityException("Pattern \""+pattern+"\" is not a valid date format.");
    	}
    }

    /**
     * Returns the value of the field from the object.
     *
     * @param object The object
     * @return The value of the field
     * @throws IllegalStateException The Java object has changed and
     *  is no longer supported by this handler, or the handler is not
     *  compatible with the Java object
     */
    public Object getValue(Object object) throws IllegalStateException {
        Root root = (Root)object;
        Date value = root.getDate();
        if (value == null) return null;
        return formatter.format(value);
    }

    /**
     * Sets the value of the field on the object.
     *
     * @param object The object
     * @param value The new value
     * @throws IllegalStateException The Java object has changed and
     *  is no longer supported by this handler, or the handler is not
     *  compatible with the Java object
     * @throws IllegalArgumentException The value passed is not of
     *  a supported type
     */
    public void setValue(Object object, Object value)
        throws IllegalStateException, IllegalArgumentException {
        Root root = (Root)object;
        Date date = null;
        try {
            date = formatter.parse((String)value);
        }
        catch(ParseException px) {
            throw new IllegalArgumentException(px.getMessage());
        }
        root.setDate(date);
    }
    
    /**
     * Creates a new instance of the object described by this field.
     *
     * @param parent The object for which the field is created
     * @return A new instance of the field's value
     * @throws IllegalStateException This field is a simple type and
     *  cannot be instantiated
     */
    public Object newInstance(Object parent)
        throws IllegalStateException
    {
        //-- Since it's marked as a string...just return null,
        //-- it's not needed.
        return null;
    }

    /**
     * Sets the value of the field to a default value.
     *
     * Reference fields are set to null, primitive fields are set to
     * their default value, collection fields are emptied of all
     * elements.
     *
     * @param object The object
     * @throws IllegalStateException The Java object has changed and
     *  is no longer supported by this handler, or the handler is not
     *  compatible with the Java object
     */
    public void resetValue(Object object)
        throws IllegalStateException, IllegalArgumentException {
        ((Root)object).setDate(null);
    }

}
      	

This implementation is similar to the first MyDateHandler example on this page, except that is adds a setConfiguration method as specified by the ConfigurableFieldHandler interface. All parameters that are configured in the mapping file will be passed in as a Properties object. The implementing method is responsible for processing the configuration data.

As a convenience, org.exolab.castor.mapping.AbstractFieldHandler already implements ConfigurableFieldHandler. However, the setConfiguration method is not doing anything. Any subclass of AbstractFieldHandler only has to override this method to leverage the configuration capabilities. Since AbstractFieldHandler and its subclass GeneralizedFieldHandler are useful abstract classes, you'd probably want to use them anyway. It eliminates the need to implement the ConfigurableFieldHandler interface yourself.

Imagine a scenario where you want to use above ConfigurableFieldHandler instance for more than one field - a valid use case as it promotes reuse.

<?xml version="1.0"?>
<mapping>
   
   <field-handler name="myFirstHandler" class="FieldHandlerImpl">
      <param name="date-format" value="yyyyMMddHHmmss"/>
   </field-handler>

   <field-handler name="mySecondHandler" class="FieldHandlerImpl">
      <param name="date-format" value="yyyy-MM-ddHH:mm:ss"/>
   </field-handler>
   
   <class name="Root">
      <field name="firstDate" type="string" handler="myFirstHandler"/>
      <field name="secondDate" type="string" handler="myFirstHandler"/>
      <field name="thirdDate" type="string" handler="mySecondHandler"/>
   </class>

</mapping>
         

For this to work, there's one more thing you will have to do: your ConfigurableFieldHandler implementation has to implement the ClonableFieldHandlerMarker interface and implement the copyFieldHandler() method. As indicated by the name, please return a clone/copy of your FieldHandler instance ... and you are all set.

A simplified sample implementation could look as follows, extending the FieldHandlerImpl class from the previous section:

public class FieldHandlerImpl implements FieldHandler, ConfigurableFieldHandler, ClonableFieldHandlerMarker {

    private DateFormat format;

    ...

    public void setFormat(DateFormat format) {
        this.format = format;
    }

    @Override
    public FieldHandler copyFieldHandler() {
        FieldHandlerImpl handler = new FieldHandlerImpl();
        handler.setFormat(this.getFormat());
        return handler;
    }
    
}    	
    	

A number of classes such as type-safe enum style classes have no constructor, but instead have some sort of static factory method used for converting a string value into an instance of the class. With a custom FieldHandler we can allow Castor to work nicely with these types of classes.

	Tip
	Castor XML automatically supports these types of classes if they have a specific method: public static {Type} valueOf(String)

	Note
	We're working on the same support for Castor JDO

Even though Castor XML supports the "valueOf" method type-safe enum style classes, we'll show you how to write a custom handler for these classes anyway since it's useful for any type of class regardless of the name of the factory method.

Let's look at how to write a handler for the following type-safe enum style class, which was actually generated by Castor XML (javadoc removed for brevity):

import java.io.Serializable;
import java.util.Enumeration;
import java.util.Hashtable;

public class Color implements java.io.Serializable {

    public static final int RED_TYPE = 0;

    public static final Color RED = new Color(RED_TYPE, "red");

    public static final int GREEN_TYPE = 1;

    public static final Color GREEN = new Color(GREEN_TYPE, "green");

    public static final int BLUE_TYPE = 2;

    public static final Color BLUE = new Color(BLUE_TYPE, "blue");

    private static java.util.Hashtable _memberTable = init();

    private int type = -1;

    private java.lang.String stringValue = null;


    private Color(int type, java.lang.String value) {
        super();
        this.type = type;
        this.stringValue = value;
    } //-- test.types.Color(int, java.lang.String)


    public static java.util.Enumeration enumerate()
    {
        return _memberTable.elements();
    } //-- java.util.Enumeration enumerate()

    public int getType()
    {
        return this.type;
    } //-- int getType()

    private static java.util.Hashtable init()
    {
        Hashtable members = new Hashtable();
        members.put("red", RED);
        members.put("green", GREEN);
        members.put("blue", BLUE);
        return members;
    } //-- java.util.Hashtable init()

    public java.lang.String toString()
    {
        return this.stringValue;
    } //-- java.lang.String toString()

    public static Color valueOf(java.lang.String string)
    {
        Object obj = null;
        if (string != null) obj = _memberTable.get(string);
        if (obj == null) {
            String err = "'" + string + "' is not a valid Color";
            throw new IllegalArgumentException(err);
        }
        return (Color) obj;
    } //-- test.types.Color valueOf(java.lang.String)

}
       

The GeneralizedFieldHandler for the above Color class is as follows (javadoc removed for brevity):

import org.exolab.castor.mapping.GeneralizedFieldHandler;
import org.exolab.castor.mapping.FieldDescriptor;

/**
 * The FieldHandler for the Color class
**/
public class ColorHandler
    extends GeneralizedFieldHandler
{

    public ColorHandler() {
        super();
    }

    public Object convertUponGet(Object value) {
        if (value == null) return null;
        Color color = (Color)value;
        return color.toString();
    }


    public Object convertUponSet(Object value) {
        return Color.valueOf((String)value);
    }

    public Class getFieldType() {
        return Color.class;
    }

    public Object newInstance( Object parent )
        throws IllegalStateException
    {
        //-- Since it's marked as a string...just return null,
        //-- it's not needed.
        return null;
    }

}
     

That's all there really is to it. Now we just need to hook this up to our mapping file and run a sample test.

If we have a root class Foo as such:

public class Foo {

    private Color _color = null;
    private int _size = 0;
    private String _name = null;

    public Foo() {
        super();
    }

    public Color getColor() {
        return _color;
    }

    public String getName() {
        return _name;
    }

    public int getSize() {
        return _size;
    }

    public void setColor(Color color) {
        _color = color;
    }

    public void setName(String name) {
        _name = name;
    }

    public void setSize(int size) {
        _size = size;
    }

}
       

Our mapping file would be the following:

<?xml version="1.0"?>
<mapping>
  <class name="Foo">
     <field name="size" type="integer">
        <bind-xml node="element"/>
     </field>
     <field name="name" type="string"/>
     <field name="color" type="string" handler="ColorHandler"/>
  </class>
</mapping>
       

We can now use our custom FieldHandler to unmarshal the following xml input:

<?xml version="1.0"?>
<foo>
   <name>MyFoo</name>
   <size>345</size>
   <color>blue</color>
</foo>
       

A sample test class is as follows:

import java.io.*;
import org.exolab.castor.xml.*;
import org.exolab.castor.mapping.*;

public class Test {

    public static void main(String[] args) {
	    try {

	        //--load mapping
	        Mapping mapping = new Mapping();
	        mapping.loadMapping("mapping.xml");

            System.out.println("unmarshalling Foo:");
            System.out.println();

            Reader reader = new FileReader("test.xml");
            Unmarshaller unmarshaller = new Unmarshaller(Foo.class);
            unmarshaller.setMapping(mapping);
            Foo foo = (Foo) unmarshaller.unmarshal(reader);
            reader.close();

            System.out.println("Foo#size : " + foo.getSize());
            System.out.print("Foo#color: ");
            if (foo.getColor() == null) {
                System.out.println("null");
            }
            else {
                System.out.println(foo.getColor().toString());
            }

            PrintWriter pw = new PrintWriter(System.out);
            Marshaller marshaller = new Marshaller(pw);
            marshaller.setMapping(mapping);
            marshaller.marshal(foo);
            pw.flush();
	    }
	    catch (Exception e) {
	        e.printStackTrace();
	    }
    }
}
        

	Note
	With Castor 0.9.6 and later, the GeneralizedFieldHandler automatically supports iterating over the items of a collection and passing them one-by-one to the convertUponGet. For backward compatibility or to handle the collection iteration yourself, simply add the following to the constructor of your GeneralizedFieldHandler implementation: setCollectionIteration(false);

If you're going to be using custom field handlers for collection fields with a GeneralizedFieldHandler using versions of Castor prior to 0.9.6, then you'll need to handle the collection iteration yourself in the convertUponGet method.

If you're not using a GeneralizedFieldHandler, then you'll need to handle the collection iteration yourself in the FieldHandler#getValue() method.

	Tip
	Since Castor incrementally adds items to collection fields, there usually is no need to handle collections directly in the convertUponSet method (or the setValue() for those not using GeneralizedFieldHandler).

This is a collection of HOW-TOs. The Castor project is actively seeking additional HOW-TO contributors to expand this collection. For information on how to do that, please see 'How to write a How-to'.