Castor 1.3.3 - Reference documentation

The introspection mode is the simplest mode to use from a user perspective, as it does not require any configuration from the user. As such, the user does not have to provide any mapping file(s), nor point Castor to any generated descriptor classes (as discussed in the 'descriptor mode' section).

In this mode, the user makes use of static methods on the org.exolab.castor.xml.Marshaller and org.exolab.castor.xml.Unmarshaller classes, providing all required data as parameters on these method calls.

To marshal an instance of the person class you simply call the org.exolab.castor.xml.Marshaller as follows:

// Create a new Person
Person person = new Person("Ryan 'Mad Dog' Madden");
person.setDateOfBirth(new Date(1955, 8, 15));

// Create a File to marshal to
writer = new FileWriter("test.xml");

// Marshal the person object
Marshaller.marshal(person, writer);
			

This produces the XML shown in Example 1.1, “XML produced in introspection mode”

XML to written
				

To unmarshal an instance of the person class from XML, you simply call the org.exolab.castor.xml.Unmarshaller as follows:

// Create a Reader to the file to unmarshal from
reader = new FileReader("test.xml");

// Marshal the person object
Person person = (Person)
Unmarshaller.unmarshal(Person.class, reader);
			

Marshalling and unmarshalling is basically that simple.

	Note
	Note: The above example uses the static methods of the marshalling framework, and as such no Marshaller and/or Unmarshaller instances need to be created. A common mistake in this context when using a mapping file is to call the org.exolab.castor.xml.Marshaller or org.exolab.castor.xml.Unmarshaller as in the above example. This won't work, as the mapping will be ignored.

In introspection mode , Castor XML uses Java reflection to establish the binding between the Java classes (and their properties) and the XML, following a set of (default) naming rules. Whilst it is possible to change to a different set of naming rules, there's no way to override this (default) naming for individual artifacts. In such a case, a mapping file should be used.

In mapping mode , the user provides Castor XML with a user-defined mapping (in form of a mapping file) that allows the (partial) definition of a customized mapping between Java classes (and their properties) and XML.

When you are using a mapping file, create an instance of the org.exolab.castor.xml.XMLContext class and use the org.exolab.castor.xml.XMLContext.addMapping(Mapping) method to provide Castor XML with one of more mapping files.

To start using Castor XML for marshalling and/or unmarshalling based upon your custom mapping, create instances of org.exolab.castor.xml.Marshaller and org.exolab.castor.xml.Unmarshalleras needed using one of the following methods:

and call any of the non-static (un)marshal methods to trigger data binding in either way.

Below code shows a full example that demonstrates unmarshalling a Person instance from XML using a org.exolab.castor.xml.Unmarshaller instance as obtained from an XMLContext previously configured to your needs.

import org.exolab.castor.xml.XMLContext; import
org.exolab.castor.mapping.Mapping; import
org.exolab.castor.xml.Unmarshaller;

// Load Mapping
Mapping mapping = new Mapping();
mapping.loadMapping("mapping.xml");


	// initialize and configure XMLContext

XMLContext context = new XMLContext();
context.addMapping(mapping);


	// Create a Reader to the file to unmarshal from

reader = new FileReader("test.xml");

// Create a new Unmarshaller
Unmarshaller unmarshaller =
context.createUnmarshaller();
unmarshaller.setClass(Person.class);

// Unmarshal the person object
Person person = (Person)
unmarshaller.unmarshal(reader);
				

To marshal the very same Person instance to XML using a org.exolab.castor.xml.Marshaller obtained from the same org.exolab.castor.xml.XMLContext, use code as follows:

import org.exolab.castor.xml.Marshaller;

// create a Writer to the file to marshal to
Writer writer = new FileWriter("out.xml");

// create a new Marshaller
Marshaller marshaller = context.createMarshaller();
marshaller.setWriter(writer);

// marshal the person object
marshaller.marshal(person);
				

Please have a look at XML Mapping for a detailed discussion of the mapping file and its structure.

For more information on how to effectively deal with loading mapping file(s) especially in multi-threaded environments, please check the best practice section.

TBD

To use "compile-time" class descriptors, one can either implement the org.exolab.castor.xml.XMLClassDescriptor interface for each class which needs to be "described", or have the Source Code Generator create the proper descriptors.

The main advantage of compile-time descriptors is that they are faster than the run-time approach.

To use "run-time" class descriptors, one can either simply let Castor introspect the classes, a mapping file can be provided, or a combination of both "default introspection" and a specified mapping file may be used.

For "default introspection" to work the class being introspected must have adequete setter/getter methods for each field of the class that should be marshalled and unmarshalled. If no getter/setter methods exist, Castor can handle direct field access to public fields. It does not do both at the same time. So if the respective class has any getter/setter methods at all, then no direct field access will take place.

There is nothing to do to enable "default introspection". If a descriptor cannot be found for a class, introspection occurs automatically.

Some behavior of the introspector may be controlled by setting the appropriate properties in the castor.properties file. Such behavior consists of changing the naming conventions, and whether primitive types are treated as attributes or elements. See castor.properties file for more information.

A mapping file may also be used to "describe" the classes which are to be marshalled. The mapping is loaded before any marshalling/unmarshalling takes place. See org.exolab.castor.mapping.Mapping

The main advantage of run-time descriptors is that it takes very little effort to get something working.

For Castor, a Java class has to map into an XML element. When Castor marshals an object, it will:

or

