BindGen default code generation

You can use the Ant 'compile' target to compile the sample code, followed by the 'bindgen' target to run BindGen on the Java 5 version of the code with default settings. Here's the actual 'bindgen' target from the build.xml:

  <!-- generate default binding and schema -->
  <target name="bindgen">
  
    <echo message="Running BindGen tool"/>
    <java classpathref="classpath" fork="true" failonerror="true"
        classname="org.jibx.binding.generator.BindGen">
      <arg value="-s"/>
      <arg value="src"/>
      <arg value="org.jibx.starter1.Order"/>
    </java>
    
  </target>

This passes the '-s' parameter to BindGen with the value 'src' to tell it the path to find the source code for the classes to be included in the XML representation. If you don't supply the source code BindGen can get all the information it needs from the Java class files (which must be on the classpath used for running BindGen), but without access to the source code Javadocs it won't be able to generate schema documentation. The third argument value tells BindGen to use the org.jibx.starter1.Order class as a root for generating the binding and schema. You can specify as many root classes as you want when running BindGen, but must have at least one - otherwise there's nothing for BindGen to generate!

Generated schema

BindGen derives the schema namespace(s) from the Java package name(s), in this case converting the package name 'org.jibx.starter1' to the namespace URI 'http://jibx.org/starter1'. The generated binding file name is just binding.xml, and the generated schema name is taken from the last part of the namespace URI: starter1.xsd. Here's the resulting schema (with the longer documentation lines split for readability):

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:tns="http://jibx.org/starter1"
    elementFormDefault="qualified" targetNamespace="http://jibx.org/starter1">
  <xs:complexType name="address">
    <xs:annotation>
      <xs:documentation>Address information.</xs:documentation>
    </xs:annotation>
    <xs:sequence>
      <xs:element type="xs:string" name="street1" minOccurs="0">
        <xs:annotation>
          <xs:documentation>First line of street information (required).</xs:documentation>
        </xs:annotation>
      </xs:element>
      <xs:element type="xs:string" name="street2" minOccurs="0">
        <xs:annotation>
          <xs:documentation>Second line of street information (optional).</xs:documentation>
        </xs:annotation>
      </xs:element>
      <xs:element type="xs:string" name="city" minOccurs="0"/>
      <xs:element type="xs:string" name="state" minOccurs="0">
        <xs:annotation>
          <xs:documentation>State abbreviation (required for the U.S. and Canada, optional
          otherwise).</xs:documentation>
        </xs:annotation>
      </xs:element>
      <xs:element type="xs:string" name="postCode" minOccurs="0">
        <xs:annotation>
          <xs:documentation>Postal code (required for the U.S. and Canada, optional
          otherwise).</xs:documentation>
        </xs:annotation>
      </xs:element>
      <xs:element type="xs:string" name="country" minOccurs="0">
        <xs:annotation>
          <xs:documentation>Country name (optional, U.S. assumed if not 
          supplied).</xs:documentation>
        </xs:annotation>
      </xs:element>
    </xs:sequence>
  </xs:complexType>
  <xs:element type="tns:order" name="order"/>
  <xs:complexType name="order">
    <xs:annotation>
      <xs:documentation>Order information.</xs:documentation>
    </xs:annotation>
    <xs:sequence>
      <xs:element name="customer" minOccurs="0">
        <xs:complexType>
          <xs:sequence>
            <xs:element type="xs:string" name="firstName" minOccurs="0">
              <xs:annotation>
                <xs:documentation>Personal name.</xs:documentation>
              </xs:annotation>
            </xs:element>
            <xs:element type="xs:string" name="lastName" minOccurs="0">
              <xs:annotation>
                <xs:documentation>Family name.</xs:documentation>
              </xs:annotation>
            </xs:element>
            <xs:element type="xs:string" name="middleName" minOccurs="0" maxOccurs="unbounded"/>
          </xs:sequence>
          <xs:attribute type="xs:long" use="required" name="customerNumber"/>
        </xs:complexType>
      </xs:element>
      <xs:element type="tns:address" name="billTo" minOccurs="0">
        <xs:annotation>
          <xs:documentation>Billing address information.</xs:documentation>
        </xs:annotation>
      </xs:element>
      <xs:element name="shipping" minOccurs="0">
        <xs:simpleType>
          <xs:annotation>
            <xs:documentation>Supported shipment methods. The "INTERNATIONAL" shipment methods
            can only be used for orders with shipping addresses outside the U.S., and one of these
            methods is required in this case.</xs:documentation>
          </xs:annotation>
          <xs:restriction base="xs:string">
            <xs:enumeration value="STANDARD_MAIL"/>
            <xs:enumeration value="PRIORITY_MAIL"/>
            <xs:enumeration value="INTERNATIONAL_MAIL"/>
            <xs:enumeration value="DOMESTIC_EXPRESS"/>
            <xs:enumeration value="INTERNATIONAL_EXPRESS"/>
          </xs:restriction>
        </xs:simpleType>
      </xs:element>
      <xs:element type="tns:address" name="shipTo" minOccurs="0">
        <xs:annotation>
          <xs:documentation>Shipping address information. If missing, the billing address is also
          used as the shipping address.</xs:documentation>
        </xs:annotation>
      </xs:element>
      <xs:element name="item" minOccurs="0" maxOccurs="unbounded">
        <xs:complexType>
          <xs:sequence>
            <xs:element type="xs:string" name="id" minOccurs="0">
              <xs:annotation>
                <xs:documentation>Stock identifier. This is expected to be 12 characters in
                length, with two leading alpha characters followed by ten decimal
                digits.</xs:documentation>
              </xs:annotation>
            </xs:element>
            <xs:element type="xs:string" name="description" minOccurs="0">
              <xs:annotation>
                <xs:documentation>Text description of item.</xs:documentation>
              </xs:annotation>
            </xs:element>
          </xs:sequence>
          <xs:attribute type="xs:int" use="required" name="quantity">
            <xs:annotation>
              <xs:documentation>Number of units ordered.</xs:documentation>
            </xs:annotation>
          </xs:attribute>
          <xs:attribute type="xs:float" use="required" name="price">
            <xs:annotation>
              <xs:documentation>Price per unit.</xs:documentation>
            </xs:annotation>
          </xs:attribute>
        </xs:complexType>
      </xs:element>
    </xs:sequence>
    <xs:attribute type="xs:long" use="required" name="orderNumber"/>
    <xs:attribute type="xs:date" name="orderDate">
      <xs:annotation>
        <xs:documentation>Date order was placed with server.</xs:documentation>
      </xs:annotation>
    </xs:attribute>
    <xs:attribute type="xs:date" name="shipDate">
      <xs:annotation>
        <xs:documentation><![CDATA[Date order was shipped. This will be
        <code>null</code> if the order has not yet shipped.]]></xs:documentation>
      </xs:annotation>
    </xs:attribute>
    <xs:attribute type="xs:float" name="total"/>
  </xs:complexType>
