EntireX	Version 9.7	SEARCH   CONTENTS   |   PDF PAGE   PDF BOOKS   |   HOME   UP   PREV   NEXT

This document covers the following topics:

• Starting the XML Mapping Editor

• The XML Mapping Editor Pages

• XML Schema Export

• XML Mapping Editor Settings

• Removing Unused Namespaces

See also Using the XML Tester.

Starting the XML Mapping Editor

To start the XML Mapping Editor

In the EntireX Workbench

• Double click on an XMM file.

  Or:
  Select an IDL or XMM file and choose Open With > EntireX XML Mapping Editor.

  If the XMM file for the selected IDL file exists, the XML Mapping Editor loads this. The Generate button is disabled because a mapping exists.

  

  If no XMM file exists for the IDL file, the mapping style is set to "SOAP" as default value. Choose the required mapping style and press Generate.

  

To close the XML Mapping Editor

• From the File menu, choose Close.

  Or:
  Click the Close icon in the editor title bar.

If the current XML mapping has not yet been saved, a dialog box appears from which the close operation can be stopped or the IDL-XML mapping can be saved. An XML mapping that is not clean is indicated with a leading asterisk in the file name, displayed in the editor title.

The XML Mapping Editor Pages

• Overview Page

• XML Request Page

• XML Response Page

• Mapping Parameters Page

• XML Sample Documents Page

Overview Page

The Overview Page is the central page and provides sections for file information, the most important mapping parameters, mapping generation, testing and validation.

These sections are:

• General Information
  This section describes the names and locations of the selected XML mapping (XMM) file and the related IDL file.

• Mapping Parameters
  Provides the Namespace and Null Value Suppression controls and contains a link to the Mapping Parameters Page.

  Note:
  Press Update Null Value Suppression to apply the mapping parameters (see Mapping Parameters Page) to a generated mapping.

• Mapping
  Starts the mapping generation for all programs.

  Note:
  Existing mappings will be overwritten!

• Testing
  Allows you to launch the XML Tester in Quick mode or HTTP mode.

• Validation
  Performs validity checks in all programs and reports the result in a new dialog. Detected problems will be displaced in the Problems view.

XML Request Page

This page contains the Mapping tree of the XML Request, which is linked together by mapping paths with the IDL tree in the Outline view.

The XML Request shows the XML tree loaded or created so far for the selected IDL program. The XML tree can be modified in various ways. See IDL to XML Mapping with the XML Mapping Editor.

The Outline view shows the IDL tree of the currently selected IDL file. The IDL tree display has the same functionality as the IDL Editor's tree display; however, due to the fact that every IDL program must be separately mapped, only one of the IDL program tree nodes can be expanded.

Use the right mouse button to display the context menu. Double-click on a tree node to display detailed information on that node. The following keyboard options are also available in the XML request mapping area:

XML Node Properties Dialog

The XML Node Properties dialog contains the XML node details, the bottom panel contains namespace settings.

To open the XML Node Properties Dialog

• Double-click on an XML node in the tree display.

  Or:
  Choose the Properties menu item in the context menus.

  Or:
  Select an XML tree node and press Enter.

The XML Node Properties can be modified. The node details panel consists of two subpanels.

The upper panel contains the following:

Correlation of Occurrence Setting and Null Value Suppression

The value for null value suppression has a higher priority than the occurrence setting of affected elements or attributes. The following rules apply:

1. NVS="Suppress Element"/"Suppress Attribute"
   Setting NVS to Suppress Element" or "Suppress Attribute" results in a value of minimum occurrence of zero, which makes it optional.

2. NVS="No Suppression"
   Setting NVS to "No Suppression" means that the element/attribute is always displayed so the value of #minOccur must be 1 - otherwise the element/attribute would be optional and could be suppressed.

3. NVS for arrays
   For arrays, the dependency of minimum occurrence and Null Value Suppression is more complex:

   1. NVS set to "No Suppression"
      For an array with fixed size the setting is #minOccur = #maxOccur = #array size.

      An array with variable size will contain all non-suppressable elements, but at least #minOccur elements. Empty elements will be generated to guarantee the number of #minOccur.

   2. NVS set to value other than "No Suppression"
      The number of array elements is at least #minOccur (empty elements will be generate and appended if number of elements is lower than #minOccur).

The lower panel is only available for element nodes and contains namespace-related properties:

Using the Context Menu

The context menu of the XML tree enables you to modify the XML structure. It contains menu items to insert new nodes, remove or rename nodes, remove an IDL mapping, change the XML part type to element or attribute, move the selected node to the top or bottom of the current subtree, move the selected node up or down within the subtree, or show the XML Node Properties dialog.

To open the context menu

• Select the XML tree node and click the right mouse button.

Using Drag-and-drop

You can use drag-and-drop operations within the XML tree instead of move and cut-and-paste. Select a node (even with subnodes) and drag it to another place. The dragged subtree is then inserted after, before or under the corresponding drop node (to insert it under the drop node, use the Ctrl key as a toggle).

Some drag-and-drop operations are illegal, e.g. dragging a node into one of its descendant nodes (children). This would result in a cyclic reference and is thus forbidden.

Dropping a dragged node into an attribute node will convert the attribute node to an element node. This is because attributes may not have descendant nodes.

