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 JavaBean 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 JavaBean 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 JavaBean property to an XML infoset representation and/or JAXB element
Default Settings:
@XmlAnyElement ( lax = false,
value = W3CDomHandler.class
)
@XmlAttribute
Maps a JavaBean property to a XML attribute
Default Settings:
@XmlAttribute ( name = ##default,
required = false,
namespace = "##default"
)
@XmlAnyAttribute
Maps a JavaBean property to a map of wildcard attributes
Default Settings:
None
 
@XmlTransient
Prevents the mapping of a JavaBean 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 JavaBean property to XML ID
Default Settings:
None
@XmlIDREF
Maps a JavaBean property to XML IDREF
Default Settings:
None
@XmlList
Used to map a property to a list simple type
Default Settings:
None
@XmlMixed
Mark a JavaBean 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 marshalingDefault Settings:
@XmlJavaTypeAdapter ( type =DEFAULT.class )
@XmlJavaTypeAdapters
A container annotation for defining multiple @XmlJavTypeAdapter annotations at the package level.
Default Settings:
none