<?xml version="1.0"?>

<document url="http://castor.org/srcgen-binding.xml">

  <properties>
    <title>Castor XML - Code generator bindings</title>
    <author email="werner DOT guttmann AT gmx DOT net">Werner Guttmann</author>
    <abstract>
       Describes the binding file available with the Castor XML code generator.
    </abstract>
    <status>Draft</status>
  </properties>

  <body>

    <title>Castor XML - Code generator bindings</title>

    <section title="Introduction">

		<p>Blah</p>

    </section>

    <section title="Binding File">
       <p>It may appear that the default binding used to generate the Java Object Model from an XML schema doesn't
       meet one's expectation. For instance, the default binding won't deal with naming collision problems that can appear since XML Schema allows
       an element declaration and a complexType definition to both share the same name. From a Java standpoint, it will result in the creation of
       two classes with the same qualified name: the second class generated will simply overwrite the first one.
       Another example is when one user wants to change the default datatype binding provided by Castor or to add validation rules by implementing his own validator
       and passing it to the SourceGenerator.</p>

       <p>The Binding declaration is an XML based language that allows the user to define such control on the generated classes.
       The aim of this section is to provide an overview of the binding file as well as a definition of the several XML components used to define this binding file.
       A more in-depth presentation  will be available soon in the
      <a href="./SourceGeneratorUser.pdf">Source Generator User Document(PDF).</a></p>

      <section title="&lt;binding> element">
         <code-panel>
&lt;binding
    defaultBindingType = (element|type)>
    (include*,
     package*,
     namingXML?,
     elementBinding*,
     attributeBinding,
     complexTypeBinding,
     groupBinding)
&lt;/binding></code-panel>
          <p>The binding element is the root element and contains the binding information. The attribute <code>defaultBindingType</code> controls the
          <a href="#Class-Creation/Mapping">Class creation type</a></p>
          <tip>
             Be careful when using <b>defaultBindingType</b> attribute
             as it will override the binding type specified in the
             <i>castorbuilder.properties</i> file.
          </tip>
      </section>

      <section title="&lt;include> element">
         <code-panel>
&lt;include
    URI = xsd:anyURI/></code-panel>
          <ul>
             <li><b>URI:</b>The URI of the binding file to include.</li>
          </ul>
          <p>This element allows one to include the binding declaration defined in another file. This allows re-usability of Binding files defined for various
          XML Schemas.</p>
      </section>

      <section title="&lt;package> element">
         <code-panel>
&lt;package>
    name = xsd:string
    (namespace|schemaLocation) = xsd:string>
&lt;/package></code-panel>
          <ul>
             <li><b>name:</b>A fully qualified java package name.</li>
             <li><b>namespace:</b>An XML namespace that will be mapped to the package name defined by the <i>name</i> element.</li>
             <li><b>schemaLocation:</b>A URL that locates the schema to be mapped to the package name defined by the <i>name</i> element.</li>
          </ul>
          <p>The <i>targetNamespace</i> attribute of an XML Schema identifies the namespace in which the XML language is defined. Such language namespace is defined
          in the java language as package declaration. The &lt;package/> element allows you to define the mapping between an XML namespace and a Java package.
          Moreover XML Schema allows you to factorize the definition of an XML Schema identified by a unique namespace by including several XML Schemas to build
          one XML Schema using the &lt;xsd:include/> element (Please make sure you understand the difference between &lt;xsd:include/> and &lt;xsd:import/>).
          &lt;xsd:include/> relies on the URI of the included XML schema and it can be needed to keep the structure hierarchy defined in XML Schema in the Java
          package generated. Thus the binding file allows to define the mapping between a schemaLocation attribute and a Java package.</p>
      </section>

     <section title="&lt;namingXML> element">
        <code-panel>
&lt;namingXML>
   (elementName,complexTypeName,modelGroupName)
&lt;/namingXML>

&lt;elementName|complexTypeName|modelGroupName>
    (prefix?, suffix?) = xsd:string
