XML Mapping

Marshalling Behavior

For Castor, a Java class has to map into an XML element. When Castor marshals an object, it will:

• use the mapping information, if any, to find the name of the element to create

or

• by default, create a name using the name of the class

It will then use the fields information from the mapping file to determine how a given property of the object has to be translated into one and only one of the following:

• an attribute

• an element

• text content

• nothing, as we can choose to ignore a particular field

This process will be recursive: if Castor finds a property that has a class type specified elsewhere in the mapping file, it will use this information to marshal the object.

By default, if Castor finds no information for a given class in the mapping file, it will introspect the class and apply a set of default rules to guess the fields and marshal them. The default rules are as follows:

• All primitive types, including the primitive type wrappers (Boolean, Short, etc…) are marshalled as attributes.

• All other objects are marshalled as elements with either text content or element content.

Unmarshalling Behavior

When Castor finds an element while unmarshalling a document, it will try to use the mapping information to determine which object to instantiate. If no mapping information is present, Castor will use the name of the element to try to guess the name of a class to instantiate (for example, for an element named ‘test-element’, Castor will try to instantiate a class named ‘TestElement’ if no information is given in the mapping file). Castor will then use the field information of the mapping file to handle the content of the element.

If the class is not described in the mapping file, Castor will instrospect the class using the Java Reflection API to determine if there is any function of the form getXxxYyy()/setXxxYyy(<type> x). This accessor will be associated with XML element/attribute named ‘xxx-yyy’. In the future, we will provide a way to override this default behavior.

Castor will introspect object variables and use direct access _only_ if no get/set methods have been found in the class. In this case, Castor will look for public variables of the form:

public <type> xxxYYY;        

and expect an element/attribute named ‘xxx-yyy’. The only handled collections for <type> are java.lang.Vector and array. (up to version 0.8.10)

For primitive <type>, Castor will look for an attribute first and then an element. If <type> is not a primitive type, Castor will look for an element first and then an attribute.

Sample domain objects

This section defines a small domain model that will be referenced by various mapping file (fragments/samples) in the following sections. The model consists of two two classes Order and OrderItem, where an order holds a list of order items.

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;
    }
}

As shown above in bold, the Order instance has a (private) field 'orderItems' to hold a collection of OrderItem instances. This field is publically exposed by corresponding getter and setter methods.

The <mapping> element

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

The <mapping> element is the root element of a mapping file. It contains:

• an optional description

• zero or more <include> which facilitates reusing mapping files

• zero of more <field-handler> defining custom, configurable field handlers

• zero or more <class> descriptions: one for each class we intend to give mapping information

• zero or more <key-generator>: not used for XML mapping

A mapping file look like this:

<?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>

The <class> element

<!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 >

The <class> element contains all the information used to map a Java class into an XML document. The content of <class> is mainly used to describe the fields that will be mapped.

The auto-complete attributes is interesting as it allow a fine degree of control of the introspector: it is possible to specifiy only the fields whose Castor default behavior does not suite our needs. These feature should simplify the handling of complexe class containing many fields. Please see below for an example usage of this attribute.

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

The <map-to> element

<!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>

<map-to> is used to specify the name of the element that should be associated with the given class. <map-to> is only used for the root class. If this information is not present, Castor will:

• for marshalling, infer the name of the element to be mapped from the name of the class: a Java class named ‘XxxYyy’ will be transformed into ‘xxx-yyy’.

• for unmarshalling, infer the name of the class from the name of the element: for an element named ‘test-element’ Castor will try to use a class named ‘TestElement’

Please note that it is possible to change the naming scheme used by Castor to translate between the XML name and the Java class name in the castor.properties file.

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

The <field> element

<!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> is used to describe a property of a Java object we want to marshal/unmarshal. It gives:

• its identity (‘name’)

• its type (infered from ‘type’ and ‘collection’)

• its access method (infered from ‘direct’, ‘get-method’, ‘set-method’)

From this information, Castor is able to access a given property in the Java class.

In order to determine the signature that Castor expects, there are two easy rules to apply.

1. Determine <type>.

