Nesting and Context

The binding definition itself uses a nested structure that's partially recursive - some of the element types in the binding definition can contain other instances of the same element as children. This nesting is an important part of how the binding definition describes the rules for converting your objects. It's used both for showing the relationships between your Java and XML structures (see the Structure mapping discussion), and for establishing the scope of definitions.

Each level of nesting establishes a definition context for shared information (such as conversion formats, namespaces, and type mappings). Definitions from an enclosing context apply automatically in all nested contexts unless they are overridden within that context. To understand how this operates, think of the nested elements as similar to curly brace blocks in Java - definitions from a block are only visible within that block (including any inner blocks it encloses). This isn't an exact comparison - for one thing, inner blocks can override definitions from an enclosing block - but it's close.

Here's a partial example from a binding definition to illustrate how context works:

<binding>
  <mapping name="base-table" 
      class="org.jibx.demo.TimeTableBean">
    <format name="flightTime" type="int"
      serializer="org.jibx.demo.Utils.minuteToTime"
      deserializer="org.jibx.demo.Utils.timeToMinute">
    <mapping class="org.jibx.demo.FlightBean" ... >
      ...
      <value name="depart" field="m_departure"
        format="flightTime"/>
      <value name="arrive" field="m_arrival"
        format="flightTime"/>
    </mapping>
    <mapping name="roundtrip" ... >
      <structure name="outbound" field="m_outbound"
        item-type="org.jibx.demo.FlightBean"/>
      <structure name="inbound" field="m_inbound"
        item-type="org.jibx.demo.FlightBean"/>
    </mapping>
    ...
  </mapping>
  <mapping name="split-table" 
      class="org.jibx.demo.SplitTableBean">
  ...

The first mapping element (with name="base-table") establishes a context. The contained format and mapping elements are definitions that apply within the scope of that context. In this case the format definition (with name="flightTime") is used within the first mapping definition, and the second mapping definition in turn uses the first one (by specifying an item-type that matches the class name).

These child definitions from the first mapping element are not available for use within the last mapping element. This element is at the same nesting level as the first one. If you wanted to make the child definitions from the first mapping available for use in the last one, you could do so by moving these definitions up to a higher level, making them children of the binding element.