Sign in Join
Wiki copytemporary

Web Service Toolkit

English · Français · Português · Русский

"Web Service Toolkit” is a web services package for FPC, Lazarus and Delphi; “Web Service Toolkit” is meant to ease web services consumption and creation by FPC, Lazarus and Delphi users.

Client Side ( service consumption )

Mailing list: http://groups.google.com/group/wst-list

Subversion checkout: svn co https://svn.code.sf.net/p/lazarus-ccr/svn/wst/trunk

Overview

“Web Service Toolkit” is made of two parts :

Given an interface definition file(a WSDL file or a pascal file describing a web service), “ws_helper” (or within Lazarus, the WSDL file importer wizard) will create a object pascal unit containing a proxy implementing that interface. At runtime when a call targeting the web service is issued, the proxy's role is to :

Behind the scene, the proxy will take care of the SOAP plumbing details.

Example

We will use the “user service” sample that ships with WST. The schema that describes the service is located in the \samples folder, the file is user_service_intf.wsdl. In order to use this service, we have to translate the service’s publicly exposed interface, which is express using the Web Services Description Language(WSDL), to Object Pascal language. We will have to compile and execute the server that provides this service. To do so, please compile the project that is located at \samples\http_server, then run the resulting program to actually provide the service; Note that on recent Microsoft Windows operating systems (OS) you may have to enable the service to have network capabilities in order to run properly. To translate the service definition to Object Pascal language, within Lazarus we can use the import wizard; we can also use ws_helper as a standalone program.

The “WSDL importer” wizard

This wizard is contained in the wst_design.lpk package located in the \ide\lazarus directory of the toolkit. Once the package installed, it adds a menu section “Web Services Toolkit” with two (2) sub-menus items to the Lazarus “Project” menu :

Click on the first menu item (Import WSDL file ...), it will bring up the dialog below. We specify the WSDL file and the directory where to store the generated files and click on OK button to finish.

It will produce two (2) pascal source files :

Import by ws_helper.

The ws_helper program is a command line version of the import wizard. In order to present its capabilities, below are printed the command line arguments it supports.

pascal
ws_helper [-uMODE] [-gOPTION] [-p] [-b] [-i] [-w] [-x] [-y] [-d] -[fSPECIFCATIONS] [-oPATH] [-aPATH] inputFilename
  -u MODE Generate the pascal translation of the WSDL input file 
    MODE value may be U for used types or A for all types
  -g  Code generation option, with the following options : 
    A  : object arrays are generated as "array" derived from TBaseObjectArrayRemotable
    C  : object arrays are generated as "collection" derived from TObjectCollectionRemotable
    EP : enum type's items are prefixed with the enum name
    EN : enum type's items are not prefixed with the enum name, the default
  -p  Generate service proxy
  -b  Generate service binder
  -i  Generate service minimal implementation. This will erase any existing implementation file!
  -o  PATH  Relative output directory
  -a  PATH  Absolute output directory
  -w  Generate WSDL file; Can be used to get wsdl from pascal
  -x  Generate XSD file; Can be used to get xsd from pascal
  -y  Generate easy access interface for wrapped parameters
  -d  Generate documentation as comment in the interface file
  -c  Indicate the parser's case sensitivity : 
    S  : the paser is case sensitive
    I  : the paser is not case sensitive
  -f  Specify unit(s) renaming option : oldName= NewName(;oldName= NewName)*

To translate the user service WDSL file of the sample execute the following command at the prompt:

pascal
ws_helper.exe -uA -p -o. user_service_intf.wsdl
ws_helper, Web Service Toolkit 0.6 Copyright (c) 2006-2014 by Inoussa OUEDRAOGO
pascal
Parsing the file : user_service_intf.wsdl
(...)
Interface file generation...
Proxy file generation...
Metadata file generation...
File "user_service_intf.wsdl" parsed successfully.

below is printed an extract of both files:

pascal
unit user_service_intf;
(...)
interface

uses SysUtils, Classes, TypInfo, base_service_intf, service_intf;

const
  sNAME_SPACE = 'urn:UserService';
  sUNIT_NAME = 'user_service_intf';

type

  TUserArray = class;
  TUser = class;
  TNote = class;  
(...)
  UserService = interface(IInvokable)
    ['{7537A085-DCD1-4B24-8B74-BC35ACB4896D}']
    function GetList():TUserArray;
    procedure Add(
      const  AUser : TUser
    );
    procedure Update(
      const  AUser : TUser
    );
    function Find(
      const  AName : string
    ):TUser;
    function Delete(
      const  AName : string
    ):boolean;
  end;

  procedure Register_user_service_intf_ServiceMetadata();
pascal
Unit user_service_intf_proxy;
{$IFDEF FPC} {$mode objfpc}{$H+} {$ENDIF}
Interface

Uses SysUtils, Classes, TypInfo, base_service_intf, service_intf, user_service_intf;

Type

  TUserService_Proxy=class(TBaseProxy,UserService)
  Protected
    class function GetServiceType() : PTypeInfo;override;
    function GetList():TUserArray;
    procedure Add(
      const  AUser : TUser
    );
    procedure Update(
      const  AUser : TUser
    );
    function Find(
      const  AName : string
    ):TUser;
    function Delete(
      const  AName : string
    ):boolean;
  End;

  Function wst_CreateInstance_UserService(const AFormat : string = 'SOAP:'; const ATransport : string = 'HTTP:'; const AAddress : string = ''):UserService;

Implementation
uses wst_resources_imp, metadata_repository;

Function wst_CreateInstance_UserService(const AFormat : string; const ATransport : string; const AAddress : string):UserService;
Var
  locAdr : string;
