38.6. 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.
Customization usage
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 38.27, “In-Line Customization of a Base Type” shows an in-line customization that maps one element in a complex type to a Java
Object
object.
Example 38.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 38.28, “External Binding File to Customize a Base Type” shows an external binding file for the customization shown in Example 38.27, “In-Line Customization of a Base Type”.
Example 38.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 38.29, “Java Class with a Modified Base Class” shows the class generated based on the schema definition in Example 38.28, “External Binding File to Customize a Base Type”.
Example 38.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 Section 38.2, “Specifying the Java Class of an XML Schema Primitive”.