Writing Advanced Applications with the XML/SOAP Wrapper

This document covers the following topics:

• Listener for XML/SOAP

• Natural Logon or Changing the Library Name

• Using Conversational RPC

• Using Natural Security

• Using Compression

• Using Security

• HTTP Proxy Settings

• HTTP Basic Authentication

• Using SSL/TLS with the RPC Server for XML/SOAP

• Null Value Suppression

• User-specified Settings

• Map Fault to IDL Parameter

• Whitespace Handling

See also Generating a Web Service with HTTP Basic Authentication and UsernameToken Authentication for EntireX Authentication under Using the EntireX Web Services Wrapper.

Listener for XML/SOAP

With the Listener for XML/SOAP 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>

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 in the IDL Editor documentation. When the RPC is executed, this library name can be overwritten.

XML/SOAP Wrapper (Java API)

To overwrite the library

• An EntireX XML/SOAP Wrapper client (Java API) must call the setLibraryName method.

To force the library to be considered by Natural RPC Servers

• Call the setNaturalLogon method.

Listener for XML/SOAP

To overwrite the library

• Use the parameter exx-natural-library.

To force the library to be considered by Natural RPC Servers

• Set the parameter exx-natural-security to "true".

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

See also Natural Logon or Changing the Library Name.

Using Conversational RPC

It is assumed that you are familiar with the concepts of conversational and non-conversational RPC. See also Conversational RPC.

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)

To enable conversational RPC

• Create a Conversation object and set this with setConversation on the wrapper object.

  Different wrapper objects can participate in the same conversation if they use the same instance of a conversation object.

To abort a conversational RPC communication

• Call the closeConversation method.

To close and commit a conversational RPC communication

• Call the closeConversationCommit method.

Listener for XML/SOAP

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

To use conversational RPC

• Use the parameter exx-conv with the value OPEN.

To continue conversational RPC

• Pick up the parameter exx-sessionID in response and set the parameter as HTTP parameter or in the same way as in the response document inside the request document.

To abort a conversational RPC communication

• Use the parameter exx-conv with the value BACKOUT.

To close and commit a conversational RPC communication

• Use the parameter exx-conv with the value COMMIT.

See also EntireX XML Tester for Conversational RPC.

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

See also Conversational RPC.

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 in the RPC Programming documentation.

XML/SOAP Wrapper (Java API)

To authenticate an EntireX XML/SOAP Wrapper client (Java API) against Natural Security

• Specify a user ID and password in the logon method of class Broker.

  If different user IDs and/or passwords are used for EntireX Security and Natural Security, use the methods setRPCUserId or setRPCPassword to set the user IDs and/or passwords for Natural Security.

To 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.

Listener for XML/SOAP

To authenticate against Natural Security

• Specify the parameters exx-userID and exx-password.

  If a different user ID or password is used for EntireX Security and Natural Security, use the parameters exx-rpc-userID and exx-rpc-password to set the user ID or password for Natural Security.

To 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.

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 Listener for XML/SOAP.

• Using Broker ID

• XML/SOAP Wrapper (Java API)

• Using setCompressionLevel()

• Listener for XML/SOAP

Using Broker ID

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

Examples

• localhost:1971?compresslevel=BEST_COMPRESSION

• localhost?poolsize=4&compresslevel=9

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

• starts with Y, compression is switched on with level 6,

• starts with N, compression is switched off (level 0).

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

Listener for XML/SOAP

To set the compression level

• Use the parameter exx-compressLevel. The values are described in the section above (XML/SOAP Wrapper (Java API)).

Using Security

• XML/SOAP Wrapper (Java API)

• Listener for XML/SOAP

XML/SOAP Wrapper (Java API)

Java-based EntireX applications that require security can use security offered by EntireX. The following approaches are possible:

• EntireX Security, see Overview of EntireX Security for a general introduction

• Broker Security, for your own security implementation. See Sample Security Exits for Broker Security.

• Encryption. For encrypted transport we strongly recommend using the Secure Sockets Layer/Transport Layer Security protocol. See SSL/TLS and Certificates with EntireX.

To use EntireX Security

• Use one of the supported methods of useEntireXSecurity() within class Broker. See also Overview of EntireX Security for additional prerequisites. The auto mode specifies that the Broker object uses EntireX Security as needed by the broker kernel. If the broker kernel is set up with security, the Broker object uses EntireX Security. If the broker kernel is not set up with EntireX Security, it is not used.

To use your own security implementation

• Implement the interface BrokerSecurity. This implementation must have an accompanying security exit for the broker kernel. See Using Sample Security Exits for Broker Security for more information. Call one of the methods of setSecurity() with the security object similar to useEntireXSecurity().

Listener for XML/SOAP

With the parameter exx-use-security (true, false) you can force the use of EntireX Security. See Using an External Configuration File.

For encrypted transport we strongly recommend using the Secure Sockets Layer/Transport Layer Security protocol. See SSL/TLS and Certificates with EntireX.

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:

• -Dhttp.proxySet=true

• -Dhttps.proxySet=true

• -Dhttp.proxyHost=httpprox.mydomain.org

• -Dhttps.proxyHost=sslprox.mydomain.org

• -Dhttp.proxyPort=8080

• -Dhttps.proxyPort=443

• -Dhttp.nonProxyHosts=*mydomain.org|localhost

• -Dhttps.nonProxyHosts=*mydomain.org|localhost

• -Dhttp.proxyUser

• -Dhttps.proxyUser

• -Dhttp.proxyPassword

• -Dhttps.proxyPassword

Add the proxy settings to the start script.

HTTP Basic Authentication

