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:
This section covers the following topics:
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 "]" surround 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 |
|---|---|---|
A |
Alphanumeric | Variable-length string node with maximum length.
|
AV |
Alphanumeric variable length | Variable-length string node.
|
AV[ |
Alphanumeric variable length with maximum length | Variable-length string node with maximum length.
|
B |
Binary | binary node with length of binary representation (base 64)
|
BV |
Binary variable length | Variable-length binary node.
|
BV[ |
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
|
K |
Kanji | Variable-length string node with maximum length.
|
KV |
Kanji variable length | Variable-length string node.
|
KV[ |
Kanji variable length with maximum length | Variable-length string node with maximum length.
|
L |
Logical | Boolean node.
|
N |
Unpacked decimal | number node. If number > 0, length increased by 2, otherwise by 1.
|
NU |
Unpacked decimal unsigned | number node. If number > 0, length increased by 2, otherwise by 1.
|
P |
Packed decimal | number node. If number > 0, length increased by 2, otherwise by 1.
|
PU |
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.
|
U |
Unicode | Variable-length Unicode node with maximum length.
|
UV |
Unicode variable length | Variable-length Unicode node.
|
UV |
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.
For SOAP additional type attributes are generated. They describe the XML Schema compliant data types of the elements.
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".
To use the mapping parameters
Switch to the Mapping Parameters page or define the XML Mapping Editor preferences.
Check the check boxes, dialog boxes and complete the text fields you need.
The mapping parameters are on the following sections.
| 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. |
| 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. |
| 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.
| Parameter | Description |
|---|---|
| Namespace Definitions Table | Manage all Namespaces with prefix and URI. |
New namespace definitions can be entered with . To change an entry choose . All selected entries can be deleted with the button. With the 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:
To map automatically with your preferred result
On the Mapping section of the Overview Page choose the preferred Mapping style and press the 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. |
This section covers the following topics:
To map an IDL file manually to an XML structure or modify an IDL-XML
mapping file
Choose direction (XML Request or XML Response).
Add/modify XML nodes.
Map IDL nodes to XML nodes.
To choose the XML Structure
Select the XML Request to get the IDL IN and INOUT
Parameter Mapping.
Select the XML Response to get the IDL OUT and INOUT
Parameter Mapping.
To create a child node to an existing (selected) XML node
Click on the existing node.
From the context menu, choose .
A dialog window is displayed.
Enter the new node's name and type (element or attribute) and use .
To insert a new node before or after an existing (selected) XML node
From the context menu, choose or , respectively.
A dialog window is displayed.
Enter the new node's name and type (element or attribute) and use .
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.
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.
To 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: , , , , which are equivalent to drag-and-drop operation. See Using the Context Menu and Using Drag-and-drop.
To add (or modify) an IDL-XML node mapping link
Click into the Mapped to field in the XML Node Properties Dialog.
A dialog displays the possible IDL mapping links.
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 button to confirm. Use the
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).
To modify the format of the XML node
Select an entry from the dialog box in the XML Node Properties Dialog.
The dialog box contains the possible format values. You cannot add new format codes.
To unmap XML nodes
Select one or more XML nodes mapped to IDL node(s).
From the context menu, choose .
This will unlink the IDL and XML nodes.
To delete arbitrary elements or attributes
Select the node(s) to delete.
From the context menu, choose . If nodes have descendants, the following window is displayed:
To delete the subtree attached to the node, choose .
To keep the elements of the subtree and move them one level higher, choose .
|
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. |
To delete the complete IDL to XML mapping (all XML Structures)
In the mapping menu, choose the item .
To delete the currently selected XML Structures
In the mapping menu, choose the item .
In the automatically mapped structures the XML node names are built from the IDL parameter names.
To change the node name
Choose from the context menu.
Or:
Double-click on the name field in the XML Node Properties Dialog.
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.
You have the possibility to switch the node type between element and attribute. Note that attributes may not have descendant nodes and namespace definitions.
To switch between elements and attributes
From the context menu, choose and .
This function works for multiple nodes, too.
Important:
Arrays must always be modelled with elements.
Every XML part can contain default values in case elements are missing in the incoming XML document.
To set the default values
In the XML Node Properties Dialog, enter a Default Value.
To define default encoding for IDL to XML mapping
Open the IDL properties and choose the XML tab
Modify the Encoding Settings section:
XML default encoding (default: UTF-8)
This is the encoding that will be used to write the mapping file
itself and if there are no XML declarations in the incoming document. Together
with the next property (Use incoming XML encoding) this encoding will be used
for the response documents.
Use incoming XML encoding (default: checked)
If this check box is checked, the last two properties are disabled
and the same encoding of the incoming document will be used for the response
documents.
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:
Checks that all elements have unique tags - produces warnings
Checks that all attributes of an element have unique names (mandatory)
Checks that the generated XML parts have correct property values (mandatory), e.g. minimum occurrences less than or equal to maximum occurrences
Checks that the IDL mapping is valid (mandatory) and the IDL parameters are not mapped to multiple XML parts (warning)
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.
To save the XML structure tree as an XML Schema (XSD) document
The current XML Mapping can be exported as XML Schema via 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.
