WsySoap Tutorial - Overview

Introduction    Implementing    Other Uses    Parts    Tutorial   Glossary

Contents

• Overview

• Application Context

  • Implementation Guide Limitations relative to "Real World" Applications

  • Difference between the TransacXML implementation and the Web Services implementation

• Preparations

• Add namespace to XML documents

• Implementing the Distributor (Publisher) functionality

  • Specifying the Web Service SOAP Entity

  • Specify XMLHandler function for each Web Service function

• Implementing the Broker (Subscriber) functionality

  • Specifying the Web Service SOAP Entity

  • Specifying the function that calls the Web Service to Import all Items in Distributor Database

  • Specifying the function that calls the Web Service to Import Specific Items from the Distributor Database

• Test the functionality

  • Create Wrapper functions

  • Generate and Build

  • Specify Web Server Configuration

  • Run the Test Functions

Overview

This tutorial is divided into two sections, the first covering the implementation of the Publisher application, and the second the implementation of the Subscriber application. See the figure below.

The tutorial implements both sides of a Web Service¹⁾.

Application Context

In this tutorial, the Web Service Publisher is a distributor of goods, while the Web Service Subscriber is a broker collecting information from different distributors for the benefit of the user (find nearest outlet, shortest delivery time, lowest price, etc.). The Broker processes the returned information and presents the results to the user of the Broker service.

Standard Web Approach	Use of Broker with Web Services
The user goes to the web sites of each of the distributors.	The user goes to the web site of a Broker that collects information from a number of distributors.

In the standard web approach interaction between the user and the distributors is browser based.

In the Web Service approach interaction between the user and the distributors is a mix of browser based communication (between the user and the Broker) and Web Services (between the Broker and the distributors). In other words, a layer of Web Service communication is inserted between the user and the distributors - but without the user needing to change browsing habits or even know about Web Services.

In this example, the communication between the Broker and a single Distributor is implemented. The Broker and Distributor interact using Web Services, where the Distributor acts as the Publisher, while the Broker acts as the Subscriber to Web Service.

Two Web Service functions will be implemented for the Distributor. The first Web Service function will return a list of all available items in the distributor database. This Web Service function will henceforth be referred to as the ReturnAll Web Service.

The second Web Service function will return a more detailed information on specific items specified by the Broker. This Web Service function will be referred to as the ReturnSpecific Web Service.

The Broker calls the ReturnAll Web Service. The returned list of items are then imported into the Broker database. When the customer who uses the Broker service has decided on which items information is wanted, the Broker calls the ReturnSpecific Web Service and subsequently processes the returned data for the customer.

The Broker and the Distributor exchange data using XML documents and Web Services. The import and export functionality used to implement this Web Service example are described in details in the TransacXML implementing section.

Tutorial Limitations relative to "Real World" Applications

The Broker only interacts with one distributor, and the retrieved data is stored in the Broker database without further processing.

In this tutorial the Broker and the Distributor are implemented in the same Plex model - this is of course different from real world applications, where the Subscriber and Publisher will be located in disparate systems.

The interaction between Broker and Distributor is strictly limited to Web Service dialogs - as it would be, if they were placed in disparate systems. Of course the Broker and Distributor could interact directly (as they do in the TransacXML Tutorial), but that would violate the the purpose of the present guide: demonstration of how to implement Web Service with Plex and Websydian.

Difference between the TransacXML implementation and the Web Services implementation

In the figure below, the export from the Distributor database to an XML document with subsequent import into the Broker database is shown as it occurs in the TransacXML implementation guide. How the XML document resulting from the first step is made available to the import in the second step is not described; it could be stored on a removable media, emailed, or copied via the Internet - the agents involved in the operation of copying data from Distributor to Broker are responsible for the transfer of the XML document.

Using simple TransacXML functionality, exchange of data between disparate systems is a two step procedure, where the XML document being used as information carrier must  somehow be transferred from one system to the other.

In the next figure, export from the Distributor database to the Broker database using Web Services is shown. Notice that the Web Service through the SOAP functions handles both the transfer of the XML document and the invocation of the remote functionality - in this example it is the Broker who requests the Distributor to export data and return the XML document through the Web Service.

Using Web Service functionality, exchange of data between disparate systems is a one-step procedure (taking place at two locations), where the Broker initiates the process, and the Distributor answers with an XML document containing the requested information (wrapped in a SOAP Envelope).

A different scenario is also very likely, in which the Distributor "pushes" information onto the Broker. In that case the Distributor and Broker trade places as Subscriber and Publisher.

Preparations

This tutorial is based on the model described in the TransacXML Tutorial.  In order to follow this implementation guide, it is necessary to complete the TransacXML Tutorial.

  A copy of the model - with all functionality implemented as described in this implementation guide - can be downloaded here.

