Version 9.5 SP1
 —  Software AG IDL Extractor for WSDL  —

Writing Web Service Client Applications

This document covers the following topics:


Web Service Clients

EntireX, in conjunction with the Software AG Common Web Services Stack (WSS), provides development and runtime functionality to support EntireX RPC clients consuming (or calling) Web services. The relevant products parts are:

For each Web service client that is deployed in XML/SOAP RPC Server, a special configuration is required. The default name of the configuration file is entirex.xmlrpcserver.configuration.xml. Example configuration:

...
<TargetServer name="http://localhost:10010/wsstack/services/example">
  <xmms>
    <exx-xmm
      name="C:\MyWorkspace\Example\example.xmm"
      wsdl="http://localhost:10010/wsstack/services/example?wsdl"
      service="example"
      port="EXAMPLESOAP11Port"
      soapVersion="1.1"
      repository="C:\SoftwareAG\WS-Stack\repository" />
  </xmms>
</TargetServer>
...
where code is the XMM mapping file for the service
  wsdl is the reachable URL for the WSDL file of the service. This WSDL file can contain additional WS-Policy information for the service that is supported by the Web Services Stack
  service is the service name inside the WSDL file of the service
  port is the port inside the WSDL file. This information is needed when the WSDL file can contain more than one port. The value in this example is the default number; this number can be changed during installation
  soapVersion can be "1.1" or "1.2"
  repository is the client "repository" of the Web Services Stack (containing the conf and modules subfolders)

Top of page

Configuring Advanced Web Service Clients

A Web Services Stack client using advanced Web services functionality (WS-Security, WS-ReliableMessaging, etc.) requires the following configuration data:

Here is an example of a client security configuration file wsclientsec.properties:

USERNAME=client
ENCRYPTION_USER=service
PASSWORD_CALLBACK_HANDLER_CLASS=com.softwareag.wsstack.test.PasswordCallbackHandler
KEYSTORE_FILE_ENCRYPT=client.jks
KEYSTORE_TYPE_ENCRYPT=jks
KEYSTORE_PASSWORD_ENCRYPT=apache
KEYSTORE_FILE_SIGN=client.jks
KEYSTORE_TYPE_SIGN=jks
KEYSTORE_PASSWORD_SIGN=apache
KEYSTORE_SSL_LOCATION=clientKS.jks
SSL_KEYSTORE_TYPE=jks
SSL_KEYSTORE_PASSWORD=apache
TRUSTSTORE_SSL_LOCATION=clientKS.jks
TRUSTSTORE_SSL_TYPE=jks
TRUSTSTORE_SSL_PASSWORD=apache

The USERNAME specifies the user name that the Web service client uses to authenticate itself with the Web service. It corresponds to Alias as described for the service configuration. ENCRYPTION_USER and PASSWORD_CALLBACK_HANDLER correspond accordingly. The example Java password callback handler from above can also be used for the client. The Web Services Stack provides some default password callback handlers that can be instantly used without needing to write a custom one. For example com.softwareag.wsstack.pwcb.ConfigFilePasswordCallbackHandler, which uses a simple user configuration file users.xml. See the separate WS-stack documentation for more details.

A Web Services Stack client that connects to a Web Service that requires advancesd Web Services policies (which are attached to the service's WSDL as policy attachment) automatically sets up and processes the necessary SOAP headers in the SOAP message exchange with the service and fills the required parameters according to the configuration information described above.

Top of page

Example: Setting up an EntireX Client to Consume a Secured Web Service

This section describes how to set up EntireX RPC clients calling a remote Web service that has a WS-Security UsernameToken policy in effect. Two scenarios are described: one where the security policy is defined in the WSDL, and one where the policy is not defined.

Setting up an EntireX RPC Server to Configure WS-Security

To set up a dedicated XML/SOAP RPC Server instance to connect EntireX RPC clients to a secured Web service, the following prerequisites apply, for example in a folder of their own in the file system:

Scenario 1: Service requires UsernameToken and has a Security Policy in the WSDL

In this scenario, the Web Services Stack runtime can use the WS-Security policy from the WSDL to determine which security headers need to be attached to the SOAP message. Follow the steps below:

Start of instruction setTo set up an XML/SOAP RPC server with defined security policy

  1. Store a copy of the service's WSDL (which also includes the policy attachment) in the test folder.

  2. Generate an XML/SOAP mapping file (.xmm) with the IDL Extractor for WSDL. Enter the name of the XML/SOAP RPC Server ("XMLSERVER" in this example) under Broker Settings on the wizard page.

  3. Start the XML/SOAP RPC Server in a command window, using the start script.

  4. Deploy the mapping file to the XML/SOAP RPC Server. Provide the location of the WSDL and specify the desired service endpoint, name and port.

  5. Configure the Web Services Stack repository for the service, using the following steps:

    1. Stop the XML/SOAP RPC Server.

    2. Edit the file entirex.xmlrpcserver.configuration.xml and add the repository definition to the TargetServer section. For example:

      <TargetServer
       name="http://localhost:10010/wsstack/services/example.EXAMPLESOAP11Port/">
        <xmms>
          <exx-xmm
            name="D:\TestWS\example.xmm"
            port="EXAMPLESOAP11Port"
            wsdl="D:\TestWS1\example.wsdl"
            service="example"
            soapVersion="1.1"
            repository="repository"/>
        </xmms>
      </TargetServer>
      
    3. Restart the XML/SOAP RPC Server.

  6. Configure security for the WSS client runtime by modifying files wsclientsec.properties and users.xml:

To test access to the remote Web service, use the XML Tester on the IDL file. See XML Tester.

Scenario 2: Service requires UsernameToken but does not declare this in the WSDL

For this scenario, perform the steps as described above. Because the WSDL does not contain a security policy stating that UsernameToken is required, perform this additional step:

Top of page