 | Introducing CodeGen customizations
In this section, you'll learn the basics of customizing CodeGen to control the structure of the code generated from a simple schema.
A simple customization example
CodeGen supports extensive customizations for many aspects of code and binding generation. The set of customizations to be applied are passed to CodeGen as an XML document, with nested elements that relate to schemas or schema components. Listing 5 gives a simple example:
Listing 5. Simple customizations example
<schema prefer-inline="true" show-schema="false" enumeration-type="simple"
generate-all="false" includes="order item"/> |
The Listing 5 customization consists of a single, unnamespaced
schema element with several different attributes giving the specific customizations to
be applied. (So far, you're only working with a single schema definition, so this very
simple form of customization can be used. Later in this tutorial, you'll see examples of customizations for working with multiple schemas.) The first customization attribute — prefer-inline="true" — tells CodeGen to inline schema definitions that are referenced only once, rather than use the default behavior of keeping them as separate classes. The second attribute — show-schema="false" — blocks embedding the schema definitions in class Javadocs. enumeration-type="simple" generates simple typesafe enumerations rather than Java 5 enums.
The final pair of attributes work together. CodeGen by default generates a separate top-level class for every global type definition in the schemas specified as input, along with a corresponding abstract mapping in the generated JiBX binding for each complexType. The generate-all="false" attribute changes this default behavior, explicitly generating only those complexTypes that are specifically included or referenced from an included type. The includes="order item" attribute then gives the names to be generated, which were chosen to keep compatibility with the test program — the <order> element is needed because that's the root element of the instance documents, and the complexType item is needed because the test program expects to find a separate top-level class for this type when it sums up the total amount of the order.
You can try out these customizations by using the Ant custgen task instead of the codegen task (or just use the full task, which runs the complete sequence of targets clean custgen compile bind run). Listing 6 shows excerpts of the generated code, which you can compare to the default generated code shown in Listing 2. The big differences (besides the simplified class Javadocs) are that the Customer class is now inlined, and the Shipping class is now an inner class using a custom typesafe enumeration class.
Listing 6. Code generated with customization
/**
* Order information.
*/
public class Order
{
private long orderNumber;
private long customerCustomerNumber;
private String customerFirstName;
private String customerLastName;
private Address billTo;
private Shipping shipping;
private Address shipTo;
private List<Item> itemList = new ArrayList<Item>();
private Date orderDate;
private Date shipDate;
private Float total;
...
/**
* 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.
*/
public static class Shipping
{
private final String value;
public static final Shipping STANDARD_MAIL = new Shipping(
"STANDARD_MAIL");
public static final Shipping PRIORITY_MAIL = new Shipping(
"PRIORITY_MAIL");
public static final Shipping INTERNATIONAL_MAIL = new Shipping(
"INTERNATIONAL_MAIL");
public static final Shipping DOMESTIC_EXPRESS = new Shipping(
"DOMESTIC_EXPRESS");
public static final Shipping INTERNATIONAL_EXPRESS = new Shipping(
"INTERNATIONAL_EXPRESS");
private static final String[] values = new String[]{"DOMESTIC_EXPRESS",
"INTERNATIONAL_EXPRESS", "INTERNATIONAL_MAIL", "PRIORITY_MAIL",
"STANDARD_MAIL"};
private static final Shipping[] instances = new Shipping[]{
DOMESTIC_EXPRESS, INTERNATIONAL_EXPRESS, INTERNATIONAL_MAIL,
PRIORITY_MAIL, STANDARD_MAIL};
private Shipping(String value) {
this.value = value;
}
public String toString() {
return value;
}
public static Shipping convert(String value) {
int index = java.util.Arrays.binarySearch(values, value);
if (index >= 0) {
return instances[index];
} else {
return null;
}
}
public static Shipping fromValue(String text) {
Shipping value = convert(text);
if (value == null) {
throw new IllegalArgumentException("Value \'" + text
+ "\' is not allowed");
} else {
return value;
}
}
}
} |
Many additional customizations are available for use with CodeGen. You'll see some
examples of these later in this tutorial, but to give a better idea of the power of these customizations, it's necessary to move on to a more complex schema.
| |
