License     Codehaus     OpenEJB     OpenJMS     OpenORB     Tyrex     
 

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

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

Related projects
  Spring ORM support
  Spring XML factories

XML
  Using XML
  XML Mapping
  XML FAQ
  XML HOW-TOs
  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
  Other Features
  JDO sample JAR

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

About
  License
  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
    Bound Properties
    Class Creation/Mapping
    Setting a super class
    Mapping XML namespaces to Java packages
    Generate equals() method
    Maps java primitive types to wrapper object
    Automatic class name conflict resolution
    Extra collection 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.

org.exolab.castor.builder.javaVersion Compliance with Java version 1.4/5.0 1.4 1.0.2
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 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

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

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

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
#
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() method

Since version: 0.9.1

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

Note: hashcode() is not currently overriden.

To generate the equals() method , edit the castorbuilder.properties file :

# Set to true if you want to generate the equals method
# 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.

 
   
  
   
 


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.