It will then use the fields information from the mapping file to determine how a given property of the object has to be translated into one and only one of the following:

This process will be recursive: if Castor finds a property that has a class type specified elsewhere in the mapping file, it will use this information to marshal the object.

By default, if Castor finds no information for a given class in the mapping file, it will introspect the class and apply a set of default rules to guess the fields and marshal them. The default rules are as follows:

When Castor finds an element while unmarshalling a document, it will try to use the mapping information to determine which object to instantiate. If no mapping information is present, Castor will use the name of the element to try to guess the name of a class to instantiate (for example, for an element named 'test-element', Castor will try to instantiate a class named 'TestElement' if no information is given in the mapping file). Castor will then use the field information of the mapping file to handle the content of the element.

If the class is not described in the mapping file, Castor will instrospect the class using the Java Reflection API to determine if there is any function of the form getXxxYyy()/setXxxYyy(<type> x). This accessor will be associated with XML element/attribute named 'xxx-yyy'. In the future, we will provide a way to override this default behavior.

Castor will introspect object variables and use direct access _only_ if no get/set methods have been found in the class. In this case, Castor will look for public variables of the form:

public <type> xxxYYY;
        

and expect an element/attribute named 'xxx-yyy'. The only handled collections for <type> are java.lang.Vector and array. (up to version 0.8.10)

For primitive <type>, Castor will look for an attribute first and then an element. If <type> is not a primitive type, Castor will look for an element first and then an attribute.

This section defines a small domain model that will be referenced by various mapping file (fragments/samples) in the following sections. The model consists of two two classes Order and OrderItem, where an order holds a list of order items.

public class Order {

    private List orderItems;
    private String orderNumber;
    
    public List getOrderItems() {
        return orderItems;
    }
    public void setOrderItems(List orderItems) {
        this.orderItems = orderItems;
    }
    public String getOrderNumber() {
        return orderNumber;
    }
    public void setOrderNumber(String orderNumber) {
        this.orderNumber = orderNumber;
    }
}

public class OrderItem {
    
    private String id;
    private Integer orderQuantity;
    
    public String getId() {
        return id;
    }
    public void setId(String id) {
        this.id = id;
    }
    public Integer getOrderQuantity() {
        return orderQuantity;
    }
    public void setOrderQuantity(Integer orderQuantity) {
        this.orderQuantity = orderQuantity;
    }
}

As shown above in bold, the Order instance has a (private) field 'orderItems' to hold a collection of OrderItem instances. This field is publically exposed by corresponding getter and setter methods.

<!ELEMENT mapping ( description?, include*, field-handler*, class*, key-generator* )>
        

The <mapping> element is the root element of a mapping file. It contains:

A mapping file look like this:

<?xml version="1.0"?>

<!DOCTYPE mapping PUBLIC "-//EXOLAB/Castor Mapping DTD Version 1.0//EN"
      castor.org
                         "http://castor.org/mapping.dtd">

<mapping>
	<description>Description of the mapping</description>
	
	<include href="other_mapping_file.xml"/>
	
	<!-- mapping for class 'A' -->
	<class name="A">
	        .........
	</class>
	
	<!-- mapping for class 'B' -->
	<class name="B">
	        .........
	</class>

</mapping>

<!ELEMENT class ( description?, cache-type?, map-to?, field+ )>
<!ATTLIST class
          name            ID       #REQUIRED
          extends         IDREF    #IMPLIED
          depends         IDREF    #IMPLIED
          auto-complete   ( true |false ) "false"
          identity        CDATA    #IMPLIED
          access          ( read-only | shared | exclusive | db-locked )  "shared"
          key-generator   IDREF    #IMPLIED >

The <class> element contains all the information used to map a Java class into an XML document. The content of <class> is mainly used to describe the fields that will be mapped.

The auto-complete attributes is interesting as it allow a fine degree of control of the introspector: it is possible to specifiy only the fields whose Castor default behavior does not suite our needs. These feature should simplify the handling of complexe class containing many fields. Please see below for an example usage of this attribute.

<class name="mypackage.OrderItem>
           
   <map-to xml="item"/>

   <field name="id" type="string">
      <bind-xml name="identity" node="attribute"/>
   </field>

   </field name="orderQuantity" type="integer">
      <bind-xml name="quantity" node="element"/>
   </field>

</class>

<?xml version="1.0" ?>        
<item identity="12">
   <quantity>100</quantity>
</item>

<class name="mypackage.OrderItem auto-complete="true">
           
   <map-to xml="item"/>

   <field name="id" type="string">
      <bind-xml name="identity" node="attribute"/>
   </field>

</class>

<?xml version="1.0" ?>        
<item identity="12">
   <order-quantity>100</order-quantity>
</item>

<class name="mypackage.OrderItem auto-complete="true">
           
   <field name="id" type="string">
      <bind-xml name="identity" node="attribute"/>
   </field>

</class>

<?xml version="1.0" ?>        
<order-item identity="12">
   <order-quantity>100</order-quantity>
</order-item>

<!ELEMENT map-to EMPTY>
<!ATTLIST map-to
          table               NMTOKEN  #IMPLIED
          xml                 NMTOKEN  #IMPLIED
          ns-uri              NMTOKEN  #IMPLIED
          ns-prefix           NMTOKEN  #IMPLIED
          ldap-dn             NMTOKEN  #IMPLIED
          element-definition  (true|false) "false"     NEW as of 1.0M3
          ldap-oc             NMTOKEN  #IMPLIED>

