Example 2: Customizing value usage, and required/optional

# Example 2: Customizing value usage, and required/optional |

JiBX Basics Overview Getting Started Binding Compiler Binding on Load Runtime Extras Building JiBX Maven Contributing License News and Status Support FAQ Mailing Lists Bugs User Comments Sponsors Start from Code Start from Code BindGen Example Code Example 1 Example 2 Example 3 Example 4 Customizations Reference SchemaGen Jibx2Wsdl Examples Customizations Start from Schema Start from Schema CodeGen Schema Datatype Handling Example Code Default Generation Simple Customizations More Customizations Modular Generation Customizations Reference Extensions Reference Binding Definition Binding Tutorial A basic binding Binding extras Structure mapping Collections and arrays Using mappings Advanced binding Method hooks Custom code Precompiled Bindings Definition details Definition contexts Conversions Date/time conversions XML summary <binding> element <include> element <format> element <namespace> element <mapping> element <value> element <structure> element <collection> element Attribute groups Usage API Runtime JavaDocs Subprojects Eclipse Plug-in Introduction Install Usage JiBX/WS Axis2 Usage JiBX/OTA Schema Library | ### Customizing BindGen code generation You can supply a customization file to BindGen to control many aspects of the schema and binding generation. Three separate customization examples are included in the samples/bindgen directory. This page discusses the first customization example (custom1.xml), which demonstrates controlling the values used from a class, how the values are accessed, and whether the values are optional or required. To pass the customization file to BindGen you need to use a '-c' command line parameter, followed by the actual path to the customization file. In the supplied Ant build.xml file the details of this may be a little obscure, due to the use of properties to select the customization and version of the Java code. Here's what the Ant target to run BindGen with customizations would look like if written without using properties:
      <!-- generate custom binding and schema -->
      <target name="custgen1">

        <echo message="Running BindGen tool"/>
        <java classpathref="classpath" fork="true" failonerror="true"
            classname="org.jibx.binding.generator.BindGen">
          <arg value="-c"/>
          <arg value="custom1.xml"/>
          <arg value="-s"/>
          <arg value="src"/>
          <arg value="org.jibx.starter1.Order"/>
        </java>

      </target>
### Field vs. property access, values used, and required vs. optional Here's the text of custom1.xml:
    <custom property-access="true">
      <class name="org.jibx.starter1.Address"
          includes="street1 city state postCode country" requireds="street1 city"/>
      <class name="org.jibx.starter1.Customer"
          requireds="firstName lastName customerNumber"/>
      <class name="org.jibx.starter1.Item" excludes="description"
          requireds="id quantity price"/>
      <class name="org.jibx.starter1.Order"
          requireds="orderNumber customer billTo shipping orderDate"/>
    </custom>
