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:

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