• If there is no ‘collection’ attribute, the <type> is just the Java type specified in <type_attribute> (the value of the ‘type’ attribute in the XML document). The value of <type_attribute> can be a fully qualified Java object like ‘java.lang.String’ or one of the allowed short name:

Castor will try to cast the data in the XML file in the proper Java type.

• If there is a collection attribute , you can use the following table:

The type of the object inside the collection is <type_attribute>. The ‘default implementation’ is the type used if the object holding the collection is found to be null and need to be instantiated.

For hashtable and maps (since 0.9.5.3), Castor will save both key and values. When marshalling output <key> and <value> elements. These names can be controlled by using a top-level or nested class mapping for the org.exolab.castor.mapping.MapItem class.

Note: for backward compatibility with prior versions of Castor, the saveMapKeys property can be set to false in the castor.properties file.

For versions prior to 0.9.5.3, hashtable and maps, Castor will save only the value during marshalling and during unmarshalling will add a map entry using the object as both the key and value, e.g. map.put(object, object).

It is necessary to use a collection when the content model of the element expects more than one element of the specified type.

Determine the signature of the function

• If ‘direct’ is set to true, Castor expects to find a class variable with the given signature:

    public <type> <name>;

• If ‘direct’ is set to false or omitted, Castor will access the property though accessor methods. Castor determines the signature of the accessors as follow: If the ‘get-method’ or ‘set-method’ attributes are supplied, it will try to find a function with the following signature:

    public <type> <get-method>();

or

    public void <set-method>(<type> value);

If ‘get-method’ and ‘set-method’ attributes are not provided, Castor will try to find the following function:

    public <type> get<capitalized-name>();

or

    public void set<capitalized-name>(<type> value);

<capitalized-name> means that Castor takes the <name> attribute and put its first letter in uppercase without modifying the other letters.

The content of <field> will contain the information on how to map this given field to SQL, XML, …

• Exceptions concerning collection fields:

The default is to treat the ‘get-method’ as a simple getter returning the collection field, and the ‘set-method’ as a simple getter used to set a new instance on the collection field.

public Iterator iterate...();

public Enumeration enum...();

public void add...(<type> value);

                  -   The fully-qualified class name of a custom field handler implementation, or
                  -   The (short) name of a [configurable field handler](http://www.castor.org/xml-fieldhandlers.html#Use-ConfigurableFieldHandler-for-more-flexibility) definition.

Description of the content

In the case of XML mapping, the content of a field element should be one and only one <bind-xml> element describing how this given field will be mapped into the XML document.

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

The <bind-xml> element

<!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">

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

Automatically create a mapping file

Castor comes with a tool that can automatically create a mapping from class files. Please see the XML FAQ for more information.

Create your own FieldHandler

Sometimes to handle complex situations you’ll need to create your own FieldHandler. Normally a FieldHandler deals with a specific class and field, however generic, reusable FieldHandlers can also be created by extending org.exolab.castor.mapping.GeneralizedFieldHandler or org.exolab.castor.mapping.AbstractFieldHandler. The FieldHandler can be specified on the <field> element.

For more information on writing a custom FieldHandler please see the following: XML FieldHandlers.

Mapping constructor arguments (since 0.9.5)

You may map any attributes to constructor arguments. For more information on how to map constructor arguments see the information available in the section on set-method above.

Please note that mapping elements to constructor arguments is not yet supported.

Tip: the XML HOW-TO section has a HOW-TO document for mapping constructor arguments.

Preventing Castor from checking for a default constructor (since 0.9.5)

Sometimes it’s useful to prevent Castor from checking for a default constructor, such as when trying to write a mapping for an interface or type-safe enum. You can use the “undocumented” verify-constructable=“false” attribute on the <class> element to prevent Castor from looking for the default constructor.

Type safe enumeration mapping (since 0.9.5)

While you can always use your own custom FieldHandler for handling type-safe enumeration classes, Castor does have a built-in approach to dealing with these types of classes. If the type-safe enum class has a public static <type> valueOf(String) method Castor will call that method so that the proper instance of the enumeration is returned. Note: You’ll also need to disable the default constructor check in the mapping file (see section 7.4 above to see more on this).