Using SOAP

Using SOAP

Sander Duivestein

The Simple Object Access Protocol (SOAP) is a hot topic these days. The technology itself is simple, as shown by Sander Duivestein in this article. But the implications of its use are very exciting. It means that you'll be able to use objects and call methods located on other machines on the Internet. It doesn't matter what language they were written in nor what platform they're running on. SOAP solves all of those problems in one stroke!

Right now I'm sitting behind my laptop in a hotel room in London. Each week I face the same trouble of getting back to the Netherlands. I have to call the travel agency that arranges my flight and train tickets. I'm totally dependent on the tight travel schedule given to me. Then I have to contact the hotel to make sure that I have a reservation for the following week.

Why do I need to spend time on these issues every week? Isn't there a way that I could make those arrangements myself? Wouldn't it make life easier if there was a Web site that incorporated all of those third party services and offered them to the public? And how would that Web site incorporate all of these third party services?

SOAP

Web sites today are developed on a variety different platforms (UNIX, Linux, NT, and so on), in different languages, and by using different object models (COM, CORBA, JAVA, RMI, and so forth). All of these Web sites expose different services to the public. So how could you use these services within your own Web site? How can you invoke remote objects that live on different servers using the Internet? The answer to all of these questions is SOAP.

Microsoft describes SOAP this way: "SOAP is a lightweight protocol for exchange of information in a decentralized, distributed environment. It's an XML-based protocol that consists of three parts: an envelope that defines a framework for describing what's in a message and how to process it, a set of encoding rules for expressing instances of application-defined datatypes, and a convention for representing remote procedure calls and responses. SOAP can potentially be used in combination with a variety of other protocols."

In this article, I want to provide a sample application that uses SOAP to demonstrate how it can be put to practical use.

Sample application

The sample application consists of several files:

? SOAPClient.htm

? SOAPServer.asp

? Authors.xsl

? ShowXML.xsl

? Authors.dll

Authors.dll is a COM component that has two classes inside: clsConnectionManager, which manages ADODB connections, and clsRetrieve, which retrieves an ADODB recordset from the database.This example is simple, as it queries the Authors table of the MS SQL Server Pubs database. A client (SOAPclient.htm) contains a HTML form that has three elements. There are two text boxes and a submit button. A user can enter a firstname and/or a lastname and then submit the form by clicking the button. But this form isn't submitted in the same way that most forms are.

When the Submit button is pushed, a Javascript function, SendSOAPRequest(), is triggered and the events specified in Table 1 happen.

Table 1. The sequence of events that happen when the SendSOAPRequest() is triggered.

The SOAP specification declares that when using SOAP over HTTP, you have to define a HTTP header. This header contains several elements:

? An endpoint—Where the receiver of the SOAP request lives. This endpoint should match the location where you have put this example on the Web server.

? SOAPAction—The SOAPAction describes the purpose of the SOAP call; in this example, the purpose of the call is to invoke the method "GetAuthors" on the remote object "Authors.clsRetrieve." Firewall administrators can also use the SOAPAction attribute to block out certain SOAP calls.

? An indication that the mime-type of the header is XML.

Setting the SOAP HTTP header is achieved using the Microsoft XMLHTTPRequest object (see Listings 1 and 2 ).

Listing 1. How to set the HTTP header.

var objXMLHTTP = _  
 
new ActiveXObject("Microsoft.XMLHTTP");

objXMLHTTP.open("POST", _  
 
"http://cp23283-a/SOAPWEB/SOAPServer.asp", false);

objXMLHTTP.setRequestHeader ("SOAPAction", _   

"Authors.clsRetrieve" + "#GetAuthors"); 

objXMLHTTP.setRequestHeader ("Content-Type", _    "text/xml"); objXMLHTTP.send(BuildSoapEnvelop()); 

Listing 2. How to build a SOAP request.

 function BuildSoapEnvelop() {

 //Retrieve FirstName and LastName

var FirstName = _ 
 
document.frmSoapClient.txtFirstName.value;

var LastName = _  
 
document.frmSoapClient.txtLastName.value; 

//Build SOAPEnvelope

var SOAPEnvelope = "<SOAP-ENV:Envelope "

 + " xmlns:SOAP-ENV="
 
+ "'http://schemas.xmlsoap.org/soap/envelope/'" 

+ " xmlns:SOAP-ENC="
 
+ "'http://schemas.xmlsoap.org/soap/encoding/'>"

 + " <SOAP-ENV:Body>" 

+ " <m:GetAuthors xmlns:m='my-namespace'>"
 
+ " <Id/>" 

+ " <FirstName>"+ FirstName+ "</FirstName>" 

+ " <LastName>" + LastName + "</LastName>"
 
+ " </m:GetAuthors>"
 
+ " </SOAP-ENV:Body>"
 
+ " </SOAP-ENV:Envelope>";
 
return SOAPEnvelope;

} 

