Version 9.5 SP1
 —  EntireX XML/SOAP Wrapper  —

Writing Advanced Applications with the XML/SOAP Wrapper

This document covers the following topics:


XML/SOAP Listener

With the XML/SOAP Listener you can define parameters inside the payload of a message. We recommend this approach rather than HTTP parameters. Define the setting in the SOAP header and under the first tag of XML document as follows:

SOAP Documents

...
<soap-env:SOAPHeader>
  <exx:EntireX xmlns:exx="urn:com.softwareag.entirex.xml.rt">
    <!-tags with parameter setting e.g: -->
    <exx-natural-library>libraryname</exx-natural-library>
    <exx-natural-security>true</exx-natural-security>
  </exx:EntireX>
...
</soap-env:SOAPHeader>
...

XML Documents

<root-tag>
  <exx:EntireX xmlns:exx="urn:com.softwareag.entirex.xml.rt">
    <!-tags with parameter setting e.g: -->
    <exx-natural-library>libraryname</exx-natural-library>
    <exx-natural-security>true</exx-natural-security>
  </exx:EntireX>
...
</root-tag>

Top of page

Natural Logon or Changing the Library Name

The library name sent with the RPC request to the EntireX RPC or the Natural RPC Server is specified in the IDL file. See library-definition under Software AG IDL Grammar. When the RPC is executed, this library name can be overwritten.

XML/SOAP Wrapper (Java API)

Start of instruction setTo overwrite the library

Start of instruction setTo force the library to be considered by Natural RPC Servers

XML/SOAP Listener

Start of instruction setTo overwrite the library

Start of instruction setTo force the library to be considered by Natural RPC Servers

Warning:
Natural RPC Servers and EntireX RPC Servers behave differently regarding the library name.

See also Natural Logon or Changing the Library Name under Common Features of Wrappers and RPC-based Components.

Top of page

Using RPC Compression

EntireX and Natural RPC support a feature called RPC compression to reduce network traffic. The default for compression is on. See also RPC Compression under Common Features of Wrappers and RPC-based Components.

XML/SOAP Wrapper (Java API)

Start of instruction setTo switch compression on and off

Start of instruction setTo check the current compression setting

XML/SOAP Listener

Start of instruction setTo switch compression on and off

Top of page

Using Conversational RPC

It is assumed that you are familiar with the concepts of conversational and non-conversational RPC. See also Conversational RPC under Common Features of Wrappers and RPC-based Components.

For conversational RPC you need an instantiated conversation object. See Conversation. Conversational RPC is enabled by passing a reference to this object to the method setConversation. See setConversation. Different stubs can participate in the same conversation if they use the same instance of a Conversation object. An RPC conversation is terminated by calling either the closeConversation method or the closeConversationCommit method for one stub.

XML/SOAP Wrapper (Java API)

Start of instruction setTo enable conversational RPC

Start of instruction setTo abort a conversational RPC communication

Start of instruction setTo close and commit a conversational RPC communication

XML/SOAP Listener

Conversations can only be used in connection with sessions. If the session is interrupted, the conversation will be deleted.

Start of instruction setTo use conversational RPC

Start of instruction setTo continue conversational RPC

Start of instruction setTo abort a conversational RPC communication

Start of instruction setTo close and commit a conversational RPC communication

See also XML Tester for Conversational RPC.

Warning:
Natural RPC Servers and EntireX RPC Servers behave differently when ending an RPC conversation.

See also Conversational RPC under Common Features of Wrappers and RPC-based Components.

Top of page

Using Natural Security

A Natural RPC Server may run under Natural Security to protect RPC requests. See also Natural Security under Common Features of Wrappers and RPC-based Components.

XML/SOAP Wrapper (Java API)

Start of instruction setTo authenticate an EntireX XML/SOAP Wrapper client (Java API) against Natural Security

Start of instruction setTo force an EntireX XML/SOAP Wrapper client (Java API) to log on to a specific Natural library

  1. Call the setLibraryName method.

  2. Call the setNaturalLogon method.

See also Natural Logon or Changing the Library Name.

XML/SOAP Listener

Start of instruction setTo authenticate against Natural Security

Start of instruction setTo force a logon to a specific Natural library

  1. Use the parameter exx-natural-library.

  2. Set the parameter exx-natural-security to True.

See also Natural Logon or Changing the Library Name.

Top of page

Using Compression

Java-based EntireX applications (including applications using classes generated by the Java Wrapper) may compress the messages sent to and received from the broker. There is a general way to enable compression using broker ID, and another way that depends on whether you use the XML/SOAP Wrapper or the XML/SOAP Listener.

