Skip to content

TWebRadServerClientDataset

Introduction

Embarcadero Rad server https://www.embarcadero.com/fr/products/rad-server is a technology for creating REST API services written in Delphi that can be hosted on Windows IIS or Linux Apacheservers. These REST APIs can be accessed from TMS WEB Core web client applications. In its most basic form, the TWebHttpRequest component can be used to perform HTTP(s) GET,PUT,POST,DELETE requests to the APIs exposed by Embarcadero Rad Server. When creating a CRUD REST API functionality, the TWebRadServerClientDataset can internally fully handle the communication and offer access to the data via a TDataset based interface to the DB-aware UI controls in your web client applications. The TWebRadServerClientDataset is multi-tenant aware. This means that it works based on userbound data, offers a login method and will perform operations on the data belonging to the logged-in user.

Configuring your Embarcadero Rad server back-end

Create a new Rad Server project from your Delphi IDE.

Create a new data module and set the ResourceName attribute to the name you want to use to access the dataset from the web client application. The TWebRadServerClientDataset will internally construct the URL to use the Rad Server REST API with.

To perform CRUD operation on a table, add methods Get,Post,GetItem,PutItem,DeleteItem to the datamodule: 

[ResourceName('tasks')]
TTasksResource = class(TDataModule)
  conn: TFDConnection;
  query: TFDQuery;
published
  procedure Get(const AContext: TEndpointContext; const ARequest:
TEndpointRequest; const AResponse: TEndpointResponse);
  [ResourceSuffix('{item}')]
  procedure GetItem(const AContext: TEndpointContext; const ARequest:
TEndpointRequest; const AResponse: TEndpointResponse);
  procedure Post(const AContext: TEndpointContext; const ARequest:
TEndpointRequest; const AResponse: TEndpointResponse);
  [ResourceSuffix('{item}')]
  procedure PutItem(const AContext: TEndpointContext; const ARequest:
TEndpointRequest; const AResponse: TEndpointResponse);
  [ResourceSuffix('{item}')]
  procedure DeleteItem(const AContext: TEndpointContext; const
ARequest: TEndpointRequest; const AResponse: TEndpointResponse);
end;

In these methods return JSON objects for the Get/GetItem procedures from the data in the dataset used and get the posted data as JSON object and insert this as a new record in the dataset.

Note that as Rad Server is a multi-tenant architecture, the logged in user information can be retrieved from the AContext parameter of the methods. From here, AContext.User.UserID can be used to get the data belonging to a specific user or insert it with the correct user information.

The full source code for a sample Rad Server package that creates a REST API for CRUD operations on a tasks table can be found under Demo\DBBackend\RadServer\Server.

After creating and compiling the Rad Server package, follow these steps to start Rad Server with your package:

1) From the command line, execute: 

EMSDevServer -l"RADServerTasks.bpl"

2) When you run this for the first time on a system

  • The EMSDevServer will not find any configuration and will ask you to Create it. Say YES.

  • Then Rad Server Setup Wizard starts. Do not change anything. Keep it at default. Note the location of DB File Directory because this is the location where it creates its EMS database for Rad Server and the INI file of parameters.

  • We are going to change the INI file there for our local Demo runs and tests. C:\Users\Public\Documents\Embarcadero\EMS
  • Click Next and keep defaults for Sample Data where it will create sample users and user groups.
  • Click Next and note down the default user-name and password for IB Console, a utility.
  • Final screen asks for confirmation to create default files. Again leave them at default and click on Finish.
  • It shows some messages giving license warnings, etc. Once you are through, the compiled Rad Server starts running.

3) The Rad Server starts running. If you get an error that can not connect to EMS database then it means that Interbase service is not running. You will need to start it from Task Manager—Services

4) Once Rad Server is running, Click on Open Browser to do a quick test. It will show a version.

5) Change the URL in the browser to show tasks: http://localhost:8080/tasks You will see JSON of the tasks present in the database. Once this works, you can start using the Client Demo that assumes that Rad Server is running on localhost:8080.

6) Stop the Server and close it.

7) EDIT the INI file emsserver.INI in the folder C:\Users\Public\Documents\Embarcadero\EMS that we noted above. Change the parameter CrossDomain’s value to *. This will get rid of cross-domain error in Chrome that you would otherwise get.

CrossDomain=*

Now run the server again from the Batch file. Remember, whenever you change the INI file, you have to stop and restart the server.

Use Rad Server via TWebRadServerClientDataset

To start using the Rad Server REST API offering CRUD access to a table, drop a new TWebRadServerClientDataset instance on the TMS WEB Core web client application form.

1) Set the WebRadServerClientDataset.RadServerURL to the URL for the Rad Server. When performing local testing, this is default http://localhost:8080

2) Set the table name WebRadServerClientDataset.TableName, i.e. this is the ResourceName attribute set for the datamodule exposing the table.

3) Set the key field for the tasks table via WebRadServerClientDataset.KeyfieldName

4) Add the field types that will be used in the client dataset via WebRadServerClientDataset.FieldDefs

To login with a user account, use WebRadServerClientDataset.Login() passing the username and password. After a successful login, the dataset becomes active and any connected DBaware control will show the data in the dataset. To signup a new user, just use the WebRadServerClientDataset.Login() method with last Boolean parameter set to true.

From this moment on, operations such as edit, insert, delete will be handled via the WebRadServerClientDataset on the Rad Server exposed table.

Reference

These are the properties, methods, events of the TWebRadServerClientDataset component

Properties

Property Description
Active Set this to True to activate the DataSet. Field definitions must be present along with other properties described below.
AppSecret Sets the optional application secret key value
KeyfieldName Sets the keyfield for the dataset
MasterSecret Sets the optional master secret key value
RadServerURL Sets the URL to perform the REST API HTTP(s) requests on
TableName Sets the resource name that will be used in the Rad Server

Methods

Method Description
Login(UserName,Password: string; IsSignup: boolean) Performs a login on the Rad Server instance. When successful, the data is fetched in the dataset. When IsSignUp is true, a new account is created on the Rad Server instance

Events

The TWebRadServerClientDataset exposes the standard TDataSet events and is as such similar in functionality