An XML schema choice element allows only one of the elements contained in the declaration to be present within the containing. Consider the following schema:
In the schema above, the Address element contains a construct that specifies that one XML instance can contain either a CAN-Address element, a US-Address element or an OtherContry element. The three elements are mutually exclusive – that is, only one of the three can appear in any one XML instance.
XML Thunder provides full support for the XML Choice construct by replicating the complete XML Choice structure declared in the XML Schema and then adding a special field called selection attribute. In the example below, all three choices have been defined in the Handler design and a selection attribute has been added. Any one occurrence of Address can contain a CAN-Address, a US-Address or an OtherCountry address.
The selection attribute is mapped to an IDS field just as any other node.
Choice Selection Attribute:
The choice selection attribute is an XML Thunder special field used for controlling XML choice structures. As with all special fields, the selection attribute will not appear in the actual XML instance created by a Writer, nor will it be searched for by an XML Reader.
By default, the name of this special field is “Selection” and its length is 100. These settings can be customized though by going to Tools -> Default Properties -> XML Rules -> XSD Indicators.
The selection attribute is mapped to an IDS field and is used by the calling program as follows:
The selection attribute is populated by the XML Reader Handler with the choice branch that was found while reading the XML document. The calling program can use the selection attribute to determine which choice was found.
The selection attribute is used to tell the XML Writer Handler which choice branch to write out. It is populated by the calling program and passed the XML Writer.
Choice Selection Attribute Value:
The value of the selection attribute value determines the choice branch to be created (for a writer) or specifies the choice branch that was read (for a reader). You have two choices for how the selection attribute value is set:
XML Node Name:
The selection attribute will contain the name of the XML node that comprises one of the choice nodes. You can only use this setting if the node names under the choice are unique with the Handler design.
Qualified XML Node Name – the selection attribute will contain the full name (including context) of the XML node that comprises one of the choice nodes. Using the qualified XML Node Name will mean the the selection attribute value be longer, but will be unique.
The easiest way to determine the possible values of the XML structure attribute is to generate the Writer Test Harness for the Handler design. It will contain all possible selection attribute values as comments in the BUSINESS-LOGIC-BEFORE paragraph.
Note: The selection attribute value will not contain the or nodes unless they are immediate children of a . That is to say, they will be not be included unless they are actual “choices”. Consider the following example:
Choice XT-XML-CHOICE-01 has three possible choices – E2, XT-XML-SEQUENCE-01 and XT-XML-CHOICE-02. The selection attribute values (using Qualified XML Node Name) for these choices are:
Choice Structure Physical IDS:
The physical IDS to support choice will contain the program fields for all possible choices. In the example below, structures to hold all three possible address types have been defined. A choice selection attribute has also been defined.
Implementing Choice in Your Calling Program
The Test Harnesses generated by XML Thunder provide examples of how choice processing is done.
The XML Handler will parse the XML nodes found into the appropriate program data fields and populate the selection attribute with the value of the choice that was found.
The calling program will populate the program data fields the appropriate choice structure, as well as the selection attribute value. The XML Writer will use the selection attribute value to determine the choice structure to write out.
XML Writer Mainline:
MOVE “Ontario” TO XT-PROVINCE.
MOVE “L5R 3R3” TO XT-POSTAL-CODE.