Example code and binding

Here's the same set of classes previously used as an example for the binding generation tool, all from the example package:

public class Customer {
    private Name name;
    private Address address;
    private Order[] orders;
}

public class Name {
    private String firstName;
    private String lastName;
}

public class Address {
    private String street;
    private String city;
    private String state;
    private Integer zip;
}

import java.math.BigDecimal;
import java.sql.Date;

public class Order {
    private Date date;
    private BigDecimal amount;
}

Here's the binding generated in the earlier example for these classes, again slightly reformatted to fit the page width:

<?xml version="1.0" encoding="UTF-8"?>
<binding forwards="false" value-style="attribute">
  <mapping class="example.Customer" name="customer">
    <structure field="name" usage="optional" name="name">
      <value style="element" name="first-name" field="firstName" usage="optional"/>
      <value style="element" name="last-name" field="lastName" usage="optional"/>
    </structure>
    <structure field="address" usage="optional" name="address">
      <value style="element" name="street" field="street" usage="optional"/>
      <value style="element" name="city" field="city" usage="optional"/>
      <value style="element" name="state" field="state" usage="optional"/>
      <value name="zip" field="zip" usage="optional"/>
    </structure>
    <structure field="orders" usage="optional"
        marshaller="org.jibx.extras.TypedArrayMapper"
        unmarshaller="org.jibx.extras.TypedArrayMapper"></structure>
  </mapping>
  <mapping class="example.Order" name="order">
    <value name="date" field="date" usage="optional"/>
    <value name="amount" field="amount" usage="optional"/>
  </mapping>
</binding>

Running the schema generator

I'll assume that the above set of classes have been compiled into the current directory, that the binding file is binding.xml, also in the current directory, and that the jibx-genschema.jar has been copied into the lib directory of the JiBX installation located at /home/dennis/jibx. Then to generate a schema for these classes I just need to run the following:

java -jar /home/dennis/jibx/lib/jibx-genschema.jar binding.xml

This generates an output binding.xsd in the current directory, with the following content (reformatted where necessary to fit the page width):

<?xml version="1.0" encoding="UTF-8"?>
<schema elementFormDefault="qualified"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns="http://www.w3.org/2001/XMLSchema">

  <!-- Created from mapping for class example.Customer -->
  <element name="customer">
    <complexType>
      <sequence>
        <element name="name" minOccurs="0">
          <complexType>
            <sequence>
              <element minOccurs="0" name="first-name" type="xsd:string"/>
              <element minOccurs="0" name="last-name" type="xsd:string"/>
            </sequence>
          </complexType>
        </element>
        <element name="address" minOccurs="0">
          <complexType>
            <sequence>
              <element minOccurs="0" name="street" type="xsd:string"/>
              <element minOccurs="0" name="city" type="xsd:string"/>
              <element minOccurs="0" name="state" type="xsd:string"/>
            </sequence>
            <attribute name="zip" type="xsd:int"/>
          </complexType>
        </element>
        <!-- No mapping for structure at (line 14, col 154, in binding_xml) -->
        <!-- Fill in details of content here to complete schema -->
      </sequence>
    </complexType>
  </element>

  <!-- Created from mapping for class example.Order -->
  <element name="order">
    <complexType>
      <sequence/>
      <attribute name="date" type="xsd:date"/>
      <attribute name="amount" type="xsd:decimal"/>
    </complexType>
  </element>
</schema>

Schema generation problems

Serious problems in the schema generation result in failures, with error information printed to the console. Cases where the schema generator simply doesn't have enough information to fill in all the details of the schema are handled by adding comments to the generated schema, as can be seen in the above example. Here the schema generator doesn't know how to handle one component of the customer element, and the comment lines in the schema describe the problem:

...
        <!-- No mapping for structure at (line 14, col 154, in binding_xml) -->
        <!-- Fill in details of content here to complete schema -->
...

The comments refer back to the source of the binding definition, in this case referencing the line:

...
    <structure field="orders" usage="optional"
        marshaller="org.jibx.extras.TypedArrayMapper"
        unmarshaller="org.jibx.extras.TypedArrayMapper"></structure>
...

The problem with this part of the binding definition is just that the schema generator doesn't know how to represent the XML processed using a custom marshaller/unmarshaller. With a little study of the documentation for the org.jibx.extras.TypedArrayMapper class I can see that it's simply going to use the mapping for the base class of the array repeatedly (once for each item in the array). Knowing this I can complete the generated schema, replacing the two comment lines with a real schema representation:

...
        <element minOccurs="0" maxOccurs="unbounded" ref="order"/>
...

Once I've made this change the schema is complete and ready to be used.