Basic authentication is used for a target server if the attribute basicAuthentication is defined in the TargetServer block. Basic authentication is used for all calls associated with the defined XMM files for the <TargetServer>.

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

• If <TargetServer> contains attributes user and password, these settings are used for basic authentication.

• Otherwise the RPC client application must provide the credentials: Enable Natural logon and set RPC user ID and RPC password.

See also Generating a Web Service with HTTP Basic Authentication and UsernameToken Authentication for EntireX Authentication under Using the EntireX Web Services Wrapper.

Using SSL/TLS with the RPC Server for XML/SOAP

To configure SSL/TLS to a target server

1. Using HTTPS to the target server requires setting Java SSL/TLS properties and changing the protocol of the target server's Web service in the configuration file (see Configuration File).

   If the web service has to be called via HTTPS (SSL/TLS), the SSL client (here the XML/SOAP Wrapper) needs the correct certificate for the web service in the truststore to be able to communicate via SSL. The certificate can either be stored in the default truststore of the JVM or in the truststore specified with the following Java property:

    -Djavax.net.ssl.trustStore=path_to_used_truststore

   The SSL parameters must be included in quotes, for example

   set SSL="-Djavax.net.ssl.trustStore=C:\myTrustStore.jks"

   Note:
   This is only an example. You must provide a truststore that matches your environment.

   The truststore keeps the trusted certificate of the web service host or the certificate of its signing (issuing) certificate authority. In the event of an SSL error, you can use the Java property -Djavax.net.debug=all to get more information. Add the SSL parameter to the start script of the XML/SOAP Wrapper and ensure it is passed to the start or Java. Example:

   ...
   set SSL="-Djavax.net.ssl.trustStore=C:\myTrustStore.jks -Djavax.net.debug=all"
   ...
   "%JAVA_HOME_BIN%java" %PROXY% %SSL% -classpath "%CLASSPATH%" com.softwareag.entirex.xml.rt.XMLRPCServer -p "%EXXPROP%" -c "%EXXCONF%" %*

   There are additional Java properties, which are usually not needed. These are described in the Java documentation.

2. Optional. If you are using an HTTPS target server's Web service address located outside the firewall, set the following Java properties:

   • https.proxyHost

   • https.proxyPort

   • http.nonProxyHosts

   • https.proxyUser

   • https.proxyPassword

3. Change the protocol of the target server's Web service address from http to https in the configuration file. Specify the fully qualified host name as TargetServer. The host name has to match the CN (Common Name) item of the host certificate. See also configuration file (see Configuration File). Example:

   <?xml version="1.0" encoding="iso-8859-1" ?>
   <EntireX
   xmlns="http://namespaces.softwareag.com/entirex/xml/runtime/configuration" version="10.1"
   >
       <XmlRuntime Version="1">
          <TargetServer name="https://targethost:8080/entirex/xmlrt">
               <xmms>
                   <exx-xmm name="yourFile1.xmm" />
                   <exx-xmm name="yourFile2.xmm" />
               </xmms>
           </TargetServer>
       </XmlRuntime>
   </EntireX>
   

Null Value Suppression

This section covers the following topics:

• Introduction

• Default Setting for Null Value Suppression

• Definition and Examples of Null Value Suppression Mode

• Default Definition of Null Value

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:

• using a general setting on tab Mapping Parameter

• on each element or attribute in the definition of request/response on tab XML Request/ XML Response

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).

Default Setting for Null Value Suppression

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.

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

<prog>
   <integer>0</integer>
</prog>

<prog>
   <integer>0</integer>
</prog>

Elements

An element is hidden if

• the element value is equal to null value

• all attributes of the element can be suppressed

• the element has only subelements that can be suppressed

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

Example 2

<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

<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.

<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

<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)

<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

<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

<prog type="integer">0
  <parm type="integer">0</parm>
</prog>

<prog />

Default Definition of Null Value

User-specified Settings

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

Map Fault to IDL Parameter

• Introduction

• Example

• Testing the Fault Mapping

Introduction

The RPC Server for XML/SOAP 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 RPC Server for XML/SOAP. This feature is available for SOAP and XML documents.

Example

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

To map fault items to IDL

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

   

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.

   

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

   

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:

   

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>".

   

7. Press the mapping path button.

   

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

   

9. Choose OK.

   

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").

    

    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

• Set up the RPC Server for XML/SOAP with this XMM.

• Set up a new Web service or use an existing one.

Testing the Fault Mapping

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

• If the "requestData" field contains any data except "throwException", the field "responseData" in the response document is set to a concatenation of the string "Receiving:" and the value of field "requestData". See Request 2).

• If the "requestData" field contains "throwException", the Web service responds with a SOAP fault.

Test Scenario

Request 1 (Expecting Normal Response)

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

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

Request 2 (Expecting Fault Document)

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

The following fault information is provided:

Whitespace Handling

This section covers the following topics:

• Attribute xml:space

• Changing the Default for Whitespace Handling

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.

Changing the Default for Whitespace Handling

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

• Listener for XML/SOAP
  Add the following line to file axis2.xml in WS-Stack Web application:

  <parameter name="exx-xml-space">preserve</parameter>

• Java API (XMLRPCService)
  Set the user property entirex.sdk.xml.runtime.xmlspace:

  XMLRPCService rpcService = new XMLRPCService(...);
  ...
  rpcService.setUserProperty("entirex.sdk.xml.runtime.xmlspace","preserve");

• RPC Server for XML/SOAP
  Add the following line to properties file of the RPC Server for XML/SOAP:

  entirex.sdk.xml.runtime.xmlspace=preserve