How to use the Spring FactoryBeans for Castor XML

Documentation Author(s):
Werner Guttmann
Steven Dolg

The following sections assume that you have a valid Castor XML mapping for a Java entity named Product as follows:

<mapping>

  <!--  Mapping for Product  -->
  <class name="org.castor.spring.xml.Product" identity="id">
    <map-to xml="product" />
	<field name="id" type="integer">
		  <bind-xml name="id" node="element"/>
		</field>
    <field name="name" type="string">
      <bind-xml name="name" node="element" />
    </field>
  </class>

</mapping>			
			

The sources for this Product entity are as follows:

public class Product {

    private int id;
    private String name;
    
    public int getId() {
        return this.id;
    }
    public void setId(int id) {
        this.id = id;
    }
    public String getName() {
        return this.name;
    }
    public void setName(String name) {
        this.name = name;
    }
}
			

As of Castor 1.2.1, a new XMLContext clas has been added to allow a single point of configuration for all data binding work related to Castor, and to re-use it throughout your work.

To define an XMLContext and base all Marshaller and Unmarshaller instances on this configuration, please add a bean definition to your application context as follows:

   <bean id="xmlContext" class="org.castor.spring.xml.XMLContextFactoryBean" />
            

The following sections describe how to ...

-	configure custom mapping(s)
-	configure (global) XML-specific properties
-	supply hints to the XMLContext where to look for (generated) descriptor classes

To pre-configure your XMLContext instances with one or more custom mapping file(s) to gain a finer level of control (as such overriding the default introspection mechanism employed otherwise), please amend above bean definition as follows:

<bean id="xmlContext" class="org.castor.spring.xml.XMLContextFactoryBean">
   <property name="mappingLocations">
      <list>
         <value>mapping.xml</value>
      </list>
   </property>
</bean>
            

XMLContext allows the programmatic definition of XML-specific properties through its setProperty(String, String) method. This functionality is accessible through the property castorProperties, a sample usage of which is shown in the following bean definition for an XMLcontext:

<bean id="xmlContext" class="org.castor.spring.xml.XMLContextFactoryBean">
   <property name="castorProperties">
      <props>
         <prop key="org.exolab.castor.indent">true</prop>
      </props>
   </property>
</bean>
            

TBA

Before you'll be able to obtain an instance of Marshaller through Spring, you have to add a Spring bean definition to your Spring configuration as follows:

<bean id="marshaller"
      class="org.castor.spring.xml.CastorMarshallerFactoryBean">
   <property name="xmlContext"><ref local="xmlContext"/></property>
</bean>
            

Please note that the XMLContext defiened in the previous section is injected by supplying a reference on the xmlContext property.

Based upon this configuration, you will be able to obtain a Marshaller instance as follows:

ApplicationContext context = ....;
Marshaller marshaller = (Marshaller) this.context.getBean("marshaller");            
            

The Marshaller instance obtained in this way does not have any mapping information associated, and will thus use the introspection mechanism to establish a mapping between the Java object and the XML representations.

With the above Marshaller instance, you can set e.g. a java.io.Writer and simply start the marshalling process as shown below:

        Writer out = new StringWriter();
        marshaller.setWriter(out);
        marshaller.marshal(product);
            

Before you'll be able to obtain an instance of Unmarshaller through Spring, you have to add a Spring bean definition to your Spring configuration as follows:

<bean id="unmarshaller"
      class="org.castor.spring.xml.CastorUnmarshallerFactoryBean">
   <property name="xmlContext"><ref local="xmlContext"/></property>
</bean>
    	    

Please note that the XMLContext defiened in the previous section is injected by supplying a reference on the xmlContext property.

Based upon this configuration, you will be able to obtain a Unmarshaller instance as follows:

ApplicationContext context = ....;
Unmarshaller unmarshaller = (Unmarshaller) this.context.getBean("unmarshaller");            
            

The Unmarshaller instance obtained in this way does not have any mapping information associated, and will thus use the default introspection mechanism to establish a mapping between the Java object and the XML representations.

With the above Unmarshaller instance, you can unmarshal the following XML document instance as shown subsequently:

<?xml version="1.0" encoding="UTF-8"?>
<product>
   <name>blah</name>
   <id>1</id>
</product>
            

Product product = (Product) unmarshaller.unmarshal(new InputSource(resource));
assertNotNull(product);
assertEquals(1, product.getId());
assertEquals("name", product.getName());
             

This section describes how to use a Castor YMLClassDescriptorResolver instance (for use with Castor versions before the XMLContext has been added) to load custom mapping files once (and once only), and how to pass this 'resolver' instance to Marshaller and Unmarshaller instances for re-use.

To specify that the Castor (Un)Marshaller instances should use a custom mapping file (in addition to the default introspection mechanism), please amend above bean definition for the 'resolver' bean as follows:

<bean id="resolver" class="org.castor.spring.xml.CastorResolverFactoryBean">
   <property name="mappingLocations">
      <list>
         <value>mapping.xml</value>
      </list>
   </property>
</bean>	   	
	   	

Please note that the mapping file location is relative to your CLASSPATH.

To use more than one mapping file, please add a bean definition for the 'resolver' as follows:

<bean id="resolver" class="org.castor.spring.xml.CastorResolverFactoryBean">
   <property name="mappingLocations">
      <list>
         <value>mapping1.xml</value>
         <value>mapping2.xml</value>
      </list>
   </property>
</bean>