Begin
  locAdr := AAddress;
  if ( locAdr = '' ) then
    locAdr := GetServiceDefaultAddress(TypeInfo(UserService));
  Result := TUserService_Proxy.Create('UserService',AFormat+GetServiceDefaultFormatProperties(TypeInfo(UserService)),ATransport + 'address=' + locAdr);
End;

function TUserService_Proxy.GetList():TUserArray;
Var
  locSerializer : IFormatterClient;
  locCallContext : ICallContext;
  locStrPrmName : string;
Begin
  locCallContext := Self as ICallContext;
  locSerializer := GetSerializer();
  Try
    locSerializer.BeginCall('GetList', GetTarget(),locCallContext);
    locSerializer.EndCall();

    MakeCall();

    locSerializer.BeginCallRead(locCallContext);
      TObject(Result) := Nil;
      locStrPrmName := 'result';
      locSerializer.Get(TypeInfo(TUserArray), locStrPrmName, Result);

  Finally
    locSerializer.Clear();
  End;
End;
(...)

We are now ready to build a simple program for the service. This sample client program invokes the GetList method of the service in order to retrieve the list of users already registered in the service; The list is then print to the screen :

pascal
program user_client_console;
uses SysUtils, fpc_http_protocol, soap_formatter,
     user_service_intf_proxy, user_service_intf;

var
  locService : UserService;
  items : TUserArray;
  item : TUser;
  i : Integer;
begin
  FPC_RegisterHTTP_Transport();
  locService := wst_CreateInstance_UserService();
  items := locService.GetList();
  try
    WriteLn('WST User Service Sample',sLineBreak);
    if (items.Length = 0) then
      WriteLn('  No user found.')
    else
      WriteLn(Format('  %d user(s) found : ',[items.Length]));
    for i := 0 to items.Length - 1 do begin
      item := items[i];
      WriteLn(Format('    Name= "%s", e-Mail= "%s"',[item.UserName,item.eMail]));
    end;
  finally
    items.Free();
  end;
end.

The units base_service_intf, service_intf, soap_formatter, fpc_http_protocol, wst_resources_imp and metadata_repository are provided by the toolkit; Below is the result of an execution session:

pascal
WST User Service Sample
pascal
2 user(s) found :
  Name= "Lazarus FreePascal", e-Mail= "Lazarus@FreePascal.wst"
  Name= "Inoussa OUEDRAOGO", e-Mail= "sample@example.wst"

It finds two (2) users. The wst_CreateInstance_UserService() function, located in the user_service_intf.pas file, creates a proxy instance based on the service's informations contained in the WSDL file. The complete source code of this example is shipped with the toolkit in the \samples\user_client_console directory; Note that the sample as it is provided in this directory is more completed that the code presented here.

Connection Parameters

The general format is:

pascal
protocol:paramName=paramValue(;paramName=paramValue)*

HTTP Basic Authentication

The toolkit has 3 HTTP implementations based on FPC's native implementation(fpc_http_server.pas), Synapse ( synapse_http_protocol.pas ) and Indy ( indy_http_protocol.pas )

In case of Synapse library (synapse_http_protocol.pas) add 2 lines to THTTPTransport constructor.

pascal
constructor THTTPTransport.Create();
begin
  inherited Create();
  FConnection := THTTPSend.Create();
  FConnection.Protocol := '1.1';

  //basic Authentication
  FConnection.UserName := <user name>;
  FConnection.Password := <password>;  
end;

HTTP Proxy Parameters

For HTTP the supported parameters are:

HTTP Connection through proxy are supported. Below is an example address string.

pascal
  const
    sADDRESS = 'http:address=http://webservices.amazon.com/AWSECommerceService/2007-04-04'+
                 ';ProxyServer=197.150.10.10;ProxyPort=9881'+
                 ';ProxyUsername=inoussa;ProxyPassword=wst';

The toolkit has 3 HTTP implementations based on FPC's native implementation(fpc_http_server.pas), Synapse ( synapse_http_protocol.pas ) and Indy ( indy_http_protocol.pas ).

HTTPS connection

The toolkit has 3 HTTP implementations based on FPC's native implementation(fpc_http_server.pas), Synapse ( synapse_http_protocol.pas ) and Indy ( indy_http_protocol.pas )

To use openssl1.x add ssl_openssl to uses section, for openssl3 - ssl_openssl3. Copy ssleay32.dll(so) and libeay32.dll(so) for openssl1.x, liblibssl-3.dll(so) and libcrypto-3.dll(so) - openssl3 to the project directory. In case of Synapse library (synapse_http_protocol.pas) add 2 lines to THTTPTransport constructor for openssl1.x or openssl3.

pascal
constructor THTTPTransport.Create();
begin
  inherited Create();
  FConnection := THTTPSend.Create();
  FConnection.Protocol := '1.1';

  //OpenSSL v1.x
  FConnection.Sock.CreateWithSSL(TSSLOpenSSL);
  FConnection.Sock.SSLDoConnect;

  //OpenSSL v3
  FConnection.Sock.CreateWithSSL(TSSLOpenSSL3);
  FConnection.Sock.SSLDoConnect;
end;

TCP connection Parameters

TCP supported parameters are:

Below is an example address string.

pascal
  Const
    sADDRESS = 'TCP:Address=10.0.0.3;Port=1234;target=UserService';

The toolkit has 3 TCP implementations based on FPC's native implementation(fpc_tcp_server.pas), Synapse (synapse_tcp_protocol.pas) and Indy (indy_tcp_protocol.pas).

LIBRARY ( LIB ) connection Parameters

The idea behind this protocol is to be able to host services in dynamic libraries ( DLL/DSO ). It can be viewed as a plug-in framework where plug-ins ( services ) are provided by dynamic libraries.

