Customizing JAXB Bindings

The following sections explain how to customize generated JAXB classes and Java program elements.

Schema-to-Java

Custom JAXB binding declarations also allow you to customize your generated JAXB classes beyond the XML-specific constraints in an XML schema to include Java-specific refinements such as class and package name mappings.

JAXB provides two ways to customize an XML schema:

• As inline annotations in a source XML schema

• As declarations in an external binding customizations file that is passed to the JAXB binding compiler

Code examples that show how to customize JAXB bindings are provided at the end of this chapter.

Java-to-Schema

The JAXB annotations defined in the javax.xml.bind.annotations package can be used to customize Java program elements to XML schema mapping.

Table 163 summarizes the JAXB annotations that can be used with a Java package.

Table 163. JAXB Annotations Associated with a Java Package

Annotation	Description and Default Setting
@XmlSchema	Maps a package to an XML target namespace. Default Settings: @XmlSchema ( xmlns = {}, namespace = "", elementFormDefault = XmlNsForm.UNSET; attributeFormDefault = XmlNsForm.UNSET, )
@XmlAccessorType	Controls default serialization of fields and properties. Default Settings: @XmlAccessorType ( value = AccessType.PUBLIC_MEMBER )
@XmlAccessorOrder	Controls the default ordering of properties and fields mapped to XML elements. Default Settings: @XmlAccessorOrder ( value = AccessorOrder.UNDEFINED )
@XmlSchemaType	Allows a customized mapping to a XML Schema built-in type. Default Settings: @XmlSchemaType ( namespace = "http://www.w3.org/2001/XMLSchema", type = DEFAULT.class )
@XmlSchemaTypes	A container annotation for defining multiple @XmlSchemaType annotations. Default Settings: None

Table 164 summarizes JAXB annotations that can be used with a Java class.

Table 164. JAXB Annotations Associated with a Java Class

Annotation	Description and Default Setting
@XmlType	Maps a Java class to a schema type. Default Settings: @XmlType ( name = "##default", propOrder = {""}, namespace = "##default", factoryClass = DEFAULT.class, factoryMethod = "" )
@XmlRootElement	Associates a global element with the schema type to which the class is mapped. Default Settings: @XmlRootElement ( name = "##default", namespace = "##default" )

Table 165 summarizes JAXB annotations that can be used with a Java enum type.

Table 165. JAXB Annotations Associated with a Java enum Type

Annotation	Description and Default Setting
@XmlEnum	Maps a Java type to a XML simple type. Default Settings: @XmlEnum ( value = String.class )
@XmlEnumValue	Maps a Java type to an XML simple type. Default Settings: None
@XmlType	Maps a Java class to a schema type. Default Settings: @XmlType ( name = "##default", propOrder = {""}, namespace = "##default", factoryClass = DEFAULT.class, factoryMethod = "" )
@XmlRootElement	Associates a global element with the schema type to which the class is mapped. Default Settings: @XmlRootElement ( name = "##default", namespace = "##default" )

Table 166 summarizes JAXB annotations that can be used with Java properties and fields.

Table 166. JAXB Annotations Associated with Java Properties and Fields

Annotation	Description and Default Setting
@XmlElement	Maps a JavaBeans property/field to a XML element derived from a property/field name. Default Settings: @XmlElement ( name = "##default", nillable = false, namespace = "##default", type = DEFAULT.class, defaultValue = "\u0000" )
@XmlElements	A container annotation for defining multiple @XmlElement annotations. Default Settings: None
@XmlElementRef	Maps a JavaBeans property/field to a XML element derived from a property/field's type. Default Settings: @XmlElementRef ( name = "##default", namespace = "##default", type = DEFAULT.class, )
@XmlElementRefs	A container annotation for defining multiple @XmlElementRef annotations. Default Settings: None
@XmlElementWrapper	Generates a wrapper element around an XML representation. Typically a wrapper XML element around collections. Default Settings: @XmlElementWrapper ( name = "##default", namespace = "##default", nillable = false )
@XmlAnyElement	Maps a JavaBeans property to an XML infoset representation and/or JAXB element. Default Settings: @XmlAnyElement ( lax = false, value = W3CDomHandler.class )
@XmlAttribute	Maps a JavaBeans property to a XML attribute. Default Settings: @XmlAttribute ( name =##default, required = false, namespace = "##default" )
@XmlAnyAttribute	Maps a JavaBeans property to a map of wildcard attributes. Default Settings: None
@XmlTransient	Prevents the mapping of a JavaBeans property to an XML representation. Default Settings: None
@XmlValue	Defines mapping of a class to an XML Schema complex type with a simpleContent or an XML Schema simple type. Default Settings: None
@XmlID	Maps a JavaBeans property to XML ID. Default Settings: None
@XmlIDREF	Maps a JavaBeans property to XML IDREF. Default Settings: None
@XmlList	Used to map a property to a list simple type. Default Settings: None
@XmlMixed	Mark a JavaBeans multi-valued property to support mixed content. Default Settings: None
@XmlMimeType	Associates the MIME type that controls the XML representation of the property. Default Settings: None
@XmlAttachmentRef	Marks a field/property that its XML form is a URI reference to mime content. Default Settings: None
@XmlInlineBinaryData	Disables consideration of XOP encoding for datatypes that are bound to base64-encoded binary data in XML. Default Settings: None

Table 167 summarizes the JAXB annotation that can be used with object factories.

Table 167. JAXB Annotations Associated with Object Factories

Annotation	Description and Default Setting
@XmlElementDecl	Maps a factory method to an XML element. Default Settings: @XmlElementDecl ( scope = GLOBAL.class, namespace = "##default", substitutionHeadNamespace = "##default", substitutionHeadName = "" )

Table 168 summarizes JAXB annotations that can be used with adapters.

Table 168. JAXB Annotations Associated with Adapters

Annotation	Description and Default Setting
@XmlJavaTypeAdapter	Use the adapter that implements the @XmlAdapter annotation for custom marshalling. Default Settings: @XmlJavaTypeAdapter ( type = DEFAULT.class )
@XmlJavaTypeAdapters	A container annotation for defining multiple @XmlJavaTypeAdapter annotations at the package level. Default Settings: None