IDL to XML Mapping with the XML Mapping Editor

The EntireX XML Mapping Editor allows you to map XML document structures to IDL libraries, programs and parameters. The mappings can be defined for the request and response to the server application, or from the server to the client. The input for the XML Mapping Editor can be a Software AG IDL file and/or an IDL-XML mapping file (perhaps produced by a previous XML Mapping Editor session or by importing a WSDL file, XML Document or XML Schema). The output is an IDL-XML mapping file, other XML structure definitions (such as sample XML files), and perhaps a created or changed IDL file.

There are two ways to create an IDL to XML mapping: automatically (and then modify the resulting structures manually), or manually.

This document covers the following topics:


Mapping IDL to XML Automatically

This section covers the following topics:

Scope

The following approaches are available:

  • Map all programs in the current IDL file with the element-preferred strategy.

  • Map all programs in the current IDL file with the attribute-preferred strategy.

  • Create a SOAP mapping for all programs in the current IDL file.

  • Mapping and XML Schema generation for all programs in the current IDL file. This creates an element-preferred mapping.

The mapping strategies generate XML tree nodes for all IDL parameters with the appropriate direction:

  • For IN and INOUT IDL parameters, XML Request nodes are generated.

  • For INOUT and OUT IDL parameters, XML Response nodes are generated.

  • Fault trees (Error trees) are generated, see Fault Document Manager under XML Response Page.

Format, length and default values of the XML nodes are set according to the IDL parameter:

In the table below, the following metasymbols and informal terms are used for the IDL.

  • The metasymbols "[" and "]" enclose optional lexical entities.

  • The informal term number (or in some cases number1.number2) is a sequence of numeric characters, for example 123.

Software AG IDL Description XML Data Type
Anumber Alphanumeric Variable-length string node with maximum length.
AV Alphanumeric variable length Variable-length string node.
AV[number] Alphanumeric variable length with maximum length Variable-length string node with maximum length.
Bnumber Binary binary node with length of binary representation (base 64)
BV Binary variable length Variable-length binary node.
BV[number]   Variable-length binary node with maximum length.
D Date XML date node. The length depends on the specified time pattern length. This is trimmed, and what is included in single quotes will be counted (without the single quotes). For example: 'T'HH:mm:ss has length=9.
F4 Floating point (small) float node of length 32.
F8 Floating point (large) float node of length 64.
I1 Integer (small) integer node of length 4.
I2 Integer (small) integer node of length 6.
I4 Integer (small) integer node of length 11
Knumber Kanji Variable-length string node with maximum length.
KV Kanji variable length Variable-length string node.
KV[number] Kanji variable length with maximum length Variable-length string node with maximum length.
L Logical Boolean node.
Nnumber1[.number2] Unpacked decimal number node. If number > 0, length increased by 2, otherwise by 1.
NUnumber1[.number2] Unpacked decimal unsigned number node. If number > 0, length increased by 2, otherwise by 1.
Pnumber1[.number2] Packed decimal number node. If number > 0, length increased by 2, otherwise by 1.
PUnumber1[.number2] Packed decimal unsigned number node. If number > 0, length increased by 2, otherwise by 1.
T Time dateTime node. The length depends on the specified time pattern length. This is trimmed, and what is included in single quotes will be counted (without the single quotes). For example: yyy-MM-dd'T'HH:mm:ss has length=19.
Unumber Unicode Variable-length Unicode node with maximum length.
UV Unicode variable length Variable-length Unicode node.
UVnumber Unicode variable length with maximum length Variable-length Unicode node with maximum length.

The resulting XML structures can be modified, see Mapping IDL to XML Manually.

The automatic mapping process can be fine-tuned by mapping parameters to be set before mapping.

For information on the attribute-preferred and element-preferred strategies see XML Structures and IDL-XML Mapping in the XML/SOAP Wrapper documentation.

Mappings

For SOAP additional type attributes are generated. They describe the XML Schema compliant data types of the elements.

SOAPAction

The SOAPAction tag in the SOAP header will be moved to the HTTP header. The SOAPAction element is generated automatically with SOAP mapping. Verify the default setting. If SOAPAction is missing, insert it: select the SOAPHeader node and add a new child node with the name SOAPAction. Then select the new element node with the name SOAPAction, open the XML Details panel and enter the value for that HTTP header into the Default attribute field. The NullValueSuppression property should have the value "Suppress Element".

Using Mapping Parameters

Start of instruction setTo use the mapping parameters

  1. Switch to the Mapping Parameters page or define the XML Mapping Editor preferences.

  2. Check the check boxes, dialog boxes and complete the text fields you need.

Mapping Parameters

The mapping parameters are on the following sections.

Document Style

graphics/idl2xml_style.png

Parameter Description
Generate Array Envelope Element Determines whether for each array a surrounding additional element (envelope) is generated or not.
WSDL Style Prepare the SOAP Mapping for selected WSDL Style. Possible values: document/literal or rpc/encoded.

