Dr.Bob's Kylix 2 Developer's Guide BizSnap chapter (XML, SOAP and WebServices)

Delphi Clinic

C++Builder Gate

Training & Consultancy

Delphi Notes Weblog

Dr.Bob's Webshop


	Kylix 2 BizSnap - XML, SOAP & WebServices (4 of 6)
See Also:	Kylix Papers and Columns

I have been working on an BizSnap chapter for the Kylix Developer's Guide - adding more coverage of Kylix 2 to this book. The BizSnap chapter will be published on my website (in six weekly parts), covering XML Document Programming and Web Services support.

BizSnap is the name given by Borland to describe the feature set of Kylix 2 Enterprise that covers XML document programming as well as Web Services (using SOAP). In this chapter, we will first cover XML document programming using the TXMLDocument component. This will be enhanced using XML Data Binding and even further using the XML Mapping Tool.
We then move on to Web Services, and after a short introduction to SOAP, we'll implement our first Web Service in Kylix 2, followed by the usage (consuming) of Web Services written in Kylix or other development environments. Finally, we show the powerful combination of BizSnap with DataSnap to produce distributed applications (even cross-platform, considering that Delphi 6 also supports this on Windows).

4. Web Service (Server)
So far you've seen the XML document capabilities of Kylix 2 Enterprise using XML Document Programming, with additional support using the Data Binding Wizard and advanced transformation capabilities using the XML Mapper. And now you're ready to examine another XML-capability of Kylix in the shape of SOAP and Web Services. It sounds difficult, but will turn out to be easy - just wait and see.
SOAP stands for Simple Object Access Protocol, and is a cross-platform and cross-language protocol, which is not only supported in Kylix 2, but also in Delphi 6, and lots of other tools.

SOAP Server Application
Start Kylix 2 Enterprise, choose File | New, go to the WebServices tab of the Object Repository, and select the SOAP Server Application icon. Note that the names of the icons are abbreviated (at least in my version of Red Hat Linux - see Figure 13), but from left to right they are as follows: Soap Server Application, Soap Server Data Module, and Web Services Importer.

Figure 13: The WebServices tab of the Object Repository

After you've double-clicked on the Soap Server Application icon, the wizard starts, asking about the type of Web server application that you want to use for your Web Service. Because an Apache DSO application requires additional configuration of the Apache Web server (see Chapter 19 for details), I've selected a CGI application for this example.

Figure 14: New SOAP Server Application

After you click on the OK button, a new SOAP Server project is created, including a Web module. Save the Web module in file SWebMod.pas and the new project itself in K2WebService.dpr (this will result in a Web service Web server application called K2WebService).

SOAP Server Web Module
The Web module already contains three components (that can also be found on the WebServices tab of the Component Palette), namely a THTTPSoapDispatcher, a THTTPSoapPascalInvoker, and a TWSDLHTMLPublish component.

Figure 15: SOAP Server Web module

The THTTPSoapDispatcher component is used to receive incoming SOAP requests and dispatch them to another component (defined by its Dispatcher property) that can interpret the request and execute it. The latter will be done in this case by the THTTPSoapPascalInvoker component, which receives the incoming SOAP request, executes (invokes) a Pascal method, and produces the response back to the THTTPSoapDispatcher. But before the THTTPSoapPascalInvoker can actually invoke the requested Pascal method, it first checks to see if the method's interface and implementation class have been registered (in the invocation registry - we'll get back to this in a moment).
Where the first two components are used when the Web service is actually consumed, the third component, TWSDLHTMLPublish, is used to produce the WSDL (Web Services Description Language) that defines the interface of the Web service itself.
You don't have to configure these three components: they are ready to be used. You only have to focus on the task at hand: build some kind of Web service engine, and define its interface so it can be published and used.

