RAD Server EMS Package to get data from a remote database through a REST API call and display the data on an EMS Client application.

Posted by on in Blogs

Embarcadero's Enterprise Mobility Services (EMS) is a turnkey middleware solution, part of RAD Server that supports secure, encrypted communication using an industry-standard REST interface. With built-in support for users and groups, EMS is a perfect platform for exposing your custom REST endpoints to a wide range of authorized clients.

Developers will especially appreciate the ease with which corporate data and features can be securely accessed from mobile clients, which normally lack the ability to easily interface with enterprise data.

A common request from developers testing EMS is how easy is it to get data from a remote database through a REST API call and display the data on an EMS Client application.

This post shows creating a new EMS Package to get data from a remote database through a REST API call and display the data on an EMS Client application.

This post will show:

FireDAC JSON Streaming Capabilities as a way to expose resources from a server database and then consume the data from a client application using a BackendEndPoint connection:

  1. SaveToStream, LoadFromStream with sfJSON format
  2. Expose as resource, consume via BackendEndPoint

Use FDSchemaAdapter, a very powerful FireDAC component to allow us to:

  1. Capture master/detail relationships on EMS Server
  2. Exposes the master/detail relationships data on the client application
  3. Direct hooks to streaming and invocation

1. First, let’s create a new EMS application.

File | New | Other | Delphi Projects | EMS | EMS Package 

EMS_Package

 2. Select “Create package with resource” because we want to expose database data.

Create_package_with_resource

 

3. Enter a “Resource name”.  This will be the URL portion we will use for the REST API call.  Later you can change this  “Resource name” in code.  Let’s call it “data”.

Resource_name

And we’ll use a Data Module, so we can add our non-visual data access controls, to drop onto the Data Module form that makes it easier to access database information.

4. Here we can implement our REST Endpoints.  For this application let’s only select Get.

Get is used for getting the entire resource like Select * from Employee, but GetItem can be used to get just one specific element from the database, like a where Last_Name = “Nelson”.

Endpoints

Click Finish

 

5. Our EMS Server project gets created, with our Data Module:

EMS_Project

6. It has our ResouceName called ‘data’ and it’s a TDataModule.  And we have our Get procedure for us to implement:

EMS_TDataModule

 And it has this generic Register procedure to automatically register the RET endpoint for us when the EMS Server starts: 

EMS_Register_Procedure

 7. Get implementation.

Get is implemented like this, so calling http://localhost:8080/data will return “data”.

EMS_Get

EMS_localhost_data

8. Add FireDAC components to DataModule to access database data.

Using FireDAC InterBase Employee database from Data Explorer, drop Employee connection onto DataModule form.  This adds EmployeeConnection (FDConnection) onto DataModule.  And add FDQuery onto DataModule.  Double-click FDQuery and enter SQL Command = select * from Employee

Click Execute query, to test that it returns data.  The FULL_NAME is the data we want to return to the client app.

EMS_Data_Explorer    EMS_EmployeeConnection    EMS_FDQuery

 EMS_FD_Select    EMS_Full_Name

In addition to the InterBase database, FireDAC also supports native database drivers that give you first-class access to the powerful and advanced features that make each database unique, including access to specific APIs and features for mostly all databases including MySQL, Microsoft SQL Server, Oracle Database, InterBase, PostgreSQL, DataSnap, SQLite, Sybase SQL Anywhere, Microsoft Access, IBM DB2 Server, Informix, Firebird, Advantage Database, Teradata (ODBC), and NoSQL Driver for MongoDB.

9. On the FDConnection (EmployeeConnection) we will set the Connected = False.

EMS_FDConnection_Flase

10.  For our FireDAC data to save data in JSON format, we need to add a few additional components to the DataModule.  We need to use FDStanStorageJSONLink component, this will add the needed Unit FireDAC.Stan.StorageJSON to our EMS Server to allow us to save data in JSON format.

And every FireDAC application needs GUI Wait Cursor component, FDGUIxWaitCursor:

EMS_FDGUIWait

We don’t need the FD InterBase Physical Database connection component, FDPhysIBDriverLink, because it’s automatically added with the EmployeeConnection, with the correct IB driver name:

EMS_IB_Driver

