WsySoap Parts

Introduction    Implementing    Other Uses    Parts    Tutorial    Glossary

Entity: HttpSoap

The HttpSoap entity forms the base for the entire WSYSOAP pattern. To implement either functionality for subscribing to a web service or for providing a web service, you must start by creating an entity that inherits from this entity.

Entity: HttpSoap.Abstract

This entity contains abstract functions that you can use to create your custom-built functions.

Function: HttpSoap.Abstract.J2EESoapProcessor

If you are deploying your (Java) SoapProcessor as a J2EE application, the SoapProcessor must inherit from this function.

Function: HttpSoap.Abstract.XmlHandler

All the XMLHandlers you use in the SoapProcessor must inherit from this function.

The XmlHandler function is an abstract function prepared to be called from the SoapProcessor. Inherit from XmlHandler and implement the business logic in the sub routine Handle Xml.

HttpSoap.Data

This entity contains the definitions for the SOAP XML structures that will be wrapped around the request and response documents. It also contains definitions for the fault element that is returned when an error occurs during the handling in the SoapProcessor.

These structures are generated and built - and are used by the SoapGenerator and the SoapProcessor to unwrap and wrap the payload documents.

You can change these structures if you want to transfer information in the SOAP header sections (or receive information contained in the headers).

Entity: HttpSoap.Data.Envelope

The Envelope entity is the base XmlElement of SOAP Requests and successful SOAP Responses (the entity Fault is used for SOAP Responses carrying error messages). 

The Envelope with its substructure of XmlElements and fields is specified as described in the SOAP 1.1 Standard.

Briefly described, a SOAP Message has the root element Envelope, which scopes the optional element Header and the mandatory element Body. A number of rules regarding namespaces and order of appearance are specified. Below is shown a rough outline of a SOAP Message (for brevity the namespace declarations are not included).

<SOAP-ENV:Envelope>
    <SOAP-ENV:Header>
        <!-- Header entries here -->
    </SOAP-ENV:Header>
    <SOAP-ENV:Body>
        <!-- Body content here -->
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Entity: HttpSoap.Data.Fault

The Fault entity is used to return errors to the subscriber. The Fault entity scopes an Envelope entity similar to the Envelope described above, except that the substructure is a bit different as the SOAP specification declares Fault and Detail elements as required by the SOAP standard.

In addition to this, the Detail element includes an errordetails repeating element. This element has two simple elements: errorcode and errordescription.

If an error occurs in the SoapProcessor during processing of a SOAP message then a SOAP Fault message will be returned and the Detail element will contain one or more errordetails elements describing the cause of the error.

Function: HttpSoap.Services

This function scopes the implemented objects that are used to implement the publishing of web services and the subscribing to web services.

Function: HttpSoap.Services.CallSoapGenerator

This is the function you should call when implementing the subscriber role (calling a web service).

The function receives the URL to call, the Soap Action and the identification of the request and the response documents.

The function resolves the different parts of the URL and calls the SoapGenerator.

Function: HttpSoap.Services.EnvelopeFlatview

This function extracts SOAP headers from a SOAP message. The SOAP headers to be extracted must be defined on the EnvelopeFlatView function, e.g:

The input parameters to the EnvelopeFlatView function are shown in the table below.

Function: HttpSoap.Services.SoapGenerator

This function performs the http client call to the provider. You can call this function directly, but it is generally easier to call it through the CallSoapGenerator function.

The SoapGenerator wraps the request document in a new SOAP Request, and then initiates a SOAP (HTTP) Dialog with the specified publisher.

When the Dialog has ended, the SoapGenerator unwraps the returned SOAP Response and returns a reference to the response document to the calling program.

Function: HttpSoap.Services.SoapProcessor

The SoapProcessor is the main function used by the publisher, being roughly the SOAP equivalent of the Websydian EventDispatcher.

The SoapProcessor receives the SOAP requests from the subscriber (through a Web Server) and acts accordingly to the contents of the SOAP Request..

If the action specified in the SOAP Request is recognized, the SOAPProcessor extracts the Request document from the SOAP Request and passes the necessary information to the proper XmlHandler.

The response from the called XmlHandler is wrapped in a SOAP Response message, which is returned to the subscriber.

Per default, the SoapProcessor handles errors by returning a SOAP Fault Message to the subscriber.

Function: HttpSoap.Services.SoapProcessor.CreateWSDL

This function is used when you are going to be the publisher of a web service, and you need to create a WSDL file to make it possible for others to call your service.

By default the triple implement SYS/No is set on this function so in order to make use of this function the default behavior must be overwritten:

Function: WebServiceCaller

The WebServiceCaller abstract function is used when you want to call a web service.

The function creates two XML parser documents - one for the request document and one for the response document.

The function  contains three important edit points:

1. Create request document

   In this edit point, you should use the InsertRow functions scoped by the XMLElement entities that models your request document to create the request document. The document you should add the elements to is specified by the object references in the local variable RequestDocument.

2. Call soap generator

   In this edit point, you should setup the parameters for the call to the soap generator - and call the CallSoapGenerator function that is scoped by the Services function under your HttpSoap entity.

3. Read response document

   In this edit point, you should use the GetFirstOccurrence, SingleFetch, ProcessGroup functions or the TraverseAndFetch functions scoped by XMLElement entities that models your response document to read the response data. The document you should read from is identified by the obejct references in the local variable ResponseDocument.