Going further with customizations

The Example 2 customizations showed some basic modifications to CodeGen default behavior. The third example goes further, using custom2.xml:

<schema-set prefer-inline="true" generate-all="false" package="org.ota.air"
    repeated-type="array" enumeration-type="simple"
    type-substitutions="xs:integer xs:int xs:decimal xs:float">
  <name-converter strip-prefixes="OTA_"
      strip-suffixes="Type AttributeGroup Group Attributes"/>
  <schema-type type-name="dateTime" java-class="org.joda.time.DateTime"
  <schema-type type-name="date" format-name="LocalDate.default"/>
  <schema-type type-name="time" format-name="LocalTime.local"/>
  <schema name="OTA_AirLowFareSearchRQ.xsd" includes="OTA_AirLowFareSearchRQ">
    <element name="OTA_AirLowFareSearchRQ" class-name="LowFareSearchRequest">
      <element path="**" name="AlternateLocationInfo" ignore="true"/>
      <element path="**" name="SpecificFlightInfo" ignore="true"/>
      <element path="**" name="ProcessingInfo" ignore="true"/>
  <schema name="OTA_AirLowFareSearchRS.xsd" includes="OTA_AirLowFareSearchRS">
    <element name="OTA_AirLowFareSearchRS" class-name="LowFareSearchResponse"/>
  <schema name="OTA_AirCommonTypes.xsd">
    <complexType name="FareType">
      <element path="**" name="Taxes" ignore="true"/>
      <element path="**" name="Fees" ignore="true"/>
      <element path="**" name="FareConstruction" ignore="true"/>
      <element path="**" name="UnstructuredFareCalc" ignore="true"/>
    <complexType name="FareInfoType">
      <element path="**" name="Date" ignore="true"/>
      <element path="**" name="FareInfo" ignore="true"/>
    <complexType name="PricedItinerariesType">
      <attribute path="**" name="OriginDestinationRefNumber"
    <complexType name="PricedItineraryType">
      <element path="**" name="AirItinerary" ignore="true"/>
      <element path="**" name="AirItineraryPricingInfo"
      <element path="**" name="Notes" ignore="true"/>
      <element path="**" name="TicketingInfo" ignore="true"/>
    <complexType name="AirItineraryPricingInfoType">
      <element path="**" name="PTC_FareBreakdowns" ignore="true"/>
    <complexType name="TravelerInformationType">
      <element path="**" name="AirTraveler" ignore="true"/>
    <complexType name="TravelerInfoSummaryType">
      <element path="**" name="PriceRequestInformation" ignore="true"/>
  <schema name="OTA_AirPreferences.xsd">
    <complexType name="AirSearchPrefsType">
      <element path="**" name="VendorPref" ignore="true"/>
      <element path="**" name="FlightTypePref" ignore="true"/>
      <element path="**" name="EquipPref" ignore="true"/>
      <element path="**" name="CabinPref" ignore="true"/>
      <element path="**" name="TicketDistribPref" ignore="true"/>
  <schema name="OTA_CommonTypes.xsd" excludes="ConnectionType">
    <complexType name="SourceType">
      <element path="**" name="Position" ignore="true"/>
      <element path="**" name="BookingChannel" ignore="true"/>

These customizations effect both the form of the generated code and the actual schema structure used to drive the code and binding generation.

On the root <schema-set> element, the repeated-type="array" attribute changes the representation of repeated values from the default Java 5 typed lists (inappropriately called "generics") to arrays, and the enumeration-type="simple" attribute changes the representation of enumerations from the default Java 5 enum format to custom type-safe enumerations. Together these changes make the generated code compatible with pre-Java 5 JDKs (you could also do this by using repeated-type="list" in place of repeated-type="array", generating simple untyped lists).

The type-substitutions="xs:integer xs:int xs:decimal xs:float" attribute gives pairs of types, with the second type in each pair substituted for the first wherever referenced in the schema definitions. This allows you to easily replace a simple type with an awkward Java representation (such as xs:integer, which uses java.math.BigInteger) with one which has a more convenient representation (such as xs:int, represented by an int primitive for a required value or a java.lang.Integer for an optional value). Naturally, you need to be careful when using this type of substitution that you maintain compatibility for the documents you're going to be using.

The first group of child elements within the root <schema-set> element (<name-converter>, <class-decorator>, and several <schema-type> elements) configures extensions to the standard code generation. The <name-converter> element modifies name handling, in this case stripping some leading and trailing text from XML names before they're converted to Java names. The <class-decorator> element adds some useful support methods for each collection value in the generated classes, using an extension class provided as part of the JiBX distribution. You can also write and use your own code generation extensions in the same way. Finally, the <schema-type> elements change the classes and/or conversion methods used for built-in schema types. In this case the changes are to use Joda date/time classes rather than Java standard classes for date/time values, with the first customization naming specific serializer/deserializer methods and the other two just referencing predefined formats.

The rest of the customizations dig down into specific schema definitions and either eliminate components which are not needed for the sample documents (by specifically including or excluding particular type definitions from a schema, or by telling CodeGen to ignore specific elements embedded within a schema definition) or specify a particular Java class name or value name to be used for a component. The ignored elements will be accepted when unmarshalling XML documents but their content will not be processed, and they will never be generated when marshalling XML documents.

Generated code

