|  |  |  | 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 - Code generator properties

Documentation Author(s):
Werner Guttmann

Overview
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

## Overview

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.

Option | Description | Values | Default | SinceVersion
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/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.

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

### 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"/>
      </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

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

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 <api>java.beans.PropertyChangeEvent</api> 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.

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

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

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

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

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

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

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

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

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

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