Using Broker ID

You may append the keyword compresslevel with one of the values below to the Broker ID.

Examples

Both examples set the compression level to 9.

XML/SOAP Wrapper (Java API)

Using setCompressionLevel()

Set the compression level with the method setCompressionLevel() as an integer or a string argument.

You can use the constants defined in class java.util.zip.Deflater.

If the string

Permitted values are the integers 0 - 9 and the corresponding strings:

Compression Level
BEST_COMPRESSION 9
BEST_SPEED 1
DEFAULT_COMPRESSION 6
DEFLATED 8
NO_COMPRESSION 0

XML/SOAP Listener

Start of instruction setTo set the compression level

Top of page

Using EntireX Security

Java-based EntireX applications that require security can use the security services offered by EntireX Security. See also Overview of EntireX Security | EntireXSecurity in the Javadoc documentation of the Java ACI.

Use the methods for security, which are included in class Broker. See Broker. The two alternatives using security are:

XML/SOAP Wrapper (Java API)

To use EntireX Security, call Broker.useEntireXSecurity() for a Broker object. You can set the encryption level with this call and you can enable the auto mode. The encryption level allows the values ENCRYPTION_LEVEL_NONE, where the message is not encrypted, ENCRYPTION_LEVEL_BROKER, where the message is encrypted on the way to the EntireX Broker, and ENCRYPTION_LEVEL_TARGET, where the message is encrypted the whole way to the target. The auto mode specifies that the Broker object uses the EntireX Security as needed by the EntireX Broker. If the EntireX Broker uses security, the EntireX Security object is used by the Broker object. The method useEntireXSecurity() must be called before the first call of logon(), which has to use a password. The security object cannot change during a session with the EntireX Broker.

To use your own security implementation, implement the interface BrokerSecurity. This implementation must have an accompaning security exit for the EntireX Broker. See Using Sample Security Exits for Broker Security. Call the methods setSecurity() with the security object and set encryption level or auto mode in the same way as the useEntireXSecurity() methods.

XML/SOAP Listener

The parameter exx-use-security (true, false) is responsible for EntireX Security. Set the encryption level with the required parameter exx-encryption-level (0,1,2).

Top of page

HTTP Proxy Settings

If the target server of your Web service has to be reached through a firewall, set and adjust to your needs the following properties:

Add the proxy settings to the start script.

Top of page

XML/SOAP RPC Server with HTTP Basic Authentication

The XML/SOAP RPC Server uses basic authentication for a Web service if the configuration contains the attribute basicAuthentication block in <TargetServer>. Basic authentication is used for all calls associated with defined XMM files for the <TargetServer>.

Basic authentication can be used with fixed credentials or credentials set from the client application:

See Configuration File for the XML/SOAP RPC Server under UNIX | Windows.

Top of page

XML/SOAP Listener with HTTP Basic Authentication and UsernameToken Authentication for EntireX Authentication

The XML/SOAP Listener allows you to use the user credentials from the incoming request by means of Basic Authentication or UsernameToken. The same credentials are used for EntireX Broker authentication and (Natural) RPC Server authentication. This means you need to make some settings for the EntireX Web service in Web Service Wizard and Configuration Editor.

Note:
UsernameToken is part of WS-Security. See WS-Security UsernameToken Specification. See also Example: Setting up an EntireX Client to Consume a Secured Web Service in the IDL Extractor for WSDL documentation.

The priority of credentials settings is as follows:

  1. exx-userID, exx-password, exx-rpc-userID, exx-rpc-password (highest priority)

  2. UsernameToken

  3. Basic Authentication (lowest priority)

Start of instruction setTo use the XML/SOAP Listener with Basic Authentication and UsernameToken Authentication

  1. Select an IDL file or XMM file.

  2. Choose Generate Web Service from Software AG....

  3. Disable check box Use Defaults.

    graphics/xmlListener_httpBasicAuth_1.png

  4. Enable at least General service parameters....

    graphics/xmlListener_httpBasicAuth_2.png

  5. If using EntireX Security or Natural Security, enable Set connection and security... too.

    graphics/xmlListener_httpBasicAuth_3.png

  6. Press Next.

  7. Enable the required authentication. In this example, both possibilities of web service authentication are enabled.

    graphics/xmlListener_httpBasicAuth_4.png

  8. Press Next.

  9. The page with XMM settings appears if it was selected before (step 5). Enable the required security (EntireX Security and/or Natural Logon).

    graphics/xmlListener_httpBasicAuth_5.png

  10. Press Next and follow the wizard.

  11. After generating the web service archive (extension "aar"), open the generated AAR file with the Configuration Editor (e.g. with double click).

