License     Codehaus     OpenEJB     OpenJMS     OpenORB     Tyrex     

Old releases
  Release 1.3
  Release 1.3rc1
  Release 1.2

  Reference guide
  Maven 2 support
  Maven 2 archetypes
  DTD & Schemas
  Recent HTML changes
  News Archive
  RSS news feed
  Project Wiki

  Mailing Lists
  Continuous builds
  Prof. services

Related projects
  Spring ORM support
  Spring XML factories
  WS frameworks


XML Code Generator
  XML Code Generator

  First steps
  Using JDO
  JDO Config
  JDO Mapping
  JDO Examples
  Tips & Tricks
  Other Features
  JDO sample JAR

  Schema generator

Advanced JDO
  Trans. & Locks
  Long Trans.
  Nested Attrs.
  Pooling Examples
  Best practice

DDL Generator
  Using DDL Generator
  Ant task
  Type Mapping

  The Examples
  3rd Party Tools
  JDO Tests
  XML Tests

  User stories
  Status, Todo
  Project Name


Castor XML - Code generator properties

Documentation Author(s):
Werner Guttmann

Customization - Lookup mechanism
Detailed descriptions
    Source generation & Java 5.0
    SimpleType Enumerations
    Bound Properties
    Class Creation/Mapping
    Setting a super class
    Mapping XML namespaces to Java packages
    Generate equals()/hashCode() method
    Maps java primitive types to wrapper object
    Automatic class name conflict resolution
    Extra collection methods
    Class printing
    Extra documentation methods


Please find below a list of properties that can be configured through the builder configuration properties, as defined in either the default or a custom XML code generator configuration file. These properties allow you to control various advanced options of the XML source generator.

org.exolab.castor.builder.javaVersion Compliance with Java version 1.4/5.0 1.4 1.0.2
org.exolab.castor.builder.forceJava4Enums Forces the code generator to create 'old' Java 1.4 enumeration classes even in Java 5 mode. true/false false 1.1.3
org.exolab.castor.builder.boundproperties Generation of bound properties true/false false 0.8.9
org.exolab.castor.builder.javaclassmapping Class generation mode element/type element 0.9.1
org.exolab.castor.builder.superclass Global super class (for all classes generated) Any valid class name - 0.8.9
org.exolab.castor.builder.nspackages XML namespace to package name mapping A series of mappings - 0.8.9
org.exolab.castor.builder.equalsmethod Generation of equals/hashCode() method true/false false 0.9.1
org.exolab.castor.builder.primitivetowrapper Generation of Object wrappers instead of primitives true/false false 0.9.4
org.exolab.castor.builder.automaticConflictResolution Specifies whether automatic class name conflict resolution should be used or not true/false false 1.1.1
org.exolab.castor.builder.extraCollectionMethods Specifies whether extra (additional) methods should be created for collection-style fields. Set this to true if you want your code to be more compatible with Castor JDO or other persistence frameworks. true/false false 0.9.1
org.exolab.castor.builder.jclassPrinterFactories Enlists the available modes for (J)Class printing during XML code generation. org.exolab.castor.builder.printing.WriterJClassPrinterFactory/ org.exolab.castor.builder.printing.TemplateJClassPrinterFactory n/a 1.2.1
org.exolab.castor.builder.extraDocumentationMethods specifying whether extra members/methods for extracting XML schema documentation should be made available. true/false false 1.2

Customization - Lookup mechanism

By default, the Castor XML code generator will look for such a property file in the following places:

  1. If no custom property file is specified, the Castor XML code generator will use the default builder configuration properties at org/exolab/castor/builder/ as shipped as part of the XML code generator JAR.
  2. If a file named is available on the CLASSPATH, the Castor XML code generator will use each of the defined property values to override the default value as defined in the default builder configuration properties. This file is commonly referred to as a custom builder configuration file.

Detailed descriptions

Source generation & Java 5.0

As of Castor 1.0.2, the Castor source generator now supports the generation of Java 5.0 compliant code. The generated code - with the new feature enabled - will make use of the following Java 5.0-specific artifacts:
-Use of parameterized collections, e.g. ArrayList<String>.
-Use of @Override annotations with the generated methods that require it.
-Use of @SupressWarnings with "unused" method parameters on the generated methods that needed it.
-Added "enum" to the list of reserved keywords.

