License     Codehaus     OpenEJB     OpenJMS     OpenORB     Tyrex     
 

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

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

Related projects
  Spring ORM support
  Spring XML factories
  WS frameworks

XML
  Using XML
  XML Mapping
  Configuration
  Properties
  XML parsers
  XML FAQ
  XML HOW-TOs
  Tips & Tricks
  Custom Handlers
  Best practice

XML Code Generator
  Introduction
  Properties
  Custom bindings
  Ant task
  Maven 2 plugin
  Command line
  Schema Support
  Example

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
  Presentations
  The Examples
  3rd Party Tools
  JDO Tests
  XML Tests
  Configuration
 
 

About
  License
  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 org.exolab.castor.mapping.Mapping will provide detailed information about mapping decisions made by Castor and will show the SQL statements being used.

Using a logger with org.exolab.castor.jdo.JDO 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 org.exolab.castor.xml.Unmarshaller will provide trace messages that show conflicts between the XML document and loaded objects.

A simple trace logger can be obtained from org.exolab.castor.util.Logger. 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.exolab.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.

 
   
  
   
 


Copyright © 1999-2005 ExoLab Group, Intalio Inc., and Contributors. All rights reserved.
 
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.