Version 9.5 SP1
 —  EntireX XML Mapping Editor  —

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:

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

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

IDL XML
IDL parameters with type A, K Generates XML string nodes with same length.
IDL parameters with type U Generates XML Unicode nodes with the same length.
IDL parameters with type B Generates XML binary nodes with length of binary representation (base 64).
IDL parameters with type I1, I2, I4 Generates XML integer nodes, length 4, 6, 11, respectively.
IDL parameters with type F4, F8 Generates XML float nodes, length 32 and 64, respectively.
IDL parameters with type L Generates XML Boolean nodes.
IDL parameters with type N, P Generates XML number nodes, length increased by 2.
IDL parameters with type D, T Generates XML date and dateTime nodes. 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. Example: yyyy-MM-dd'T'HH:mm:ss has length=19.
Variable-sized data types AV,KV Are mapped to variable-sized strings.
Variable-sized data types UV Are mapped to variable-sized unicodes.

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 XML encoding is not checked (for XML-based clients), or if the XML/SOAP RPC Server 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 in 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

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.

Top of page

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

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)

Start of instruction setTo delete the currently selected XML Structures

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

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

Top of page

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:

Top of page

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.

Top of page

Exporting the IDL-XML Mapping to an XML Schema

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

See also XML Schema Parser Standards Conformance and XML Schema Writer Standards Conformance.

Top of page