[See the full index of articles for more information] In this blog post, you’ll learn how to build your first RAD Server service-based applications using...
[See the full index of articles for more information]
In this blog post, you’ll learn how to build your first RAD Server service-based applications using Delphi and C++Builder. Before you begin development, you’ll want to make sure that your InterBase database server is running. RAD Server uses an InterBase database for the storage of user information, user groups, analytics, registered devices, version information, registered Edge Modules, push notification messages and more.
Figure 1: InterBase 2017 Server Manager
The fastest way to get started is to use the New Projects menu (File | New | Other…) and choose the RAD Server | RAD Server Package wizard for Delphi or C++Builder.
Figure 2: RAD Server Project Wizard choices for Delphi and C++
Select the RAD Server Package project. A wizard will appear to help create the starting project. On the first page choose how the wizard will create the resources and endpoints that will appear in the RAD Server application. The RAD Server Package Wizard provides two choices to proceed.
Choice 1: Create an empty package that does not register a resource. Choose this option if you are going to add your resources later. Using this choice, a package project will be created with a starting main library.
Figure 3: Create an empty RAD Server package
Clicking the
Finish button will create the starting project for additional development work to create the finished RAD Server application.
Choice
2: Create a package with a resource that extends the REST API of for the RAD Server. Click the Next Button and two additional wizard steps will appear to help create the package project, resource and endpoints. To build the first RAD Server project make this choice.
Figure 4: Create a resource based RAD Server package
On the
wizard’s second page set the Resource name to “Test”. The File type radio buttons presents two options: 1) create a unit for implementing the resource in code, and 2) create a data module for implementing the resource using the IDE’s designer, components and code editor. For this first RAD Server application chose to use a Data Module.
Figure 5: RAD Server Package Wizard page 2 – set the resource name and file type
Click the Next button to create a starting set of endpoints.
Figure 6: RAD Server Package Wizard page 3 – choose starting EndPoints
On the wizard’s third page choose
from a set of predefined EndPoints: Get (REST GET), GetItem (REST GET with a segment at the end of the URL that identifies the item to get) , Post (REST Post), PutItem (REST Put with a segment at the end of the URL that
identifies the item to put), and DeleteItem (REST Delete with a segment at the end of the URL that identifies the item to delete). There is also a Select/deselect all check box at the bottom of the EndPoints list.
To create a package project with all of the EndPoints defined, click on all of the starting end points or choose Select All.
You can also step back through the wizard or click on the step links to make changes to the Package, Resource and Endpoints. To create your starting project is to click the Finish button.
After the wizard completes, you are placed back in the IDE. The first thing to do is to save the project. For the C++ and Delphi data module, use the name “MyDMUnit”. For the C++ project and package use the name “MyFirstCppRADServerPackage”. For the Delphi project and package use the name “MyFirstDelphiRADServerPackage”.
Here are the projects and source code created by the wizard for Delphi and C++. For the C++ code I have added a couple of lines of code in the Get
and GetItem endpoint implementations to set the response (look for the // sample code comment line in MyDMUnit.cpp).
Delphi:
Figure 7: Generated Delphi project and Figure 8: Generated Delphi resource module
package MyFirstDelphiRADServerPackage; {$R *.res} {$IFDEF IMPLICITBUILDING This IFDEF should not be used by users} {$ALIGN 8} {$ASSERTIONS ON} {$BOOLEVAL OFF} {$DEBUGINFO OFF} {$EXTENDEDSYNTAX ON} {$IMPORTEDDATA ON} {$IOCHECKS ON} {$LOCALSYMBOLS ON} {$LONGSTRINGS ON} {$OPENSTRINGS ON} {$OPTIMIZATION OFF} {$OVERFLOWCHECKS OFF} {$RANGECHECKS OFF} {$REFERENCEINFO ON} {$SAFEDIVIDE OFF} {$STACKFRAMES ON} {$TYPEDADDRESS OFF} {$VARSTRINGCHECKS ON} {$WRITEABLECONST OFF} {$MINENUMSIZE 1} {$IMAGEBASE $400000} {$DEFINE DEBUG} {$ENDIF IMPLICITBUILDING} {$RUNONLY} {$IMPLICITBUILD ON} requires rtl, emsserverapi; contains MyDMUnit in 'MyDMUnit.pas' {TestResource1: TDataModule}</span>; end. |
MyDMUnit.pas:
unit MyDMUnit; // EMS Resource Module interface uses System.SysUtils, System.Classes, System.JSON, EMS.Services, EMS.ResourceAPI, EMS.ResourceTypes; type [ResourceName('Test')] TTestResource1 = class(TDataModule) 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</span>; implementation {%CLASSGROUP 'System.Classes.TPersistent'} {$R *.dfm} procedure TTestResource1.Get(const AContext: TEndpointContext; const ARequest: TEndpointRequest; const AResponse: TEndpointResponse); begin // Sample code AResponse.building.SetValue(TJSONString.Create('Test'), True) end</span>; procedure TTestResource1.GetItem(const AContext: TEndpointContext; const ARequest: TEndpointRequest; const AResponse: TEndpointResponse); var LItem: string</span>; begin LItem := ARequest.Params.Values['item'</span>]; // Sample code AResponse.building.SetValue(TJSONString.Create('Test ' + LItem), True) end</span>; procedure TTestResource1.Post(const AContext: TEndpointContext; const ARequest: TEndpointRequest; const AResponse: TEndpointResponse); begin end</span>; procedure TTestResource1.PutItem(const AContext: TEndpointContext; const ARequest: TEndpointRequest; const AResponse: TEndpointResponse); var LItem: string</span>; begin LItem := ARequest.Params.Values['item'</span>]; end</span>; procedure TTestResource1.DeleteItem(const AContext: TEndpointContext; const ARequest: TEndpointRequest; const AResponse: TEndpointResponse); var LItem: string</span>; begin LItem := ARequest.Params.Values['item'</span>]; end</span>; procedure Register</span>; begin RegisterResource(TypeInfo(TTestResource1)); end</span>; initialization Register</span>; end. |
C++:
Figure 9: Generated C++ project and Figure 10: Generated C++ resource module
MyFirstCppRADServerPackage.cpp:
// EMS Package //--------------------------------------------------------------------------- #include <System.hpp> #pragma hdrstop USEFORM("MyDMUnit.cpp", TestResource1); /* TDataModule: File Type */ //--------------------------------------------------------------------------- #pragma package(smart_init) //--------------------------------------------------------------------------- // Package source. //--------------------------------------------------------------------------- #pragma argsused extern "C" int _libmain(unsigned long reason) { return</span> 1; } //--------------------------------------------------------------------------- |
MyDMUnit.h:
// EMS Resource Modules //--------------------------------------------------------------------------- #ifndef MyDMUnitH #define MyDMUnitH //--------------------------------------------------------------------------- #include <System.Classes.hpp> #include <System.SysUtils.hpp> #include <EMS.Services.hpp> #include <EMS.ResourceAPI.hpp> #include <EMS.ResourceTypes.hpp> //--------------------------------------------------------------------------- #pragma explicit_rtti methods (public) class TTestResource1 : public TDataModule { __published: private: public: __fastcall TTestResource1(TComponent* Owner); void Get(TEndpointContext* AContext, TEndpointRequest* Arequest, TEndpointResponse* AResponse); void GetItem(TEndpointContext* AContext, TEndpointRequest* Arequest, TEndpointResponse* AResponse); void Post(TEndpointContext* AContext, TEndpointRequest* Arequest, TEndpointResponse* AResponse); void PutItem(TEndpointContext* AContext, TEndpointRequest* Arequest, TEndpointResponse* AResponse); void DeleteItem(TEndpointContext* AContext, TEndpointRequest* Arequest, TEndpointResponse* AResponse); }; #endif MyDMUnit.cpp: //--------------------------------------------------------------------------- #pragma hdrstop #include "MyDMUnit.h" #include <memory> //--------------------------------------------------------------------------- #pragma package(smart_init) #pragma classgroup "System.Classes.TPersistent" #pragma resource "*.dfm" //--------------------------------------------------------------------------- __fastcall TTestResource1::TTestResource1(TComponent* Owner) : TDataModule(Owner) { } void TTestResource1::Get(TEndpointContext* Acontext, TEndpointRequest* ARequest, TEndpointResponse* AResponse) { // Sample code AResponse->building->SetValue(new TJSONString("Test"), True);} void TTestResource1::GetItem(TEndpointContext* Acontext, TEndpointRequest* ARequest, TEndpointResponse* AResponse) { String item; item = ARequest->Params->Values["item"</span>]; // Sample code AResponse->building->SetValue(new TJSONString("Test "+item), True); } void TTestResource1::Post(TEndpointContext* Acontext, TEndpointRequest* ARequest, TEndpointResponse* AResponse) { } void TTestResource1::PutItem(TEndpointContext* Acontext, TEndpointRequest* ARequest, TEndpointResponse* AResponse) { String item; item = ARequest->Params->Values["item"</span>]; } void TTestResource1::DeleteItem(TEndpointContext* Acontext, TEndpointRequest* ARequest, TEndpointResponse* AResponse) { String item; item = ARequest->Params->Values["item"</span>]; } static void Register() { std::auto_ptr<TEMSResourceAttributes> attributes( new TEMSResourceAttributes()); attributes->ResourceName = "Test"</span>; attributes->ResourceSuffix["GetItem"] = "{item}"</span>; attributes->ResourceSuffix["PutItem"] = "{item}"</span>; attributes->ResourceSuffix["DeleteItem"] = "{item}"</span>; RegisterResource(__typeinfo(TTestResource1), attributes.release()); } #pragma startup Register 32 |
Now that you’ve used the wizard to build your first RAD Server application, you can use the IDE to compile and test the application. The IDE uses the EMSDevServer as the host executable (EMDDevServer.exe) to start execution with the parameter being the package file to load. There are two versions of the EMSDevServer for Win32 and Win64 development ($(BDS)\bin\EMSDevServer.exe and $(BDS)\bin64\EMSDevServer.exe).
Figure 11: Run | Parameters… dialog showing EMSDevServer.exe as the Host application
RAD Studio also includes EMSDevConsole.exe which will start the EMSDevConsole server and open the EMS Console Server Window. The EMS Console provides a web application which displays analytics, provides for user/group management, and more for your RAD Server application.
Choose the Run | Run menu item or hit F9 to compile, link and run the starting application. The RAD Server Development Server will start, by default, using TCP port 8080. The RAD Server Development Console uses, by default, port 8081.
If this is the first time that you’ve tried to run a RAD Server Application you will see a dialog box that says the RAD Server configuration file, emsserver.ini, was not found. This happens when there is no RAD Server registry key or if the configuration file does not exist.
Figure 12: Trying to start the RAD Server Development Server without a configuration file
Click the Yes button to run the RAD Server configuration wizard.
Figure 13: RAD Server setup wizard page 1 – specify the new EMS database connection parameters
In the first wizard step, enter the InterBase server instance (by default RAD Studio’s development version of InterBase Server uses gds_db). If you previously installed InterBase using a different server instance name, enter that name string. This wizard page also contains the name for the RAD Server database (emsserver.ib), and directory that will contain the database and configuration file.
Click the Next button to tell the wizard whether you to create sample RAD Server database data for users and user groups. For development and testing we’ll set both check boxes.
Figure 14: RAD Server setup wizard page 2 – choose to generate sample data for the database
Click the Next button to set up the user name and password for logging into the RAD Server console.
Figure 15: RAD Server setup wizard page 2 – choose a Console user name and password
Click the Next button to go to the final wizard step. The wizard is ready to create the RAD Server database file, configuration file, and set the Windows registry key for the currently logged in user.
Figure 16: Final RAD Server configuration wizard page
This page displays the database file path and name, configuration path and name and the Windows Registry key. You can always make changes to the RAD Server configuration file (emsserver.ini) at any time. Click the Finish button. A confirmation dialog will appear with a reminder that the configuration will use an instance of InterBase that does not have a RAD Server license. The development license limits your RAD Server application to a maximum of 5 users.
Figure 17: Confirmation dialog box – using InterBase instance without a RAD Server license
When you are ready to deploy your RAD Server application, you’ll be able to use your deployment licenses for RAD Server and InterBase.
Click the Yes button. The wizard will display location of the emsserver.ini configuration file. It also lists the sample data that has been added to the database.
Figure 18: List of RAD Server files created by the configuration wizard
Click the OK button. Two
files now appear in the C:\Users\Public\Documents\Embarcadero\EMS directory.
Figure 19: Files on disk created by the RAD Server configuration wizard
You can use InterBase’s IBConsole
program to view the emsserver.ib database.
Figure 20: IBConsole view of the emsserver.ib database file
Use RegEdit to view the registry key created for the RAD Server configuration file location.
Figure 21: RAD Server configuration file registry key
When the RAD Server configuration server is created, the RAD Server Development Server will start executing. On my development computer, the EMSDevServer reports that the default port (8080) is already in use because some other application (Tomcat Server, another web server or some other running application) is already using the port 8080.
Figure 22: The RAD Server application cannot start – the default port is already in use.
To fix this problem, Click the OK
button.
Figure 23: RAD Server Development Server not started due to a port conflict
You can use the edit box to enter an unused port number (I chose port 8087). Click the Start button and, if the new port number is unused, the RAD Server Development server will start running for this first launch.
To make the port change permanent for your all of your development work, edit the RAD Server development emsserver.ini configuration file. Use a text editor to open the emsserver.ini file. Search for the [Server.Connection.Dev] section. Edit the unused port number and save the configuration file
[Server.Connection.Dev] Port=8087
The RAD Server configuration file will be covered in more detail in the chapter titled “RAD Server Configuration INI File Explaned”.
When you hit run in the IDE your RAD Server Development Server will start executing and the Log will show the operations that take place for your package application.
Figure 24: RAD Server Development Server starting the first C++ application package
Figure 25: RAD Server Development Server starting the first Delphi application package
The RAD Server Development Server log will display the configuration, database connection, licensing information, the application package that was loaded, the resources that were registered, and endpoints that were created.
Clicking the Open Browser button will start your default browser and display the JSON result of calling the GetVersion built-in endpoint. You’ve now used your first RAD Server REST endpoint!
Figure 26: Browser showing the output from calling the version endpoint
In the browser, change the URL to localhost:8087/Test and hit enter. The browser will receive the JSON response from the Get endpoint.
Figure 27: Browser showing the JSON output from the Test resource’s Get method
If you pass an additional item on the URL, the GetItem endpoint will be called, and the code behind will return a JSON string containing the resource name plus the item you typed.
Figure 28: Browser showing the JSON output from the Test resource’s GetItem method
For simple examples it’s okay to return a JSON string, but for larger, more complex data structures, you may not want to return a large JSON string.
RAD Studio provides many other ways to generate JSON data including using JSON objects, JSON streams and the JSON writer.
Edit the URL to use the “Users” resource which will call the default GetUsers endpoint to display JSON for the user generated by the RAD Server configuration wizard in the RAD Server datastore (there is only one to start).
Figure 29: JSON response in the Browser for a call to the GetUsers end point
You’ve now used four of the endpoints that were generated by the RAD Server project wizard.
RAD Server’s Enterprise Mobility Services (EMS)
http://docwiki.embarcadero.com/RADStudio/en/Enterprise_Mobility_Services_(EMS)
Setting Up Your RAD Studio (EMS) Server
http://docwiki.embarcadero.com/RADStudio/en/Setting_Up_Your_EMS_Server
Configuring Your EMS Server or EMS Console Server on Windows
Contact our sales team to get a personalized demo of our database management software for SQL Server!