&lt;/elementName|complexTypeName|modelGroupName></code-panel>
         <ul>
            <li><b>prefix:</b>The prefix to add to the names of the generated classes.</li>
            <li><b>suffix:</b>The suffix to append to the the names of the generated classes</li>
         </ul>
         <p>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 which
         results in name collisions when generated the sources. Defining a binding for every element and complexType that share the same name is sometimes not
         a convenient solution (for instance the BPML XML Schema or the UDDI v2.0 XML Schema use the same names for top-level complexTypes and top-level elements).
         The aim of the &lt;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.<br/>
         <b>Note:</b>It is not possible to control the names of the classes generated to represent nested model groups (all, choice, sequence).</p>
      </section>

       <section title="&lt;componentBinding> element">
         <code-panel>
&lt;elementBinding|attributeBinding|complexTypeBinding|groupBinding
    name = xsd:string>
   ((java-class|interface|member),
     elementBinding*,
     attributeBinding*,
     complexTypeBinding*,
     groupBinding*)
&lt;/elementBinding|attributeBinding|complexTypeBinding|groupBinding></code-panel>
         <ul>
            <li><b>name:</b>The name of the XML schema component for which we are defining a binding.</li>
         </ul>
         <p>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 (&lt;java-class/>, &lt;interface> or &lt;member>) will determine the type of binding one is defining.
         Please note that defining a &lt;java-class> binding on an XML Schema attribute will have absolutely no <b>effect</b>.</p>
         <p>The binding file being 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 throught the <tt>name</tt> attribute.</p>
         <p>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 <a href="http://www.w3.org/TR/xpath">XPath</a><sup>3</sup>.
         The grammar of that language can be defined by the following BNF:</p>
         <pre>
            [1]Path         ::= LocationPath('/'LocationPath)*
            [2]LocationPath ::= (Complex|ModelGroup|Attribute|Element)
            [3]Complex      ::= 'complexType:'<a href="http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/datatypes.html#NCName">NCName</a>
            [4]ModelGroup   ::= 'group:'<a href="http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/datatypes.html#NCName">NCName</a>
            [5]Attribute    ::= '@'<a href="http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/datatypes.html#NCName">NCName</a>
            [6]Element      ::= <a href="http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/datatypes.html#NCName">NCName</a>
         </pre>
         <p>The second option to identify a XML Schema Component is to embed its binding definition inside its parent binding definition.</p>
         <p>For instance, the following
         binding definition will be equivalent and will identify the element 'foo' defined in the top-level complexType 'fooType'.</p>

         <code-panel>
&lt;elementBinding name="complexType:fooType/foo>
   &lt;member name="MyFoo" handler="mypackage.myHandler"/>
&lt;/elementBinding>

&lt;complexTypeBinding name="fooType">
   &lt;elementBinding name="foo>
      &lt;member name="MyFoo" handler="mypackage.myHandler"/>
   &lt;/elementBinding>
&lt;complexTypeBinding></code-panel>
       </section>

       <section title="&lt;java-class> element">
         <code-panel>
&lt;java-class
    name? = xsd:string
    package? = xsd:string
    final? = xsd:boolean
    abstract? = xsd:boolean
    equals? = xsd:boolean
    bound? = xsd:boolean >
    (implements*,extends?)
