CodeGen default code generation

You can use the Ant 'codegen' target to generate code from the schema using the CodeGen default settings. Here's the actual 'codegen' target from the build.xml:

  <!-- generate using default settings -->
  <target name="codegen" depends="check-runtime,clean">
    
    <echo message="Running code generation from schema"/>
    <java classname="org.jibx.schema.codegen.CodeGen" fork="yes"
        classpathref="classpath" failonerror="true">
      <arg value="-t"/>
      <arg value="gen/src"/>
      <arg value="otasubset/OTA_AirLowFareSearch*.xsd"/>
    </java>
    
  </target>

This passes the '-t' parameter to CodeGen with the value 'gen/src' to tell it the target generation directory. The third argument value tells CodeGen to use schemas from the otasubset directory with names matching the pattern "OTA_AirLowFareSearch*.xsd" as input for code generation. You can specify as many schema names or schema name patterns as you want when running CodeGen, but must have at least one - otherwise there's nothing for CodeGen to generate!

Generated code

Run the 'codegen' target and see the gen/src directory. (You can also use the 'full' 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.)

CodeGen's default behavior is to derive the package used for generated code from the schema namespace URI. In this case, the schema namespace is http://www.opentravel.org/OTA/2003/05 (only the OTA_AirLowFareSearchRQ.xsd and OTA_AirLowFareSearchRS.xsd schemas actually define this target namespace, but the other schemas assume that namespace by being included into these two schemas, either directly or indirectly). To derive a package from the namespace, first the entire URI is converted to lowercase. Next the http://www. part is stripped, then the remaining components of the authority (host name) are converted to lowercase and reverse-ordered. This gives org.opentravel. Finally, the remaining path components are processed. Characters in the path component which are not valid Java name characters are discarded. This include any path components consisting only of digits, so the only component that gets used in the package name is OTA. The final package name is org.opentravel.ota.

The generated classes in this case directly model the schema (with the exception of xs:union simpleTypes - xs:union is currently not supported directly, instead using a simple String value as the most general representation). CodeGen was only asked to generate two schema documents, OTA_AirLowFareSearchRQ.xsd and OTA_AirLowFareSearchRS.xsd - but these schemas include the other schemas in the supplied OTA subset, either directly or indirectly. Unless you tell it otherwise, CodeGen generates every definition (with the exception of xs:attributeGroup and xs:group definitions which are only referenced once) in each schema, since in the general case all these definitions are necessary. This does create a lot of classes, though; in this case, 261 top-level classes and an additional 153 inner classes, for a total of 414 classes.

If you look at the generated Java class files, you'll see that each class definition starts with a JavaDoc comment giving first the documentation from the schema component matching the Java class, and then the schema fragment matching the class definition. This schema fragment is from a normalized version of the schema generated after type substitutions and inlining (the latter not a factor with the default generation used in this example), stripping annotations, and simplifications from eliminating schema components not handled by CodeGen (such as xs:unions - currently handled just as String values - and xs:restriction facets other than xs:enumeration).

Here's a sample of the generated code (reformated for a reasonable page width), showing portions of the two main classes used for the response message:

/** 
 * 
 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
 type
 - 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"
                 minOccurs="0"/>
 *           &lt;xs:element type="ns:PricedItinerariesType"
                 name="PricedItineraries"/>
 *         &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>
 * </pre>
 */
public class OTAAirLowFareSearchRS
{
    private int choiceSelect = -1;
    private static final int SUCCESS_CHOICE = 0;
    private static final int ERRORS_CHOICE = 1;
    private SuccessType success;
    private WarningsType warnings;
    private PricedItinerariesType pricedItineraries;
    private ErrorsType errors;
    private OTAPayloadStdAttributes OTAPayloadStdAttributes;

    private void setChoiceSelect(int choice) {
        if (choiceSelect == -1) {
            choiceSelect = choice;
        } else if (choiceSelect != choice) {
            throw new IllegalStateException(
                "Need to call clearChoiceSelect() before changing existing choice");
        }
    }

    /** 
     * Clear the choice selection.
     */
    public void clearChoiceSelect() {
        choiceSelect = -1;
    }

    /** 
     * Check if Success is current selection for choice.
     * 
     * @return <code>true</code> if selection, <code>false</code> if not
     */
    public boolean ifSuccess() {
        return choiceSelect == SUCCESS_CHOICE;
    }

    /** 
     * Get the 'Success' element value. Success
     Standard way to indicate successful processing of an OTA message. Returning an
     empty element of this type indicates success.
     * 
     * @return value
     */
    public SuccessType getSuccess() {
        return success;
    }

    /** 
     * Set the 'Success' element value. Success
     Standard way to indicate successful processing of an OTA message. Returning an
     empty element of this type indicates success.
     * 
     * @param success
     */
    public void setSuccess(SuccessType success) {
        setChoiceSelect(SUCCESS_CHOICE);
        this.success = success;
    }

    /** 
     * Get the 'Warnings' element value.  Standard way to indicate successful
     processing of an OTA message, but one in which warnings are generated.

     * 
     * @return value
     */
    public WarningsType getWarnings() {
        return warnings;
    }

