Castor XML -- Code generator bindings

Documentation Author(s):
Werner Guttmann

This section defines the Castor XML binding file and describes, with examples, how to use it.

The default binding used to generate the Java Object Model from an XML schema may not meet your expectations. For instance, the default binding doesn't deal with naming collisions that can appear because XML Schema allows an element declaration and a complexType definition to use the same name. The source generator will attempt to create two Java classes with the same qualified name. However, the second class generated will simply overwrite the first one.

Another example of where the default source generator binding may not meet your expectations is when you want to change the default datatype binding provided by Castor or when you want to add validation rules by implementing your own validator and passing it to the Source Generator.

The Binding declaration is an XML-based language that allows the user to control and tweak details about source generation for the generated classes. The aim of this section is to provide an overview of the binding file and a definition of the several XML components used to define this binding file.

A more in-depth presentation will be available soon in the Source Generator User Document (PDF).

<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 aim of the binding file is to avoid naming collisions. Indeed, XML Schema allows elements and complexTypes 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 aim of the <naming/> XML element is to define a prefix and a suffix 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>

name:

The name of the XML schema component for which we are defining a binding.

These elements are the tenets of the binding file since they contain the binding definition for an XML Schema element, attribute, complexType and modelGroup 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. First we can define it through the name attribute.

The value of the name attribute uniquely identifies the XML Schema Component. It can refer to the top-level component using the NCName of that component or it can use a location language based on XPath³. The grammar of that language can be defined by the following BNF:

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

Please note that as of Castor 1.1, all values for the name attribute have to start with a '/'.

The second option to identify an XML Schema Component is to embed its binding definition inside its parent binding definition.

For instance, the following binding definitions are equivalent and identify the element 'foo' defined in the top-level complexType 'fooType'.

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

name:

The name of the class that will be generated.

package:

The package of the class to be generated. if set, this option overrides the mapping defined in the <package/> element.

final:

If true, the generated class will be final.

abstract:

If true, the generated class will be abstract.

equals:

If true, the generated class will implement the equals() and hashCode() method.

bound:

If true, the generated class will implement bound properties, allowing property change notification.

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

name:

The name of the class member that will be generated.

java-type:

the fully qualified name of the java type.

wrapper:

If true, a wrapper object will be generated in case the Java type is a java primitive.

handler:

The fully qualified name of the FieldHandler to use.

collection:

If the schema component can occur more than once then this attribute allows specifying the collection to use to represent the component in Java.

validator:

The fully qualified name of the FieldValidator to use.

visibility:

A custom visibility of the content class member generated, with the default being public.

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 declaraiton of a complex type definition. It allows the definition of its name and its visibility

name:

The name of the class member that will be generated, overriding the default name of _content.

visibility:

A custom visibility of the content class member generated, with the default being public.

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

The <javadoc> element allows one to enter the necessary JavaDoc representing the generated classes or members.

    <interface>
        name = xsd:string
    </interface>

This element specifies the name of the interface to be generated for an XML schema component.

As mentioned previously, you use a binding file for two main reasons:

For the latter case, you'll (often) notice such collisions by looking at generated Java code that frequently does not compile. Whilst this is realtively easy for small(ish) XML schema(s), this task gets tedious for more elaborate XML schemas. To ease your life in the context of this 'collision detection', the Castor XML code generator provides you with a few advanced features. The following sections cover these features in detail.

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 already mentioned, this mode emits warning messages to stdout, and asks you whether you want to continue with the code generation or not. This allows for very fine grained control over the extent of the code generation.

Please note that there is several setter methods on the org.exolab.castor.builder.SourceGenerator that allow you to fine-tune various settings for this reporting mode. Genuinly, we belive that for automated code generation through either Ant or Maven, the new informViaLog is better suited for these needs.

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:

For selecting one of the two strategies during XML code generation, please see the documentation for the following code artefacts:

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.

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

<complexType name="BType">
	<sequence>
		<element name="c" type="CType2" />
	</sequence>
</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.

This strategy will prepend an XPATH fragment to the default Java name as derived during code generation, the default name (frequently) being the name of the XML schema artefact, e.g. the element name of the complex type name. The XPATH fragment being prepended is minimal in the sense that the resulting rooted XPATH is unique for the XML schema artefact being processed.

With automatic collision resolution enabled and the strategy 'XPATH' selected, Castor will create the following two classes, simply prepending the name of the complex type to the default element name:

This strategy will append 'type' information to the default Java name as derived during code generation, the default name (frequently) being the name of the XML schema artefact, e.g. the element name of the complex type name.

With automatic collision resolution enabled and the strategy 'TYPE' selected, Castor will create the following two classes, simply appending the name of the complex type to the default element name (with a default 'By' inserted):

To override the default 'By' inserted between the default element name and the type information, please override the following property in your custom property file as shown below:

# 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

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

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