Castor XML -- Best practices

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.

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.

Creating instances of org.exolab.castor.xml.Marshaller and org.exolab.castor.xml.Unmarshaller 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 org.exolab.castor.xml.ClassDescriptorResolver component. This cache allows reuse of these Descriptor instances between (Un)Marshaller invocations.

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.

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.

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

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.

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.