|  |  |  | License Codehaus OpenEJB OpenJMS OpenORB Tyrex

Old releases
General
Release 1.3
Release 1.3rc1
Release 1.2

Main
Home
About
Features
Download
Dependencies
Reference guide
Publications
JavaDoc
Maven 2 support
Maven 2 archetypes
DTD & Schemas
Recent HTML changes
News Archive
RSS news feed
Project Wiki

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

Related projects
Spring ORM support
Spring XML factories
WS frameworks

XML
XML

XML Code Generator
XML Code Generator

JDO
Introduction
First steps
Using JDO
JDO Config
Types
JDO Mapping
JDO FAQ
JDO Examples
JDO HOW-TOs
Tips & Tricks
Other Features
JDO sample JAR

Tools
Schema generator

Advanced JDO
Caching
OQL
Trans. & Locks
Design
KeyGen
Long Trans.
Nested Attrs.
Pooling Examples
LOBs
Best practice

DDL Generator
Using DDL Generator
Properties
Ant task
Type Mapping

More
The Examples
3rd Party Tools
JDO Tests
XML Tests
Configuration

About
License
User stories
Contributors
Marketplace
Status, Todo
Changelog
Library
Contact
Project Name

## How to use a binding file with source generation

Intended Audience
Background
The Supply Chain XSD
Binding file? - IT IS REQUIRED!
References

## Intended Audience

Anyone who wants to use a binding file with the Castor XML source generator. This document discusses various main concepts in the context of a non-trivial real word example, and intends to help people to get familiar with the basic concepts and discusses some implementation details.

The example given describes the steps required to build a binding file that helps users to overcome typical problems related to the use of more complex XML Schemas.

## Background

Two companies wish to trade with each other using a Supply Chain messaging system. This system sends and receives Purchase Orders and Order Receipt messages. After many months of discussion they have finally decided upon the structure of the Version 1.0 of their message XSD and both are presently developing solutions for it. One of the companies decides to use Java and Castor XML supprt for (un)marshalling and Castor's code generator to accelerate their development process.

## The Supply Chain XSD

supplyChainV1.0.xsd

    <?xml version="1.0" encoding="UTF-8"?>
    <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
                  elementFormDefault="qualified"
                  attributeFormDefault="unqualified">
        <xs:element name="Data">
          <xs:annotation>
            <xs:documentation>This section contains the supply chain message
    		  data</xs:documentation>
          </xs:annotation>
          <xs:complexType>
            <xs:choice>
              <xs:element name="PurchaseOrder">
                <xs:complexType>
                  <xs:sequence>
                    <xs:element name="LineItem" type="LineItemType" maxOccurs="unbounded"/>
                  </xs:sequence>
                  <xs:attribute name="OrderNumber" type="xs:string" use="required"/>
                </xs:complexType>
              </xs:element>
              <xs:element name="OrderReceipt">
                <xs:complexType>
                  <xs:sequence>
                    <xs:element name="LineItem" type="ReceiptLineItemType" maxOccurs="unbounded"/>
                  </xs:sequence>
                  <xs:attribute name="OrderNumber" type="xs:string" use="required"/>
                </xs:complexType>
        	  </xs:element>
        	</xs:choice>
          </xs:complexType>
        </xs:element>
        <xs:complexType name="SkuType">
          <xs:annotation>
            <xs:documentation>Contains Product Identifier</xs:documentation>
          </xs:annotation>
          <xs:sequence>
            <xs:element name="Number" type="xs:integer"/>
            <xs:element name="ID" type="xs:string"/>
          </xs:sequence>
        </xs:complexType>
        <xs:complexType name="ReceiptSkuType">
          <xs:annotation>
            <xs:documentation>Contains Product Identifier</xs:documentation>
          </xs:annotation>
          <xs:complexContent>
            <xs:extension base="SkuType">
              <xs:sequence>
                <xs:element name="InternalID" type="xs:string"/>
              </xs:sequence>
            </xs:extension>
          </xs:complexContent>
        </xs:complexType>
        <xs:complexType name="LineItemType">
          <xs:sequence>
            <xs:element name="Sku" type="SkuType"/>
            <xs:element name="Value" type="xs:double"/>
            <xs:element name="BillingInstructions" type="xs:string"/>
            <xs:element name="DeliveryDate" type="xs:date"/>
            <xs:element name="Number" type="xs:integer"/>
          </xs:sequence>
        </xs:complexType>
        <xs:complexType name="ReceiptLineItemType">
          <xs:sequence>
            <xs:element name="Sku" type="ReceiptSkuType"/>
            <xs:element name="Value" type="xs:double"/>
            <xs:element name="PackingDescription" type="xs:string"/>
            <xs:element name="ShipDate" type="xs:dateTime"/>
            <xs:element name="Number" type="xs:integer"/>
          </xs:sequence>
        </xs:complexType>
    </xs:schema>

