|  |  |  | License Codehaus OpenEJB OpenJMS OpenORB Tyrex

Old releases
General
Release 1.3
Release 1.3rc1
Release 1.2

Main
Home
About
Features
Download
Dependencies
Reference guide
Publications
JavaDoc
Maven 2 support
Maven 2 archetypes
DTD & Schemas
Recent HTML changes
News Archive
RSS news feed
Project Wiki

Development/Support
Mailing Lists
SVN/JIRA
Contributing
Support
Continuous builds
Prof. services

Related projects
Spring ORM support
Spring XML factories
WS frameworks

XML
XML

XML Code Generator
XML Code Generator

JDO
Introduction
First steps
Using JDO
JDO Config
Types
JDO Mapping
JDO FAQ
JDO Examples
JDO HOW-TOs
Tips & Tricks
Other Features
JDO sample JAR

Tools
Schema generator

Advanced JDO
Caching
OQL
Trans. & Locks
Design
KeyGen
Long Trans.
Nested Attrs.
Pooling Examples
LOBs
Best practice

DDL Generator
Using DDL Generator
Properties
Ant task
Type Mapping

More
The Examples
3rd Party Tools
JDO Tests
XML Tests
Configuration

About
License
User stories
Contributors
Marketplace
Status, Todo
Changelog
Library
Contact
Project Name

## How to use the Spring FactoryBeans for Castor XML

Documentation Author(s):
Werner Guttmann
Steven Dolg

## Prerequisites

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

## How to bootstrap Castor XML configuration

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

### Adding mappings

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>

### Setting global properties

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

### Finding generated descriptors

TBA

## How to use the CastorMarshallerFactoryBean

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

## How to use the CastorUnmarshallerFactoryBean

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());

## Backwards compatibility - Resolvr & how to specify a mapping file

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>

<notice> Copyright © 1999-2005 ExoLab Group, Intalio Inc., and Contributors. All rights reserved. </notice>
<notice> Java, EJB, JDBC, JNDI, JTA, Sun, Sun Microsystems are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and in other countries. XML, XML Schema, XSLT and related standards are trademarks or registered trademarks of MIT, INRIA, Keio or others, and a product of the World Wide Web Consortium. All other product names mentioned herein are trademarks of their respective owners. </notice>