18.6. Developing Web Service

There are three fundamental technologies of SOAP ( Simple Object Access Protocol ), WSDL ( Web Services Description Language ) and UDDI ( Universal Description, Discovery and Integration ) in the Web Service. All the data is in XML format, and the services are implemented by using internet protocols such as HTTP/SMTP.

SophiaFramework provides SOAP and WSDL classes.

Table 18.13. SOAP class

Class name	Description
`SFXSOAPParser`	Class for parsing SOAP message using DOM method.
`SFXSOAPWriter`	Class for creating SOAP message.
`SFXSOAPRPC`	Class for handling SOAP-RPC protocol.

Table 18.14. WSDL class

Class name	Description
`SFXSOAPServiceProxy`	The WSDL document is automatically parsed, and the Function to create SOAP message are provided.

18.6.1. SOAP

SOAP ( Simple Object Access Protocol ) document consists of three elements: Envelope, Header and Body.

SFXSOAPParser class inherites SFXXMLDOMParser class and expands the DOM tree onto memory. Any SOAP message information can be obtained only by parsing the SOAP message without the need to get the DOM tree.

Main functions of SFXSOAPParser class

Table 18.15. Main Function of SFXSOAPParser

Function Name	Description
`SFXSOAPParser::GetEnvelope`	get envelope element of SOAP message
`SFXSOAPParser::GetHeader`	get header element of SOAP message
`SFXSOAPParser::GetBody`	get body element of SOAP message
`SFXSOAPParser::GetFault`	get fault element of SOAP message

Table 18.16. Main Helper Function

Function Name	Description
`SFXSOAPParser::GetBodyEntries`	get all the entry nodes in the body of SOAP message
`SFXSOAPParser::GetHeaderEntries`	get all the entry nodes in the header of SOAP message
`SFXSOAPParser::GetBodyEntry`	get the entry node in the body of the SOAP message
`SFXSOAPParser::GetRPCParameter`	get parameter element in the body of SOAP message
`SFXSOAPParser::GetRPCResult`	get the first child element of the first entry in the body of SOAP message
`SFXSOAPParser::GetRPCStruct`	get the first entry in the body of SOAP message

SFXSOAPWriter is the class to create the elements of SOAP message using SFXXMLDocument.

SFXSOAPRPC is the class to implement SOAP-RPC protocol using SFXSOAPParser and SFXSOAPWriter.

Web service is called by setting the Web service method name, the targetted URI, parameters, Web service IP address, soapAction attribute of Web service functions, and the callback function.

Set the SOAP message created by using the SFXSOAPWriter class as argument of the SFXSOAPRPC::Invoke function, then the Web service is called. In the shortest case, its code size may be less than 10 lines.

18.6.2. WSDL

WSDL ( Web Services Description Language ) is a standard language to define the Web service APIs. By using WSDL, Web services such as SOAP binding can be abstractly defined in a high level instead of in the SOAP message layer.

If using SFXSOAPServiceProxy, you don't need to understand the contents described in WSDL. You have only to set the Web service name, the port name, the function name, and parameters of the calling function for calling a Web service.

The mechanism to implement a Web service in SFXSOAPServiceProxy is as follows, a WSDL document is parsed by using SFXXSDDOMParser, then a SOAP message corresponding to the WSDL document is generated and passed to the SFXSOAPRPC object.

SFXXSDDOMParser is the parser corresponding to the XML Schema grammar. (WSDL document is implemented by using XML Schema. )

	Caution
	Note that a lot of memory is needed when parsing a WSDL document by the DOM parser.

18.6.3. Input Parameters

If SFXSOAPRPC is used, the parameters must be correctly set on the basis of SOAP message.

In case of SFXSOAPServiceProxy, only the input parameters described in the WSDL document are set.

18.6.4. Return Values

If SFXSOAPRPC and SFXSOAPServiceProxy are used, connecting to a server is through the HTTP/HTTPS protocol.

The replied message in SOAP format is obtained using a callback function. The replied mesage should be parsed by one of the following three functions.

Parse the SOAP message using SFXSOAPParser. If there is the definition maxOccurs="unbounded" in the WSDL document, for an element defined by the XML Schema, two or more parameters with the same name may exist. there is a possibility that same name parameters may exist in the elements defined by XML Schema. In this case, Sophiaframework keeps the last parameter and ignores the others.
Get each element using the SFXSOAPRPC::GetParams function. Each parameter element in the SOAP message is sequentially saved as the SFXSOAPRPC::PARAMETER structure.
Get each element using the helper functions of SFXSOAPRPC and SFXSOAPServiceProxy such as a GetResultValueByName function.

	Frequently Used Method
	To parse the SOAP message, usually adopt the first method using the `SFXSOAPParser` function.

	SOAP Fault
	If the SOAP message replied from the web server includes the SOAP Fault message, the error value to be notified to the callback function will be SFERR_SOAP_FAULT_MESSAGE. Moreover, detailed information on this error value can be obtained by accessing the SOAP Fault message of the `SFXSOAPRPC::FAULT` structure.