The structure element defines a structure component of a binding.
This can take any of several forms. The first is where the structure is a
complex XML element (one with attributes or child elements) that's linked to
an object property of the containing object type. This is the most common form
of usage. It's essentially equivalent to an "in-line" mapping
definition. This variation applies when both an element name and an object
property are defined by the structure element (or when the property
is implied rather than defined directly, as when the structure element is
the child of a collection element).
Variations of the structure element that define either an element
name or a linked property value (but not both) are used for structure mapping. Each of these variations
works differently depending on whether the structure element is empty
(does not have any child elements). The full set of structure mapping variations
is shown in the table below.
||What it Does
Adds an empty element to the XML when marshalling (unless optional, in
which case it's ignored when marshalling), discards and ignores
the named element when unmarshalling.
Structure mapping that defines a complex element (one with attributes or
child elements) in the XML representation with no corresponding object. Child
attribute or element values are in this case linked directly to properties of
the containing object type.
References the mapping for the property object type, which must be
defined within some enclosing context of this definition. If the property type
exactly matches a defined mapping, that mapping will be used; if not, the
mapping will be determined by the element name when unmarshalling or the actual
object type when marshalling. This allows generic
references to be used, as long as a mapping is defined for the actual type of
the item. The only restriction is that if this type of reference is defined as
optional it must be the last element in a list (otherwise, if the expected
element is missing in a document being unmarshalled the next sibling element
will be used instead).
Structure mapping that defines an object with no corresponding XML
element. Attributes or child elements defined within this structure
are part of the XML element defined by the containing structure or
mapping. Optional structures with no associated element name are subject to some
unmarshalling limitations. If the structure defines both attribute and element
values, the presence or absence of the structure is determined based only on the
attributes - if one of the defined attributes is present on the containing
element the structure is considered to be present, otherwise it is not and the
property will be set to
Structures with child definitions may be ordered (where the XML components
bound to the child definitions occur in a particular sequence) or unordered
(where the XML components can occur in any order), as determined by the ordered attribute of the
structure attribute group. In
the case of unordered structures only optional components are allowed as
A structure element can be used without either an
element name or a linked property value when you just want to say that some
child elements make up an unordered set:
<mapping name="alphas" class="AlphabetBean">
<value name="a" field="a"/>
<value name="b" field="b" usage="optional"/>
<value name="c" field="c" usage="optional"/>
<value name="d" field="d"/>
The above binding definition unmarshals both the element sequences (a, b, c,
d) and (a, c, b, d). Since the unordered elements are (and have to be) optional,
though, the binding will also allow (a, b, d), (a, c, d), and just (a, d). The
unordered elements may also be duplicated without an error, so (a, c, b, c, d)
would also be accepted (with repeated values stored in order, so that the final
value for a property would be that of the last instance of the element). When
marshalling an unordered group the sequence used in the binding definition will
always be followed (so (a, c, b, d) would marshal as (a, b, c, d)). If you need
to control the order of elements (or preserve the order, when starting from an
unmarshalled document) you'll need to instead work with objects that can be held
in a collection.
When a structure element is used with an object property JiBX will
reuse an existing instance of the object during unmarshalling. The way this
works is that JiBX only creates a new instance of the object for use in
unmarshalling if the property value is
null. If an element name is
used with an optional structure, and that name is missing from an input XML
document, the object property for that structure will always be set to
null (since the representation is missing from the XML). If you
don't want the property to ever be set to
null, use a wrapper
structure element for the optional element name around the actual
The structure element supports one unique attribute along with
several common attribute groups, listed below. The unique attribute is used to
reference mapping definitions for objects. It may only be used when
a property is supplied (or implied).
This optional attribute can be used to override the type (or type name)
to be used for a mapping reference. If used as a type, the value of this
attribute must be the fully-qualified class name for the mapped type, and the
specified class must be assignment compatible with the actual property type (so
you can't map a
java.lang.Integer field as a
java.lang.String, for instance, but can map a field typed
java.lang.Object as a
java.lang.String). If used as a
type name, the name must match the type name defined by an abstract mapping.
A structure element with no property reference can use the map-as
attribute to invoke a specified mapping for the
this object (where
the mapping must be assignment compatible with the
type). As of JiBX 1.1, the value of this attribute is interpreted as namespace
A value-style attribute present on the structure element sets a
default for all contained elements. See the style attribute group description
for usage details.
Attributes from the name group define an element mapped to the structure
definition as a whole. The element defined in this way will be a wrapper for the
XML representations of all child values defined by the structure. The name is optional
unless this structure defines a mapping reference to the property type (property
definition with no children, see the third row of the table at the top of this
page), in which case it's forbidden. See the name attribute group description
for usage details.
Attributes from the object group define the way object instances are
created and used in marshalling and unmarshalling. See the object attribute group description
for usage details.
Attributes from the property group define a property value, including how
it is accessed and whether it is optional or required. See the property attribute group description
for usage details.
Attributes from the structure group define ordering and reuse of
child binding components. See the
structure attribute group
description for usage details.