Fuse ESB - Developing Applications Using JAX-WS [DRAFT] - Specifying the Base Type of an Element or an Attribute

Specifying the Base Type of an Element or an Attribute

Overview

Occasionally you need to customize the class of the object generated for an element, or for an attribute defined as part of an XML Schema complex type. For example, you might want to use a more generalized class of object to allow for simple type substitution.

One way to do this is to use the JAXB base type customization. It allows a developer, on a case by case basis, to specify the class of object generated to represent an element or an attribute. The base type customization allows you to specify an alternate mapping between the XML Schema construct and the generated Java object. This alternate mapping can be a simple specialization or a generalization of the default base class. It can also be a mapping of an XML Schema primitive type to a Java class.

To apply the JAXB base type property to an XML Schema construct use the JAXB baseType customization element. The baseType customization element is a child of the JAXB property element, so it must be properly nested.

Depending on how you want to customize the mapping of the XML Schema construct to Java object, you add either the baseType customization element's name attribute, or a javaType child element. The name attribute is used to map the default class of the generated object to another class within the same class hierarchy. The javaType element is used when you want to map XML Schema primitive types to a Java class.

	Important
	You cannot use both the `name` attribute and a `javaType` child element in the same `baseType` customization element.

Specializing or generalizing the default mapping

The baseType customization element's name attribute is used to redefine the class of the generated object to a class within the same Java class hierarchy. The attribute specifies the fully qualified name of the Java class to which the XML Schema construct is mapped. The specified Java class must be either a super-class or a sub-class of the Java class that the code generator normally generates for the XML Schema construct. For XML Schema primitive types that map to Java primitive types, the wrapper class is used as the default base class for the purpose of customization.

For example, an element defined as being of xsd:int uses java.lang.Integer as its default base class. The value of the name attribute can specify any super-class of Integer such as Number or Object.

	Tip
	For simple type substitution, the most common customization is to map the primitive types to an `Object` object.

Example 15.27 shows an in-line customization that maps one element in a complex type to a Java Object object.

Example 15.27. In-Line Customization of a Base Type

<complexType name="widgetOrderInfo">
  <all>
    <element name="amount" type="xsd:int" />
     <element name="shippingAdress" type="Address>
      <annotation>
        <appinfo>
           <jaxb:property>
             <jaxb:baseType name="java.lang.Object" />
           </jaxb:property>
        </appinfo>
      </annotation>
    </element>
    <element name="type" type="xsd:string"/>
  </all>
</complexType>

Example 15.28 shows an external binding file for the customization shown in Example 15.27.

Example 15.28. External Binding File to Customize a Base Type

<jaxb:bindings xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
               jaxb:version="2.0">
  <jaxb:bindings schemaLocation="enumMap.xsd">
    <jaxb:bindings node="xsd:ComplexType[@name='widgetOrderInfo']">
      <jaxb:bindings node="xsd:element[@name='shippingAddress']">
        <jaxb:property>
          <jaxb:baseType name="java.lang.Object" />
        </jaxb:property>
      </jaxb:bindings>
    </jaxb:bindings>
  </jaxb:bindings>
<jaxb:bindings>

The resulting Java object's @XmlElement annotation includes a type property. The value of the type property is the class object representing the generated object's default base type. In the case of XML Schema primitive types, the class is the wrapper class of the corresponding Java primitive type.

Example 15.29 shows the class generated based on the schema definition in Example 15.28.

Example 15.29. Java Class with a Modified Base Class

public class WidgetOrderInfo {

    protected int amount;
    @XmlElement(required = true)
    protected String type;
    @XmlElement(required = true, type = Address.class)
    protected Object shippingAddress;

    ...
    public Object getShippingAddress() {
        return shippingAddress;
    }


    public void setShippingAddress(Object value) {
        this.shippingAddress = value;
    }

}

Usage with `javaType`

The javaType element can be used to customize how elements and attributes defined using XML Schema primitive types are mapped to Java objects. Using the javaType element provides a lot more flexibility than simply using the baseType element's name attribute. The javaType element allows you to map a primitive type to any class of object.

For a detailed description of using the javaType element, see Specifying the Java Class of an XML Schema Primitive.