Web Service Interface
Although you now have the Web Service skeleton, you have no SOAP object or Web Service interface to expose to the outside world (yet). To get an idea what kinds of functionality is suited as Web Service application, you can take a look at the list of Web services http://www.xmethods.org, which already includes half a dozen Delphi 6 and Kylix 2 Web Services written by yours truly (see also http://www.drbob42.com/SOAP for some more). In fact, the only Kylix 2 Web Service listed at www.xmethods.org at this time is the EuroConversion (written by me).
As example for this section, I want to produce a Web Service that can convert inches to centimeters and back. It's only a small example, but will illustrate all the Web Services functionality quite nicely (and it's actually quite useful if you live in Europe and are used to centimeters but want to estimate whether or not a 19" LCD screen will fit between the table desktop and the bookshelf). You must start with the interface definition. Let's give the interface the name ICmInch. It must be derived from IInvokable, and also needs a GUID (press Ctrl+Shift+G to produce a GUID in the Kylix 2 IDE). Then, you need two functions: Cm2Inch and Inch2Cm, both taking a Double as argument and returning a Double again. The code can be seen in the listing below, which is saved in unit CentimeterInchIntf.pas:

  unit CentimeterInchIntf;
  interface
  uses
    Types;

  type
    ICmInch = interface(IInvokable)
      ['{C53E42A9-8488-4521-BCB4-60863FF09E83}']
      function Cm2Inch(Inch: Double): Double; stdcall;
      function Inch2Cm(Cm: Double): Double; stdcall;
    end;

  implementation
  uses
    InvokeRegistry;

  initialization
    InvRegistry.RegisterInterface(TypeInfo(ICmInch));
  end.

Note that the calling convention that I'm using here is stdcall (which is a good idea for any method you declare inside your SOAP interface). Also note the call to RegisterInterface, which is needed to register the ICmInch interface.
After you've typed the complete (short) source code from this listing in a new unit, you need to make sure that this unit is added to your K2WebService project.

Web Service Implementation
Apart from defining the Web Service ICmInch interface, you must also implement the ICmInch interface (otherwise nobody could use it). This is done in the following unit, in which the new class TCmInch is derived from TInvokableClass and specified to implement the ICmInch interface (saved in unit CentimeterInchImpl.pas):

  unit CentimeterInchImpl;
  interface
  uses
    CentimeterInchIntf, InvokeRegistry;

  type
    TCmInch = class(TInvokableClass, ICmInch)
    public
      function Cm2Inch(Inch: Double): Double; stdcall;
      function Inch2Cm(Cm: Double): Double; stdcall;
    end;

  implementation
  const
    CmPerInch = 2.54;

  function TCmInch.Cm2Inch(Inch: Double): Double;
  begin
    Result := Inch / CmPerInch
  end;

  function TCmInch.Inch2Cm(Cm: Double): Double;
  begin
    Result := Cm * CmPerInch
  end;

  initialization
    InvRegistry.RegisterInvokableClass(TCmInch)
  end.

Again, you need to register, but this time the TCmInch class implements the SOAP object itself. And again this unit must be added to the K2WebService project.

Deploying the SOAP Server
This is it. After you've saved your project files, you can compile the Web Service application. To use it, you must now deploy it as the CGI Web server application that you selected before. Just for your convenience, I've done that already, and the K2WebService is available to use as demonstration on my Linux-based Web site (hosted by TDMWeb) at http://www.drbob42.co.uk/cgi-bin/K2WebService.
Note that this direct URL won't do anything. You actually have to pass the additional PathInfo /wsdl to get the Web Service Description Language (automatically produced by the TWSDLHTMLPublish component), resulting in http://www.drbob42.co.uk/cgi-bin/K2WebService/wsdl. See Figure 16.

Figure 16: WebService listing of K2WebService/wsdl

If you click on the link for the WSDL for ICmInch (or directly go to the URL http://www.drbob42.co.uk/cgi-bin/K2WebService/wsdl/ICmInch) then you get the full WSDL for the ICmInch interface. (This cannot be shown by Netscape, but you can save the resulting XML file for later use, such as when writing a Web Service client, which is also known as consuming a Web Service).

Next Time, Dr.Bob says...
In the next section, we'll continue our coverage of SOAP when we start to consume Web Services (such as the one we just made) using Kylix 2 Enterprise. All this and more next week, so stay tuned...