LIB supported parameters are:

Below is an example address string.

pascal
  Const
    sADDRESS = 'LIB:FileName=..\library_server\lib_server.dll;target=UserService';

The toolkit has one LIB implementation ( library_protocol.pas ).

The samples folder contains 4 projects user_client_console, tcp_server, http_server and library_server which demonstrate the TCP, HTTP and LIBRARY protocols.

Same Process (SAME_PROCESS) connection Parameters

The idea behind this protocol is to be able to host services in the client process. It allows the build of a layered application within a unique program that can latter be transformed to a fully multi-layered application. It can also be used to facilitate debugging during the project development.

SAME_PROCESS supported parameters are:

Below is an example address string.

pascal
  Const
    sADDRESS = 'SAME_PROCESS:Address=UserService';

The toolkit has one implementation (same_process_protocol.pas).

Multi-Address service ( Address per operation )

Certain services ( like the eBay SOAP services ) use a address per operation. The toolkit uses extended meta data ( see the services meta data chapter below ) to set operation's addresses. The “eBay” SOAP sample located under the tests\ebay folder demonstrates the operation's address setting.

Troubleshooting

'Invalid parameter : "AProtocolData"' error message

This happens when it is not clear wich protocol to use. Make sure that a valid formatter is selected (for example: 'SOAP:') and that the corresponding formatter is registered. This is done by adding the appropriate xxx_formatter unit to your uses-clausule. (for example: soap_formatter)

Server Side ( service creation )

Overview

Web Service Toolkit contains a server side framework and a WSDL based type library editor for service creation. Key features are:

Example

In order to create a service, we have to:

Defining the service Interface

Starting from the 0.5 version, the WST provides a WSDL based Type library Editor to define types and services used by an implementation. The figure (3) below presents the general interface of this tool. The Type library Editor is provided as:

Type Library Editor features:

Below some sample images are shown. We will use the user_service_intf.wsdl file located in the \samples directory for our sample.

Export the pascal files.

The Type Library Editor has option to generate the pascal version of the WSDL file. To do so, click on the “Files\Save generated files ...” (it can also be done through the contextual menu ); It will bring up the dialog box shown in the following image.

Click OK the button to complete. The program ws_helper has the same capabilities and the files can be generated with the following command :

pascal
ws_helper\ws_helper.exe -i -b -o. user_service_intf.wsdl
ws_helper, Web Service Toolkit 0.5 Copyright (c) 2006, 2007 by Inoussa OUEDRAOGO
Parsing the file : user_service_intf.wsdl
Information : Parsing "tns:TUserArray" ...
Information : Parsing "tns:TUser" ...
Information : Parsing "tns:TUser" ...
Information : Parsing "xsd:string" ...
Information : Parsing "tns:TUser" ...
Information : Parsing "xsd:string" ...
Information : Parsing "xsd:boolean" ...
Information : Parsing "TUserArray" ...
Information : Parsing "TUser" ...
Information : Parsing "TUserCategory" ...
Information : Parsing "TNote" ...
Interface file generation...
Proxy file generation...
Metadata file generation...
File "user_service_intf.wsdl" parsed succesfully.

The complete projects of the example is located in the folder “samples”. Below is printed a extract of the generated interface file.

pascal
unit user_service_intf;
{$IFDEF FPC} {$mode objfpc}{$H+} {$ENDIF}
interface

uses SysUtils, Classes, TypInfo, base_service_intf, service_intf;

const
  sNAME_SPACE = 'urn:UserService';
  sUNIT_NAME = 'user_service_intf';

type

  TUser = class;
  TUserArray = class;

  TUserCategory = ( 
    Normal
    ,Admin
  );

  TUser = class(TBaseComplexRemotable)
  published
    property Category : TUserCategory read FCategory write FCategory;
    property UserName : string read FUserName write FUserName;
    property eMail : string read FeMail write FeMail;
    property Preferences : string read FPreferences write FPreferences;
    property Note : TNote read FNote write FNote;
  end;

  TUserArray = class(TBaseObjectArrayRemotable)
  private
    function GetItem(AIndex: Integer): TUser;
  public
    class function GetItemClass():TBaseRemotableClass;override;
    property Item[AIndex:Integer] : TUser Read GetItem;Default;
  end;

  UserService = interface(IInvokable)
    ['{CA6F6192-C3DE-4D9C-B3DF-E616376A0DC9}']
    function GetList():TUserArray;
    procedure Add(
      Const AUser : TUser
    );
    procedure Update(
      Const AUser : TUser
    );
    function Find(
      Const AName : string
    ):TUser;
    function Delete(
      Const AName : string
    ):boolean;
  end;
(...)

Providing an implementation for the service

The user_service_intf_imp.pas unit generated above contains a skeleton implementation class for the interface. It defines a procedure named RegisterUserServiceImplementationFactory. The procedure registers the class as the service implementation provider in the implementation registry.

pascal
Unit user_service_intf_imp;
{$IFDEF FPC} {$mode objfpc}{$H+} {$ENDIF}
Interface
Uses SysUtils, Classes, 
     base_service_intf, server_service_intf, server_service_imputils,
     user_service_intf, cursor_intf;

Type
  { TUserService_ServiceImp }

  TUserService_ServiceImp=class(TBaseServiceImplementation,UserService)
  Protected
    function GetList():TUserArray;
    procedure Add(
      Const AUser : TUser
    );
    procedure Update(
      Const AUser : TUser
    );
    function Find(
      Const AName : string
    ):TUser;
    function Delete(
      Const AName : string
    ):boolean;
  End;

  procedure RegisterUserServiceImplementationFactory();

Implementation
(...)

procedure TUserService_ServiceImp.Add(Const AUser : TUser);
var
  locObj : TUser;