<map-to> is used to specify the name of the element that should be associated with the given class. <map-to> is only used for the root class. If this information is not present, Castor will:

Please note that it is possible to change the naming scheme used by Castor to translate between the XML name and the Java class name in the castor.properties file.

<class name="myPackage.OrderItem">
   ...
   <map-to xml="item" />
   ...
</class>

<class name="myPackage.OrderItem">
   ...
   <map-to xml="item" ns-uri="http://castor.org/sample/mapping/"
           ns-prefix="castor"/>
   ...
</class>

<?xml version="1.0" ?>        
<castor:order-item xmlns:castor="http://castor.org/sample/mapping/" identity="12">
   <castor:order-quantity>100</castor:order-quantity>
</castor:order-item>

<!ELEMENT field ( description?, sql?, bind-xml?, ldap? )>
<!ATTLIST field
    name           NMTOKEN  #REQUIRED
    type           NMTOKEN  #IMPLIED
    handler        NMTOKEN  #IMPLIED
    required       ( true | false )  "false"
    direct         ( true | false )  "false"
    lazy           ( true | false )  "false"
    transient      ( true | false )  "false"
    nillable       ( true | false )  "false"
    container      ( true | false )  "false"
    get-method     NMTOKEN  #IMPLIED
    set-method     NMTOKEN  #IMPLIED
    create-method  NMTOKEN  #IMPLIED
    collection     ( array | vector | hashtable | collection | set | map )  #IMPLIED>
        

<field> is used to describe a property of a Java object we want to marshal/unmarshal. It gives:

From this information, Castor is able to access a given property in the Java class.

In order to determine the signature that Castor expects, there are two easy rules to apply.

1. Determine <type>.

It is necessary to use a collection when the content model of the element expects more than one element of the specified type.

Determine the signature of the function

In the case of XML mapping, the content of a field element should be one and only one <bind-xml> element describing how this given field will be mapped into the XML document.

<field name="foo" set-method="%1" get-method="getFoo" type="string">
   <bind-xml node="attribute"/>
</field>

<class name="org.some.package.Root">
   <field name="member" type="string" handler="org.some.package.CustomFieldHandlerImpl"/>
</class>

<field-handler name="myHandler" class="org.some.package.CustomFieldHandlerImpl">
   <param name="date-format" value="yyyyMMddHHmmss"/>
</field-handler>

<class name="org.some.package.Root">
   <field name="member" type="string" handler="myHandler"/>
</class>

<class name="some.example.Order">
            
   ...
   <field name="item" type="some.example.Item" >
      <bind-xml> name="item" node="element" />
   </field>
   ...
</class>

<class name="some.example.Item">
   <field name="id" type="long" />
   <field name="description" type="string" />
</class>

<order>
    ...
    <item>
        <id>100</id>
        <description>...</description>
    </item>
</order>

<field name="item" type="some.example.Item" container="false" >
   <bind-xml> name="item" node="element" />
</field>

<order>
    ...
    <id>100</id>
    <description>...</description>
</order>

Castor comes with a tool that can automatically create a mapping from class files. Please see the XML FAQ for more information.

Sometimes to handle complex situations you'll need to create your own FieldHandler. Normally a FieldHandler deals with a specific class and field, however generic, reusable FieldHandlers can also be created by extending org.exolab.castor.mapping.GeneralizedFieldHandler or org.exolab.castor.mapping.AbstractFieldHandler. The FieldHandler can be specified on the <field> element.

For more information on writing a custom FieldHandler please see the following: XML FieldHandlers.

You may map any attributes to constructor arguments. For more information on how to map constructor arguments see the information available in the section on set-method above.

Please note that mapping elements to constructor arguments is not yet supported.

Tip: the XML HOW-TO section has a HOW-TO document for mapping constructor arguments.

Sometimes it's useful to prevent Castor from checking for a default constructor, such as when trying to write a mapping for an interface or type-safe enum. You can use the "undocumented" verify-constructable="false" attribute on the <class> element to prevent Castor from looking for the default constructor.

While you can always use your own custom FieldHandler for handling type-safe enumeration classes, Castor does have a built-in approach to dealing with these types of classes. If the type-safe enum class has a public static <type> valueOf(String) method Castor will call that method so that the proper instance of the enumeration is returned. Note: You'll also need to disable the default constructor check in the mapping file (see section 7.4 above to see more on this).

It is not generally recommended to generate code into the default package, especially since code in the default package cannot be referenced from code in any other package.

Additionally, we recommend that generated code go into a different package then the code that makes use of the generated code. For example, if your application uses Castor to process an XML configuration file that is used by code in the package org.example.userdialog then we do not recommend that the generated code also go into that package. However, it would be reasonable to generate source to process this XML configuration file into the package org.example.userdialog.xmlconfig.

Creating instances of org.exolab.castor.xml.Marshaller and org.exolab.castor.xml.Unmarshaller for the purpose of XML data binding is easy to achieve at the API usage level. However, details of API use have an impact on application performance; each instance creation involves setup operations.

This is generally not an issue for one-off invocations; however, in a multi-threaded, high volume use scenario this can be become a serious issue. Internally, Castor uses a collection of Descriptor classes to keep information about the Java entities to be marshaled and unmarshaled. With each instance creation of (Un)Marshaller, this collection will be built from scratch (again and again).

