Castor XML - Code generator properties
Documentation Author(s): Werner Guttmann
Overview Available properties News: 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
Overview
Please find below a list of properties that can be set in the
castor-builder.properties file to control various advanced
options of the source generator. By default, the Castor XML code
will look for such a property file in the following places:
- 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.
- 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 explained
above. This fiel is commonly referred to as a custom
builder configuration file.
Option |
Description |
Values |
Default |
Since Version |
org.exolab.castor.builder.javaVersion |
Compliance with Java version |
1.4 or 5.0 |
1.4 |
1.0.2 |
org.exolab.castor.builder.boundproperties |
Generation of bound properties |
true or false |
false |
0.8.9 |
org.exolab.castor.builder.javaclassmapping |
Class generation mode |
element or 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 or false |
false |
0.9.1 |
org.exolab.castor.builder.primitivetowrapper |
Generation of Object wrappers instead of primitives |
true or false |
false |
0.9.4 |
|
Available properties
News: 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
artefacts:
|
- | 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.
| 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() 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 |
|
|