Begin
  locObj := Find(AUser.UserName);
  if ( locObj <> nil ) then
    raise Exception.CreateFmt('Duplicated user : "%s"',[AUser.UserName]);
  locObj := TUser.Create();
  locObj.Assign(AUser);
  FUserList.Add(locObj);
End; 

procedure RegisterUserServiceImplementationFactory();
Begin
  GetServiceImplementationRegistry().Register(
    'UserService',
TImplementationFactory.Create(TUserService_ServiceImp) as IServiceImplementationFactory);
End;

(...)

“ws_helper” has options to generate proxy file, basic implementation skeleton file and a binder file (see the following listing).

pascal
ws_helper, Web Service Toolkit 0.4 Copyright (c) 2006, 2007 by Inoussa OUEDRAOGO
ws_helper [-uMODE] [-p] [-b] [-i] [-oPATH] inputFilename
  -u MODE Generate the pascal translation of the WSDL input file
       MODE value may be U for used types or A for all types
  -p  Generate service proxy
  -b  Generate service binder
  -i  Generate service minimal implementation
  -o  PATH  Relative output directory
  -a  PATH  Absolute output directory

The starting implementation file could also be create using ws_helper with the -i and -b options as above;

pascal
ws_helper\ws_helper.exe -i -b -o. user_service_intf.wsdl
ws_helper, Web Service Toolkit 0.4 Copyright (c) 2006, 2007 by Inoussa OUEDRAOGO
Parsing the file : user_service_intf.wsdl
Proxy file generation...
Binder file generation...
Implementation file generation...
Metadata file generation...
File "user_service_intf.wsdl" parsed succesfully..

Providing a binder for the service

The binder's role is to:

The user_service_intf_binder.pas unit generated above, contains:

The following code extract shows the unit interface part and a method handler of the binder.

pascal
unit user_service_intf_binder;
{$IFDEF FPC} {$mode objfpc}{$H+} {$ENDIF}
interface
uses SysUtils, Classes, base_service_intf, server_service_intf, user_service_intf;

type
  TUserService_ServiceBinder=class(TBaseServiceBinder)
  Protected
    procedure GetListHandler(AFormatter:IFormatterResponse);
    procedure AddHandler(AFormatter:IFormatterResponse);
    procedure UpdateHandler(AFormatter:IFormatterResponse);
    procedure FindHandler(AFormatter:IFormatterResponse);
    procedure DeleteHandler(AFormatter:IFormatterResponse);
  Public
    constructor Create();
  End;

  TUserService_ServiceBinderFactory = class(TInterfacedObject,IItemFactory)
  protected
    function CreateInstance():IInterface;
  End;

  procedure Server_service_RegisterUserServiceService();

(...)

procedure TUserService_ServiceBinder.AddHandler(AFormatter:IFormatterResponse);
Var
  cllCntrl : ICallControl;
  tmpObj : UserService;
  callCtx : ICallContext;
  strPrmName : string;
  procName,trgName : string;
  AUser : TUser;
Begin
  callCtx := GetCallContext();
  TObject(AUser) := Nil;
  
  strPrmName := 'AUser';  AFormatter.Get(TypeInfo(TUser),strPrmName,AUser);
  If Assigned(Pointer(AUser)) Then
    callCtx.AddObjectToFree(TObject(AUser));
  
  tmpObj := Self.GetFactory().CreateInstance() as UserService;
  if Supports(tmpObj,ICallControl,cllCntrl) then
    cllCntrl.SetCallContext(GetCallContext());
  
  tmpObj.Add(AUser);
  
  procName := AFormatter.GetCallProcedureName();
  trgName := AFormatter.GetCallTarget();
  AFormatter.Clear();
  AFormatter.BeginCallResponse(procName,trgName);
  AFormatter.EndCallResponse();
  
  callCtx := Nil;
End;

Host the service into an application server

The application server's role is to route incoming service requests to the Web Service Toolkit runtime. For the runtime to process service requests:

The runtime interface is defined in the server_service_intf unit. This unit contains :

Starting from the version 0.5, the toolkit provides a simplified model to develop applications server . This is achieved using the listener classes. A listener implements a transport between the server and its clients. The toolkit provides two (2) HTTP listeners implementations:

Three (3) TCP listeners implementations are provided:

All listeners derive from TwstListener defined in the server_listener.pas file.

Below is printed an HTTP server sample. The code is divided into three (3) parts :

pascal
  Server_service_RegisterSoapFormat(); 
  Server_service_RegisterXmlRpcFormat();
  Server_service_RegisterBinaryFormat() ;
pascal
  RegisterUserServiceImplementationFactory();
  Server_service_RegisterUserServiceService();
pascal
  AppObject  := TwstFPHttpListener.Create();
  AppObject.Start();

Complete listing:

pascal
program http_server;
{$mode objfpc}{$H+}
uses
  {$IFDEF UNIX}{$IFDEF UseCThreads}
  cthreads,
  {$ENDIF}{$ENDIF}
  Classes, SysUtils,
  fpc_http_server, metadata_service, logger_extension, server_listener,
  server_service_soap, server_binary_formatter, server_service_xmlrpc, config_objects,
  user_service_intf, user_service_intf_binder, user_service_intf_imp;
var
  AppObject : TwstListener;
begin
  Server_service_RegisterBinaryFormat();
  Server_service_RegisterSoapFormat();
  Server_service_RegisterXmlRpcFormat();

  RegisterUserServiceImplementationFactory();
  Server_service_RegisterUserServiceService();
  AppObject := TwstFPHttpListener.Create();
  try
    WriteLn('"Web Service Toolkit" HTTP Server sample listening at:');
    WriteLn('');
    WriteLn('http://127.0.0.1:8000/');
    WriteLn('');
    WriteLn('Press enter to quit.');
    AppObject.Start();
    ReadLn();
  finally
    FreeAndNil(AppObject);
  end;