To avoid this initial configuration 'penalty', Castor allows you to cache these Descriptor classes through its org.exolab.castor.xml.ClassDescriptorResolver component. This cache allows reuse of these Descriptor instances between (Un)Marshaller invocations.

With the introduction of the new org.exolab.castor.xml.XMLContext class, the use of a ClassDescriptorResolver has been greatly simplified in that such an instance is managed by the XMLContext per default. As such, there's no need to pass a ClassDescriptorResolver instance to Marshaller/ Unmarshaller instances anymore, as this is done automatically when such instances are created through

For example, to create a Marshaller instance that is pre-configured with an instance of ClassDescriptorResolver, use the following code fragment:

Mapping mapping = new Mapping();
mapping.loadMapping(new InputSource(...));
        
XMLContext context = new XMLContext();
context.addMapping(mapping);

Marshaller marshaller = context.createMarshaller();

In the case where no mapping file is used, it is still possible to instruct the org.exolab.castor.xml.XMLContext to pre-load class descriptors for a given package via the methods enlisted below.

As above, create an instance of org.exolab.castor.xml.XMLContext and configure it according to your needs as shown below:

XMLContext context = new XMLContext();
context.addPackage("your.package.name");

Marshaller marshaller = context.createMarshaller();

The org.exolab.castor.xml.XMLContext class provides for various methods to load class descriptors for individual classes and/or packages.

	Note
	For some of the methods, pre-loading class descriptords will only work if you provide the .castor.cdr file with your generated classes (as generated by the XML code generator). If no such file is shipped, Castor will not be able to pre-load the descriptors, and will fall back to its default descriptor loading mechanism.

Create a new instance of the Marshaller class and use the setEncoding method. You'll also need to make sure the encoding for the Writer is set properly as well:

 ...
 String encoding = "ISO-8859-1";
 FileOutputStream fos = new FileOutputStream("result.xml");
 OutputStreamWriter osw = new OuputStreamWriter(fos, encoding);
 Marshaller marshaller = new Marshaller(osw);
 marshaller.setEncoding(encoding);
 ...
			

	Note
	For Castor 0.9.5.2 only

The issue occurs with newer versions of Xerces than the version 1.4 that ships with Castor. The older version works OK. For some reason, when the newer version of Xerces encounters an "xml" prefixed attribute, such as "xml:lang", it tries to automatically start a prefix mapping for "xml". Which, in my opinion, is technically incorrect. They shouldn't be doing that. According to the w3c, the "xml" prefix should never be declared.

The reason it started appearing in the new Castor (0.9.5.2), is because of a switch to SAX 2 by default during unmarshaling.

Solution: A built in work-around has been checked into the Castor SVN and will automatically exist in any post 0.9.5.2 releases. For those who are using 0.9.5.2 and can't upgrade, I found a simple workaround (tested with Xerces 2.5). At first I thought about disabling namespace processing in Xerces, but then realized that it's already disabled by default by Castor ... so I have no idea why they call #startPrefixMapping when namespace processing has been disabled. But in any event... explicitly enabling namespace processing seems to fix the problem:

in the castor.properties file, change the following line:

 org.exolab.castor.parser.namespaces=false
			

to:

 org.exolab.castor.parser.namespaces=true
			

	Note
	This work-around has only been tested with Xerces 2.5 and above.

The get method will be called a second time during the validation process. To prevent this from happening, simply disable validation on the Marshaller or Unmarshaller.

There are probably other approaches you can use as well, but those seem to be the most popular ones. Let us know if you have a solution that you think we should add here.

Castor loads the castor.properties in the following order:

Each properties file overrides the previous. So you don't have to come up with a properties file with all the properties and values, just the ones you want to change. This also means you don't have to touch the properties file found in the jar file.

	Note
	Note: You can also use LocalConfiguration.getInstance().getProperties() to change the properties values programatically.

Yes, many of these properties can be set directly on the Marshaller or Unmarshaller, but you can also use LocalConfiguration.getInstance().getProperties() to change the properties values programatically.

Castor does not currently support introspection of private methods. Please make sure proper public accesssor methods are available for all fields that you wish to be handled by the Marshalling Framework.

Make sure you are not using one of the static methods on the Marshaller/Unmarshaller. Any configuration changes that you make to the Marshaller or Unmarshaller are not available from the static methods.

Yes! We provide one such tool, see org.exolab.castor.tools.MappingTool . There are some 3rd party tools as well.

For a specific field you can use a QName for the value of the bind-xml name attribute as such:

 <bind-xml name="foo:bar" xmlns:foo="http://www.acme.com/foo"/>
			

Note: The namespace prefix is only used for qualification during the loading of the mapping, it is not used during Marshaling. To map namespace prefixes during marshaling you currently need to set these via the Marshaler directly.

For a class mapping, use the <map-to> element. For more information see the XML Mapping documentation .

Set the transient attribute on the <bind-xml> element to true:

 <bind-xml transient="true"/>
			

Note: You can also set transient="true" on the <field> element.

For all versions of Castor:

To enable pretty-printing (indenting, line-breaks) just modify the castor.properties file and uncomment the following:

 # True if all documents should be indented on output by default
 #
 #org.exolab.castor.indent=true
			

Note: This will slow down the marshalling process

If you are using Castor's default introspection to automatically map the objects into XML, then there is no guarantee on the order. It simply depends on the order in which the fields are returned to Castor using the Java reflection API.

