EntireX XML Tester

This document covers the following topics:


Introduction to the EntireX XML Tester

Using the EntireX XML Tester you can send an XML document to the EntireX Listener for XML/SOAP.

The EntireX XML Tester supports drag-and-drop editing, and you can restore the last used session within a workspace. If the mapping file has changed, the views for request and response are cleared.

The EntireX XML Tester is provided by the Designer as an Eclipse View and can be opened from the XML Mapping Editor or XML/SOAP Wrapper. It is also accessible from Windows > Show View > Other... > Software AG > XML Tester. The following test modes are available:

  • Direct Test (Using the Java Interface)

  • HTTP Test (Using the EntireX Listener for XML/SOAP)

See sample screen and description of options below.

graphics/xmlTester_overview.png

EntireX XML Tester Options

Name Type Description
Direct Test Check box Check this box to test the Java interface of the XML/SOAP Runtime. If checked, the Settings action will open the Direct Test Details dialog.
XMM or AAR File Text field The AAR file, which contains one or more mapping files (XMM files), or the XMM file, which contains the mapping information. Accept absolute path. If the file does not exist, the action Create Sample XML... is disabled. When the file is found, the Broker ID and Server Address are read and the corresponding fields in the Direct Test Details dialog are filled.
Combo box

Behavior depends on content of field XMM or AAR File:

  • If this field contains an AAR file, this combo is enabled and filled with all the mappings stored in the archive. Select the mapping you want from the list.

  • If this field contains an XMM file, the combo box is disabled.

Browse... Button Open a File open dialog to select the XMM or AAR file from the file system.
HTTP Test Check box Check this box to test the HTTP interface (EntireX Listener for XML/SOAP) of the XML/SOAP Runtime. If checked, the Settings action will open the HTTP/HTTPS Parameters dialog.
HTTP URI to contact Combo box URI of the EntireX Listener for XML/SOAP. Will store the last ten called URLs.
Input XML Document to send Text field File name of the XML Document to be sent.
Browse... Button Open a File open dialog to select the XML Document file from the file system.
Create Sample XML... Action graphics/xmlTester_createSampleAction.png Open the Create Sample XML... dialog, see below. If the text file for the XMM file does not contain a valid file path, the Create Sample XML... button is disabled.
input - area Tree/Text/Raw view Input field for the XML data to be sent to the Broker, this area is filled with the text/tree representation of the selected file, see Input XML Document to send. If empty, the Play action is disabled.
output - area Tree/Text/Raw view Output field for the XML data response from the Broker. By default, the response will be displayed in platform encoding. But if the XML data request contains a valid encoding in the XML declaration, this encoding will be used and a tooltip text will inform you of this. This view will also display the status and errors.
Settings Action graphics/xmlTester_settingsAction.png Open either Direct Test Details or HTTP/HTTPS Parameters dialog. See Direct Test and HTTP Test above.
Play/Stop Action graphics/xmlTester_playAction.png / graphics/xmlTester_stopAction.png Start/stop the test. This action is disabled if there is no text in the input - area.
Reset Action graphics/xmlTester_resetAction.png Reset the input and output areas.

Direct Test Details Dialog

Use the Direct Test Details dialog to change the Direct Test parameters. The Broker ID, Server Address, the Security Settings, the Natural Settings can be modified for this EntireX XML Tester session. Compression Level is a non-editable box that contains all possible values. Broker ID and Server Address are editable dialog boxes and hold the last five used values. Use the Reliable RPC check box to turn reliable messaging on or off (mode is AUTO-COMMIT). See Reliable RPC.

graphics/xmlTester_directTest_parameters.png

HTTP/HTTPS Parameters Dialog

With the HTTP Header tab you can add more information for the call and set the SOAPAction. An entry must be selected to be active. The Value box holds the last five used values for the corresponding property. It is editable, which means you can change a value by clicking directly in the table.

graphics/xmlTester_httpHeader.png

