Home | Download | PDF | API | FAQ | Search | Feedback | History

> ## Customizing JAXB Bindings

> ### 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 16-3 summarizes the JAXB annotations that can be used with a Java package.

> Table 16-3 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 16-4 summarizes JAXB annotations that can be used with a Java class.

> Table 16-4 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 16-5 summarizes JAXB annotations that can be used with a Java enum type.

> Table 16-5 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 16-6 summarizes JAXB annotations that can be used with a Java properties and fields.

> Table 16-6 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 XML representation. Default Settings: None
> `@XmlValue` | Defines mapping a class to a XML Schema complex type with a simpleContent or a 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
> `@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 )`

> Table 16-7 summarizes JAXB annotations that can be used with ObjectFactories.

> Table 16-7 JAXB Annotations Associated with ObjectFactories
> 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 16-8 summarizes JAXB annotations that can be used with adapters.

> Table 16-8 JAXB Annotations Associated with Adapters
> Annotation | Description and Default Setting
> --- | ---
> `@XmlJavaTypeAdapter` | Use the adapter that implements @`XmlAdapter` for custom marshaling. Default Settings: `@XmlJavaTypeAdapter ( type = DEFAULT.class )`
> `@XmlJavaTypeAdapters` | A container annotation for defining multiple `@XmlJavaTypeAdapter` annotations at the package level. Default Settings: None