Monday, 2 January 2012

JAXB Mapping Overview

XML SchemaDetailsJavaAnnotation / CustomizationComments
target namespace-
  • package
  • ObjectFactory
-Just as the target XML namespace provides a naming context for schema components, the Java package provides a naming context for Java interfaces and classes
simple type definition-property
  • @XmlID
  • @XmlIDREF
  • @XmlAttachmentRef
  • @XmlList
While not necessary to perform by default, a simple type definition may be bound to a Java class. This binding is necessary to preserve a simple type definition referred to by "xsi:type" attribute in an XML instance document. It is enabled via the global binding customization attribute "mapSimpleTypeDefs". The binding is the same as for a complex type with simple content ("value" property ...)
A schema component using a simple type definition (element, attribute ...) typically binds to a Java property. The simple type definition defines the property's:
  • base type
  • collection type (xsd:list)
  • predicate
The rest of the property is specified in the schema component using the simple type definition. A "predicate" throws a TypeConstraintException when constraints expressed in the source schema simple type facets are violated (min, max, length, pattern ...)
enumeration facetenum
  • @XmlEnum
  • @XmlEnumValue
Customization: typesafeEnumBase, typesafeEnumMemberName, typesafeEnumMaxMembers, typesafeEnumClass, typesafeEnumMember
There is no mechanism to derive an enum type name for an anonymous simple type definition, the customization must provide it
complex type definitionglobal (named)
  • class
  • ObjectFactory typeInstanceFactory
  • @XmlType
  • @XmlValue (for simple content)
If "generateValueClass" is specified as false, a schema-derived interface and implementation class is generated instead of a class. A content interface can only be created with an ObjectFactory method whereas a value class can also be created with a public constructor
The attributes and children elements of a complex type definition are represented as properties of the Java class. A complex type definition with simple content binds its content to a property named "value" and annotated with @XmlValue. An element of type "xsd:anyType" is bound to an Object property
anonymous within global, non-nillable, non-substitution element declaration
  • class with @XmlRootElement
  • ObjectFactory typeInstanceFactory
Same as above, with name and package being derived from the enclosing element declaration
anonymous within local or nillable or substitution element declaration
  • class without @XmlRootElement
  • ObjectFactory typeInstanceFactory
attribute group definition---There is no default mapping for an attribute group definition. When an attribute group is referenced, each attribute in the attribute group definition becomes a part of the attribute uses property of the referencing complex type definition
model group definition-
  • a set of properties (maxOccurs=1)
  • a general content List<Object> property (maxOccurs>1)
-When a named model group definition is referenced, the JAXB property set representing its content model is aggregated into the Java value class representing the complex type definition that referenced the named model group definition. This binding style results in the same properties occurring within several value classes. However, when a model group definition’s content model contains an XML Schema component that is to be bound to a Java value class, element class or enum type, a single Java representation is created, not one for each complex content that references the named model group definition
attribute declaration-property-An attribute declaration is bound to a Java property when it is referenced or declared (see attribute use)
element declarationglobal with anonymous type definitionObjectFactory elementInstanceFactory
  • @XmlElementDecl
  • @XmRootlElement
If "generateElementClass" specified as true, a schema-derived Element class is generated for each element declaration that has an element factory method
-
global with named type definitionObjectFactory elementInstanceFactory-
local within "general content property"ObjectFactory elementInstanceFactory-
localproperty@XmlElementIf maxOccurs>1, the property is a list property
reference to substitution group headJAXBElement<? extends T> property@XmlElementRef
attribute use-property
  • @XmlAttribute
  • @XmlID (type="xs:ID")
  • @XmlIDREF (type="xs:IDREF")
-
"fixed" value constraintpublic static final variable@XmlAttribute and fixedAttributeAsConstantProperty="true"-
attribute wildcard-Map<QName, String> getOtherAttributes@XmlAnyAttribute-
redefine---A redefined complex type definition is bound to a Java value class or interface name that prepends "_" to the original class name and extends the original class
identity constraint---An identity constraint does not represent any data, it represents a constraint that is enforced by validation
complex type definition content model (particle, model group, wildcard)complex type definition "mixed" content modelList<Object> general content property named "content"@XmlMixedCharacter information data is inserted as instances of String
particle with maxOccurs>1List<Object> property of value classes
  • @XmlElements
  • @XmlElement (for each unique type)
Only if the content model has no wildcard, no abstract element, no substitution group head, no "xsd:list" element, no IDREF element, at most one "nillable" element and, most importantly, all elements have different types
particle with maxOccurs>1List<Object> property of JAXB elements
  • @XmlElements
  • @XmlElement (for each JAXBElement)
Only "choice" and "sequence" can have maxOccurs>1: the allowed values for "all" minOccurs/maxOccurs are restricted to 0 or 1 by the XSD specification
single wilcard particleObject property named "any" (List<Object> if maxOccurs>1)@XmlAnyElementIf there is more than one wilcard particle, then fallback to representing the entire content model as a single general content property
non-repeating choice particlesimple propertychoiceContentProperty="true"-
content model "derived by extension" with naming collisionsList<Object> property named "rest"-The colliding properties are represented by a general content property with the default property name "rest"
other particlesproperty-If it is not possible to map each element declaration to a unique content property (name collisions ...), fallback to representing the entire content model as a single general content property