<?xml version="1.0" encoding="ISO-8859-1"?>
<document url="http://castor.org/howto/how-to-use-a-binding-file-with-source-generation.xml">
  <properties>
    <title>How to use a binding file with source generation</title>
    <abstract>
       General information about using a binding file with source generation
    </abstract>
    <status>Final</status>
  </properties>
  <body>
    <title>How to use a binding file with source generation</title>

    <section title="Intended Audience">

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

        <p>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.</p>
        
    </section>
    
    <section title="Background">
         <p>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.</p>
    </section>
	
    <section title="The Supply Chain XSD">
			
		    <code-panel top-caption="supplyChainV1.0.xsd">
&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;xs:schema xmlns:xs=&quot;http://www.w3.org/2001/XMLSchema&quot; 
              elementFormDefault=&quot;qualified&quot; 
              attributeFormDefault=&quot;unqualified&quot;&gt;
    &lt;xs:element name=&quot;Data&quot;&gt;
      &lt;xs:annotation&gt;
        &lt;xs:documentation&gt;This section contains the supply chain message 
		  data&lt;/xs:documentation&gt;
      &lt;/xs:annotation&gt;
      &lt;xs:complexType&gt;
        &lt;xs:choice&gt;
          &lt;xs:element name=&quot;PurchaseOrder&quot;&gt;
            &lt;xs:complexType&gt;
              &lt;xs:sequence&gt;
                &lt;xs:element name=&quot;LineItem&quot; type=&quot;LineItemType&quot; maxOccurs=&quot;unbounded&quot;/&gt;
              &lt;/xs:sequence&gt;
              &lt;xs:attribute name=&quot;OrderNumber&quot; type=&quot;xs:string&quot; use=&quot;required&quot;/&gt;
            &lt;/xs:complexType&gt;
          &lt;/xs:element&gt;
          &lt;xs:element name=&quot;OrderReceipt&quot;&gt;
            &lt;xs:complexType&gt;
              &lt;xs:sequence&gt;
                &lt;xs:element name=&quot;LineItem&quot; type=&quot;ReceiptLineItemType&quot; maxOccurs=&quot;unbounded&quot;/&gt;
              &lt;/xs:sequence&gt;
              &lt;xs:attribute name=&quot;OrderNumber&quot; type=&quot;xs:string&quot; use=&quot;required&quot;/&gt;
            &lt;/xs:complexType&gt;
    	  &lt;/xs:element&gt;
    	&lt;/xs:choice&gt;
      &lt;/xs:complexType&gt;
    &lt;/xs:element&gt;
    &lt;xs:complexType name=&quot;SkuType&quot;&gt;
      &lt;xs:annotation&gt;
        &lt;xs:documentation&gt;Contains Product Identifier&lt;/xs:documentation&gt;
      &lt;/xs:annotation&gt;
      &lt;xs:sequence&gt;
        &lt;xs:element name=&quot;Number&quot; type=&quot;xs:integer&quot;/&gt;
        &lt;xs:element name=&quot;ID&quot; type=&quot;xs:string&quot;/&gt;
      &lt;/xs:sequence&gt;
    &lt;/xs:complexType&gt;
    &lt;xs:complexType name=&quot;ReceiptSkuType&quot;&gt;
      &lt;xs:annotation&gt;
        &lt;xs:documentation&gt;Contains Product Identifier&lt;/xs:documentation&gt;
      &lt;/xs:annotation&gt;
      &lt;xs:complexContent&gt;
        &lt;xs:extension base=&quot;SkuType&quot;&gt;
          &lt;xs:sequence&gt;
            &lt;xs:element name=&quot;InternalID&quot; type=&quot;xs:string&quot;/&gt;
          &lt;/xs:sequence&gt;
        &lt;/xs:extension&gt;
      &lt;/xs:complexContent&gt;
    &lt;/xs:complexType&gt;
    &lt;xs:complexType name=&quot;LineItemType&quot;&gt;
      &lt;xs:sequence&gt;
        &lt;xs:element name=&quot;Sku&quot; type=&quot;SkuType&quot;/&gt;
        &lt;xs:element name=&quot;Value&quot; type=&quot;xs:double&quot;/&gt;
        &lt;xs:element name=&quot;BillingInstructions&quot; type=&quot;xs:string&quot;/&gt;
        &lt;xs:element name=&quot;DeliveryDate&quot; type=&quot;xs:date&quot;/&gt;
        &lt;xs:element name=&quot;Number&quot; type=&quot;xs:integer&quot;/&gt;
      &lt;/xs:sequence&gt;
    &lt;/xs:complexType&gt;
    &lt;xs:complexType name=&quot;ReceiptLineItemType&quot;&gt;
      &lt;xs:sequence&gt;
        &lt;xs:element name=&quot;Sku&quot; type=&quot;ReceiptSkuType&quot;/&gt;
        &lt;xs:element name=&quot;Value&quot; type=&quot;xs:double&quot;/&gt;
        &lt;xs:element name=&quot;PackingDescription&quot; type=&quot;xs:string&quot;/&gt;
        &lt;xs:element name=&quot;ShipDate&quot; type=&quot;xs:dateTime&quot;/&gt;
        &lt;xs:element name=&quot;Number&quot; type=&quot;xs:integer&quot;/&gt;
      &lt;/xs:sequence&gt;
    &lt;/xs:complexType&gt;
