Chapter 38. Customizing How Types are Generated
Abstract
The default JAXB mappings address most of the cases encountered when using XML Schema to define the objects for a Java application. For instances where the default mappings are insufficient, JAXB provides an extensive customization mechanism.
38.1. Basics of Customizing Type Mappings
Overview
The JAXB specification defines a number of XML elements that customize how Java types are mapped to XML Schema constructs. These elements can be specified in-line with XML Schema constructs. If you cannot, or do not want to, modify the XML Schema definitions, you can specify the customizations in external binding document.
Namespace
The elements used to customize the JAXB data bindings are defined in the namespace
http://java.sun.com/xml/ns/jaxb
. You must add a namespace declaration similar to the one shown in Example 38.1, “JAXB Customization Namespace”. This is added to the root element of all XML documents defining JAXB customizations.
Example 38.1. JAXB Customization Namespace
xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
Version declaration
When using the JAXB customizations, you must indicate the JAXB version being used. This is done by adding a
jaxb:version
attribute to the root element of the external binding declaration. If you are using in-line customization, you must include the jaxb:version
attribute in the schema
element containing the customizations. The value of the attribute is always 2.0
.
Example 38.2, “Specifying the JAXB Customization Version” shows an example of the
jaxb:version
attribute used in a schema
element.
Example 38.2. Specifying the JAXB Customization Version
< schema ... jaxb:version="2.0">
Using in-line customization
The most direct way to customize how the code generators map XML Schema constructs to Java constructs is to add the customization elements directly to the XML Schema definitions. The JAXB customization elements are placed inside the
xsd:appinfo
element of the XML schema construct that is being modified.
Example 38.3, “Customized XML Schema” shows an example of a schema containing an in-line JAXB customization.
Example 38.3. Customized XML Schema
<schema targetNamespace="http://widget.com/types/widgetTypes" xmlns="http://www.w3.org/2001/XMLSchema" xmlns:jaxb="http://java.sun.com/xml/ns/jaxb" jaxb:version="2.0"> <complexType name="size"> <annotation> <appinfo> <jaxb:class name="widgetSize" /> </appinfo> </annotation> <sequence> <element name="longSize" type="xsd:string" /> <element name="numberSize" type="xsd:int" /> </sequence> </complexType> <schema>
Using an external binding declaration
When you cannot, or do not want to, make changes to the XML Schema document that defines your type, you can specify the customizations using an external binding declaration. An external binding declaration consists of a number of nested
jaxb:bindings
elements. Example 38.4, “JAXB External Binding Declaration Syntax” shows the syntax of an external binding declaration.
Example 38.4. JAXB External Binding Declaration Syntax
<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="schemaUri" | wsdlLocation="wsdlUri"> <jaxb:bindings node="nodeXPath"> binding declaration </jaxb:bindings> ... </jaxb:bindings> <jaxb:bindings>
The
schemaLocation
attribute and the wsdlLocation
attribute are used to identify the schema document to which the modifications are applied. Use the schemaLocation
attribute if you are generating code from a schema document. Use the wsdlLocation
attribute if you are generating code from a WSDL document.
The
node
attribute is used to identify the specific XML schema construct that is to be modified. It is an XPath statement that resolves to an XML Schema element.
Given the schema document
widgetSchema.xsd
, shown in Example 38.5, “XML Schema File”, the external binding declaration shown in Example 38.6, “External Binding Declaration” modifies the generation of the complex type size.
Example 38.5. XML Schema File
<schema targetNamespace="http://widget.com/types/widgetTypes" xmlns="http://www.w3.org/2001/XMLSchema" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" version="1.0"> <complexType name="size"> <sequence> <element name="longSize" type="xsd:string" /> <element name="numberSize" type="xsd:int" /> </sequence> </complexType> <schema>
Example 38.6. External Binding Declaration
<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="wsdlSchema.xsd"> <jaxb:bindings node="xsd:complexType[@name='size']"> <jaxb:class name="widgetSize" /> </jaxb:bindings> </jaxb:bindings> <jaxb:bindings>
To instruct the code generators to use the external binging declaration use the wsdl2java tool's
-b binding-file
option, as shown below:
wsdl2java -b widgetBinding.xml widget.wsdl