11. All the needed components have been added to the DataModule, now we can move to write some code to implement the Get verb:  First, we’ll Connect to the EmployeeConnection, then we can run the Query:

 EMS_GET_Connect

The EMS Server is stateless, so every time we connect, we can run the Query.  Now that we have our connection and Query, we can fill in the Response.  The Response Body is the actual content we will send back to the client.  The Body has a few ways to send back the data, such as SetValue, SetBytes, SetStream, but here we will use SetStream.  And to return a Stream, we need a Stream variable (aStream: TStream).  aStream of type TStream.  And we’ll need an instance that can be any memory stream, so we’ll use aStream := tMemoryStream.Create;.  

EMS_MemoryStream_Create

Next, we save to the Stream. So what we can do is take our FDQuery and call SaveToStream and pass in our Stream.  The second parameter is the format we want for the Stream, we have a few options for the format we can use, such as XML, Binary or JSON, but for this example, we will use JSON which is a common Open format for use, especially with REST Servers.  Note:  Binary would be more compressed data, but we will use JSON data for our EMS REST Server.

Now that we have the Stream, we can return the Stream to our clients as the Result.  We have two parameters to add to our AResponse.Body.SetStream(aStream,,) method.  First is the Content type that we are returning, which is just the JSON, which is ‘application/json that is part of the standard JSON format, and the last parameter is if we own the Stream, if we own the value of the Response, then we say True.  

EMS_SetStream

If we pass the Stream once owned by the Response, once the Response is returned, it will free the response automatically.  Otherwise if we create the Stream right away, then it will not be available for the Response.  This is the standard mechanism that the Response owns the Stream.

12. This project is part of a package.  When we build the EMS Package we get Warnings that we have dependencies, like this.  This is fine and expected.  So we click OK to add these needed dependencies to the project.  If you re-build you should no longer get any warnings.

EMS_Build_Warnings 

13.  Run the project.  This starts the EMS Development Server. And loads our EMSFireDAC.bpl package, and exposes our ‘data’ resource and our “Get” endpoint:

EMS_Dev_Server

 14.  Click Open Browser button on EMS Dev Server to check if our Get Endpoint is working.

 By default, the EMS Server calls the ‘version’ Endpoint and returns the version and server information for this EMS Server:

EMS_version

We can now call our ‘data’ resource that will call our “Get” Endpoint by default.  And here is our Query returned in JSON format.  Very cool!!

EMS_data_endpoint

 15. And the EMS server logs all the requests:

EMS_logs

EMS Client Application

16. Next, we can create EMS Client applications to connect to the EMS Server, call the ‘data’ resource and return data to the client.

a. To the same project, add a New | Delphi | Multi-Device Application | Blank Application. 

b. Call it and Save it as ‘EMSFireDACClient’.

c. Start the EMSFireDAC Dev Server, if not already started.

d. Style = Android.

e. Add Button (align to TOP), Text=Get Data and ListView (align to Client) to the UI.

EMS_FireDAC_Client

f. Next, we need to connect to the EMS Server.  There are multiple ways to do this.  Such as REST components, and that’s fine, but adds some complexity when you need to add authentication.  We will use the simpler, more compatible with the BAAS providers, it’s part of the Back End As a Server technology that we built in XE6.  We will use the EMSProvider component.  The EMSProvider component is specifically tied to EMS.  Add EMSProvider to the form.

EMS_EMS_Provider

16. Set EMProvider URLHost, URLPort and URLProtocol to your EMS values:

EMS_URLHost

 17. Right-click EMSProvider component | TEST Connection:  The Endpoint ‘version’ gets returned if successful connection:

EMS_version

18. Next, we need an Endpoint.  An Endpoint is a generic connection to an URL on the EMS Server.

Add BackendEndpoint component onto the form.  The BackendEndpoint component hooks automatically to the EMSProvider.  And we will enter the specific resource on the EMS server we want to call, the ‘data’ resource.

Note:  We could also hook up a Response object, or we can just have the Response object created automatically for us. 

EMS_Backendpoint  EMS_Backend_EMSProvider  EMS_Resource_data

19.  You can test the Response Object returns, by right-click the BackendEndpoint | Execute.  A Response code 200 – OK means a successful Response from the EMS Server, and the Response property gets filled.

EMS_Response_OK   EMS_Response_Backend