With the HTTPS Parameters tab you can set parameters required for an HTTPS connection. An entry must be selected to be active. The Value box holds the last five used values for the corresponding property. It is editable, which means you can change a value by clicking directly in the table.

graphics/xmlTester_httpsParameters.png

Add New HTTP Parameter Dialog

With the Add new HTTP(S) Parameter dialog you can add a new HTTP or HTTPS parameter. All Software AG's predefined HTTP parameters are listed in the Key box. For HTTPS, the Key box contains predefined properties for HTTPS communication.

Edit HTTP Parameter Dialog

With the Edit HTTP(S) Parameter dialog you can change the value of a property. The Value box is editable and holds the last five used values. The Key value for all predefined properties cannot be modified.

graphics/xmlTester_editHttpParameter.png

Using the EntireX XML Tester

Using the EntireX XML Tester you can send an XML document to the EntireX Listener for XML/SOAP.

Start of instruction setTo open the EntireX XML Tester

  • In perspectives other than EntireX, choose Window > Show View > EntireX XML Tester, in other perspectives, choose Window > Show View > Other ... > Software AG > XML Tester.

    Or:
    Choose Window > Open Perspective > Other... and select EntireX Perspective. The EntireX XML Tester view is part of this perspective.

    Or:
    In the XML Mapping Editor, switch to the Overview page, choose Direct Test or HTTP Test in the testing section.

    Or:
    In the XML Mapping Editor, switch to page XML Samples, select one document, choose EntireX XML Tester in the context menu.

Start of instruction setTo run a test

  1. Load the mapping information. In field XMM or AAR File, enter the absolute path to the AAR or XMM file that is being tested (you can use the Browse... button or a drag-and-drop operation). If you enter an AAR file, all mappings contained in the archive are listed in the combo box next to the XMM or AAR File field.

    graphics/xmlTester_aar_input.png

  2. Select the testing interface (Java or HTTP):

    • Java interface: the XMM or AAR File field must contain the full path and name of an XMM or AAR archive. Choose the Direct Test option to use this interface.

    • HTTP interface: enter the name of the URI of the running EntireX Listener for XML/SOAP. Choose the HTTP Test option to use this interface.

  3. Complete the input area:

    • Type your XML document.

    • Use the Create Sample XML... button and follow the dialog.

      Note:
      If the IDL file contains only one library with one program, this is used for the sample generation without opening the dialog.

      Example dialog:

      graphics/xmlTester_sampleGeneration.png

    • Load sample document, using drag-and-drop operation on the sample page of XML Mapping Editor or file browser.

      graphics/xmlTester_dragAndDrop.png

      The following tabs are available:

      • The Text View tab will try to color the request syntactically, making the XML easier to read.

      • The Raw View tab is initially empty. When the first request is sent, it is filled with the exact message sent together with information on the request method and the used HTTP headers with their values.

      • From then on the Raw View is displayed and is updated with the last sent request.

    • Select an existing XML document (you can use the Browse button) and enter it in the field Input XML file to send.

  4. If the testing interface is Java, the Settings action will open the Direct Test Details dialog.

    The dialog contains the three tabs with the following settings:

    • Main

    • Broker Security

    • Natural Security

    See Direct Test Details Dialog.

  5. If using option HTTP Test, the Settings action will open the HTTP/HTTPS Parameters dialog. The dialog contains two tabs with settings for the HTTP call:

    • HTTP Header

    • HTTPS Parameters

    See HTTP/HTTPS Parameters Dialog.

  6. Send the request by choosing action Play. If the testing interface is HTTP, the Sending request dialog appears. Here you have several options:

    • hide the dialog by pressing Run in Background button

    • cancel the request. This will terminate the session with the server

    • show details about all running Eclipse jobs

    A progress bar on the Eclipse status bar shows to indicate that the request is being sent.

    graphics/xmlTester_sendingRequest.png

    If you used the Direct Test option, you cannot cancel the request.

  7. When a response is received, it is displayed in the output area. Errors are also displayed in the output area.

    The Text View tab displays the XML response as formatted and syntactically colored text. The Raw View tab displays the response "as is". Information on the used request method, response code and HTTP headers with their values is displayed for the XML response.