Run the 'custgen2' target and see the gen/src directory (or use the 'custom2' target to generate and compile the code, run the binding compiler, and finally run a supplied test program which roundtrips the sample documents from the samples directory). The number of generated classes is now reduced to just 15 top-level classes and 35 inner classes, or a total of 50, while still maintaining all the components needed for the sample documents. The generated class names have also been simplified by eliminating the repetitive name suffixes used in the schemas, and usage has been improved by replacing java.math.BigDecimal and java.math.BigInteger references with java.lang.Float and java.lang.Integer references, respectively.

Here's a sample of the generated code (reformated for a reasonable page width, and leaving out the methods), showing the same classes as in the Example 2 generated code (with the significant differences shown in bold):

 The Low Fare Search Response message contains a number of 'Priced Itinerary'
 options. Each includes:
 - A set of available flights matching the client's request.
 - Pricing information including taxes and full fare breakdown for each passenger
 - Ticketing information
 - Fare Basis Codes and the information necessary to make a rules entry.
 This message contains similar information to a standard airline CRS or GDS Low
 Fare Search Response message.
 * Schema fragment(s) for this class:
 * <pre>
 * &lt;xs:element xmlns:ns="http://www.opentravel.org/OTA/2003/05"
       xmlns:xs="http://www.w3.org/2001/XMLSchema" name="OTA_AirLowFareSearchRS">
 *   &lt;xs:complexType>
 *     &lt;xs:sequence>
 *       &lt;xs:choice>
 *         &lt;xs:sequence>
 *           &lt;xs:element type="ns:SuccessType" name="Success"/>
 *           &lt;xs:element type="ns:WarningsType" name="Warnings"
 *             &lt;!-- Reference to inner class Warnings -->
 *           &lt;/xs:element>
 *           &lt;xs:element type="ns:PricedItinerariesType"
 *         &lt;/xs:sequence>
 *         &lt;xs:element type="ns:ErrorsType" name="Errors"/>
 *       &lt;/xs:choice>
 *     &lt;/xs:sequence>
 *     &lt;xs:attributeGroup ref="ns:OTA_PayloadStdAttributes"/>
 *   &lt;/xs:complexType>
 * &lt;/xs:element>
 * &lt;xs:complexType xmlns:ns="http://www.opentravel.org/OTA/2003/05"
       xmlns:xs="http://www.w3.org/2001/XMLSchema" name="SuccessType"/>
 * &lt;xs:complexType xmlns:ns="http://www.opentravel.org/OTA/2003/05"
       xmlns:xs="http://www.w3.org/2001/XMLSchema" name="PricedItinerariesType">
 *   &lt;xs:sequence>
 *     &lt;xs:element name="PricedItinerary" maxOccurs="unbounded">
 *       &lt;!-- Reference to inner class PricedItinerary -->
 *     &lt;/xs:element>
 *   &lt;/xs:sequence>
 * &lt;/xs:complexType>
 * &lt;xs:complexType xmlns:ns="http://www.opentravel.org/OTA/2003/05"
       xmlns:xs="http://www.w3.org/2001/XMLSchema" name="ErrorsType">
 *   &lt;xs:sequence>
 *     &lt;xs:element type="ns:ErrorType" name="Error" maxOccurs="99">
 *       &lt;!-- Reference to inner class _Error -->
 *     &lt;/xs:element>
 *   &lt;/xs:sequence>
 * &lt;/xs:complexType>
 * </pre>
public class LowFareSearchResponse
    private int choiceSelect = -1;
    private static final int SUCCESS_CHOICE = 0;
    private static final int ERRORS_CHOICE = 1;
    private Warnings warnings;
    private PricedItinerary[] pricedItineraries;
    private _Error[] errors;
    private PayloadStd payloadStd;
     *  Itinerary with pricing information.
     * Schema fragment(s) for this class:
     * <pre>
     * &lt;xs:element xmlns="http://www.opentravel.org/OTA/2003/05"
           xmlns:xs="http://www.w3.org/2001/XMLSchema" name="PricedItinerary"
     *   &lt;xs:complexType>
     *     &lt;xs:complexContent>
     *       &lt;xs:extension base="PricedItineraryType">
     *         &lt;xs:attribute type="xs:int" use="optional"
     *       &lt;/xs:extension>
     *     &lt;/xs:complexContent>
     *   &lt;/xs:complexType>
     * &lt;/xs:element>
     * &lt;xs:complexType xmlns="http://www.opentravel.org/OTA/2003/05"
           xmlns:xs="http://www.w3.org/2001/XMLSchema" name="PricedItineraryType">
     *   &lt;xs:sequence>
     *     &lt;xs:element type="AirItineraryPricingInfoType"
               name="AirItineraryPricingInfo" minOccurs="0">
     *       &lt;!-- Reference to inner class PricingInfo -->
     *     &lt;/xs:element>
     *   &lt;/xs:sequence>
     *   &lt;xs:attribute type="xs:string" use="required"
     * &lt;/xs:complexType>
     * </pre>
    public static class PricedItinerary
        private PricingInfo pricingInfo;
        private String sequenceNumber;
        private Integer refNumber;

The differences from the generated code shown for the last example are the names used for the top-level class and some of the other classes, arrays in place of typed lists, the names of some of the fields and the simplified form of the PricedItinerary class (which only includes three fields rather than six, due to components eliminated by customizations), and the use of a java.lang.Integer in place of a java.math.BigInteger for the referemce number within the PricedItinerary class.

Next: Example 4: Modular code generation