Encoding Settings

graphics/idl2xml_encoding.png

Parameter Description
XML Default Encoding This encoding is used for the sent XML/SOAP document if the box Use incoming encoding is not checked (for XML-based clients), or if the RPC Server for XML/SOAP is used.
Use Incoming Encoding Check this box to enable the XML/SOAP Wrapper to use same encoding for the incoming document as for the outgoing document.

Null Value Suppression

graphics/idl2xml_null_value.png

Parameter Description
Enable null value suppression Switch on/off the null value suppression.
Simple Element Suppress Elements. Possible Values: No Suppression or Suppress Element.
Simple Attribute Suppress Attributes. Possible Values: No Suppression or Suppress Attribute.
Array Types Suppress Array Types. Possible Values: No Suppression, All empty cells or Cells at end (Trim).
Complex Types Suppress Complex Types. Possible Values: No Suppression (no special handling of complex types - null value suppression defined for 'Simple Element' is used), or Suppress Group Elements.

For more details on null value suppression, see Null Value Suppression under Writing Advanced Applications with the XML/SOAP Wrapper.

Namespace Definitions

graphics/idl2xml_namespace_def.png

Parameter Description
Namespace Definitions Table Manage all Namespaces with prefix and URI.

New namespace definitions can be entered with Add... . To change an entry choose Edit... . All selected entries can be deleted with the Remove button. With the Default button you mark the Namespace used for the Payload Root node, e.g. in XML Mapping the Root Element and in SOAP Mapping the first element in the SOAP-Body.

The Edit dialog (and similar Add dialog) looks like:

graphics/idl2xml_namespace_edit.png

Start of instruction setTo map automatically with your preferred result

  • On the Mapping section of the Overview Page choose the preferred Mapping style and press the Generate All button.

The various generated XML Structures can be modified, see Mapping IDL to XML Manually.

If errors/warnings have occurred, the Validity Check window will be displayed. The errors/warnings for all programs will be found in the Problems View. In the first line of this View you will find a short summary of the problems. If you click on an error/warning, the XML structure for it is displayed with the invalid node highlighted.

Warning:
There are rare cases when the SOAP default mapping generates warnings (for example for IDL files with cascaded arrays). A dialog is displayed stating that illegal mappings have been generated. The warnings mostly deal with duplicate element names. You may ignore them as long as you do not use the mapping for WSDL or XML Schema. For details, see the Problem View.

Mapping IDL to XML Manually

This section covers the following topics:

Summary of Steps

Start of instruction setTo map an IDL file manually to an XML structure or modify an IDL-XML mapping file

  1. Choose direction (XML Request or XML Response).

  2. Add/modify XML nodes.

  3. Map IDL nodes to XML nodes.

Choosing XML Request or XML Response XML Structure

Start of instruction setTo choose the XML Structure

  1. Select the XML Request to get the IDL IN and INOUT Parameter Mapping.

  2. Select the XML Response to get the IDL OUT and INOUT Parameter Mapping.

Adding an XML Node

Start of instruction setTo create a child node to an existing (selected) XML node

  1. Click on the existing node.

  2. From the context menu, choose New child node.

    A dialog window is displayed.

    graphics/idl2xml_new_node.png

  3. Enter the new node's name and type (element or attribute) and use OK.

Start of instruction setTo insert a new node before or after an existing (selected) XML node

  1. From the context menu, choose Insert before or Insert after, respectively.

    A dialog window is displayed.

  2. Enter the new node's name and type (element or attribute) and use OK.

Note that new attribute nodes do not have a format, length and default property assigned. You must assign at least a format to the node before saving the mapping file. See Quick Test Details Dialog. Use the Validity Checks to make sure that all nodes have the necessary properties.

Grouping XML Elements or Attributes

You can introduce new elements by grouping one or more existing elements or attributes. See also XML Structures and IDL-XML Mapping in the XML/SOAP Wrapper documentation.

Start of instruction setTo group XML elements or attributes

  • Add a new XML part and move the existing nodes into the new node.

You can use cut-and-paste or a drag-and-drop operation to reorder the XML parts. Four move functions are available in the XML context menu: Bring to top, Bring to bottom, Move up, Move down, which are equivalent to drag-and-drop operation. See Using the Context Menu and Using Drag-and-drop.

Mapping an IDL Node to an XML Node

Start of instruction setTo add (or modify) an IDL-XML node mapping link

  1. Click into the Mapped to field in the XML Node Properties Dialog.

    A dialog displays the possible IDL mapping links.

  2. Choose one of the menu items to map the IDL node to the XML node.

    If the XML node had a previous IDL mapping link, it is released.

    Or:
    Use a drag-and-drop operation to move the IDL node to be mapped directly to the XML node. If the XML node had a previous IDL mapping link, it is released. See Using Drag-and-drop.

    Or:
    Use the keyboard to tab into the Mapped to text field, and press Enter. This will open the dialog Mapped to. Select a mapping link from the list and use the OK button to confirm. Use the Cancel button to cancel the action.

