This document covers the following topics:

• Generating Web Services from Software AG IDL File

• Deploying Web Services

• Testing Web Services

• Developing Web Service Client Applications

• Undeploying Web Services

• Removing Web Services

---

Generating Web Services from Software AG IDL File

A typical scenario starts from an existing (legacy) server application "wrapped" with EntireX technology and accessible to RPC clients via the EntireX RPC protocol. The interface of the (legacy) server is described by an IDL file (see Software AG IDL File). If there is a related client-side mapping file (Natural | COBOL), this is also used (internally). Using the EntireX Web Services Wrapper, the (legacy) server is exposed as a Web service. For example, the following files are generated from example.idl:

• a SOAP mapping (example.xmm)

• a WSDL description (example.wsdl)

• a service archive for the Web Services Stack (example.aar)

This section covers the following topics:

• Generating a Web Service

• Generating a Web Service with HTTP Basic Authentication and UsernameToken Authentication for EntireX Authentication

• Generating a Web Service for EntireX Security or Natural Security

Generating a Web Service

This section describes the general approach for generating a Web service archive with the Web Services Wrapper.

To generate a Web service

1. Before the wizard is started for the first time, initialize the preference pages Window > Preferences > Software AG > EntireX and Window > Preferences > Software AG > EntireX > Web Services Wrapper with values appropriate for your environment.

2. Select the IDL file to be processed. From the context menu of this IDL file, choose Properties.

   

   • Change the EntireX settings if necessary.

   • If necessary, change the Web service generation settings using the WSDL tab (Service Name and Service URL).

   • Choose OK to leave the Properties dialog.

3. Select the IDL file to be processed. If there is a related client-side mapping file (Natural | COBOL), this is also used (internally). From the context menu of the IDL file, choose Web Service > Generate Web Service....

   

   You can select more than one Software AG IDL File to merge all IDL files into one Web service. As a result you will get multiple XML mapping files, one WSDL file and one Web service archive. Merging does not support the use of the same IDL program name in different IDL libraries.

4. The EntireX Web Services Wrapper is launched:

   

   You can enter a service name. The default name is the name of the selected IDL file.

   If you check Deploy service, an additional confirmation page is displayed. See Deploying Web Services for this dialog.

   If you check Register service to CentraSite, a confirmation page is displayed. See CentraSite Integration for this dialog.

   If you uncheck Use defaults for the Configure EntireX Service section, you can select the following configuration items:

   

   • General service parameters (XML-INIT.xml)
     An additional configuration page is appended.

     

     The parameters on this page are described in the Web Services Stack Configuration Editor. See also Initialization Parameters for the Listener for XML/SOAP.

   • Set connection and security parameters in mapping file
     An additional configuration page is appended.

     

     The parameters on this page are described in the Web Services Stack Configuration Editor. See also Service Parameters.

   • Send connection and security parameters with SOAP message
     An additional configuration page is appended.

     

   The selected parameters are generated in alphabetical order and are enclosed by xsd:all in the SOAP header section of the generated WSDL file. Example:

   <xsd:schema targetNamespace="urn:com.softwareag.entirex.xml.rt">   
    <xsd:element   name="EntireX">  
     <xsd:complexType > 
      <xsd:all >  
       <xsd:element name="exx-brokerID" type="xsd:string"/> 
       <xsd:element name="exx-natural-library" type="xsd:string"/>   
           ...
       <xsd:element name="exx-userID" type="xsd:string"/>
      </xsd:all>  
     </xsd:complexType>  
    </xsd:element> 
   </xsd:schema>
   

   A web service client will then be able to set these parameters in the SOAP header of the SOAP message. See also The HTTP Interface in the XML/SOAP Wrapper documentation.

5. Choose Next, enter your configuration parameters and select the methods for which the Web service is to be generated.

6. Choose Finish to generate the Web service (XML/SOAP mapping file (Workbench file with extension .xmm), WSDL file and Web service archive (Workbench file with extension .aar)).

Generating a Web Service with HTTP Basic Authentication and UsernameToken Authentication for EntireX Authentication

This section describes specific settings required when you generate a Web service archive (Workbench file with extension .aar) with the Web Services Wrapper for HTTP Basic Authentication and UsernameToken Authentication.

To generate a Web service with HTTP Basic Authentication and UsernameToken Authentication

• In general, follow the steps under Generating a Web Service.

  In step 4, check General service parameters (XML-INIT.xml) and in the additional configuration page enable User Name Token and Basic Authentication.

  

  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)

Generating a Web Service for EntireX Security or Natural Security

This section describes specific settings required when you generate a Web service archive (Workbench file with extension .aar) with the Web Services Wrapper for EntireX Security or Natural Security.

To generate a Web service for EntireX Security or Natural Security