end.

Server_service_RegisterUserServiceService located in the user_service_intf_binder unit ( generated by ws_helper ) registers the UserService service by calling in turn GetServerServiceRegistry:

pascal
procedure Server_service_RegisterUserServiceService();
Begin
  GetServerServiceRegistry().Register(
    'UserService',TUserService_ServiceBinderFactory.Create() as IitemFactory
  );
End;

Server_service_RegisterSoapFormat located in the server_service_soap unit ( provided by the toolkit ) registers the SOAP implementation by calling in turn GetFormatterRegistry:

pascal
  procedure Server_service_RegisterSoapFormat();
  begin
    GetFormatterRegistry().Register(
      sPROTOCOL_NAME,
      sSOAP_CONTENT_TYPE,
      TSimpleItemFactory.Create(TSOAPFormatter) as IitemFactory
    );
    RegisterStdTypes();
  end;

Server_service_RegisterBinaryFormat located in the server_binary_formatter unit ( provided by the toolkit ) registers the Binary message implementation by calling in turn GetFormatterRegistry:

pascal
  procedure Server_service_RegisterBinaryFormat();
  begin
    GetFormatterRegistry().Register(
      sPROTOCOL_NAME,
      sBINARY_CONTENT_TYPE,
      TBinaryFormatterFactory.Create() as IitemFactory
    );
  end;

Server_service_RegisterXmlRpcFormat located in the server_service_xmlrpc unit ( provided by the toolkit ) registers the XMLRPC message implementation by calling in turn GetFormatterRegistry:

pascal
  procedure Server_service_RegisterXmlRpcFormat();
  begin
    GetFormatterRegistry().Register(
      sPROTOCOL_NAME,
      sXMLRPC_CONTENT_TYPE,
      TSimpleItemFactory.Create(TXmlRpcFormatter) as IItemFactory
    );
  end;

In order to give it a try one have to:

  1. compile the server ( \samples\tcp_server\tcp_server.lpi it is a console program),
  2. compile the client application ( \samples\user_client_console\user_client_console.lpi ),
  3. execute the server and start listening,
  4. execute the client.

WSDL generation

Services in the toolkit are organized into meta data repositories. Conceptually a repository corresponds:

The repository is the toolkit WSDL generation unit.

The Metadata Service

The toolkit is provided with an easy to use metadata service implementation which in turn uses the raw interface defined in the metadata_repository unit (see above). A Lazarus GUI client application is located in the tests\metadata_browser folder.

WSDL generation API

The metadata_wsdl pascal unit contains the GenerateWSDL function for WSDL generation from a repository (see the signature below).

pascal
  PServiceRepository = ^TServiceRepository;
  TServiceRepository = record
    NameSpace        : ShortString;
    Name             : ShortString;
    RootAddress      : ShortString;
    ServicesCount    : Byte;
    Services         : PService;
  end;

  procedure GenerateWSDL(AMdtdRep : PServiceRepository; ADoc : TDOMDocument);
WSDL Customization

The WSDL generation is based on the IWsdlTypeHandler and the IWsdlTypeHandlerRegistry interfaces located in the metadata_wsdl unit. In order to customize the generated WSDL, one has to provide a class implementing the IWsdlTypeHandler interface. Then that class has to be registered in the registry. The metadata_wsdl unit contains implementations for pascal enumerations, TBaseComplexRemotable descendants, and TBaseArrayRemotable descendants.

Sample

A functional sample project is located under \samples\http_server. It is an Indy base http server.

Services Extensions

Services extensions provide a mean to hook into all the services request processing stages. Services extensions may be used, for example, to implement authentication, request logging, data compression, etc. The IServiceExtension below is the interface used by the toolkit runtime to call services extensions.

pascal
  TMessageStage = (
    msAfterDeserialize, msAfterSerialize, msBeforeDeserialize, msBeforeSerialize
  );

  IServiceExtension = interface
    ['{E192E6B3-7932-4D44-A8AC-135D7A0B8C93}']
    procedure ProcessMessage(
      const AMessageStage     : TMessageStage;
               ACallContext   : ICallContext;
               AMsgData       : IInterface
    );
  end;

The AMsgData parameter actual type depends on the message processing state and corresponds to:

These types are located in the server_service_intf unit. Extensions have to be registered in the extensions registry ( located in the server_service_intf unit ) printed below

pascal
  IServiceExtensionRegistry = Interface
    ['{68DC78F1-E6CF-4D6B-8473-75288794769C}']
    function Find(const AName : string):IServiceExtension;
    procedure Register(
      const AName    : string;
            AFactory : IItemFactory
    );
  end;

In order for an service implementation to use a service extension, it has to register himself to that extension. To that end, the IServiceImplementationFactory interface provides the RegisterExtension method. A complete sample is included in the \samples\http_server sample ( implemented in \samples\logger_extension.pas ).

Services meta data