For more information on the Configuration Editor see Configuring Web Services.

Top of page

Using SSL or TLS with the XML/SOAP RPC Server

Using HTTPS with XML/SOAP RPC Server requires setting Java properties and changing the protocol from http to https in the configuration file. This section covers the following topics:

See also Configuration File for the XML/SOAP RPC Server under UNIX | Windows.

SSL or TLS Settings

Start of instruction setTo configure SSL communication for the JRE

For more information about Java and SSL, see your Java documentation (JSSE documentation).

Sample Start Script

set CLASSPATH=.;.\classes\entirex.jar;..\WS-Stack\lib\wsstack-client.jar

set PROXYSETTINGS=-Dhttps.proxySet=true
-Dhttps.proxyHost=sslproxy.mydomain 
-Dhttps.proxyPort=443 
-Dhttps.nonProxyHosts="localhost" 

set SSL=-Djavax.net.ssl.keyStore=C:\myKeystore.p12 
-Djavax.net.ssl.keyStorePassword=myKeystorePassword
-Djavax.net.ssl.keyStoreType=pkcs12 
-Djavax.net.ssl.trustStore=C:\myTrustStore.jks 
-Djavax.net.ssl.trustStorePassword=myTruststorePassword

java -classpath %CLASSPATH% %SSL% %PROXYSETTING% com.softwareag.entirex.xml.rt.XMLRPCServer

For the changes that are required to the start script, see your Java documentation (JSSE documentation).

Configuration File Settings

Specify the fully qualified host name as TargetServer. The host name has to match the CN (Common Name) item of the host certificate.

<?xml version="1.0" encoding="iso-8859-1" ?>
<EntireX
xmlns="http://namespaces.softwareag.com/entirex/xml/runtime/configuration" version="8.0"
>
    <XmlRuntime Version="1">
       <BrokerInfo>
       <BrokerId>localhost:1971</BrokerId>
       <ServerAddress>RPC/XMLSRV1/JAVA</ServerAddress>
       </BrokerInfo>
       <TargetServer name="https://targethost:8080/entirex/xmlrt">
            <xmms>
                <exx-xmm name="yourFile1.xmm" />
                <exx-xmm name="yourFile2.xmm" />
            </xmms>
        </TargetServer>
    </XmlRuntime>
</EntireX>

Top of page

Using Internationalization with EntireX XML Components

XML components support Conversion and Translation for Internationalization. If you choose Conversion (which is recommended), the correct codepage must be send as locale string to the EntireX Broker matching the encoding of the data sent. This codepage must also be a codepage supported by the broker, see Locale String Mapping for information on how the broker derives the codepage from the locale string. For Translation and more details on Conversion, see Internationalization with EntireX.

To enable EntireX XML components to send a codepage as locale string to the EntireX Broker, they must be prepared as described below:

XML/SOAP Wrapper (Java API)

Start of instruction setTo enable use of the encoding of an incoming XML document for Broker communication

  1. Call useCodePage(true) on the XMLRPCService object. The XML/SOAP Wrapper will then use the codepage retrieved from the XML document to send data to EntireX Broker.

  2. Use a stream-oriented method of XMLRPCService to transfer the data to XML/SOAP Wrapper.

XML/SOAP Listener

Start of instruction setTo enable use of the encoding of an incoming XML document for broker communication

XML/SOAP RPC Server

The encoding for broker communication is defined by the parameter codepage.

The encoding for the outgoing XML document is determined by the IDL to XML Mapping. See Defining the XML Encoding.

Top of page

Null Value Suppression

This section covers the following topics:

Introduction

The EntireX XML/SOAP Runtime introduced a feature called null value suppression to reduce to amount of data transferred between Web client and Web service. Null value suppression (NVS) allows you to hide tags or attributes with a specified value (so-called null value).

The different types of NVS are explained below. The EntireX XML Mapping Editor provides two ways of setting/modifying the NVS type:

For several data types, a null value is defined by default. See Default Definition of Null Value. To change one of these null values, open the XML Request/XML Response tab, select the element/attribute and modify the property of the null value manually. For this modification use the Properties view or the Properties dialog (open with the context menu).

graphics/map01.png

Default Setting for Null Value Suppression

Data Type Suppression Mode
Simple Elements No Suppression
Simple Attributes No Suppression
Array Types Cells at end (trim)
Complex Types Suppress group elements

