Unwrapping Microsoft's SOAP Toolkit, Page 2
While this all may feel a bit mystical in its simplicity, there really is nothing very extraordinary on the server. SOAP takes care of packaging the method call on the client, and unpackages the request on the server. For the code that implements the GetStockQuote method, there are but three important lines of code in the services.asp file.
set oWire = Server.CreateObject("Rope.WireTransfer") sBuffer = "http://moneycentral.msn.com/scripts/webquote.dll?iPage=lqd&Symbol=" & Symbol sBuffer = oWire.GetPageByURI(CStr(sBuffer))
The WireTransfer object provides functionality for conducting HTTP POST and GET operations, and the GetPageByURI retrieves a page based on a supplied URI, which in this case invokes the Web service and returns the requested data to the client. Another dozen or so lines of code in GetStockQuote prettify and extract the data from the returned sBuffer string.
The code to return the server system time from the GetServerTime function demonstrates just how much rocket science is involved:
GetServerTime = Now
It just doesn't get simpler than that!
One nice tool in the toolkit is the SDL wizard. The wizard can generate a Service Definition file from any existing COM component that provides the Web service. The wizard creates the XML file necessary to expose the COM object as a Web Service as well as a skeleton listener file that receives client requests, instantiates the COM object, and calls the requested method. All you need to do is add any additional code to the ASP or ISAPI listener file to make the service work properly. The wizard saves a lot of work and helps you learn how to structure SOAP on the server.
Figure 2 shows how the SDL Wizard steps you through the process of auto-generating and XML file that describes the services provided by a COM object. Here you can select which methods you want to include in the Web service.
SOAP on a ROPE
Proving that the punmeisters are working hard, the SOAP toolkit introduces ROPE, the Remote Object Proxy Engine. The other parts of the toolkit are sufficient for using SOAP itself, but it can be hard work writing the code that packages everything together into the required formats defined by SOAP that HTTP can handle. So ROPE provides an infrastructure in the form of ActiveX objects to build SOAP applications on both the client and server.
On the client, ROPE assists the application with packaging the SOAP message and then unpacking any reply that it receives from the server. On the server, it supports building a listener' application that can receive, parse, and dispatch SOAP messages back to the client, as well as executing locally the methods requested by the client.
ROPE provides several COM objects, but the one you're likely to use most often is Proxy. There are but five properties and methods to Proxy, making it painless to package and send a SOAP request, here in a non-browser Visual Basic application:
Private Sub btnGetStockQuote_Click()Dim sBuffer As StringDim oProxy As ROPE.Proxy Set oProxy = New ROPE.Proxy oProxy.LoadServicesDescription icSTRING, ServicesDescription sBuffer = oProxy.GetStockQuote(txtSymbol.Text, "any company") MsgBox "Share price = " & sBuffer, vbOKOnly, txtSymbol.Text Set oProxy = NothingEnd Sub
This code retrieves a current stock price from a Web service by providing the stock symbol and description as parameters. After creating an instance of the ROPE Proxy object, it loads the Services Description file that contains information about the methods the Web service makes available, parameter data types, and any return data types. This file is written using the Service Description Language (SDL), an XML file that does for SOAP roughly what a type library does for COM: identify what the component or service can do.
The Services Description file identifies the URL or URI needed to locate the Web service, sets up namespaces, and defines the available methods. For our stock quote example, this is the SDL:
<interface name="QuoteInterface"> <requestResponse name="GetStockQuote"> <request ref="ss:GetStockQuoteInput" /> <response ref="ss:GetStockQuoteOutput" /> <parameterorder>symbol description</parameterorder> </requestResponse></interface>
This is XML as defined in the SDL specification, describing the interface, methods, and parameters used by the Web service methods. SDL is quite flexible, allowing for features such as interface definitions, request and response definitions, and a form of inheritance.
Back in the Visual Basic code, once the Service Description file loads, the Proxy object's interface is expanded to support the methods of the Web service, allowing immediate invocation of any method. A potential problem with this way of doing things is that the methods of the Web service are late bound even if the Proxy object itself is early bound, since there is no way to know at design time what methods the Web service will provide at run time. I'm not too concerned about that because in my experience any slowness from using late bound objects likely pales to the delay from passing the information over the Internet, even small chunks of text. But it also prevents development environments like Visual Basic and Visual C++ from using Intellisense to provide a list of available Web service methods.
Once the client application invokes the method, it can use any return data and then release the Proxy instance. The whole process should feel remarkably familiar, almost like doing any kind of remote call with DCOM, but with different infrastructure requirements. Using ROPE saves a lot of work in your applications, and makes it easy to accommodate changes in SOAP as the standard evolves. Best of all, the full C++ source code for the ROPE.dll is included in the toolkit.
As I write this, SOAP is still a relatively new W3C Note, the first step on the way to becoming a standard. Changes are sure to come as the standards committee forms and begins its work. But with the weight of Microsoft behind it, and their commitment to make it a part of the next version of the Visual Studio tools, SOAP is sure to have an impact on how we do Web development in the years to come, at least on Windows.
About the author: Don Kiely is a Software Technologist at Third Sector Technologies in Fairbanks, Alaska, and has written and co-written several programming books.