</xs:schema>

BindGen defaults to a mixed schema style, where type definitions are inlined if they're only used in one place. In this case that results in only two global complexType definitions: 'address' for the Address class (needed because there are two references to Address within the Order class) and 'order' for the Order class. The remaining Java classes are represented by local (i.e., nested) type definitions embedded within the 'order' type: Customer and Item as complexType definitions, and Shipping as a simpleType definition. The only global element definition is for the 'order' element, since that's the one class specified as input to BindGen.

Simple values of limited length (including Java primitive types, as well as date/time variations) are represented by default using XML attributes, while elements are used for any structured data. Elements are also used for java.lang.String values, since there's no limit on the length of a string and very long attribute values are generally discouraged in XML. Primitive values are treated as required by default, while object values are treated as optional (since a null value can easily be used to indicate that an object value is missing, while primitives have no such marker).

As you can see in the above listing, BindGen automatically creates schema documentation taken from Java source code Javadocs. By default, BindGen examines the field definitions within each class to find the data to be included in the XML representation of that class, and the Javadocs associated with the fields are the source of the schema documentation for individual elements and attributes. Schema documentation for generated complexType definitions is taken directly from the corresponding class-level Javadocs. If the Javadoc includes any HTML or XML tags it's wrapped in a CDATA section, as you can see for the 'shipData' attribute near the end of the listing.