Tip:
The default setting for elements and attributes changed with version 7.3 from "Suppress Element/Attribute" to "No Suppression". The null value suppression for elements and attributes can be set independently. The null value suppression for Complex Types was introduced with version 7.3.

Definition and Examples of Null Value Suppression Mode

If there is a significant difference between pure XML and SOAP for a null value suppression mode, two examples are introduced.

Suppression Mode Valid for
No Suppression Elements, attributes
Elements Elements
Attributes Attributes
Cells at End (Trim) Elements inside an array definition
All Empty Cells Elements inside an array definition
Suppress Group Elements Elements inside a group definition
Depends On Element Attributes

No Suppression

The element or attribute is always present in document. The minimum and maximum occurrence of element/attribute must be set to one.

Example 1

XML document Displayed XML Document
<prog>
   <integer>0</integer>
</prog>
<prog>
   <integer>0</integer>
</prog>

Elements

An element is hidden if

The minimum occurrence of element must be zero, and the maximum occurrence of element must be one.

Example 2

XML document Displayed XML Document
<prog>
    <gr>
     <integer>0</integer>
    </gr>
</prog>
<prog />

Attributes

An attribute with null value is hidden.

The minimum occurrence of attribute must be zero, and the maximum occurrence of attribute must be one.

Example 3

XML document Displayed XML Document
<prog integer="0" name="Henry"/>
<prog name="Henry"/>

Cells at End (Trim)

All elements of array that fulfills the assertion of "Suppress Element/Attribute" are suppressed if its index is higher than the highest index of the non-suppressed element.

The minimum occurrence of elements must be lower than the maximum occurrence, and the maximum occurrence of elements must be the maximum number of elements or unlimited.

XML document Displayed XML Document
<prog>
   <array>
      <integer>0</integer>
      <integer>1</integer>
      <integer>0</integer>
      <integer>2</integer>
      <integer>0</integer>
      <integer>0</integer>
  </array>
</prog>
<prog>
   <array>
      <integer>0</integer>
      <integer>1</integer>
      <integer>0</integer>
      <integer>2</integer>
   </array>
</prog>

All Empty Cells

All elements of array that fulfills the assertion of NVS_FIELD are suppressed.

The minimum occurrence of elements must be lower than the maximum of occurrence and maximum occurrence of elements must be maximum number of elements or unlimited.

Example 5a

XML document Displayed XML Document
<prog>
   <array>
      <integer>0</integer>
      <integer>1</integer>
      <integer>0</integer>
      <integer>2</integer>
      <integer>0</integer>
      <integer>0</integer>
  </array>
</prog>
<prog>
   <array>
      <integer>1</integer>
      <integer>2</integer>
   </array>
</prog>

Example 5b (for SOAP documents the XML/SOAP Runtime creates position attributes)

SOAP document Displayed SOAP Document
<prog>
   <array>
      <integer>0</integer>
      <integer>1</integer>
      <integer>0</integer>
      <integer>2</integer>
      <integer>0</integer>
      <integer>0</integer>
  </array>
</prog>
<prog>
  <array>
    <integer SOAP-ENC:position="[1]">1</integer>
    <integer SOAP-ENC:position="[3]">2</integer>
  </array>
</prog>

Suppress Group Elements

The suppression mode allows you to suppress group information if - and only if - all elements of the group can be suppressed.

The minimum occurrence of elements must be zero.

Example 6

XML document Displayed XML Document
<prog>
  <person>
    <firstname>Henry</ firstname >
    <lastname>Miller</ lastname >
    <someInformation>2</ someInformation >
  </person>
  <person>
    <firstname></ firstname >
    <lastname></ lastname >
    <someInformation>0</ someInformation >
  </person>
  <person>
    <firstname>John</ firstname >
    <lastname>Miles</ lastname >
    <someInformation>0</ someInformation >
  </person>
</prog>
<prog>
  <person>
    <firstname>Henry</ firstname >
    <lastname>Miller</ lastname >
    <someInformation>2</ someInformation >
  </person>
  <person/>
  <person>
    <firstname>John</ firstname >
    <lastname>Miles</ lastname >
    <someInformation>0</ someInformation >
  </person>
</prog>

Depends On Element

Attribute of the element is visible if the element does not have the null value.

The minimum occurrence of attribute and associated element must be zero, and the maximum occurrence must be one.

Example 7

XML document Displayed XML Document
<prog type="integer">0
  <parm type="integer">0</parm>
</prog>
<prog />

Default Definition of Null Value

Data Types Null Value
String Empty String
Integer 0
Floating Point 0.0
Numeric 0.0
Time No default definition
Date No default definition
Binary No default definition
Boolean False