Note: If you use a mapping file Castor will generate the XML in the order in which the mapping file is specified.

Not directly, however you can convert your DTD to an XML Schema fairly easily. We provide a tool ( org.exolab.castor.xml.dtd.Converter ) to do this. You can also use any number of 3rd-party tools such as XML Spy or XML Authority.

Also: I used the source code generator, but all my xml element names are getting marshaled as lowercase with hyphens, what's up with that?

Solution: Are the generated class descriptors compiled? Make sure they get compiled along with the source code for the object model.

Example: Castor generates the following:

 import types.Foo;
			

instead of:

 import com.acme.types.Foo;
			

This usually happens when the namespaces for the imported schemas have not been mapped to appropriate java packages in the castorbuilder.properties file.

Solution:

For those using 0.9.5.1, you'll need to upgrade due to a bug that is fixed in later releases.

For Castor 0.9.4 and above:

Castor JDO requires a reference to the actual collection to be returned from the get-method. By default the source generator does not provide such a method. To enable such methods to be created, simple add the following line to your castorbuilder.properties file:

 org.exolab.castor.builder.extraCollectionMethods=true
			

Note: The default castorbuilder.properties file has this line commented out. Simply uncomment it.

Your mapping file will also need to be updated to include the proper set/get method names.

Yes! We provide such a tool. Please see org.exolab.castor.xml.schema.util.XMLInstance2Schema . It's not 100% perfect, but it does a reasonable job.

To enable XML validation at the parser level, please add properties to your castor.properties file as follows:

 org.exolab.castor.parser.namespaces=true
 org.exolab.castor.sax.features=http://xml.org/sax/features/validation,\
 http://apache.org/xml/features/validation/schema,\
 http://apache.org/xml/features/validation/schema-full-checking
			

Please note that the example given relies on the use of Apache Xerces, hence the apache.org properties; similar options should exist for other parsers.

When using a custom FieldHandlerFactory as in the following example

 Mapping mapping = ... ;
 FieldHandlerFactoyt factory = ...;
 Marshaller m = new Marshaller(writer);
 ClassDescriptorResolverImpl cdr = new ClassDescriptorResolverImpl();
 cdr.getIntrospector().addFieldHandlerFactory(factory);
 m.setResolver(cdr);
 marshaller.setMapping(mapping);
			

please make sure that you set the mapping file after you set the ClassDescriptorResolver. You will note the following in the Javadoc for org.exolab.castor.xml.Marshaller.html#setResolver(org.exolab.castor.xml.ClassDescriptorResolver) :

	Note
	Note: This method will nullify any Mapping currently being used by this Marshaller

Yes and no. It actually depends. When requiring pretty printing during marshalling, Castor internally relies on Apache's Xerces to implement this feature. As such, when not using this feature, Xerces is not a requirement, and any JAXP-compliant XML parser can be used (for unmarshalling).

In other words, with the latter use case, you do not have to download (and use) Xerces separetely.

No. Starting with release 1.1, we have added support for using the Xerces instance as shipped with the JRE/JDK for serialization. As such, for Java 5.0 users, this removes the requirement to download Xerces separately when wanting to use 'pretty printing' with Castor XML during marshalling.

To enable this feature, please change the following properties in your local castor.properties file (thus redefining the default value) as shown below:

 # Defines the XML parser to be used by Castor. 
 # The parser must implement org.xml.sax.Parser.
 org.exolab.castor.parser=org.xml.sax.helpers.XMLReaderAdapter

 # Defines the (default) XML serializer factory to use by Castor, which must
 # implement org.exolab.castor.xml.SerializerFactory; default is
 # org.exolab.castor.xml.XercesXMLSerializerFactory
 org.exolab.castor.xml.serializer.factory=org.exolab.castor.xml.XercesJDK5XMLSerializerFactory

 # Defines the default XML parser to be used by Castor.
 org.exolab.castor.parser=com.sun.org.apache.xerces.internal.parsers.SAXParser
			

Starting with release 1.3.3, the Castor source generator supports a new naming scheme for Java field names, which will be enabled by default. As such, Java field names as generated will follow more closely the standard Java property naming conventions. Should there be a need to keep using the old naming schema, please amend the following property in your custom castorbuilder.properties file:

#
# Property specifying whether for Java field names the old naming conventions
# should be used.
#
# Possible values:
# - true
# - false (default)
# 
# <pre>
# org.exolab.castor.builder.field-naming.old = false
# </pre>
#
org.exolab.castor.builder.field-naming.old=true
	        

With support for Java 5.0 enabled, the generated code will support the following Java 5.0-specific artifacts:

To disable this feature (on by default), please amend the following property in your custom castorbuilder.properties file:

# Specifies whether the sources generated should be source compatible with
# Java 1.4 or Java 5.0. Legal values are "1.4" and "5.0".  When "5.0" is
# selected, generated source will use Java 5 features such as generics and
# annotations.
# Defaults to "5.0".
#
org.exolab.castor.builder.javaVersion=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:

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>

 # 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 a property definition to your custom builder configuration file as follows:

# 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

Please note that setting this property will not affect class creation when the defaultBindingType is explicitely used in a binding file. In that case, the value set there will take precedence.

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). Please 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: 1.3.2

Specifies whether cycle breaker code should be added to generated methods equals() and hashcode().