Add namespace to XML documents

When doing WebServices it is recommended adding a namespace to the XML documents used by the WebService. This enables the developer to create well formed WSDL files.
 

Add the following triples to the model.

Add information to the source codes specifying the namespace and prefix

CommonXML.ReturnOffer.Namespace
  http://www.websydian.com/webservicedemo

CommonXML.ReturnOffer.Prefix
  wsdemo

CommonXML.ItemList.Namespace
  http://www.websydian.com/webservicedemo

CommonXML.ItemList.Prefix
  wsdemo

Implementing the Distributor (Publisher) functionality

The Distributor implements two Web Service functions; ReturnAll, and ReturnSpecific.

Specifying the Web Service SOAP Entity

The base entity for the Publisher is the HttpSoap entity.

The core functions in the HttpSoap entity are the SoapGenerator and SoapProcessor. The SoapGenerator is used by a Subscriber to communicate with a web service, whereas the SoapProcessor is used by a Publisher to implement a web service.

The Distributor acts only as Publisher and does not make use of the SoapGenerator function, which should not be generated.

Create the directory c:\temp\SoapProcessor (this is where the SoapProcessor function stores temporary files).

Create an executable file wrapper for the SoapProcessor function.

Open the SOAPDisA.ini file and add the following lines:

[TransacXML]
MAX_CONTENT_LENGTH=10240
TEMPORARY_FILES=c:\temp\SoapProcessor\

The MAX_CONTENT_LENGTH parameter is used to limit the size of accepted Web Service requests, and the TEMPORARY_FILES parameter is used to specify where the SoapProcessor should place temporary files.

Specify XMLHandler function for each Web Service function

The Distributor exports from the database into XML documents both when responding to ReturnAll and ReturnSpecific Web Service requests.

An XmlHandler function is used to implement a web service function. In this tutorial the Distributor implements two XmlHandlers: One for the ReturnAll web service function and one for the ReturnSpecific web service function.

Specify triples to define the XMLHandler function ReturnList:

Open the action diagram for ReturnList and specify the following code in the Edit Point XmlHandler functionality:

Edit Point XmlHandler functionality

Call ExportItemListToXML

  // Map OutputDocument<BodyOutObjectStoreReference>
  // Map OutputDocument<BodyOutDocument>

Call Meta.CheckCall
 

Specify the XMLHandler function ReturnOffer:

Open the action diagram for ReturnOffer and specify the following code in the Edit Point XmlHandler functionality

Edit Point XmlHandler functionality

Call ExportToReturnOffer

  // Map InputDocument<BodyInObjectStoreReference>

  // Map InputDocument<BodyInDocument>

  // Map OutputDocument<BodyOutObjectStoreReference>
  // Map OutputDocument<BodyOutDocument>
 

Specify the XmlHandler functions in the SoapProcessor:

The SoapProcessor now knows two XmlHandler functions, and will - upon Web Service requests - be able to direct the requests to the corresponding XmlHandler functions.

Implementing the Broker (Subscriber) functionality

The Broker imports from the returned XML data into the database both when calling the ReturnAll Web Service and the ReturnSpecific Web Service.

When calling the ReturnSpecific Web Service the Broker exports from the Broker database to an XML document which is passed to the SoapGenerator as the payload of the ReturnSpecific Web Service request.

Specifying the Web Service SOAP Entity

The base entitiy for the Subscriber is the SOAP entity.

Specify  Broker inheritance:

The Broker acts as Subscriber only, and does not make use of the SoapProcessor function.

Specifying the function that calls the Web Service to Import all Items in Distributor Database

The Broker (Subscriber) requests the Distributor to return a list of items. To make such a request it is necessary to call the Distributor (Publisher) Web Service with the correct parameters.
 

Specify a function, WSItemListExchange, which acts as a wrapper function for the Broker SoapGenerator function:

The WSItemListExchange function first calls the Broker SoapGenerator, then imports the returned data into the Broker database.

Open the action diagram of the WSItemListExchange function and add the following code in the specified edit points:

Edit Point Process XML document

Call Broker.Services.SoapGenerator

  // Map Local/InputDocument<ObjectDocument>
  // Map Local/InputDocument<ObjectStoreReference>
  // Map Local/OutputDocument<ObjectDocument>
  // Map Local/OutputDocument<ObjectStoreReference>
  // Map Connection<SOAPAction>
  // Map Connection<InternetServerName>
  // Map Connection<InternetServerPort>
  // Map Connection<InternetApplicationName>
  // Map Connection<InternetUrl>
  // Map <CharSet.utf-8>
  // Map <UseSSL.*No>
Go Sub Check error