To enable this feature (off by default), please uncomment the following property in your custom file:

# This property specifies whether the sources generated
# should comply with java 1.4 or 5.0; defaults to 1.4

SimpleType Enumerations

In previous versions, castor only supported (un)marshalling of "simple" java5 enums, meaning enums where all facet values are valid java identifiers. In these cases, every enum constant name can be mapped directly to the xml value. See the following example:

<xs:simpleType name="AlphabeticalType">
  <xs:restriction base="xs:string">
    <xs:enumeration value="A"/>
    <xs:enumeration value="B"/>
    <xs:enumeration value="C"/>

public enum AlphabeticalType {
    A, B, C


So if there is at least ONE facet that cannot be mapped directly to a valid java identifier, we need to extend the enum pattern. Examples for these cases are value="5" or value="-s". Castor now introduces an extended pattern, similar to the jaxb2 enum handling. The actual value of the enumeration facet is stored in a private String property, the name of the enum constant is translated into a valid identifier. Additionally, some convenience methods are introduced, details about these methods are described after the following example:

<xs:simpleType name="CompositeType">
  <xs:restriction base="xs:string">
    <xs:enumeration value="5"/>
    <xs:enumeration value="10"/>

public enum CompositeType {

    private final java.lang.String value;

    private CompositeType(final java.lang.String value) {
        this.value = value;

    public static CompositeType fromValue(final java.lang.String value) {
        for (CompositeType c: CompositeType.values()) {
            if (c.value.equals(value)) {
                return c;
        throw new IllegalArgumentException(value);

    public java.lang.String value() {
        return this.value;
    public java.lang.String toString() {
        return this.value;



Unmarshalling of complex enums

Castor uses the static void fromValue(String value) method to retrieve the correct instance from the value in the xml input file. In our example, the input is "5", fromValue returns CompositeType.VALUE_5

Marshalling of complex enums

Currently, we have to distinguish between enums with a class descriptor and the ones without. If you are using class descriptors, the EnumerationHandler uses the value() method to write the xml output.

If no descriptor classes are available, castor uses per default the toString() method to marshall the value. In this case, the override of the java.lang.Enum.toString() method is mandatory, because java.lang.Enum.toString returns the NAME of the facet instead of the VALUE. So in our example, "VALUE_10" would be returned instead of "10". To avoid this, castor expects an implementation of toString that returns "this.value".

Source Generation of complex enums

If the java version is set to "5.0", the new default behavior of castor is to generate complex java5 enums for simpleType enumerations, as described above. In java 1.4 mode, nothing has changed and the old style enumeration classes using a HashMap are created.

Users, who are in java5 mode and still want to use the old style java 1.4 classes, can force this by setting the new "org.exolab.castor.builder.forceJava4Enums" property to true.

# Forces the code generator to create 'old' Java 1.4 enumeration classes instead 
# of Java 5 enums for xs:simpleType enumerations, even in Java 5 mode.
# Possible values:
# - false (default)
# - true

Bound Properties

Bound properties are "properties" of a class, which when updated the class will send out a java.beans.PropertyChangeEvent to all registered java.beans.PropertyChangeListeners.

To enable bound properties, please add the following property definition to your custom builder configuration file:

# To enable bound properties uncomment the following line. Please
# note that currently *all* fields will be treated as bound properties
# when enabled. This will change in the future when we introduce
# fine grained control over each class and it's properties.

When enabled, all properties will be treated as bound properties. For each class that is generated a setPropertyChangeListener method is created as follows:

 * Registers a PropertyChangeListener with this class.
 * @param pcl The PropertyChangeListener to register.

public void addPropertyChangeListener (java.beans.PropertyChangeListener pcl)
} //-- void addPropertyChangeListener

Whenever a property of the class is changed, a java.beans.PropertyChangeEvent will be sent to all registered listeners. The property name, the old value and the new value will be set in the java.beans.PropertyChangeEvent.

To prevent unnecessary overhead, if the property is a collection, the old value will be null.

Class Creation/Mapping

The source generator can treat the XML Schema structures such as <complexType> and element in two main ways. The first, and current default method is called the "element" method. The other is called the "type" method.

'element' The "element" method creates classes for all elements whose type is a <complexType>. Abstract classes are created for all top-level <complexType>s. Any elements whose type is a top-level type will have a new class create that extends the abstract class which was generated for that top-level complexType.
Classes are not created for elements whose type is a <simpleType>.
'type' The "type" method creates classes for all top-level <complexType>s, or elements that contain an "anonymous" (in-lined) <complexType>.
Classes will not be generated for elements whose type is a top-level type.

To change the "method" of class creation, please add the following property definition to your custom builder configuration file:

# Java class mapping of <xsd:element>'s and <xsd:complexType>'s

Setting a super class

The source generator enables the user to set a super class to all the generated classes (of course, class descriptors are not affected by this option). Pleae note that, though the binding file, it is possible to define a super class for individual classes

To set the global super class, please add the following property definition to your custom builder configuration file:

# This property allows one to specify the super class of *all*
# generated classes

Mapping XML namespaces to Java packages

An XML Schema instance is identified by a namespace. For data-binding purposes, especially code generation it may be necessary to map namespaces to Java packages.

This is needed for imported schema in order for Castor to generate the correct imports during code generation for the primary schema.

To allow the mapping between namespaces and Java packages , edit the file :

# XML namespace mapping to Java packages

Generate equals()/hashCode() method

Since version: 0.9.1

The Source Generator can override the equals() and hashCode() method for the generated objects.

To have equals() and hashCode() methods generated, override the following property in your custom file:

# Set to true if you want to have an equals() and 
# hashCode() method generated for each generated class;
# false by default

Maps java primitive types to wrapper object

Since version 0.9.4

It may be convenient to use java objects instead of primitives, the Source Generator provides a way to do it. Thus the following mapping can be used:
-boolean to java.lang.Boolean
-byte to java.lang.Byte
-double to java.lang.Double
-float to java.lang.Float
-int and integer to java.lang.Integer
-long to java.lang.Long
-short to java.lang.Short

To enable this property, edit the castor file:

# Set to true if you want to use Object Wrappers instead
# of primitives (e.g Float instead of float).
# false by default.

Automatic class name conflict resolution

Since version 1.1.1

With this property enabled, the XML code generator will use a new automatic class name resolution mode that has special logic implemented to automatically resolve class name conflicts.

This new mode deals with various class name conflicts where previously a binding file had to be used to resolve these conflicts manually.

To enable this feature (turned off by default), please add the following property definitio to your custom file:

# Specifies whether automatic class name conflict resolution
# should be used or not; defaults to false.

Extra collection methods

Specifies whether extra (additional) methods should be created for collection-style fields. Set this to true if you want your code to be more compatible with Castor JDO (or other persistence frameworks).

Adds additional getter/setter methods for the field in question, such as get/set by reference and set as copy methods.

Class printing

As of release 1.2, Castor supports the use of Velocity-based code templates for code generation. For the time being, Castor will support two modes for code generation, i.e. the new Velocity-based and an old legacy mode. Default will be the legacy mode; this will be changed with a later release of Castor.

In order to use the new Velocity-based code generation, please call the setJCLassPrinterType(String) method on the SourceGenerator class with a value of velocity.

As we consider the code stable enough for a major release, we do encourage users to use the new Velocity-based mode and to provide us with (valuable) feedback.

Please note that we have changed the mechanics of changing the JClass printing type between releases 1.2 and 1.2.1.

Extra documentation methods

As of release 1.2, the Castor XML code generator - if configured as shown below - now supports generation of additional methods to allow programmatic access to <xs:documentation> elements for top-level type/element definitions as follows:

public java.lang.String getXmlSchemaDocumentation(final java.lang.String source);
public java.util.Map getXmlSchemaDocumentations();

In order to have these additional methods generated as shown above, please override the following code generator property in a custom as shown:

# Property specifying whether extra members/methods for extracting XML schema
# documentation should be made available; defaults to false


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.