    /** 
     * Set the 'Warnings' element value.  Standard way to indicate successful
     processing of an OTA message, but one in which warnings are generated.

     * 
     * @param warnings
     */
    public void setWarnings(WarningsType warnings) {
        setChoiceSelect(SUCCESS_CHOICE);
        this.warnings = warnings;
    }

    /** 
     * Get the 'PricedItineraries' element value. Successfull Low Fare priced
     itineraries in response to a Low Fare Search request.
     * 
     * @return value
     */
    public PricedItinerariesType getPricedItineraries() {
        return pricedItineraries;
    }

    /** 
     * Set the 'PricedItineraries' element value. Successfull Low Fare priced
     itineraries in response to a Low Fare Search request.
     * 
     * @param pricedItineraries
     */
    public void setPricedItineraries(PricedItinerariesType pricedItineraries) {
        setChoiceSelect(SUCCESS_CHOICE);
        this.pricedItineraries = pricedItineraries;
    }
    ...
}

/** 
 * Container for priced itineraries.
 * 
 * Schema fragment(s) for this class:
 * <pre>
 * &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>
 * </pre>
 */
public class PricedItinerariesType
{
    private List<PricedItinerary> pricedItineraryList =
        new ArrayList<PricedItinerary>();

    /** 
     * Get the list of 'PricedItinerary' element items.
     * 
     * @return list
     */
    public List<PricedItinerary> getPricedItineraryList() {
        return pricedItineraryList;
    }

    /** 
     * Set the list of 'PricedItinerary' element items.
     * 
     * @param list
     */
    public void setPricedItineraryList(List<PricedItinerary> list) {
        pricedItineraryList = list;
    }
    /** 
     *  Itinerary with pricing information.
     * 
     * 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="PricedItinerary"
           maxOccurs="unbounded">
     *   &lt;xs:complexType>
     *     &lt;xs:complexContent>
     *       &lt;xs:extension base="ns:PricedItineraryType">
     *         &lt;xs:attribute type="xs:integer" use="optional"
                   name="OriginDestinationRefNumber"/>
     *       &lt;/xs:extension>
     *     &lt;/xs:complexContent>
     *   &lt;/xs:complexType>
     * &lt;/xs:element>
     * </pre>
     */
    public static class PricedItinerary extends PricedItineraryType
    {
        private BigInteger originDestinationRefNumber;

        /** 
         * Get the 'OriginDestinationRefNumber' attribute value. This attribute
         refers back to origin destination information in the OTA_AirLowFareSearchRQ
         message.
         * 
         * @return value
         */
        public BigInteger getOriginDestinationRefNumber() {
            return originDestinationRefNumber;
        }

        /** 
         * Set the 'OriginDestinationRefNumber' attribute value. This attribute
         refers back to origin destination information in the OTA_AirLowFareSearchRQ
         message.
         * 
         * @param originDestinationRefNumber
         */
        public void setOriginDestinationRefNumber(
                BigInteger originDestinationRefNumber) {
            this.originDestinationRefNumber = originDestinationRefNumber;
        }
    }
}

The above code sample illustrates several aspects of the default code generation. The OTAAirLowFareSearchRS class represents an <OTA_AirLowFareSearchRS> element, with a schema structure consisting of a choice between a sequence of a <Success> element, an optional <Warnings> element, and a <PricedItineraries> element, or an <Errors> element. The <OTA_AirLowFareSearchRS> element also has a group of attributes named OTA_PayloadStdAttributes.

The choice between the sequence starting with the <Success> element and the <Errors> element is represented in the Java code with an internal state variable. The public methods ifSuccess() and ifErrors() allow you to check the state currently set for an instance of the class, while any of the set methods for values (setSuccess(), setWarnings(),' setPricedItineraries(), and setErrors()) check the internal state. If the state is not yet set when one of these methods is called, the state is set to match the value. If the state is set to a conflicting choice, an IllegalStateException is thrown. There's also a clearChoiceSelect() method which allows you to clear the current state. These methods all work together to enforce the semantics of the choice structure of the schema definition. There are other options for the details of how choices are implemented, though - see the choice-exposed and choice-handling customization attributes.

The PricedItinerariesType class shows the default handling for repeated values, as a Java 5 typed collection with simple get/set access methods. As with the choice handling, you can use customizations to change the list handling - see the repeated-type customization, which is used in Example 3: More extensive customizations to change the generated code to use arrays rather than lists. If you stay with lists (either using the Java 5 typed default, or untyped lists compatible with older versions of Java) you can add convenience methods to the list handling using a <class-decorator> customization referencing the org.jibx.schema.codegen.extend.CollectionMethodsDecorator.

You can also see from the code listing how CodeGen uses schema documentation components in creating class and method JavaDocs. The class JavaDoc begins with any documentation for the corresponding schema component (see import-docs), followed by the actual schema fragment matching the class (see show-schema and delete-annotations). The get/set access methods for each value in a class describe the schema equivalent of the value (as an element or attribute name) in the first sentence, followed by any schema documentation provided for that element or attribute (again controlled by import-docs).

Next: Example 2: Generating only the required classes