# Property specifying whether cycle breaker code should be added
# to generated methods 'equals' and 'hashcode'. 
#
# Possible values:
# - true (default)
# - false
#
# <pre>
# org.exolab.castor.builder.useCycleBreaker
# </pre>
org.exolab.castor.builder.useCycleBreaker=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:

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 in general).

By setting this property to true, additional getter/setter methods for the field in question, such as get/set by reference and set as copy methods, will be added. In order to have these additional methods generated, please override the following code generator property in a custom castorbuilder.properties as shown:

# Enables generation of extra methods for collection fields, such as get/set by
# reference and set as copy.  Extra methods are in addition to the usual
# collection get/set methods.  Set this to true if you want your code to be
# more compatible  with Castor JDO.
#
# Possible values:
# - false (default) 
# - true
org.exolab.castor.builder.extraCollectionMethods=true
            

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 method setJClassPrinterType(String) on org.exolab.castor.builder.SourceGenerator 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

<binding
    defaultBindingType = (element|type)>
    (include*,
     package*,
     namingXML?,
     elementBinding*,
     attributeBinding,
     complexTypeBinding,
     groupBinding)
</binding>

The binding element is the root element and contains the binding information.

<include
    URI = xsd:anyURI/>

This element allows you to include a binding declaration defined in another file. This allows reuse of binding files defined for various XML schemas.

<package>
    name = xsd:string
    (namespace|schemaLocation) = xsd:string>
</package>

The targetNamespace attribute of an XML schema identifies the namespace in which the XML schema elements are defined. This language namespace is defined in the generated Java source as a package declaration. The <package/> element allows you to define the mapping between an XML namespace and a Java package.

Moreover, XML schema allows you to factor the definition of an XML schema identified by a unique namespace by including several XML schemas instances to build one XML schema using the <xsd:include/> element. Please make sure you understand the difference between <xsd:include/> and <xsd:import/>. <xsd:include/> # relies on the URI of the included XML schema. This element allows you to keep the structure hierarchy defined in XML schema in a single generated Java package. Thus the binding file allows you to define the mapping between a schemaLocation attribute and a Java package.

<namingXML>
   (elementName,complexTypeName,modelGroupName)
</namingXML>

<elementName|complexTypeName|modelGroupName>
    (prefix?, suffix?) = xsd:string
</elementName|complexTypeName|modelGroupName>

One of the aims of the binding file is to avoid naming collisions. Indeed, XML schema allows <element>s and <complexType>s to share the same name, resulting in name collisions when generating sources. Defining a binding for each element and complexType that share the same name is not always a convenient solution (for instance the BPML XML schema and the UDDI v2.0 XML schema use the same names for top-level complexTypes and top-level elements).

The main aim of the <namingXML/> element is to define default prefices and suffices for the names of the classes generated for an <element>, a <complexType> or a model group definition.

	Note
	It is not possible to control the names of the classes generated to represent nested model groups (all, choice, and sequence).

<elementBinding|attributeBinding|complexTypeBinding|groupBinding
    name = xsd:string>
   ((java-class|interface|member|contentMember),
     elementBinding*,
     attributeBinding*,
     complexTypeBinding*,
     groupBinding*)
</elementBinding|attributeBinding|complexTypeBinding|groupBinding>

These elements are the tenets of the binding file since they contain the binding definition for an XML schema element, attribute, complex type and model group definition. The first child element (<java-class/>, <interface>, <member> or <contentMember/>) will determine the type of binding one is defining. Please note that defining a <java-class> binding on an XML schema attribute will have absolutely no effect.

The binding file is written from an XML schema point of view; there are two distinct ways to define the XML schema component for which we are defining a binding.

[1]Path         ::= '/'LocationPath('/'LocationPath)*
[2]LocationPath ::= (Complex|ModelGroup|Attribute|Element|Enumeration)
[3]Complex      ::= 'complexType:'(NCName)
[4]ModelGroup   ::= 'group:'NCName
[5]Attribute    ::= '@'NCName
[6]Element      ::= NCName
[7]Enumeration  ::= 'enumType':(NCName)
                    

<complexType name="fooType">
    <sequence>
        <element name="foo" type="string" />
    </sequence>
</complexType>

<elementBinding name="/complexType:fooType/foo>
   <member name="MyFoo" handler="mypackage.myHandler"/>
</elementBinding>

<complexTypeBinding name="/fooType">
   <elementBinding name="/foo>
      <member name="MyFoo" handler="mypackage.myHandler"/>
   </elementBinding>
<complexTypeBinding>

<java-class
    name? = xsd:string
    package? = xsd:string
    final? = xsd:boolean
    abstract? = xsd:boolean
    equals? = xsd:boolean
    bound? = xsd:boolean
    (implements*,extends?)
</java-class>

This element defines all the options for the class to be generated, including common properties such as class name, package name, and so on.

For instance, the following binding definition instructs the source generator to generate a class CustomTest for a global element named 'test', replacing the default class name Test with CustomTest.

<elementBinding name="/test">
   <java-class name="CustomTest" final="true"/>
</elementBinding>

In addition to the properties listed above, it is possible to define that the class generated will extend a class given and/or implement one or more interfaces.

For instance, the following binding definition instructs the source generator to generate a class TestWithInterface that implements the interface org.castor.sample.SomeInterface in addition to java.io.Serializable.

<elementBinding name="/test">
   <java-class name="TestWithInterface">
      <implements>org.castor.sample.SomeInterface</implements>
   </java-class>
</elementBinding>
                 