• In general, follow the steps under Generating a Web Service. In step 4, check Set connection and security parameters in mapping file and in the additional configuration page enable Use Security and/or Natural Logon. If required, also set the Natural library.

  

Deploying Web Services

• Prerequisites

• Deploying the Web Service

Prerequisites

The following resources are required to deploy and run a Web service:

• An application server where the Web Services Stack is installed (wsstack.war). The Web Services Stack is accessible by default at the URL http://<host-name>:<port-number>/wsstack/sagdeployer with port number 10010. The default port can be changed during installation. In the case of deployment in custom application servers, the port is configured by the corresponding server administration tools. For more details see the Web Services Stack documentation in the Software AG Infrastructure Administrator's Guide, also available under http://documentation.softwareag.com > Guides for Tools Shared by Software AG Products.

• The EntireX Runtime (entirex.jar) containing the Listener for XML/SOAP. This must be located in the WEB-INF\lib folder of the Web Services Stack Web application. See Listener for XML/SOAP.

• The Eclipse plug-ins of the Web Services Stack must be installed.

• EntireX Broker and the RPC server hosting the server implementation are up and running. See Setting up Broker Instances under z/OS | UNIX | Windows | BS2000 | z/VSE and EntireX RPC Servers and Listeners.

Deploying the Web Service

Deploying a Web service means sending a Web service archive (Workbench file with extension .aar) to a running Web Services Stack Web application. The Web Services Stack Web application stores the Web service archive in the WEB-INF/services folder of the Web Services Stack Web application.

To deploy a Web service

1. From the context menu of the generated Web service archive, choose Software AG Web Services Stack > Deploy Web Service Package. In a wizard you can select hostname, port number, and a servlet address of the Web Services Stack Deployment Servlet. You also need to supply your credentials (user ID and password).

2. Choose Finish to send the Web service archive to the selected deployment connection point.

Notes:

1. For more information, see Deploy Web Services Stack in the Software AG Infrastructure Administrator's Guide, also available under http://documentation.softwareag.com > Guides for Tools Shared by Software AG Products.
2. You can verify the deployment of your service with context menu item Software AG Web Services Stack >View Web Services Stack... or Software AG Web Services Stack > View Web Service.
3. An advanced Web service application (e.g. requiring WS-Security) may need special settings in the Web service archive before you deploy it to the Web Services Stack. You can manage the settings with the Web Services Stack Configuration Editor.

Testing Web Services

• Testing a Web Service with the EntireX XML Tester

• WSDL Query of Web Services

Testing a Web Service with the EntireX XML Tester

To test a Web Service with the EntireX XML Tester

• From the context menu of the generated Web service archive (Workbench files with extension .aar), choose Test EntireX Web Service. This starts the EntireX XML Tester. If the Web service archive contains multiple XMM/SOAP mapping files (Workbench file with extension .xmm), select the one you want. Refer to the documentation of the EntireX XML Tester to create a sample document.

WSDL Query of Web Services

You can retrieve the WSDL of a Web service deployed in the Web Services Stack running in a servlet engine.

To query the WSDL of a Web Service

• Use a browser and append "?wsdl" to the Web service URI. Example:

  http://host:port/wsstack/service/myService?wsdl

  The returned WSDL will return to the requestor all relevant configuration information of the Web service, for example all endpoints through which the Web service is accessible and policies that are in effect for the Web service.

Developing Web Service Client Applications

Once the Web service is up and running and its WSDL is accessible (using HTTP), Web service client applications can be developed. See also Writing Web Service Client Applications in the IDL Extractor for WSDL documentation.

Undeploying Web Services

Undeploying a Web service means informing a running Web Services Stack Web to remove a deployed Web service. The Web Services Stack Web removes the corresponding Web service archive from the WEB-INF/services folder of the Web Services Stack Web.

To undeploy a Web service

• Choose Windows > Preferences > Software AG > Web Services Stack > Undeploy Web Service Package...

Notes:

1. For more information, see Deploy Web Services Stack in the Software AG Infrastructure Administrator's Guide, also available under http://documentation.softwareag.com > Guides for Tools Shared by Software AG Products.
2. You can verify the undeployment with the help of a browser. The undeployed Web service should disappear from the list of the deployed Web services (e.g. http://localhost:10010/wsstack/services/listServices).

Removing Web Services

When a Web service is removed from an Eclipse project, using Web Services Stack > Remove Web Service, the following artifacts are additionally deleted depending on the source of the generated Web service.

Generated from	Additionally Deleted Artifacts
Natural/COBOL	IDL file XMM/SOAP mapping file Server mapping file (if applicable, see Client-side Mapping for Natural | COBOL in the EntireX Workbench documentation) WSDL file
IDL File	XMM/SOAP mapping file WSDL file
XMM File	WSDL file (if applicable)