&lt;/java-class></code-panel>
		   
         <p>This element defines all the options for the class to be generated, including 
			common properties such as class name, package name, etc.</p>
		   
         <ul>
            <li><b>name:</b>The name of the class that will be generated.</li>
            <li><b>package:</b>The package of the class to be generated. if set, this option overrides the mapping defined in the &lt;package/> element.</li>
            <li><b>final:</b>If true, the generated class will be final.</li>
            <li><b>abstract:</b>If true, the generated class will be abstract.</li>
            <li><b>equals:</b>If true, the generated class will implement the equals method.</li>
            <li><b>bound:</b>If true, the generated class will implement the bound properties.</li>
         </ul>

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

         <code-panel>
   &lt;elementBinding name=&quot;/test&quot;&gt;
      &lt;java-class name=&quot;CustomTest&quot; final=&quot;true&quot;/&gt;
   &lt;/elementBinding&gt;</code-panel>
		   
		   <p>In addition to above properties, it is possible to define that the class generated 
			  will extend a class given and/or implement one or more interfaces.</p>
		   
		   <p>For instance, the following binding definition instructs the source generator
			  to generate a class <tt>TestWithInterface</tt> that implements the interface
			  <tt>org.castor.sample.SomeInterface</tt> in addition to 
			  <tt>java.io.Serializable</tt>.</p>

         <code-panel>
   &lt;elementBinding name=&quot;/test&quot;&gt;
      &lt;java-class name=&quot;TestWithInterface&quot;&gt;
         &lt;implements&gt;org.castor.sample.SomeInterface&lt;/implements&gt;
      &lt;/java-class&gt;
   &lt;/elementBinding&gt;</code-panel>
		   
		   <p>The subsequent binding definition instructs the source generator
			  to generate a class <tt>TestWithExtendsAndInterface</tt> that implements the interface
			  <tt>org.castor.sample.SomeInterface</tt> in addition to 
			  <tt>java.io.Serializable</tt>, and extends from (a possible) abstract base class
			  <tt>SomeAbstractBaseClass</tt>.</p>

           <code-panel>
   &lt;elementBinding name=&quot;/test&quot;&gt;
      &lt;java-class name=&quot;TestWithExtendsAndInterface&quot;&gt;
         &lt;extends&gt;org.castor.sample.SomeAbstractBaseClass&lt;/extends&gt;
         &lt;implements&gt;org.castor.sample.SomeInterface&lt;/implements&gt;
      &lt;/java-class&gt;
   &lt;/elementBinding&gt;</code-panel>

		   <p>The generated class <tt>SomeAbstractBaseClass</tt> will have a class signature
		      identical to ...</p>
		   
		   <code-panel>
   ...

   public class TestWithExtendsAndInterface
      extends SomeAbstractBaseClass
      implements SomeInterface, java.io.Serializable {
      ...
		   </code-panel>
		   		   
       </section>


       <section title="&lt;member> element">
         <code-panel>
 &lt;member
  name? = xsd:string
  java-type? = xsd:string
  wrapper? = xsd:boolean
  handler? = xsd:string
  collection? = (array|vector|arraylist|hashtable|collection|odmg|set|map|sortedset)
  validator? = xsd:string/></code-panel>
         <ul>
            <li><b>name:</b>The name of the class member that will be generated.</li>
            <li><b>java-type:</b>the fully qualified name of the java type.</li>
            <li><b>wrapper:</b>If true, a wrapper object will be generated in case the java type is a java primitive.</li>
            <li><b>handler:</b>The fully qualified name of the FieldHandler to use.</li>
            <li><b>collection:</b>If the schema component can occur more than once then this attribute allows to specify the collection to use
            to represent the component in Java.</li>
            <li><b>validator:</b>The fully qualified name of the FieldValidator to use.</li>
         </ul>
            <p>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 Marshalling framework in handling that member. Defining a validator is also
            possible. The names given for the validator and the fieldHandler must be fully qualified.</p>
       </section>

       <section title="Not implemented yet">
		   
		   <section title="&lt;enumBinding&gt;">

			  <code-panel>
	 &lt;enumBinding>
		(enumClassName|enumMemberName)
	 &lt;/enumBinding></code-panel>
			   
			  <p>This element will allow more control on the type safe enumerations 
				 generated to represent an XML Schema simpleType enumeration</p>

   		   </section>
		   
		   <section title="&lt;javadoc&gt;">

			   <p>The &gt;javadoc&gt; element will allow one to enter the necessary javadoc 
				  that represents the generated classes or members.</p>
			   
		   </section>
			   
		   <section title="&lt;interface> element">
			   
			 <code-panel>
	&lt;interface&gt;
		name = xsd:string
	&lt;/interface&gt;</code-panel>
			 <ul>
				<li><b>name:</b>The name of the interface that will be generated.</li>
			 </ul>
			   
			 <p>This element specifies the name of the interface to be generated for an 
				XML schema component.</p>
	
		   </section>

		   
       </section>

    </section>

	<section title="Non-trivial real world example">
		
		<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>

  </body>

</document>