## Binding file? - IT IS REQUIRED!

If you run the Castor CodeGenerator on the above XSD you end up with the following set of classes. [You also get lots of warning messages with the present 0.99 version.]

    Data.java
    DataDescriptor.java
    LineItem.java
    LineItemDescriptor.java
    LineItemType.java
    LineItemTypeDescriptor.java
    OrderReceipt.java
    OrderReceiptDescriptor.java
    PurchaseOrder.java
    PurchaseOrderDescriptor.java
    ReceiptLineItemType.java
    ReceiptLineItemTypeDescriptor.java
    ReceiptSkuType.java
    ReceiptSkuTypeDescriptor.java
    Sku.java
    SkuDescriptor.java
    SkuType.java
    SkuTypeDescriptor.java

The problem here is that there are two different elements with the same name in different locations in the XSD. This causes a java code generation conflict. Castor uses the element name as the name of the class. So the second class generated for the LineItem definition, which is different than the first, overwrites the first class generated.

A binding file is therefore necessary to help the Castor code generator differentiate between these generated classes. [i.e. You can 'bind' an element in the XSD to a differently named class file that you want to generate. Thus keeping different elements seperate]

Tip:

The warning messages for Castor 0.99+ are very usefull in assisting you in your creation of the binding file. For the example the warning messages for the example are;
`Warning: A class name generation conflict has occured 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 occured 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 occured 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 occured 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 occured 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 occured 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`

The following binding file definition will overcome the naming issues for the generated classes.

binding.xml

    <binding xmlns="http://www.castor.org/SourceGenerator/Binding"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                xsi:schemaLocation="http://www.castor.org/SourceGenerator/Binding
                    C:\\Castor\\xsd\\binding.xsd"
                defaultBinding="element">

       <elementBinding name="/Data/PurchaseOrder/LineItem">
          <java-class name="PurchaseOrderLineItem"/>
       </elementBinding>

       <elementBinding name="/Data/OrderReceipt/LineItem">
          <java-class name="OrderReceiptLineItem"/>
       </elementBinding>

       <elementBinding name="/complexType:ReceiptLineItemType/Sku">
          <java-class name="OrderReceiptSku"/>
       </elementBinding>

       <elementBinding name="/complexType:LineItemType/Sku">
          <java-class name="PurchaseOrderSku"/>
       </elementBinding>

    </binding>

Things to notice in the above binding.xml file are that the name path used is relative to the root of the XSD NOT the root of the target XML. Also notice that the two complex types have the "complexType:" prefix to identify them, and then the name path relative to the root of the XSD.

The new list of generated classes is:

    Data.java
    DataDescriptor.java
    LineItem.java
    LineItemDescriptor.java
    LineItemType.java
    LineItemTypeDescriptor.java
    OrderReceipt.java
    OrderReceiptDescriptor.java
    OrderReceiptLineItem.java
    OrderReceiptLineItemDescriptor.java
    OrderReceiptSku.java
    OrderReceiptSkuDescriptor.java
    PurchaseOrder.java
    PurchaseOrderDescriptor.java
    PurchaseOrderLineItem.java
    PurchaseOrderLineItemDescriptor.java
    PurchaseOrderSku.java
    PurchaseOrderSkuDescriptor.java
    ReceiptLineItemType.java
    ReceiptLineItemTypeDescriptor.java
    ReceiptSkuType.java
    ReceiptSkuTypeDescriptor.java
    Sku.java
    SkuDescriptor.java
    SkuType.java
    SkuTypeDescriptor.java

The developers can now use these generated classes with Castor to (un)marshal the supply chain messages sent by their business partner.

## References

- | Castor Source Generator

<notice> Copyright © 1999-2005 ExoLab Group, Intalio Inc., and Contributors. All rights reserved. </notice>
<notice> Java, EJB, JDBC, JNDI, JTA, Sun, Sun Microsystems are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and in other countries. XML, XML Schema, XSLT and related standards are trademarks or registered trademarks of MIT, INRIA, Keio or others, and a product of the World Wide Web Consortium. All other product names mentioned herein are trademarks of their respective owners. </notice>