The `property-access="true"` attribute on the root 'custom' element tells BindGen to use property access methods for values, rather than just going directly to the fields in the class. This applies both to finding the values in the first place, and to the generated binding. 'property-access' is a nesting attribute, which means that it can be set on any element of the customizations and applies to all contained elements (and to any classes not represented by elements in the customizations) unless overridden by another setting. This simple example directly specifies each class to be customized with a 'class' element, using fully-qualified class names (including the package). In this case, the attributes on the 'class' elements control the values used from each class, the order of the values in the XML representation, and whether the values are required or optional. The 'includes' attribute lists the value names to be included in the XML representation. The 'requireds' attributes list which of the values are required. The single 'excludes' attribute lists the values (in this case, only one) which are not to be included in the XML representation. Since property access methods are being used in this example, the value names in each list are property names as defined by get/set (or is/set, for `boolean` values) methods. If field access were being used, the value names would be the actual field names (optionally with leading prefixes or trailing suffixes stripped off, as you'll see in a later example). ### Value order BindGen always inspects each class to find the values to be included in the XML representation, either directly accessing the fields of the class or (as controlled by the 'property-access' setting) checking for properties defined by get/set access methods. If no 'class' customization element is used for the class, the order of values in the XML representation is the order in which the values are found by inspecting the class file using the Java Reflection API. With most Java compilers and JVMs this order will match that of the definitions in the source code, but there's no guarantee that this will be the case. The 'includes', 'requireds', and 'optionals' (not used in this case, but just the inverse of 'requireds') attributes of the 'class' customization element all have an additional effect besides their main function: The order of values in the lists controls the order of the corresponding XML elements or attributes. In the case of attributes this doesn't really matter, but order is important for values represented by elements. If an 'includes' attribute is used, only those values present in the list will be used, and they'll be represented in the XML in the same order as in the list. If no 'includes' attribute is present, order is determined in several steps. If a 'requireds' attribute is present, the values present in that list will be the first ones in the XML representation, and they'll be in the same order as the list. If an 'optionals' attribute is present, the values present in that list will be next after those in the 'requireds' list (if any). Any values not included in either a 'requireds' or 'optionals' list (or an 'excludes' list, of course) will then be added in the default Java Reflection order. ### Customized generated schema You can try out the above customization by again using the Ant 'compile' target to compile the sample code, followed by the 'custgen1' target to run BindGen using the above customizations. Here's the resulting schema (again with the longer documentation lines split):
    <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"/>
          <xs:element type="xs:string" name="city"/>
          <xs:element type="xs:string" name="state" minOccurs="0"/>
          <xs:element type="xs:string" name="postCode" minOccurs="0"/>
          <xs:element type="xs:string" name="country" minOccurs="0"/>
        </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">
            <xs:complexType>
              <xs:sequence>
                <xs:element type="xs:string" name="firstName"/>
                <xs:element type="xs:string" name="lastName"/>
              </xs:sequence>
              <xs:attribute type="xs:long" use="required" name="customerNumber"/>
            </xs:complexType>
          </xs:element>
          <xs:element type="tns:address" name="billTo"/>
          <xs:element name="shipping">
            <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:element name="item" minOccurs="0" maxOccurs="unbounded">
            <xs:complexType>
              <xs:sequence>
                <xs:element type="xs:string" name="id"/>
              </xs:sequence>
              <xs:attribute type="xs:int" use="required" name="quantity"/>
              <xs:attribute type="xs:float" use="required" name="price"/>
            </xs:complexType>
          </xs:element>
        </xs:sequence>
        <xs:attribute type="xs:long" use="required" name="orderNumber"/>
        <xs:attribute type="xs:date" use="required" name="orderDate"/>
        <xs:attribute type="xs:date" name="shipDate"/>
        <xs:attribute type="xs:float" name="total"/>
      </xs:complexType>
    </xs:schema>
If you compare this to the Example 1 schema you'll see that the 'includes', 'excludes', and 'requireds' customization attributes have had their intended effects: The 'street2' value is now missing from the 'address' complexType definition (at the top of the listing), since it was left out of the 'includes' list; the 'description' value is now missing from the embedded 'item' definition (near the end of the listing), since it was listed in the 'excludes' list; and many of the elements which previously were defined as optional with `minOccurs="0"` now are required, as are many of the attributes which now have `use="required"`, since the corresponding values were listed in one of the 'requireds' lists. One thing that hasn't changed is the order of the elements and attributes that are still present in the schema. The order of value names in the 'includes' and 'requireds' lists all match the order of the values in the source code, so the order of elements and attributes in the generated schema definition stays the same. Since the element order stayed the same, and nothing new has been added, the schema generated using this customization is compatible with the original default generated schema, in that documents matching this new schema will also match the original schema (but not necessarily the other way around - some components which were optional in the original schema are now required, and the 'street2' and 'description' optional elements in the original schema are not allowed by the customized schema). ### Generated binding Here again, there's not much to be said about the generated binding. It differs from the Example 1 binding in that it uses access methods rather than direct field access, and reflects the changes to required values shown in the schema. Here's a sample of the generated binding:
    <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" get-method="getOrderNumber"
            set-method="setOrderNumber"/>
        <structure get-method="getCustomer" set-method="setCustomer" name="customer">
          <value style="element" name="firstName" get-method="getFirstName"
              set-method="setFirstName"/>
          <value style="element" name="lastName" get-method="getLastName"
              set-method="setLastName"/>
          <value style="attribute" name="customerNumber"
              get-method="getCustomerNumber" set-method="setCustomerNumber"/>
        </structure>
        <structure map-as="tns:address" get-method="getBillTo" set-method="setBillTo"
            name="billTo"/>
        <value style="element" name="shipping" get-method="getShipping"
            set-method="setShipping"/>
        <value style="attribute" name="orderDate" get-method="getOrderDate"
            set-method="setOrderDate"/>
        <structure map-as="tns:address" get-method="getShipTo" set-method="setShipTo"
            usage="optional" name="shipTo"/>
        ...
### Testing the binding The same sample document as used for Example 1 also works with the modified binding and schema. Once you've run the Ant 'compile', 'custgen1', and 'bind' targets you can test the generated binding using the same 'run-base' target as used for Example 1. You can also try out the full 'compile', 'custgen1', 'bind', and 'run-base' sequence by using the Ant target 'custom1'.