The subsequent binding definition instructs the source generator to generate a class TestWithExtendsAndInterface that implements the interface org.castor.sample.SomeInterface in addition to java.io.Serializable, and extends from a (probably abstract) base class SomeAbstractBaseClass.

<elementBinding name="/test">
   <java-class name="TestWithExtendsAndInterface">
      <extends>org.castor.sample.SomeAbstractBaseClass</extends>
      <implements>org.castor.sample.SomeInterface</implements>
   </java-class>
</elementBinding>
                 

The generated class SomeAbstractBaseClass will have a class signature as shown below:

...

public class TestWithExtendsAndInterface
   extends SomeAbstractBaseClass
   implements SomeInterface, java.io.Serializable {
   ...
                 

 <member
  name? = xsd:string
  java-type? = xsd:string
  wrapper? = xsd:boolean
  handler? = xsd:string
  visibility? = (public|protected|private)
  collection? = (array|vector|arraylist|hashtable|collection|odmg|set|map|sortedset)
  validator? = xsd:string/>

This element represents the binding for class member. It allows the definition of its name and java type as well as a custom implementation of FieldHandler to help the Marshaling framework in handling that member. Defining a validator is also possible. The names given for the validator and the fieldHandler must be fully qualified.

For instance, the following binding definition:

<elementBinding name="/root/members">
   <member collection="set"/>
</elementBinding>

instructs the source generator to generate -- within a class Root -- a Java member named members using the collection type java.util.Set instead of the default java.util.List:

         public class Root {
         
            private java.util.Set members;
         
            ...
         
         }

The following (slightly amended) binding element:

<elementBinding name="/root/members">
   <member name="memberSet" collection="set"/>
</elementBinding>

instructs the source generator to generate -- again within a class Root -- a Java member named memberSet (of the same collection type as in the previous example), overriding the name of the member as specified in the XML schema:

public class Root {

   private java.util.Set memberSet;

   ...

}

          <contentMember
           name? = xsd:string
           visiblity? = (public|protected|private)

This element represents the binding for content class member generated as a result of a mixed mode declaration of a complex type definition. It allows the definition of its name and its visibility

For a complex type definition declared to be mixed such as follows ...

<complexType name="RootType" mixed="true">
   <sequence>
      ...
   >/sequence>
>/complexType>

... the following binding definition ...

<elementBinding name="/complexType:RootType">
   <contentMember name="customContentMember"/>
</elementBinding>

instructs the source generator to generate -- within a class RootType -- a Java member named customContentMember of type java.lang.String:

public class RootType {

   private java.util.String customContentMember;

   ...
}

<enumBinding>
   (enumDef)
</enumBinding>

<enumDef>
   (enumClassName = xsd:string, enumMember*)
</enumDef>

<enumMember>
   (name = xsd:string, value = xsd:string)
</enumMember>

The <enumBinding> element allows more control on the code generated for type-safe enumerations, which are used to represent an XML Schema <simpleType> enumeration.

For instance, given the following XML schema enumeration definition:

<xs:simpleType name="durationUnitType">
  <xs:restriction base='xs:string'>
    <xs:enumeration value='Y' />
    <xs:enumeration value='M' />
    <xs:enumeration value='D' />
    <xs:enumeration value='h' />
    <xs:enumeration value='m' />
    <xs:enumeration value='s' />
  </xs:restriction>
</simpleType>

the Castor code generator would generate code where the default naming convention used during the generation would overwrite the first constant definition for value 'M' with the one generated for value 'm'.

The following binding definition defines -- through the means of an <enumMember> definition for the enumeration value 'M' -- a special binding for this value:

<enumBinding name="/enumType:durationUnitType">
  <enum-def>
    <enumMember>
      <value>M</value>
      <javaName>CUSTOM_M</javaName>
    </enumMember>
  </enum-def>
</enumBinding>

and instructs the source generator to generate -- within a class DurationUnitType -- a constant definition named CUSTOM_M for the enumeration value M.

During code generation, the Castor XML code generator will run into situations where a class (about to be generated, and as such about to be written to the file system) will overwrite an already existing class. This, for example, is the case if within one XML schema there's two (local) element definitions within separate complex type definitions with the same name. In such a case, Castor will emit warning messages that inform the user that a class will be overwritten.

As of release 1.1, the Castor XML code generator supports two reporting modes that allow different levels of control in the event of such collisions, warnViaConsoleDialog and informViaLog mode.

Please select the reporting mode of your choice according to your needs, the default being warnViaConsoleDialog. Please note that the informViaLog reporting mode should be the preferred choice when using the XML code generator in an automated environment.

In general, the warning messages produced are very useful in assisting you in your creation of the binding file, as shown in below example for the warnViaConsoleDialog mode:

 Warning: A class name generation conflict has occurred between element
         '/Data/OrderReceipt/LineItem' and element '/Data/PurchaseOrder/LineItem'.
         Please use a Binding file to solve this problem.Continue anyway [not recommended] (y|n|?)y
 Warning: A class name generation conflict has occurred between element
         '/Data/OrderReceipt/LineItem' and element '/Data/PurchaseOrder/LineItem'.
         Please use a Binding file to solve this problem.Continue anyway [not recommended] (y|n|?)y
 Warning: A class name generation conflict has occurred between element
         '/Data/OrderReceipt/LineItem' and element '/Data/PurchaseOrder/LineItem'.
         Please use a Binding file to solve this problem.Continue anyway [not recommended] (y|n|?)y
 Warning: A class name generation conflict has occurred between element
         'complexType:ReceiptLineItemType/Sku' and element 'complexType:LineItemType/Sku'.
         Please use a Binding file to solve this problem.Continue anyway [not recommended] (y|n|?)y
 Warning: A class name generation conflict has occurred between element
         'complexType:ReceiptLineItemType/Sku' and element 'complexType:LineItemType/Sku'.
         Please use a Binding file to solve this problem.Continue anyway [not recommended] (y|n|?)y
 Warning: A class name generation conflict has occurred between element
         'complexType:ReceiptLineItemType/Sku' and element 'complexType:LineItemType/Sku'.
         Please use a Binding file to solve this problem.Continue anyway [not recommended] (y|n|?)y
                         

As of Castor 1.1.1, support has been added to the Castor XML code generator for a (nearly) automatic conflict resolution. To enable this new mode, please override the following property in your custom property file as shown below:

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

As a result of enabling automatic conflict resolution, Castor will try to resolve such name collisions automatically, using one of the following two strategies:

In order to explain the modus operandi of these two modes, please assume two complex type definitions AType and BType in an XML schema, with both of them defining a local element named c.

<xs:complexType name="AType">
    <xs:sequence>
        <xs:element name="c" type="CType1" />
    </xs:sequence>
</xs:complexType>            

<xs:complexType name="BType">
    <xs:sequence>
        <xs:element name="c" type="CType2" />
    </xs:sequence>
</xs:complexType>

Without automatic collision resolution enabled, Castor will create identically named classes C.java for both members, and one will overwrite the other. Please note the different types for the two c element definitions, which requires two class files to be generated in order not to lose this information.

# Property specifying the 'string' used in type strategy to be inserted 
# between the actual element name and the type name (during automatic class name 
# conflict resolution); defaults to 'By'.
org.exolab.castor.builder.automaticConflictResolutionTypeSuffix=ByBy

2.4.2.2.4. Conflicts covered

The Castor XML code generator, with automatic collision resolution enabled, is capable of resolving the following collisions automatically:

• Name of local element definition same as name of a global element

• Name of local element definition same as name of another local element definition.

	Note
	Please note that collision resolution for a local to local collision will only take place for the second local element definition encountered (and subsequent ones).

As shown in the subsequent table, there's multiple ways of specifying the input for the Castor code generator. At least one input source has to be specified.

In addition, a nested <fileset> can be specified as the source of input. Please refer to the samples shown below.

Please find below the complete list of parameters that can be set on the Castor source generator to fine-tune the execution behavior.

To be able to start source code generation from XML schema from within Maven, you will have to configure the Maven 2 Castor plugin as follows:

<plugin>
   <groupId>org.codehaus.mojo</groupId>
   <artifactId>castor-maven-plugin</artifactId>
   <version>2.0</version>
</plugin>

Above configuration will trigger source generation using the default values as explained at the Castor plugin page, assuming that the XML schema(s) are located at src/main/castor, and code will be saved at target/generated-sources/castor. When generating sources for multiple schemas at the same time, you can put namespace to package mappings into src/main/castor/castorbuilder.properties.

To e.g. change some of these default locations, please add a <configuration> section to the plugin configuration as follows:

<plugin>
   <groupId>org.codehaus.mojo</groupId>
   <artifactId>castor-maven-plugin</artifactId>
   <version>2.0</version>
   <configuration>
      <schema>src/main/resources/org/exolab/castor/builder/binding/binding.xsd</schema>
      <packaging>org.exolab.castor.builder.binding</packaging>
      <properties>src/main/resources/org/exolab/castor/builder/binding.generation.properties</properties>
   </configuration>
 </plugin>      

Details on the available configuration properties can be found here.

By default, the Maven Castor plugin has been built and tested against a particular version of Castor. To switch to a newer version of Castor (not the plugin itself), please use a <dependencies> section as shown below to point the plugin to e.g. a newer version of Castor:

<plugin>
   <groupId>org.codehaus.mojo</groupId>
   <artifactId>castor-maven-plugin</artifactId>
   <version>2.0</version>
   <dependencies>
     <dependency> 
       <groupId>org.codehaus.castor</groupId>
       <artifactId>castor</artifactId>
       <version>1.3.1-SNAPSHOT</version>
     </dependency>
   </dependencies>
 </plugin>      

To integrate source code generation from XML schema into your standard build life-cycle, you will have to add an <executions> section to your standard plugin configuration as follows:

<plugin>
   <groupId>org.codehaus.mojo</groupId>
   <artifactId>castor-maven-plugin</artifactId>
   <version>2.0</version>
   <executions>
      <execution>
         <goals>
            <goal>generate</goal>
         </goals>
      </execution>
   </executions>            
</plugin>       

Below command shows how to instruct Maven (manually) to generate Java sources from the XML schemas as configured above.

> mvn castor:generate

java org.exolab.castor.builder.SourceGeneratorMain -i foo-schema.xsd \
    -package com.xyz
            

This will generate a set of source files from the the XML Schema foo-schema.xsd and place them in the package com.xyz.

To compile the generated classes, simply run javac or your favorite compiler:

javac com/xyz/*.java

Created class will have marshal and unmarshal methods which are used to go back and forth between XML and an Object instance.

The source code generator has a number of different options which may be set. Some of these are done using the command line and others are done using a properties file located by default at org/exolab/castor/builder/castorbuilder.properties.