IDL-XML mapping uses the full path notation. This notation is a slash-separated list of IDL node names, starting with the program name, ending with the addressed IDL node, and containing all IDL nodes between program and the IDL node (the path from the program name to the node).

Start of instruction setTo modify the format of the XML node

The dialog box contains the possible format values. You cannot add new format codes.

Unmapping XML Nodes

Start of instruction setTo unmap XML nodes

  1. Select one or more XML nodes mapped to IDL node(s).

  2. From the context menu, choose Unmap.

This will unlink the IDL and XML nodes.

Deleting Nodes

Start of instruction setTo delete arbitrary elements or attributes

  1. Select the node(s) to delete.

  2. From the context menu, choose Delete. If nodes have descendants, the following window is displayed:

    graphics/idl2xml_delete.png

  3. To delete the subtree attached to the node, choose Yes.

  4. To keep the elements of the subtree and move them one level higher, choose NO.

Warning:
If IDL nodes are not mapped in the incoming XML request, the result for the runtime component is that the corresponding IDL parameters are filled with zero strings.

Deleting XML Structures

Start of instruction setTo delete the complete IDL to XML mapping (all XML Structures)

  • In the mapping menu, choose the item New mapping for all programs.

Start of instruction setTo delete the currently selected XML Structures

  • In the mapping menu, choose the item New mapping.

Modifying the Element or Attribute Name

In the automatically mapped structures the XML node names are built from the IDL parameter names.

Start of instruction setTo change the node name

To avoid accidental changes, there is no other way to modify the name.

When the name of an XML part is modified, various checks of the XML structure are performed, e.g. attribute name duplication, IDL mapping legality. The IDL-XML-mapping link is not influenced by the name change.

Changing Elements to Attributes and Vice Versa

You have the possibility to switch the node type between element and attribute. Note that attributes may not have descendant nodes and namespace definitions.

Start of instruction setTo switch between elements and attributes

  • From the context menu, choose Set to Element and Set to Attribute.

This function works for multiple nodes, too.

Important:
Arrays must always be modelled with elements.

Assigning Default Values

Every XML part can contain default values in case elements are missing in the incoming XML document.

Start of instruction setTo set the default values

Defining the XML Encoding

Start of instruction setTo define default encoding for IDL to XML mapping

  1. Open the IDL properties and choose the XML tab

    graphics/idl2xml_editor.png

  2. Modify the Encoding Settings section:

    • For scenarios with the Listener for XML/SOAP:

      • XML Default Encoding (default: UTF-8)
        This is the encoding that will be used to write the mapping file itself. If Use incoming Encoding is disabled, this encoding will be used for the response documents.

      • Use incoming Encoding (default: checked)
        If this check box is checked, the same encoding of the incoming document will be used for the response documents. The XML Default Encoding is not used.

    • For scenarios with the RPC Server for XML/SOAP:

      • XML Default Encoding (default: UTF-8)
        This is the encoding that will be used to write the mapping file itself. This encoding will be used for the outgoing XML documents.

      • Use incoming Encoding
        Not used.

Validity Checks

The Validity check is automatically performed for automatic mapping and when an existing IDL-XML mapping file is opened, but can also be performed manually.

The following validity checks are available:

  1. Checks that all elements have unique tags - produces warnings

  2. Checks that all attributes of an element have unique names (mandatory)

  3. Checks that the generated XML parts have correct property values (mandatory), e.g. minimum occurrences less than or equal to maximum occurrences

  4. Checks that the IDL mapping is valid (mandatory) and the IDL parameters are not mapped to multiple XML parts (warning)

  5. Checks that all IDL parameter nodes are mapped to one or more XML parts, (so that the runtime component finds XML values for all IDL parameters or vice versa) (warning)

The first four of the checks apply to XML tree nodes, i.e. search for invalid settings or mapping rules of XML elements or attributes. The fifth check applies to the IDL tree.

The check messages may be divided into warnings (message text starts with (W)) and errors. Warnings can even be caused by automatic mapping. Generally, they can be ignored. Errors should not be ignored.

Generating an XML Schema from IDL-XML Mapping

Start of instruction setTo save the XML structure tree as an XML Schema (XSD) document

  • An XML Schema can be generated from the current XML Mapping using the context menu of the XMM file. The XML Schema style "Russian Doll" or "Venetian Blind" can be selected in the preferences.

See Mapping IDL Data Types to an XML Schema (XSD) for mapping of IDL data types to XSD.

See also XML Schema Parser Standards Conformance and XML Schema Writer Standards Conformance under XML Schema Standards Conformance (XML/SOAP Wrapper) in the XML/SOAP Wrapper documentation.