20. Next, we need a FDMemTable, because that is where we want to store our information, even just in memory on the client application.  Add a FDMemTable to the form.

EMS_FDMemTable

21.  We need to add another FD JSON Streamer component (FDStanStorageJSONLink) onto the form because on the client now we will be doing the opposite operation from the Server of reading from the FDMemTable.  This is what FireDAC requires.  Add a FDStanStorageJSONLink onto the form.

EMS_FDStanStorageJSONLInk

22. Next, let’s connect the ListView with the data.  One way to do this is to use the FDMemTable Fields EditorRight-click FDMemTable component | Fields Editor, Right-Click | New Field.  Type = String , Size = 40.

EMS_New_Field  EMS_FULL_NAME_FDMemTable

We are creating this at Design Time, so we can visualize Live Bindings to use the field automatically at Design Time.

23.  Use Live Bindings Designer (View | Live Bindings Designer)

EMS_Live_Binding

24. And we want the FDMemTable to be synched with the ListView (connect * of FDMemtable to Synch of ListView), and FULL_NAME on FDMemtable connected to TEXT of ListView:

EMS_FDMemtable_ListView

25. Lastly, we need to write the Button Click code to get the data from EMS Server.

Here we will be doing the opposite of what we have done on the EMS Server.

Double-click the Button ‘Get Data’

First, we’ll execute the ‘data’ REST call by calling BackendEndPoint1.Execute;

Next, we'll check if we got a Response, using BackendEndpoint1.Response.Content;

EMS_ButtonClick

Next, we’ll get our FDMemtable object and load that data returned from the EMS Server:  FDMemTable.LoadFromStream();

The LoadFromStream method is the opposite of what we did on the EMS Server side.

And similar to the EMS side, we need a Stream variable on the client also; var aStream: TStream;

Any inMemory Stream can be used here, but what is handy is to use a TStringStream because then we can pass the constructor directly the String with the content:

To reset the position of the Stream, we can call:   aStream.Position := 0;

Next, we’ll get our FDMemtable object and load that data returned from the EMS Server

The LoadFromStream method is the opposite of what we did on the EMS Server side.

So, similar to the EMS side, we need a Stream variable on the client also.

Now we can read the aStream in a JSON structure that we are reading back into our client application

FDMemTable1.LoadFromStream(aStream, sfJSON);

 

Lastly, since we don't have automatic management like we had on the EMS Server, we need to free the stream:

EMS_FDMemtable_LoadFromStream

 26.  Run the EMSFIreDACClient application.

With the EMS Server running, run the EMSFIreDACClient client application.  Click the Get Data button.  This calls the ‘data’ Resource on the EMS Server that runs the Query on the Employee database and returns the JSON array back to the client and displays the FULL_NAME on the client application.  Excellent!  Congratulations!

EMS_Client_App

And that's how easy it is to get data from a remote database through a REST API call and display the data on an EMS Client application using the Embarcadero RAD Server EMS Server and FireDAC!

 



About
Gold User, Rank: 91, Points: 4
Al Mannarino has 25+ years of software development experience, including object-oriented analysis and design (OOAD) and developing and deploying production applications. He is currently a Principal Software Consultant and Evangelist for Embarcadero Technologies. Prior to joining Embarcadero, Al spent three years working with CodeGear, a division of Borland that was acquired by Embarcadero in 2008. He also worked for five years as a lead systems engineer for Borland supporting application lifecycle management, software delivery optimization and developer tools solutions. Prior to Borland, Al served as a systems engineer for companies including Objectivity, Versant, Red Brick Systems, Information Builders, and was an electrical engineer for Grumman Aerospace performing application implementations on complex electrical-mechanical systems. Al has a bachelor's of science degree in electrical engineering from Manhattan College.

Comments

  • Ahmed Sayed
    Ahmed Sayed Saturday, 18 March 2017

    In step 12. This project is part of a package. When we build the EMS Package we get Warnings that we have dependencies, like this. This is fine and expected. So we click OK to add these needed dependencies to the project. If you re-build you should no longer get any warnings.
    How can I make the IDE show me this message when I build a package I never seen this message before using C++ Builder? Is this a Delphi only feature?

  • Please login first in order for you to submit comments
  • Page :
  • 1

Check out more tips and tricks in this development video: