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

## Using Castor XML

Reference: The XML Framework API

Note: This documentation is not yet finished

Introduction
Castor XML - The XML data binding framework
Introspection mode
Mapping mode
Descriptor mode
Sources and destinations
XMLContext - A consolidated way to bootstrap Castor
Using existing Classes/Objects
Class Descriptors
Compile-Time Descriptors
Run-Time Descriptors

## Introduction

Castor XML is an XML databinding 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 one 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.

## Castor XML - The XML data binding framework

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, <api>org.exolab.castor.xml.Marshaller and <api>org.exolab.castor.xml.Unmarshaller respectively, and a bootstrap class <api>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:

- | introspection mode
- | mapping mode
- | descriptor mode(aka generation mode)

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

### 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 Marshaller and Unmarshaller classes, providing all required data as parameters on these method calls.

To marshal an instance of the person class you simply call the 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);

To unmarshal an instance of the person class from XML, you simply call the 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: 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 Marshaller or 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 artefacts. In such a case, a mapping file should be used.

### Mapping mode

In mapping mode, the user provides Castor XML with a user-defined mapping (in form of a mapping file) that allows the (partial) definition of a customized mapping between Java classes (and their properties) and XML.

When you are using a mapping file, create an instance of the <api>org.exolab.castor.xml.XMLContext class and use the addMapping(Mapping) method to provide Castor XML with one of more mapping files.

To start using Castor XML for marshalling and/or unmarshalling based upon your custom mapping, create instances of <api>org.exolab.castor.xml.Marshaller and <api>org.exolab.castor.xml.Unmarshaller as needed using one of the following methods:

createMarshaller | Creates a Marshaller instance.
createUnmarshaller | Creates a Unmarshaller instance.

and call any of the non-static (un)marshal methods to trigger data binding in either way.

Below code shows a full example that demonstrates unmarshalling a `Person` instance from XML using a Unmarshaller instance as obtained from an XMLContext previously configured to your needs.

Unmarshalling from XML using a mapping

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

To marshal the very same `Person` instance to XML using a Marshaller obtained from the same XMLContext, use code as follows:

Marshalling to XML using a mapping

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

Please have a look at XML Mapping for a detailed discussion of the mapping file and its structure.

For more information on how to effectively deal with loading mapping file(s) especially in multi-threaded environments, please check the best practice section.

### Descriptor mode

TBD

## Sources and destinations

TBD

## XMLContext - A consolidated way to bootstrap Castor

With Castor 1.1.2, the 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 Marshaller and Unmarshaller instances as needed.

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

When you need more than one Unmarshaller instance in your application, please call 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.

## Using existing Classes/Objects

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.

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 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 The Marshalling Framework demonstrates how to use the framework with existing classes.

## Class Descriptors

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

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

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

#### Compile-Time Descriptors

To use "compile-time" class descriptors, one can either implement the <api>org.exolab.castor.xml.XMLClassDescriptor interface for each class which needs to be "described", or have the Source Code Generator create the proper descriptors.

The main advantage of compile-time descriptors is that they are faster than the run-time approach.

#### Run-Time Descriptors

To use "run-time" class descriptors, one can either simply let Castor introspect the classes, a mapping file can be provided, or a combination of both "default introspection" and a specified mapping file may be used.

For "default introspection" to work the class being introspected must have adequete setter/getter methods for each field of the class that should be marshalled and unmarshalled. If no getter/setter methods exist, Castor can handle direct field access to public fields. It does not do both at the same time. So if the respective class has any getter/setter methods at all, then no direct field access will take place.

There is nothing to do to enable "default introspection". If a descriptor cannot be found for a class, introspection occurs automatically.

Some behavior of the introspector may be controlled by setting the appropriate properties in the castor.properties file. Such behavior consists of changing the naming conventions, and whether primitive types are treated as attributes or elements. See castor.properties file for more information.

A mapping file may also be used to "describe" the classes which are to be marshalled. The mapping is loaded before any marshalling/unmarshalling takes place. See <api>org.exolab.castor.mapping.Mapping

The main advantage of run-time descriptors is that it takes very little effort to get something working.

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