Services in the toolkit are organized into ***meta data repositories( see the “services's meta data” below )***. Conceptually a repository corresponds:

The ws_helper tool, when parsing the interface definition file, records the meta data of the services contained in the file to a Lazarus resource file. The resource file is then embedded into the generated binder's unit file( see the unit “initialization” part ). At runtime the service's recorded meta data are accessible through the interface IModuleMetadataMngr defined in the metadata_repository unit ( see below ). The GetModuleMetadataMngr function defined in the same unit returns an instance of an object supporting that interface.

pascal
  IModuleMetadataMngr = interface
    ['{B10ACF6A-A599-45A3-B083-BEEFB810C889}']
    function IndexOfName(const ARepName : shortstring):Integer;
    function GetCount():Integer;
    function GetRepositoryName(const AIndex : Integer):shortstring;
    procedure SetRepositoryNameSpace(const ARepName,ANameSpace : shortstring);
    function LoadRepositoryName(
      const ARepName,ARootAddress  : shortstring;
      out   ARepository  : PServiceRepository
    ):Integer;
    procedure ClearRepository(var ARepository : PServiceRepository);
    procedure SetServiceCustomData(
      const ARepName       : shortstring;
      const AServiceName   : shortstring;
      const ADataName,
            AData          : string
    );
    procedure SetOperationCustomData(
      const ARepName       : shortstring;
      const AServiceName   : shortstring;
      const AOperationName : shortstring;
      const ADataName,
            AData          : string
    );
    function GetServiceMetadata(const ARepName,AServiceName : shortstring) : PService;
    procedure ClearServiceMetadata(var AService : PService);
  end;

Extended Meta data

The meta data interface provides a way to add custom data to recorded ones. Services's metadata can be set through SetServiceCustomData, operation's metadata be set through the SetOperationCustomData method.

A repository's extended meta data has to be registered after the service meta data recorded in the resource file have been registered. So for client application the generated proxy unit contains a conditional code fragment to call a registration procedure like shown below for the eBay sample located in the tests\ebay folder. The procedure name is obtained from the interface unit name ( the repository's name ) : Register_%UNIT_NAME%_ServiceMetadata .

pascal
  initialization
    {$i ebay.lrs}

    {$IF DECLARED(Register_ebay_ServiceMetadata)}
    Register_ebay_ServiceMetadata();
    {$ENDIF}
  End.

Headers support

The THeaderBlock class

pascal
  THeaderBlock = class(TBaseComplexRemotable)
  public
    property Direction : THeaderDirection read FDirection write FDirection;
    property Understood : Boolean read FUnderstood write FUnderstood;
  published
    property mustUnderstand : Integer read FmustUnderstand write SetmustUnderstand 
      stored HasmustUnderstand;
  end;

The THeaderBlock shown above ( the private part has been omitted for brevity), located in the base_service_intf unit, is the root class all header classes are derived from.. The Direction property indicate whether it is an incoming header or an outgoing one. The mustUnderstand property define whether the header is a mandatory one.

Defining header class

Soap headers are derived from the THeaderBlock base class located in the base_service_intf unit. They have to be registered in the type registry. Below is reproduced an header example extracted from the “calculator” sample project.

pascal
  TCalcHeader = class(THeaderBlock)
  published
    property Login : string read FLogin write FLogin;
    property Password : string read FPassword write FPassword;
    property WantedPrecision : Integer read FWantedPrecision write FWantedPrecision;
  end;

The ICallContext interface

pascal
  ICallContext = Interface
    ['{855EB8E2-0700-45B1-B852-2101023200E0}']
    procedure AddObjectToFree(const AObject : TObject);
    procedure Clear();
    function AddHeader(
      const AHeader        : THeaderBlock;
      const AKeepOwnership : Boolean
    ):Integer;overload;
    function AddHeader(
      const AHeader        : TBaseRemotable;
      const AKeepOwnership : Boolean;
      const AName          : string = ''
    ):Integer;overload;
    function GetHeaderCount(const ADirections : THeaderDirections):Integer;
    function GetHeader(const AIndex : Integer) : THeaderBlock;
    procedure ClearHeaders(const ADirection : THeaderDirection);
  End;

The ICallContext interface defined in the base_service_intf unit represents the service call context. The AddHeader method allows headers sending while the GetHeader method retrieves header in the call context.

Client side headers

An ICallContext reference may be obtained from the current service proxy instance simply by querying it for that interface as shown in the code fragment below extracted from the “calculator” client example project.

pascal
  var
    ch : TCalcHeader;
    hdrs : ICallContext;
  begin
    FObj := TCalculator_Proxy.Create('Calculator', edtFormat.Text, edtAddress.Text);

    ch := TCalcHeader.Create();
    ch.mustUnderstand := 1;
    ch.Login := 'azerty';
    ch.Password := 'qwerty';
    ch.WantedPrecision := 1210;
    hdrs := FObj as ICallContext;
    hdrs.AddHeader(ch,true);

A header may be made mandatory by setting its mustUnderstand property to 1 as in the code above.

Server side headers

The ICallControl interface

pascal
  ICallControl = interface
    ['{7B4B7192-EE96-4B52-92C7-AE855FBC31E7}']
    procedure SetCallContext(ACallContext : ICallContext);
    function GetCallContext():ICallContext;
  end;

The ICallControl interface, located in the server_service_intf unit, is used by the toolkit runtime to share the executing call environment with service implementation classes. When the runtime is about to issue a call against a implementation class instance, it queries that instance for ICallControl interface support; If the implementation has ICallControl interface support then the obtained reference is used to set the call context through the SetCallContext method. The implementation instance can then access the call context by calling the GetCallContex method.

The toolkit provides the TBaseServiceImplementation class which has support for the ICallControl interface and can be used as a base implementation class. It is the base class used by the ws_helper generated skeleton implementation class when invoked with the -i command line option.

The method printed below, extracted from the calculator sample service demonstrates the access to headers for read and write.

