JiBX: <structure> Element

<structure> Element Definition

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.

Structure Mapping Variations

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 child definitions.

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"/>
    <structure ordered="false">
      <value name="b" field="b" usage="optional"/>
      <value name="c" field="c" usage="optional"/>
    </structure>
    <value name="d" field="d"/>
  </mapping>

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 structure definition.

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).

Attributes