Warning: If you drag a subtree into or out of an array, the IDL mapping links of all nodes of that subtree will be deleted. This is because the cardinality of the node occurrence has changed, and the resulting IDL mapping is very likely to be incorrect.

Drag-and-drop from an IDL Tree Node to the XML Tree

If you drag an IDL tree node onto an XML tree node, the IDL-XML mapping link for that XML node is changed. The new XML-IDL mapping of this XML tree node is to the dragged IDL node. The IDL tree is not changed.

This is a quick way to change IDL mappings for XML parts. Note that there is no immediate check for duplicate assignment of an IDL node; however, the validity checks will detect it.

XML Response Page

This page contains the Mapping Tree of the XML Response, which is linked together by mapping paths with the IDL tree in the Outline View. The page extends the XML Request page with an additional section, Fault Document Manager, at the bottom.

The Fault Document Manager contains the entry for the XML Fault Response Document. By selecting the entry, the Edit... button will be enabled. Press Edit... to display the following dialog:

The same operations as for the XML Request and XML Response trees are possible. Confirm the changes with OK, or click Cancel to exit without changes.

Mapping Parameters Page

This page covers the Mapping Parameters to affect the Mapping Structure. The default values for that page will be managed in the preferences and can be loaded by using the Restore Defaults button in the upper right corner.

⁽¹⁾ For more details on null value suppression, see below or Null Value Suppression in Writing Advanced Applications with the XML/SOAP Wrapper.

XML Sample Documents Page

This page allows the generation and modification of XML Sample Documents. They can be used to test the Mapping by sending the generated Request Document to the XML Tester. Another useful point is to compare the XML Sample Document structure with the real XML Document returned by your application to detect differences, for example Namespace Definitions, typos or anything else.

All generated XML Sample Documents can be stored in parallel to the selected XMM file by using the Save All toolbar button in the upper right corner of this page or the Save command in the context menu. The generated file name is built as follows:

[xmm name] .[library name].[program name].[direction (request | response)].xml

For example: example.EXAMPLE.CALC.request.xml

If a file already exists, a dialog will prompt you for confirmation to overwrite it.

Using the Context Menu of XML Samples

The XML Samples context menu allows the generation of XML Sample Documents.

There are two different menus:

• Library or Program is selected

  

  Generate All means both directions (Request and Response). When a Library is selected, the commands here will be inherited by all Programs.

• Request or Response Document is selected

  

  The XML Tester... command sends the selected XML Sample Document to the XML Tester as Quick Test and enters the name of the XMM file.

XML Schema Export

The current XML Mapping can be exported as XML Schema, using the context menu of the XMM file. The XML Schema style "Russian Doll" or "Venetian Blind" can be selected in the preferences.

The generated XML Schema files will be stored in parallel to the selected XMM file, where one file represents the direction (request or response) and the defined prefixed element.

For example: a SOAP mapping creates four files from the example CALC program: two prefixes ("SOAP-ENV" and "m"), and two directions (request and response). The generated file name is built as follows.

[xmm name].[library name].[program name].[direction (request | response)][(optional).additional prefix].xsd

Example

• example.EXAMPLE.CALC.request.xsd

• example.EXAMPLE.CALC.request.m.xsd

• example.EXAMPLE.CALC.response.xsd

• example.EXAMPLE.CALC.response.m.xsd

If a file already exists, a dialog will prompt you for confirmation to overwrite it.

XML Mapping Editor Settings

The preference page XML Mapping Editor manages the default values.

For XML Schema the style "Russian Doll" or "Venetian Blind" can be selected.

All other parameters are described under Mapping Parameters.

Removing Unused Namespaces

To remove one or more unused namespaces

1. Open the XML Mapping Editor for the XMM file.

2. Select tab XML Request.

   

3. Select the element that defines namespace(s) to be removed.

4. From the context menu, choose Properties.

   

5. Select (unused) namespace entry/entries in list and choose Remove.

6. Press OK.

7. Repeat these steps for the XML response (select the XML Response tab and repeat the steps above).

8. Save the XMM file.

9. Switch to XML Samples tab, which shows the following:

   

10. The XMM file defines the following:

    ...
    <FromXml>
    <Method relatedIdlLibrary="EXAMPLE" relatedIdlProgram="CALC" encoding="UTF-8"
    useIncomingEncoding="true">
    <XmlNode name="Envelope" length="0" min="1" max="1" namespacePrefix="SOAP-ENV"
    nullSuppression="NVS_NONE" nullValue="" >
    <XmlNamespaceDef prefix="SOAP-ENV" uri="http://schemas.xmlsoap.org/soap/envelope/"/>
    <XmlNamespaceDef prefix="SOAP-ENC" uri="http://schemas.xmlsoap.org/soap/encoding/"/>
    <XmlNode name="Header" length="0" min="1" max="1" namespacePrefix="SOAP-ENV"
    nullSuppression="NVS_NONE" nullValue="" >
    <XmlNode name="SOAPAction" format="string" type="xsd:string" length="0" min="1" max="1"
    default="CALC" nullSuppression="NVS_NONE" nullValue="" programNode="ev" >
    </XmlNode>
    ...

www.softwareag.com

Copyright © 1997-2014 Software AG, Darmstadt, Germany.

SEARCH   CONTENTS   |   PDF PAGE   PDF BOOKS   |   HOME   UP   PREV   NEXT