|  |  |  | 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 - Tips & Tricks

Logging and Tracing
Indentation
XML:Marshal validation
NoClassDefFoundError
Mapping: auto-complete
Create method
MarshalListener and UnmarshalListener

## Logging and Tracing

When developing using Castor, we recommend that you use the various `setLogWriter` methods to get detailed information and error messages.

Using a logger with <api>org.exolab.castor.mapping.Mapping</api> will provide detailed information about mapping decisions made by Castor and will show the SQL statements being used.

Using a logger with <api>org.exolab.castor.jdo.JDO</api> will provide trace messages that show when Castor is loading, storing, creating and deleting objects. All database operations will appear in the log; if an object is retrieved from the cache or is not modified, there will be no trace of load/store operations.

Using a logger with <api>org.exolab.castor.xml.Unmarshaller</api> will provide trace messages that show conflicts between the XML document and loaded objects.

A simple trace logger can be obtained from <javadoc>org.exolab.castor.util.Logger</javadoc>. This logger uses the standard output stream, but prefixes each line with a short message that indicates who generated it. It can also print the time and date of each message. Since logging is used for warning messages and simple tracing, Castor does not require a sophisticated logging mechanism.

Interested in integratating Castor's logging with Log4J? Then see this question in the JDO FAQ.

## Indentation

By default the marshaler writes XML documents without indentation. When developing using Castor or when debugging an application that uses Castor, it might be desireable to use indentation to make the XML documents human-readable. To turn indentation on, modify the Castor properties file, or create a new properties file in the classpath (named `castor.properties`) with the following content:

    org.exolab.castor.indent=true

Indentation inflates the size of the generated XML documents, and also consumes more CPU. It is recommended not to use indentation in a production environment.

## XML:Marshal validation

It is possible to disable the validation in the marshaling framework by modifying the Castor properties file or by creating a new properties file in the classpath (named `castor.properties`) with the following content:

    org.exolab.castor.marshalling.validation=false

## NoClassDefFoundError

Check your CLASSPATH, check it often, there is no reason not to!

## Mapping: auto-complete

Note: this only works with Castor-XML.

To save time when writing your mappings, try using the auto-complete attribute of class. When using auto-complete, Castor will introspect your class and automatically fill in any missing fields.

Example:

    <class name="com.acme.Foo" auto-complete="true"/>

This is also compatible with generated descriptor files. You can use a mapping file to override some of the behavior of a compiled descriptor by using auto-complete.

**Note: Be careful to make sure you use the exact field name as specified in the generated descriptor file in order to modify the behavior of the field descriptor! Otherwise, you'll probably end up with two fields being marshaled!

## Create method

Castor requires that classes have a public, no-argument constructor in order to provide the ability to marshal & unmarshal objects of that type.

create-method is an optional attribute to the `<field>` mapping element that can be used to overcome this restriction in cases where you have an existing object model that consists of, say, singleton classes where public, no-argument constructors must not be present by definition.

Assume for example that a class "`A`" that you want to be able to unmarshal uses a singleton class as one of its properties. When attempting to unmarshal class "`A`", you should get an exception because the singleton property has no public no-arg constructor. Assuming that a reference to the singleton can be obtained via a static getInstance() method, you can add a "create method" to class `A` like this:

                public MySingleton getSingletonProperty()
                {
                   return MySingleton.getInstance();
                }

and in the mapping file for class A, you can define the singleton property like this:

                <field name="mySingletonProperty"
                      type="com.u2d.MySingleton"
                      create-method="getSingletonProperty">
                   <bind-xml name="my-singleton-property" node="element" />
                </field>

This illustrates how the create-method attribute is quite a useful mechanism for dealing with exceptional situations where you might want to take advantage of marshaling even when some classes do not have no-argument public constructors.

Note: As of this writing, the specified create-method must exist as a method in the current class (i.e. the class being described by the current `<class>` element). In the future it may be possible to use external static factory methods.

## MarshalListener and UnmarshalListener

Castor allows control on the object being marshaled or unmarshaled by a set of two listener interfaces: MarshalListener and UnmarshalListener.

The MarshalListener interface located in

    org.exolab.castor.xml

listens to two different events that are intercepted by the following methods:

- | preMarshal: this method is called before an object gets marshaled.
- | postMarshal: this method is called once an object has been marshaled.

The UnmarshalListener located also in

    org.castor.xml

listens to four different events that are intercepted by the following methods:

- | initialized: this method is called once an object has been instantiated.
- | attributesProcessed: this method is called when the attributes have just been read and processed.
- | fieldAdded: this method is called when an object is added to a parent.
- | unmarshalled: this method is called when an object has been fully unmarshaled.

Note: The

    UnmarshalListener

had been part of

    org.exolab.castor.xml

but as an extention of this interface had been required a new interface in

    org.castor.xml

was introduced. Currently the

    org.exolab.castor.xml.UnmarshalListener

interface can still be used but is deprecated.

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