The SOAP request / message contains several elements:

? A mandatory Envelope

? An optional Header

? A mandatory Body

The Body element contains the methodname (GetAuthors) and the parameters of the method (FirstName and LastName).

Submit the SOAP request

This is the simplest part of the application. Just call the method send of the XML.HTTP component:

 objXMLHTTP.send(BuildSoapEnvelop());

Receive, translate and invoke the SOAP request

The first thing the SOAPServer.asp does is parse the submitted SOAPAction from the HTTPHeader into the remote object's name (Authors.clsRetrieve) and the remote object's method (GetAuthors).

 'Get the HTTPHeader SOAPAction strSOAPAction = _    Request.ServerVariables("HTTP_SOAPAction")  'Strip the SOAPAction into two parts:  ' the remote object and the methodname strObject = _    Left(strSOAPAction, Instr(strSOAPAction, "#") - 1) strMethod = _    Right(strSOAPAction, _       Len(strSOAPAction) - Instr(strSOAPAction, "#"))

The only things you need to know now are the FirstName and the LastName.

 'Get FirstName and LastName from XML strFirstName = _    objXML.getElementsByTagName("*").item(4).text strLastName = _   

objXML.getElementsByTagName("*").item(5).text InvokeRemoteObject strObject, strMethod, _    strFirstName, strLastName

The method InvokeRemoteObject simply invokes the remote object Authors.clsRetrieve. (This component must be registered on the Web server by using regsvr32) . This COM component queries the Authors table from the Microsoft SQL Server Pubs database. The result of the query is returned as an ADODB.Recordset to the SOAPServer.asp. In order to query the database, you have to adjust the strConnectionString in the SOAPServer.asp. The ConnectionString contains the name of the MS SQL Server database.

Build SOAP response

The ADODB.Recordset is then translated into an XML message:

 'Query remote component

Set oRs = _   

oAuthors.GetAuthors (strConnectionString, _     

 strFirstName, strLastName)

 'Build XML Resultset

strXML = strXML & _   

"<m:" & strMethod & _  

 "Response xmlns:m='my-namespace'>"

strXML = strXML & _ 
 
"<SOAP-ENC:Array SOAP-ENC:arrayType=" & _  
 
"'xyz:Author[" & oRs.RecordCount & "]'>"

strXML = strXML & _  

 "<results type='xyz:Author[" & _   

oRs.RecordCount & "]'>"
 
'Loop through the recordset

Do While Not oRs.EOF   

strXML = strXML & "<Author>"  
 
For i = 0 To oRs.Fields.Count - 1      

strXML = strXML & _         

"<" & oRs.Fields.Item(i).Name & ">" & _      

oRs.Fields.Item(i).Value & "</" & _      

oRs.Fields.Item(i).Name & ">" 

Next   

oRs.MoveNext   

strXML = strXML & "</Author>"

Loop

strXML = strXML & "</results>"

strXML = strXML & "</m:" & strMethod & "Response>"

As you can see, a SOAP response is identified by using the original method name (GetAuthors) post-fixed with the word Response. After building the SOAP response, you can return this result back to the client.

Receive and show SOAP response

In this example, I have defined three layers: One layer shows the SOAPRequest, one layer shows the SOAPResponse, and one layer shows the SOAPResponse in an HTML table.

//Show SOAP Response

objXMLDOM.loadXML(objXMLHTTP.responseXML.xml);

 if (document.frmSoapClient.chkShowSOAP.checked == true) {    LoadXSL("ShowXML.xsl", SOAPResponse);

}

 //Translate SOAP Response to HTML and show HTML

 LoadXSL("Authors.xsl", HTMLResponse);

Conclusion

This is a very simple SOAP example, as it only took me several hours to build, which is one of the underlying goals of the SOAP specification: "Keep SOAP simple and make it easy to implement." I haven't dealt with all of the issues. For example, I didn't consider SOAP Faults in the application, but you should when you build your own. I also didn't loosely couple my COM component from my SOAPServer (SOAPListener).

At this moment, there are several (free!) tools on the market that you can download to help build this kind of application yourself. The first one you should check out is the Microsoft SOAP toolkit on the Microsoft Web site.

If you want to know more about SOAP, I suggest you take a look at the following Web sites. They provide a wealth of information:

? http://www.develop.com/soap

? http://www.soap-wrc.com/