Top of page

User-specified Settings

For further settings, use the method setUserProperty in XMLRPCService (EntireX XML/SOAP Runtime).

Top of page

Map Fault to IDL Parameter

Introduction

The XML/SOAP RPC Server maps the values of IDL parameters to XML/SOAP documents and vice versa. If the Web service responds with a fault document, this information is mapped to an error and returned to RPC client normally. With the optional feature Map Fault to IDL Parameter you can map values from a normal response and also from a fault document response. This means that no RPC error is returned to the RPC client; instead the fault information is contained in the IDL file. An RPC error is returned to the client only if internal error processing problems occurred within the XML/SOAP RPC Server. This feature is available for SOAP and XML documents.

Example

Note:
This example illustrates the feature Map Fault to IDL Parameter. Other features mentioned here, such as renaming parameters or assigning a prefix/namespace to a parameter, are described elsewhere.

Sample IDL File

/* Sample IDL file
library 'Demo' is
  program 'FaultToIDL' is
    define data parameter
      1 MyRequest  In
      2  RequestData     (AV)
      1 MyResponse Out
      2  ResponseData    (AV)
      1 MyStatus   Out   ** parameters for fault information
      2   Code		(AV)
      2   String    (AV)
      2   Detail    (AV)
    end-define

IDL-XML Mapping

Start of instruction setTo map fault items to IDL

  1. In the XML Mapping Editor, generate a (SOAP) mapping and select the response tab.

    graphics/mapFaultToIdl_01.png

  2. Remove the parameter MyStatus, including its children, because the regular response will not contain these parameters and the corresponding IDL parameters will be used for fault information later.

    graphics/mapFaultToIdl_02.png

  3. Open the Fault Document Manager (see bottom of opened tab Response) and select the document to open the following wizard:

    graphics/mapFaultToIdl_03.png

  4. In the following steps, map "faultcode", "faultstring" and "detail" to IDL parameters. Fault item "faultactor" is not used in this example.

  5. Select "faultcode" and open the properties shown on the following screen:

    graphics/mapFaultToIdl_04.png

  6. Check Fault Mapped to IDL to enable the mapping path button. In this example, a mapping path has not yet been entered and the button is labelled "<none>".

    graphics/mapFaultToIdl_05.png

  7. Press the mapping path button.

    graphics/mapFaultToIdl_06.png

  8. Select the path to IDL parameter, for example "FaultToIDL/MyStatus/Code" and choose OK to display the following screen:

    graphics/mapFaultToIdl_07.png

  9. Choose OK.

    graphics/mapFaultToIdl_08.png

  10. Repeat the steps above to select the fault items "faultstring" (path to IDL parameter e.g. "FaultToIDL /MyStatus/String") and "detail" (path to IDL parameter e.g. "FaultToIDL /MyStatus/Detail").

    graphics/mapFaultToIdl_09.png

    Note:
    The fault item "info:detail" contains the complete document fragment enclosed by an associated tag (in this example tag <detail>).

  11. Choose OK to save the IDL-XML mapping.

In subsequent steps you need to

Testing the Fault Mapping

As a quick test, implement a Web service that behaves as follows:

Test Scenario

graphics/mapFaultToIdl_testScenario.png

Request 1 (Expecting Normal Response)

The following screen illustrates a request that expects a normal response:

graphics/mapFaultToIdl_10.png

The following response is received (field responseData is filled):

graphics/mapFaultToIdl_11.png

Request 2 (Expecting Fault Document)

The following screen illustrates a request where a fault document from the Web service is expected:

graphics/mapFaultToIdl_12.png

The following fault information is provided:

graphics/mapFaultToIdl_13.png

Top of page

Whitespace Handling

The XML/SOAP Runtime trims whitespace in values by default. The whitespace handling is also determined by defining attribute xml:space (see XML specification) on element(s). The attribute xml:space has the higher priority and is inherited from children of the element recursively.

This section covers the following topics:

Attribute xml:space

The attribute xml:space can be added in the XML Mapping Editor. Select an element and add new child, select the checkbox for xml:space and choose OK. Depending on the application, perform these steps for the request and/or response document definition. The attribute is added with value "preserve". If another value is required, open the properties on the attribute and change the default value.

Note:
The XML/SOAP Runtime only supports the value "preserve" for attribute xml:space, all other values disable the preserving of whitespace (that is, whitespace is trimmed).

Changing the Default for Whitespace Handling

The steps required to keep whitespace as default depend on the EntireX component:

Top of page