pascal
  function TCalculator_ServiceImp.AddInt(
    Const A : Integer;
    Const B : Integer
  ):TBinaryArgsResult;
  var
    hdr : TCalcResultHeader;
    h : TCalcHeader;
    cc : ICallContext;
  Begin
    hdr := TCalcResultHeader.Create();
    cc := GetCallContext();
    if Assigned(cc) and ( cc.GetHeaderCount([hdIn]) > 0 ) and ( cc.GetHeader(0).InheritsFrom(TCalcHeader) ) then begin
      h := cc.GetHeader(0) as TCalcHeader;
      h.Understood := True;
      hdr.Assign(h);
    end;
    hdr.TimeStamp := DateTimeToStr(Now());
    hdr.SessionID := 'testSession';
    cc.AddHeader(hdr,True);
    hdr := nil;
    Result := TBinaryArgsResult.Create();
    Try
      Result.Arg_OP := '+';
      Result.Arg_OpEnum := coAdd;
      Result.Arg_A := A;
      Result.Arg_B := B;
      Result.Arg_R := A + B;
      Result.Comment := 'Doing an + operation';
    Except
      FreeAndNil(Result);
      Raise;
    End;
  End;

Headers that does not derived from THeaderBlock

Classes that inherit from TBaseRemotable can also be used as headers; In that case a THeaderBlockProxy’s instance is automatically created and used as a wrapper to allow a TBaseRemotable instance to be sent and received as a header block. The ICallContext has an overloaded AddHeader method that accepts TBaseRemotable’s instances.

SOAP Specific

Binding style

The binding style is used to indicate whether the service is RPC oriented or Document oriented.

Client side

The binding style may be specified in the SOAP protocol string on the creation of a service proxy. The default value for the binding style is RPC. Below is printed a sample code that demonstrates the use of Document style.

pascal
  locService := TSampleService_Proxy.Create(
                  'SampleService',
                  'SOAP:Style=Document;EncodingStyle=Literal',
                  'http:Address=http://127.0.0.1/services/SampleService'
                );

Server side

Currently services created with the toolkit use the RPC binding style.

Encoding style

The encoding style indicates the rules used to encode types in XML. Supported values are Encoded and Literal.

Client side

The encoding style may be specified in the SOAP protocol string on the creation of a service proxy. The default value for the encoding style is Encoded. The above sample demonstrates the use of Literal style.

Server side

Currently services created with the toolkit use the Encoded encoding style.

Provided examples

The samples are located under the “tests” folder.

Client side examples ( tested on Windows XP, Ubuntu and MacOS on PowerPC)

Server side examples

Status

The toolkit is usable for simple types and for class types. The serialization is designed to allow customization of basic types and class types by implementing classes derived from “TBaseRemotable”. This classes have to be registered in the type registry.

Serialization

The serialization is based on the IFormatterBase interface located in the base_service_intf unit.

The toolkit has four serializers implementations : the SOAP serializer, the XMLRPC serializer, the JSONRPC serializer and a binary serializer. This serializers has been tested on fpc 2.x and Delphi 7.

SOAP serializer

The SOAP serializer implements SOAP 1.1. It has support for the following pascal types:

Binary serializer

The Binary serializer is more efficient in time and space compared to the SOAP serializer . It uses big endian to stream data. It has support for the following pascal types:

Class type serialization

The toolkit has support for instances of classes derived from TBaseRemotable. TBaseRemotable is the abstract base class used by the formatter interface to allow customization of the serialization. The toolkit provides the TBaseComplexRemotable class which implements serialization for its descendants classes published properties. It also provides TBaseObjectArrayRemotable class for serialization of array of TBaseRemotable descendant classes.

The root “TBaseRemotable” class
pascal
  TBaseRemotable = class(TPersistent)
  Public
    constructor Create();virtual;
    class procedure Save(
            AObject   : TBaseRemotable;
            AStore    : IFormatterBase;
      Const AName     : String;
      Const ATypeInfo : PTypeInfo
    );virtual;abstract;
    class procedure Load(
      Var   AObject   : TObject;
            AStore    : IFormatterBase;
      var   AName     : String;
      const ATypeInfo : PTypeInfo
    );virtual;abstract;
  End;

TBaseRemotable is the abstract base class used by the formatter interface to allow customization of the serialization. This class defines a virtual constructor and mainly two(2) virtual abstract class methods :

The “TBaseComplexRemotable” serialization
pascal
  TBaseComplexRemotable = class(TAbstractComplexRemotable)
  public
    class procedure Save(
            AObject   : TBaseRemotable;
            AStore    : IFormatterBase;
      const AName     : string;
      const ATypeInfo : PTypeInfo
    );override;
    class procedure Load(
      var   AObject   : TObject;
            AStore    : IFormatterBase;
      var   AName     : string;
      const ATypeInfo : PTypeInfo
    );override;
    class procedure RegisterAttributeProperty(const AProperty : shortstring);virtual;
    class procedure RegisterAttributeProperties(const APropertList : array of shortstring);virtual;
    class function IsAttributeProperty(const AProperty : shortstring):Boolean;
    procedure Assign(Source: TPersistent); override;
  end;

TBaseComplexRemotable implements serialization for its descendants classes published properties. The serialization is based on runtime type information (RTTI) and can be customized to:

The following class shows a the serialization's customization sample.

pascal
  TSampleClass = class(TBaseComplexRemotable)
  private
    FProp_Always: Integer;
    FProp_Never: Integer;
    FProp_Optional: Integer;
    function GetStoredProp_Optional: boolean;
  published
    //This property will always be serialized
    property Prop_Always : Integer read FProp_Always write FProp_Always;
    //This property will never be serialized
    property Prop_Never : Integer read FProp_Never write FProp_Never stored False;
    //This property will be serialized if "Self.GetStoredProp_Optional() = True"
    property Prop_Optional : Integer read FProp_Optional write FProp_Optional stored GetStoredProp_Optional;
  End;

TBaseComplexRemotable allows properties serialization as attributes. Theses properties have to be registered as such with the RegisterAttributeProperty class method or RegisterAttributeProperties one.