If NOT Environment<*Returned status> IS <State: OBJECTS/*Returned status.*Abnormal>
  Call ImportItemListFromXML

    // Map Local/OutputDocument<ObjectStoreReference>
    // Map Local/OutputDocument<ObjectDocument>

  Go Sub Check error

else

  Go Sub Check error

Pre Point Handle error message
Dialog Message Message: OBJECTS/Message
  // Map Environment<*Message text>

Specifying the function that calls the Web Service to Import Specific Items from the Distributor Database

The Broker requests the Distributor to return a list of specific items, based on a supplied XML document. This functionality is exactly the same as in WSItemListExchange, except that the Web Service in this case needs an XML document as input (containing the items for which an offer is requested).

Specify the function, WSReturnOfferExchange

Open the action diagram for WsReturnOfferExchange and add the following code in the specified edit points:

Edit Point Process XML document

Call Broker.Services.SoapGenerator

  // Map Local/InputDocument<ObjectDocument>
  // Map Local/InputDocument<ObjectStoreReference>
  // Map Local/OutputDocument<ObjectDocument>
  // Map Local/OutputDocument<ObjectStoreReference>
  // Map Connection<SOAPAction>
  // Map Connection<InternetServerName>

  // Map Connection<InternetServerPort>
  // Map Connection<InternetApplicationName>
  // Map Connection<InternetUrl>
  // Map <CharSet.utf-8>
  // Map <UseSSL.*No>
If NOT Environment<*Returned status> IS <State: OBJECTS/*Returned status.*Abnormal>

  Call ImportReturnOfferFromXML

    // Map Local/OutputDocument<ObjectStoreReference>
    // Map Local/OutputDocument<ObjectDocument>

  Go Sub Check error

else

  Go Sub Check error

Pre Point Handle error message
Dialog Message Message: OBJECTS/Message
  // Map Environment<*Message text>

Test the functionality

To test the functions, it is necessary to setup the Web Server, and generate and build the functions used.

Create Wrapper functions

First it is necessary to create a test wrapper function for WSItemListExchange and WSReturnOfferExchange, respectively.

Specify the function TestWSItemListExchange:

Specify the contents of the InternetUrl message to Distributor/SoapDisA.EXE

Specify the contents of the SOAPAction message to ReturnList

Insert the following action diagram code into the TestWSItemListExchange function:

Edit Point Execute

Format Message Message: TestWSItemListExchange.InternetUrl, local<interneturl>

Format Message Message: TestWSItemListExchange.SoapAction, Local<SOAPAction>
Call WSItemListExchange

  // Map <FileName.*Blank>
  // Map <version.*Blank>
  // Map <Encoding.*Blank>
  // Map <FileName.*Blank>
  // Map <InternetServerName.localhost>
  // Map <InternetServerPort.HTTP>
  // Map <InternetApplicationName.*Blank>
  // Map Local<InternetUrl>
  // Map Local<SOAPAction>
Go Sub Terminate
 

Specify the function TestWSReturnOffer:

Specify the contents of the InternetUrl message to Distributor/SoapDisA.EXE

Specify the contents of the SOAPAction message to CalculateOffer

Specify the contents of the InputDocument message to c:\temp\Request.xml

Insert the following action diagram code into the TestWSReturnOffer function:

Edit Point Execute

Format Message Message: TestWSReturnOffer.InternetUrl, Local<InternetUrl>
Format Message Message: TestWSReturnOffer.SoapAction, Local<SOAPAction>
Format Message Message: TestWSReturnOffer.InputDocument, Local<BodyFile>

Call WSReturnOfferExchange

  // Map <FileName.*Blank>
  // Map <version.*Blank>
  // Map <Encoding.*Blank>
  // Map Local<BodyFile>
  // Map <InternetServerName.localhost>
  // Map <InternetServerPort.HTTP>
  // Map <InternetApplicationName.*Blank>
  // Map Local<InternetUrl>
  // Map Local<SOAPAction>
Go Sub Terminate

Generate and Build

Generate and build each function implemented in this implementation guide:

• WSReturnOfferExchange
• WSItemListExchange
• TestWSReturnOffer
• TestWSItemListExchange
• Broker
• DistributorA

Create executable wrappers for the functions TestWSReturnOffer and TestWSItemListExchange.

Add the following information to the ini files for the functions

[TransacXML]
TEMPORARY_FILES=c:\temp\SoapGenerator\

Specify Web Server Configuration

To make the Distributor Web Services available for the Broker, it is necessary to setup a web server. Please consult the appropriate section of the Websydian documentation for details on how to do this.

Run the Test Functions

Run the functions TestWSItemListExchange and TestWSReturnOffer.

As a result of running TestWSItemListExchange the database Data.All Items now holds the entire inventory from Distributor A.

As a result of running TestWSReturnOffer the database Data..Returned Items now holds the requested items specified in the input XML document, but with more details (price and delivery time).