Customizing Generated Classes and Java Program Elements (original) (raw)

Custom JAXB binding declarations 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 customization file that is passed to the JAXB binding compiler

Code examples that show how to customize JAXB bindings are provided later in 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 17-3 summarizes the JAXB annotations that can be used with a Java package.

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

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

Table 17-5 JAXB Annotations Associated with a Java enum Type

Annotation	Description and Default Setting
@XmlEnum	Maps a Java type to an 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 17-6 summarizes JAXB annotations that can be used with Java properties and fields.

Table 17-6 JAXB Annotations Associated with Java Properties and Fields

Annotation	Description and Default Setting
@XmlElement	Maps a JavaBeans property/field to an 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 an 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 an 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 an XML ID. Default Settings: None
@XmlIDREF	Maps a JavaBeans property to an XML IDREF. Default Settings: None
@XmlList	Maps a property to a list simple type. Default Settings: None
@XmlMixed	Marks 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 data types that are bound to base64-encoded binary data in XML. Default Settings: None

Table 17-7 summarizes the JAXB annotation that can be used with object factories.

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

Table 17-8 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