&lt;/xs:schema&gt;</code-panel>
    </section>
		
    <section title="Binding file? - IT IS REQUIRED!">
        
        <p>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.]</p>
			
    <code-panel>
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</code-panel>
	
        <p>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.</p>

        <p>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]</p>

        <tip><p>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;<br/>
<tt>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<br/>
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<br/>
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<br/>
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<br/>
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<br/>
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</tt>
        </p></tip>
			
        <p>The following binding file definition will overcome the naming issues for 
           the generated classes.</p>
			   
    <code-panel top-caption="binding.xml">
&lt;binding xmlns=&quot;http://www.castor.org/SourceGenerator/Binding&quot; 
            xmlns:xsi=&quot;http://www.w3.org/2001/XMLSchema-instance&quot; 
            xsi:schemaLocation=&quot;http://www.castor.org/SourceGenerator/Binding
                C:\\Castor\\xsd\\binding.xsd&quot; 
            defaultBinding=&quot;element&quot;&gt;

   &lt;elementBinding name=&quot;/Data/PurchaseOrder/LineItem&quot;&gt;
      &lt;java-class name=&quot;PurchaseOrderLineItem&quot;/&gt;
   &lt;/elementBinding&gt;
	
   &lt;elementBinding name=&quot;/Data/OrderReceipt/LineItem&quot;&gt;
      &lt;java-class name=&quot;OrderReceiptLineItem&quot;/&gt;
   &lt;/elementBinding&gt;
	
   &lt;elementBinding name=&quot;/complexType:ReceiptLineItemType/Sku&quot;&gt;
      &lt;java-class name=&quot;OrderReceiptSku&quot;/&gt;
   &lt;/elementBinding&gt;
	
   &lt;elementBinding name=&quot;/complexType:LineItemType/Sku&quot;&gt;
      &lt;java-class name=&quot;PurchaseOrderSku&quot;/&gt;
   &lt;/elementBinding&gt;	
	
&lt;/binding&gt;</code-panel>

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

        <p>The new list of generated classes is:</p>
    <code-panel>
Data.java
DataDescriptor.java
LineItem.java
LineItemDescriptor.java
LineItemType.java
LineItemTypeDescriptor.java
OrderReceipt.java
OrderReceiptDescriptor.java
<b><font color="red">OrderReceiptLineItem.java</font></b>
OrderReceiptLineItemDescriptor.java
<b><font color="red">OrderReceiptSku.java</font></b>
OrderReceiptSkuDescriptor.java
PurchaseOrder.java
PurchaseOrderDescriptor.java
<b><font color="red">PurchaseOrderLineItem.java</font></b>
PurchaseOrderLineItemDescriptor.java
<b><font color="red">PurchaseOrderSku.java</font></b>
PurchaseOrderSkuDescriptor.java
ReceiptLineItemType.java
ReceiptLineItemTypeDescriptor.java
ReceiptSkuType.java
ReceiptSkuTypeDescriptor.java
Sku.java
SkuDescriptor.java
SkuType.java
SkuTypeDescriptor.java</code-panel>
	
        <p>The developers can now use these generated classes with Castor to 
           (un)marshal the supply chain messages sent by their business partner.</p>
    </section>

    <section title="References">

        <ul>
            <li><a href="sourcegen.html">Castor Source Generator</a></li>
        </ul>
        
    </section>
    
    </body>
</document>
