Using the EntireX Web Services Wrapper

This document covers the following topics:


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

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

Start of instruction setTo 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.

    graphics/using_generate_ws-props.png

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

    graphics/using_generate_ws-generateWs.png

    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:

    graphics/using_generate_ws-launch.png

    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:

    graphics/using_generate_ws-defaults.png

    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 (Designer file with extension .xmm), WSDL file and Web service archive (Designer 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 (Designer file with extension .aar) with the Web Services Wrapper for HTTP Basic Authentication and UsernameToken Authentication.

Start of instruction setTo 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.

    graphics/using_generate_auth.png

    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 (Designer file with extension .aar) with the Web Services Wrapper for EntireX Security or Natural Security.

Start of instruction setTo 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.

    graphics/using_generate_sec.png

Deploying Web Services

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

Start of instruction setTo 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.

Deploying Web Services Stack Runtime to WebSphere 8.5.5

If you want to deploy the Web Services Stack Web application to WebSphere 8.5.5, perform the following steps:

Note:
Java 8 Extension is required.

Start of instruction setTo deploy to WebSphere 8.5.5

  1. Copy Software AG_directory/WS-Stack/webapp/wsstack.war to a temporary location.

  2. Unpack the WAR file.

  3. Copy all MAR files from WEB-INF/modules to WEB-INF/lib and change their extensions to JAR.

    Important:
    There might be an issue with mapping of MAR files when using Microsoft Office. When you have Microsoft Office installed, you cannot rename those files using Windows Explorer. In this case, use the ren command prompt command. For example, <TEMP_Directory>\WEB-INF\modules>copy addressing-1.41.mar addressing-1.41.jar copies the MAR file and changes its extension from MAR to JAR.

  4. Copy entirex.jar to folder../wsstack/WEB-INF/lib.

  5. Recreate the WAR file. You can use WinZip or any other application with support for ZIP files.

  6. Log on to the Administrative Console and navigate to Applications > New Application > New Enterprise Application.

  7. Enter the location of the wsstack.war file or browse for it using the Browse button. Then click Next.

  8. Select the Fast Path - Prompt only when additional information is required radio button and then click Next.

  9. Click Next and leave the default values for the options in the Step 1 Select installation options, Step 2 Map modules for servers, and Step 3 Map virtual hosts for Web modules screens.

  10. Click Next to go to the Step 4 Map context roots for Web modules screen, and type in "wsstack" in the Context root field.

  11. Click Save to save the changes to the master configuration.

  12. Navigate to Applications > Application Types > WebSphere Enterprise Applications.

  13. Click wsstack_war to open the configuration dialog.

  14. In the configuration dialog, click the Class loading and update detection link.

  15. For Class loader order, select Classes loaded with local class loader first (parent last) radio button.

  16. For WAR class loader policy, select Single class loader for application radio button.

  17. Navigate to Applications > Application Types > WebSphere Enterprise Applications.

  18. Start the Web Services Stack Web application.

Testing Web Services

Testing a Web Service with the EntireX XML Tester

Start of instruction setTo test a Web Service with the EntireX XML Tester

  • From the context menu of the generated Web service archive (Designer 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 (Designer 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.

Start of instruction setTo 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.

Start of instruction setTo 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 Designer documentation)

  • WSDL file

IDL File
  • XMM/SOAP mapping file

  • WSDL file

XMM File
  • WSDL file (if applicable)