Castor XML - Code generator properties

Documentation Author(s):
Werner Guttmann

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.

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/castorbuilder.properties as shipped as part of the XML code generator JAR.
2. If a file named castorbuilder.properties 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.

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 castorbuilder.properties file:

# This property specifies whether the sources generated
# should comply with java 1.4 or 5.0; defaults to 1.4
org.exolab.castor.builder.javaVersion=5.0

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"/>
  </xs:restriction>
</xs:simpleType>    

public enum AlphabeticalType {
    A, B, C
}

<root>
  <AlphabeticalType>A</AlphabeticalType>    
</root>
    

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"/>
  </xs:restriction>
</xs:simpleType> 

public enum CompositeType {
    VALUE_5("5"),
    VALUE_10("10");

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

<root>
  <CompositeType>5</CompositeType>    
</root>    

    

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
org.exolab.castor.builder.forceJava4Enums=false

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.
#
org.exolab.castor.builder.boundproperties=true

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)
{
   propertyChangeListeners.addElement(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.

Note

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

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.

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
#
org.exolab.castor.builder.javaclassmapping=type

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
#
org.exolab.castor.builder.superclass=com.xyz.BaseObject

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 castorbuilder.properties file :

# XML namespace mapping to Java packages
#
#org.exolab.castor.builder.nspackages=\
   http://www.xyz.com/schemas/project=com.xyz.schemas.project,\
   http://www.xyz.com/schemas/person=com.xyz.schemas.person

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 castorbuilder.properties file:

# Set to true if you want to have an equals() and 
# hashCode() method generated for each generated class;
# false by default
org.exolab.castor.builder.equalsmethod=true

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 builder.properties file:

# Set to true if you want to use Object Wrappers instead
# of primitives (e.g Float instead of float).
# false by default.
#org.exolab.castor.builder.primitivetowrapper=false

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 castorbuilder.properties file:

# Specifies whether automatic class name conflict resolution
# should be used or not; defaults to false.
#
org.exolab.castor.builder.automaticConflictResolution=true

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.

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.

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 castorbuilder.properties as shown:

# Property specifying whether extra members/methods for extracting XML schema
# documentation should be made available; defaults to false
org.exolab.castor.builder.extraDocumentationMethods=true