|
|
Users Guide | Patterns Reference | WebsydianExpress | Search |
|
|
Users Guide | Patterns Reference | WebsydianExpress | Search |
| » Related Information |
|---|
Introduction Implementing Other Uses Parts Tutorial Glossary
The Soap entity forms the base for the entire WsySOAP pattern. The Soap entity consists of the transportation method invariant parts of a SOAP implementation, and transportation method specific implementations inherit from the Soap entity.
The Soap entity is an abstract entity which should only be inherited from when binding an implementation to a new transportation method not present in the pattern. In the present version of WsySOAP the transportation method HTTP is implemented in HttpSoap described below.
The Abstract entity contains the functions SoapGenerator, which generates and sends SOAP Messages, SoapProcessor, which receives and responds to SOAP Messages, Transport which is an empty transport shell function, and XmlHandler, which is a function prepared for interaction with the SoapProcessor.
The SoapGenerator is the main function used by the Subscriber.
The SoapGenerator wraps the SOAP Payload in a new SOAP Request, and then initiates a SOAP Dialog with the specified Publisher.
When the Dialog has ended, the SoapGenerator unwraps the returned SOAP Payload and returns a reference to the Payload for the Subscriber to use.
As input parameters the SoapGenerator takes a reference to the input SOAP Payload (BodyFile), the parameters necessary to connect to the Publisher, and the encoding wanted for the response SOAP Payload. Also, the SoapGenerator takes certain SOAP parameters as input.
The usage of the SoapGenerator is described in detail in the Implementing section.
The SoapProcessor is the main function used by the Publisher, being roughly the SOAP equivalent of the Websydian Dispatcher.
The SoapProcessor receives the SOAP Requests from the Subscriber (through a Web Server when HTTP is the transportation method) and acts accordingly to the contents of the SOAP Request.
If the action specified in the SOAP Request is recognized (and optional subsequent validation passed) the SoapProcessor extracts the SOAP Payload from the SOAP Request and passes the necessary information to the proper XmlHandler (described below).
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.
The SoapProcessor scopes a function for creating a WSDL (Web Services Description Language) file. This functionality is described in detail in the Create WSDL Guide.
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 overwriten:
| MySoap.Services.SoapProcessor.CreateWSDL | implement SYS | Yes |
The abstract Transport function is basically an empty shell with entry points prepared for specific transportation method code. The Transport function is called from the SoapGenerator function and takes care of both sending SOAP Requests and receiving the corresponding SOAP Responses.
When a Subscriber is bound to a transportation method, the abstract Transport is replaced by an implemented Transport function, e.g. HttpTransport (described below).
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 routines Subscriber Validation and Handle Xml.
Usage of the XmlHandler function is described in detail in the Implementing section.
The Soap.Data entity scopes the two entities Envelope and Fault, shared by the SoapGenerator and the SoapProcessor. Both Envelope and Fault are XML document structures, reflecting the structure of SOAP Messages when no errors are encountered (Envelope) and when a Fault is returned to the Subscriber (Fault).
Use of the Envelope and Fault entities are automated in the SoapGenerator and SoapProcessor, but additional processing can be added by the developer.
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 adher to the SOAP 1.1 Standard. A thorough description of the SOAP 1.1 standard is not within the scope of this document, and we refer to the various sources of information on the Internet, e.g. SoapWares "Busy Developers Guide to SOAP". The authoritative (but rather technical) description of the SOAP 1.1 standard can be found in W3's repository for Technical Reports and Publications: SOAP Specification.
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>
The Fault entity is used to return Fault to the Subscriber. The Fault entity scopes an Envelope entity similar to the Envelope described above, except that the sub structure 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.
An example can be found here.
Contains various helper functions for the SoapGenerator and SoapProcessor functions.
This function extracts SOAP headers from a SOAP message. The SOAP headers to be extracted must be defined on the EnvelopeFlatView function, e.g:
| MySoap.Services.EnvelopeFlatView | is a FNC | MySoap.Data.Envelope.Header.MyHeader.FieldHolder |
The input parameters to the EnvelopeFlatView function are shown in the table below.
| Input | Map with |
|---|---|
| ObjectStoreReference | ObjectStoreReference to the SOAP message document |
| ObjectElement | Reference to the Envelope element in the SOAP message |
The ValidateSOAPMessage and ExtractSOAPBody functions are used internally by the SoapGenerator and SoapProcessor functions. In most cases it is not necessary to make explicit calls to these functions or modify them in any way.
The HttpSoap entity inherits from Soap and is bound to the HTTP transportation method.
Inherit from HttpSoap if you want to use HTTP as transportation method.
If deploying the web service (SoapProcessor) as a J2EE application then the SoapProcessor must inherit from this function.
HttpSoap.Services scope the implemented SoapGenerator and SoapProcessor used to implement Subscriber and/or Publisher functionality for the HTTP protocol.
The function HttpTransport is used by the HttpSoap.
Online documentation - Websydian v6.0