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

## Castor XML -- Best practices

Introduction
General
Source Generator
Performance Considerations
General
Use of XMLContext - With and without a mapping file
Use of Marshaller/Unmarshaller
Use of ClassDescriptorResolver
Use of ClassDescriptorResolver with no mappings

## Introduction

There are many users of Castor XML who (want to) use Castor XML in in high-volume applications. To fine-tune Castor for such an environment, it is necessary to understand many of the product features in detail and to be able to balance their use according to the application needs. Even though many of these features are documented in various places, people frequently asked for a 'best practises' document, a document that brings together these technical topics in one place and that presents them as a set of easy-to-use recipes.

Please be aware that this document is under construction. But still we believe that this document -- even when in its conception phase -- provides valuable information to users of Castor XML.

## General

### Source Generator

It is not generally recommended to generate code into the default package, especially since code in the default package cannot be referenced from code in any other package.

Additionally, we recommend that generated code go into a different package then the code that makes use of the generated code. For example, if your application uses Castor to process an XML configuration file that is used by code in the package `org.example.userdialog` then we do not recommend that the generated code also go into that package. However, it would be reasonable to generate source to process this XML configuration file into the package `org.example.userdialog.xmlconfig`.

## Performance Considerations

### General

Creating instances of <api>org.exolab.castor.xml.Marshaller</api> and <api>org.exolab.castor.xml.Unmarshaller</api> for the purpose of XML data binding is easy to achieve at the API usage level. However, details of API use have an impact on application performance; each instance creation involves setup operations.

This is generally not an issue for one-off invocations; however, in a multi-threaded, high volume use scenario this can be become a serious issue. Internally, Castor uses a collection of Descriptor classes to keep information about the Java entities to be marshaled and unmarshaled. With each instance creation of (Un)Marshaller, this collection will be built from scratch (again and again).

To avoid this initial configuration 'penalty', Castor allows you to cache these Descriptor classes through its <api>org.exolab.castor.xml.ClassDescriptorResolver</api> component. This cache allows reuse of these Descriptor instances between (Un)Marshaller invocations.

### Use of XMLContext - With and without a mapping file

With the introduction of the new `XMLContext` class, the use of a `ClassDescriptorResolver` has been greatly simplified in that such an instance is managed by the XMLContext per default. As such, there's no need to pass a `ClassDescriptorResolver` instance to `Marshaller`/ `Unmarshaller` instances anymore, as this is done automatically when such instances are created through

- | createMarshaller()
- | createUnmarshaller()

For example, to create a `Marshaller` instance that is pre-configured with an instance of `ClassDescriptorResolver`, use the following code fragment:

    Mapping mapping = new Mapping();
    mapping.loadMapping(new InputSource(...));

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

    Marshaller marshaller = context.createMarshaller();

In the case where no mapping file is used, it is still possible to instruct the `XMLContext` to pre-load class descriptors for a given package via the methods enlisted below.

As above, create an instance of `XMLContext` and configure it according to your needs as shown below:

    XMLContext context = new XMLContext();
    context.addPackage("your.package.name");

    Marshaller marshaller = context.createMarshaller();

The `XMLContext` class provides for various methods to load class descriptors for individual classes and/or packages.

Method | Description | .castor.cdr
`addClass(Class)` | Loads the class descriptor for one class. | n/a
`addClass(Class[])` | Loads the class descriptors for a collection of classes. | n/a
`addPackage(String)` | Loads the class descriptor for all classes in the defined package. | Required
`addPackages(String[])` | Loads the class descriptor for all classes in the defined packages. | Required

Note

For some of the methods, pre-loading class descriptords will only work if you provide the `.castor.cdr` file with your generated classes (as generated by the XML code generator). If no such file is shipped, Castor will not be able to pre-load the descriptors, and will fall back to its default descriptor loading mechanism.

### Use of Marshaller/Unmarshaller

#### Use of ClassDescriptorResolver

When you do not use the `XMLContext` class, you will have to manually manage your `XMLClassDescriptorResolver`. To do so, first create an instance of `XMLClassDescriptorResolver` using the following code fragment:

    XMLClassDescriptorResolver classDescriptorResolver =
       (XMLClassDescriptorResolver) ClassDescriptorResolverFactory.createClassDescriptorResolver(BindingType.XML);
    MappingUnmarshaller mappingUnmarshaller = new MappingUnmarshaller();
    MappingLoader mappingLoader =
       mappingUnmarshaller.getMappingLoader(mapping, BindingType.XML);
    classDescriptorResolver.setMappingLoader(mappingLoader);

and then reuse this instance as shown below:

       Unmarshaller unmarshaller = new Unmarshaller();
       unmarshaller.setResolver(classDescriptorResolver);
       unmarshaller.unmarshal(...);

#### Use of ClassDescriptorResolver with no mappings

In the case where there's no mapping file, it is still possible to instruct the `XMLClassDescriptorResolver` to pre-load class descriptors for a given package via the `loadClassDescriptors(String)` method.

As above, create an instance of `XMLClassDescriptorResolver` using the following code fragment:

       XMLClassDescriptorResolver classDescriptorResolver = (XMlClassDescriptorResolver)
          ClassDescriptorResolverFactory.createClassDescriptorResolver(BindingType.XML);
       classDescriptorResolver.setClassLoader(...);
       classDescriptorResolver.addPackage("your.package.name");

and then reuse this instance as shown above. The `XMLClassDescriptorResolver` interface provides various other methods to load class descriptors for individual classes and/or packages.

Method | Description | .castor.cdr
`addClass(String)` | Loads the class descriptor for one class. | n/a
`addClass(String[])` | Loads the class descriptors for a collection of classes. | n/a
`addPackage(String)` | Loads the class descriptor for all classes in the defined package. | Required
`addPackages(String[])` | Loads the class descriptor for all classes in the defined packages. | Required

Note

For some of the methods, pre-loading class descriptords will only work if you provide the `.castor.cdr` file with your generated classes (as generated by the XML code generator). If no such file is shipped, Castor will not be able to pre-load the descriptors, and will fall back to its default descriptor loading mechanism.

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