TBaseComplexRemotable

TBaseComplexSimpleContentRemotable provides implementation for the “XML Schema” complex types which extend simple types with attributes. The following example illustrates this :

xml
  <xs:complexType name="DecimalWithUnits">
    <xs:simpleContent>
      <xs:extension base="xs:decimal">
        <xs:attribute name="Units" type="xs:string"
                      use="required"/>
      </xs:extension>
    </xs:simpleContent>
  </xs:complexType>

This type will be translate by ws_helper to Pascal as:

pascal
  DecimalWithUnits = class(TComplexFloatExtendedContentRemotable)
  private
    FUnits : string;
  published
    property Units : string read FUnits write FUnits;
  end;

using the predefined types ( in base_service_intf.pas )

pascal
  TBaseComplexSimpleContentRemotable =
     class(TAbstractComplexRemotable)
  protected
    class procedure SaveValue(
      AObject : TBaseRemotable; 
      AStore : IformatterBase
    );virtual;abstract;
    class procedure LoadValue(
      var AObject : TObject; 
      AStore : IformatterBase
    );virtual;abstract;
  public
    class procedure Save(
            AObject   : TBaseRemotable;
            AStore    : IFormatterBase;
      const AName     : string;
      const ATypeInfo : PTypeInfo
    );override;
    class procedure Load(
      var   AObject   : TObject;
            AStore    : IFormatterBase;
      var   AName     : string;
      const ATypeInfo : PTypeInfo
    );override;
  end;

  TComplexFloatExtendedContentRemotable =
     class(TBaseComplexSimpleContentRemotable)
  private
    FValue: Extended;
  protected
    class procedure SaveValue(
      AObject : TBaseRemotable; 
      AStore : IformatterBase
    );override;
    class procedure LoadValue(
       var AObject : TObject; 
       AStore : IformatterBase
    );override;
  public
    property Value : Extended read FValue write FValue;
  end;

An instance of this type looks like the one below. Every attribute must be registered using the RegisterAttributeProperty() method. The toolkit provides class for Pascal basic types( TComplexInt8UContentRemotable, TComplexInt8SContentRemotable, TComplexInt16SContentRemotable, ...).

xml
  <example Units = "meter">
    12.10
  </example>
Provided array implementations

The toolkit provides array implementation for basic types ( in the base_service_intf unit ) listed below. The implementations are based on the serialization's customization.

The toolkit array's implementation support “embedded” array serialization. This type of array occurs typically with types like the following one ( the "ResponseGroup" may be repeated ):

xml
  <xs:complexType name="CustomerContentSearchRequest">
    <xs:sequence>
      <xs:element name="CustomerPage" type="xs:positiveInteger"
         minOccurs="0"/>
      <xs:element name="Email" type="xs:string" minOccurs="0"/>
      <xs:element name="Name" type="xs:string" minOccurs="0"/>
      <xs:element name="ResponseGroup" type="xs:string"
           minOccurs="0" maxOccurs="unbounded"/>
    </xs:sequence>
  </xs:complexType>

which could be instantiated as

xml
  <search>
    <CustomerPage> 1 </CustomerPage>
    <Name>Sample name</Name>
    <ResponseGroup>Group 1</ResponseGroup>
    <ResponseGroup>Group 2</ResponseGroup>
    <ResponseGroup>Group 3</ResponseGroup>
  </search>

This type will be translate to Pascal by ws_helper as (the private and protected parts are omitted to be short)

pascal
(...)
  CustomerContentSearchRequest_ResponseGroupArray =
    class(TBaseSimpleTypeArrayRemotable)
  public
    class function GetItemTypeInfo():PTypeInfo;override;
    procedure SetLength(const ANewSize : Integer);override;
    property Item[AIndex:Integer] : string 
      read GetItem write SetItem; default;
  end;

  CustomerContentSearchRequest = class(TBaseComplexRemotable)
  published
    property CustomerPage : positiveInteger 
       read FCustomerPage 
       write FCustomerPage stored HasCustomerPage;
    property Email : string 
       read FEmail 
       write FEmail 
       stored HasEmail;
    property Name : string read FName write FName stored HasName;
    property ResponseGroup :
       CustomerContentSearchRequest_ResponseGroupArray
       read FResponseGroup 
       write FResponseGroup;
  end;

implementation
(...)
  GetTypeRegistry().ItemByTypeInfo[
    TypeInfo(CustomerContentSearchRequest_ResponseGroupArray)]
    .RegisterExternalPropertyName(sARRAY_STYLE,sEmbedded);
(...)

The last instruction set the array style to “Embedded” and so the SOAP formatter will serialize the array accordingly.

Test cases

TODO

TODO Common

TODO Client-Side

TODO Server-Side

Extend the toolkit to Server side for :

]]

License

All the code in WST is under the FPC' RTL license (modified LGPL).

Download & NewsGroup

FAQ

The Web Service Toolkit:FAQ.

Changes Log

Version 0.7

Version 0.6

Version 0.5

Version 0.4

Version 0.3.1 ( 21 August 2006 )

Version 0.3 ( 5 August 2006 )

Version 0.2.3.2 ( 5 July 2006 )

Version 0.2.3 ( 4 July 2006 )

Version 0.2.2 ( 7 June 2006 )

Author

Inoussa OUEDRAOGO, http://inoussa12.googlepages.com/

See also

From the Free Pascal wiki, page "Web Service Toolkit", as it stood on 2024-02-22 after a change by Mig-31, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's Licensing page. If you have concerns about this material, message the admin.

Revision 1, last changed by WikiArchive .

Talk about this page

Nobody has opened a bench for this page yet. Sign in to open one.