Generated binding

There's not a lot to be said about the generated binding, except that it uses direct field access for values (rather than get/set access methods) and matches the schema in terms of which values are optional and which required. Here's the generated binding in full:

<binding xmlns:tns="http://jibx.org/starter1" name="binding" package="org.jibx.starter1">
  <namespace uri="http://jibx.org/starter1" default="elements"/>
  <mapping abstract="true" type-name="tns:order" class="org.jibx.starter1.Order">
    <value style="attribute" name="orderNumber" field="orderNumber"/>
    <structure field="customer" usage="optional" name="customer">
      <value style="attribute" name="customerNumber" field="customerNumber"/>
      <value style="element" name="firstName" field="firstName" usage="optional"/>
      <value style="element" name="lastName" field="lastName" usage="optional"/>
      <collection field="middleNames" usage="optional" create-type="java.util.ArrayList">
        <value name="middleName" type="java.lang.String"/>
      </collection>
    </structure>
    <structure map-as="tns:address" field="billTo" usage="optional" name="billTo"/>
    <value style="element" name="shipping" field="shipping" usage="optional"/>
    <structure map-as="tns:address" field="shipTo" usage="optional" name="shipTo"/>
    <collection field="items" usage="optional" create-type="java.util.ArrayList">
      <structure type="org.jibx.starter1.Item" name="item">
        <value style="element" name="id" field="id" usage="optional"/>
        <value style="element" name="description" field="description" usage="optional"/>
        <value style="attribute" name="quantity" field="quantity"/>
        <value style="attribute" name="price" field="price"/>
      </structure>
    </collection>
    <value style="attribute" name="orderDate" field="orderDate" usage="optional"/>
    <value style="attribute" name="shipDate" field="shipDate" usage="optional"/>
    <value style="attribute" name="total" field="total" usage="optional"/>
  </mapping>
  <mapping class="org.jibx.starter1.Order" name="order">
    <structure map-as="tns:order"/>
  </mapping>
  <mapping abstract="true" type-name="tns:address" class="org.jibx.starter1.Address">
    <value style="element" name="street1" field="street1" usage="optional"/>
    <value style="element" name="street2" field="street2" usage="optional"/>
    <value style="element" name="city" field="city" usage="optional"/>
    <value style="element" name="state" field="state" usage="optional"/>
    <value style="element" name="postCode" field="postCode" usage="optional"/>
    <value style="element" name="country" field="country" usage="optional"/>
  </mapping>
</binding>

Testing the binding

The examples/bindgen directory includes a sample document, data1.xml, matching the default generated schema. Here's the listing:

<order orderNumber="12345678" orderDate="2008-10-18" shipDate="2008-10-22"
    xmlns="http://jibx.org/starter1">
  <customer customerNumber="5678">
    <firstName>John</firstName>
    <lastName>Smith</lastName>
  </customer>
  <billTo>
    <street1>12345 Happy Lane</street1>
    <city>Plunk</city>
    <state>WA</state>
    <postCode>98059</postCode>
    <country>USA</country>
  </billTo>
  <shipping>PRIORITY_MAIL</shipping>
  <shipTo>
    <street1>333 River Avenue</street1>
    <city>Kirkland</city>
    <state>WA</state>
    <postCode>98034</postCode>
    <country>USA</country>
  </shipTo>
  <item quantity="1" price="5.99">
    <id>FA9498349851</id>
  </item>
  <item quantity="2" price="9.50">
    <id>GC1234905049</id>
  </item>
  <item quantity="1" price="8.95">
    <id>AX9300048820</id>
  </item>
</order>

Once you've run the Ant 'compile', 'bindgen', and 'bind' targets you can test the generated binding using 'run-base' (which runs the supplied test program org.jibx.starter1.Test to read in the order document, compute the order total, and write the document back out with total included as out1.xml). You can also try out the full 'compile', 'bindgen', 'bind', and 'run-base' sequence by using the Ant target 'full'.