Using the Broker and RPC User ID/Password

EntireX supports two user ID/password pairs: a broker user ID/password pair and an (optional) RPC user ID/password pair sent from RPC clients to RPC servers. With EntireX Security, the broker user ID/password pair can be checked for authentication and authorization.

The RPC user ID/password pair is designed to be used by the receiving RPC server. This component's configuration determines whether the pair is considered or not. Useful scenarios are:

  • Credentials for Natural Security

  • Impersonation under z/OS (CICS, Batch, IMS) | z/VSE (CICS)

  • Web Service Transport Security with the RPC Server for XML/SOAP, see XML Mapping Files

  • Service execution with client credentials for EntireX Adapter Listeners, see Configuring Listeners

  • etc.

Sending the RPC user ID/password pair needs to be explicitly enabled by the RPC client. If it is enabled but no RPC user ID/password pair is provided, the broker user ID/password pair is inherited to the RPC user ID/password pair.

The check box Enable Natural Logon (see below) enables sending the RPC user ID/password pair in Direct Test mode. In HTTP test mode, the HTTP parameter exx-natural-security has to be set. If you do so, we strongly recommend using SSL/TLS. See SSL/TLS and Certificates with EntireX.

Start of instruction setTo use the broker and RPC user ID/password with Direct Test mode

  1. Specify a broker user ID and broker user password in the Broker Security tab.

  2. Activate the Natural tab and check the check box Enable Natural Logon to enable sending the RPC user ID/password pair.

  3. If different user IDs and/or passwords are used for broker and RPC, enter RPC User ID and RPC User Password in the Natural tab to provide a different RPC user ID/password pair.

  4. By default the library name sent to the RPC server is retrieved from the IDL file (see library-definition under Software AG IDL Grammar in the IDL Editor documentation). The library name can be overwritten. This is useful if communicating with a Natural RPC server. Specify a Natural library in the Natural tab.

Start of instruction setTo use the broker and RPC user ID/password with HTTP Test mode

  1. Activate the HTTP Header tab.

  2. Add exx-user and exx-password as HTTP parameters.

  3. Add HTTP parameter exx-natural-security to enable sending the RPC user ID/password pair.

  4. If different user IDs and/or passwords are used for broker and RPC, add exx-rpc-user and exx-rpc-password as HTTP parameters to provide a different RPC user ID/password pair.

  5. By default the library name sent to the RPC server is retrieved from the IDL file (see library-definition under Software AG IDL Grammar in the IDL Editor documentation). The library name can be overwritten. This is useful if communicating with a Natural RPC server. Specify a Natural library in HTTP parameter exx-natural-library.

Using Conversational RPC

Start of instruction setTo use conversational RPC with HTTP Test mode

  1. Open Settings.

    graphics/xmlTester_convRpc-1.png

  2. Add key exx-conv and set value to "OPEN".

    graphics/xmlTester_convRpc-2.png

  3. Press OK.

    graphics/xmlTester_convRpc-3.png

  4. Select exx-conv.

    graphics/xmlTester_convRpc-4.png

  5. Press OK.

  6. Send the request.

  7. The response contains the exx-xml-sessionID used for conversational communication. This parameter is also added to HTTP/HTTPS parameters for the next call(s) automatically. The parameter exx-conv is deactivated simultaneously.

  8. <!-- snippet with exx-xml-sessionID in response document -->
         <axis2ns1:EntireX xmlns:axis2ns1="urn:com.softwareag.entirex.xml.rt">
            <exx-xml-sessionID>XML610C044029044C05</exx-xml-sessionID>
         </axis2ns1:EntireX>
    <!-- snippet -->
  9. To finish the conversation, open the settings again, activate the exx-conv and set its value to "COMMIT" or "BACKOUT".

  10. The conversation is closed with the next sent call.