Tutorial: Implementing Your First EMS Resource

Go Up to EMS Resource Overview

You can create a new resource on the EMS server by Creating an EMS Package.

To create a new Delphi package:

1. Go to File > New > Other .
2. Go to Delphi Projects > EMS > EMS Package.
3. Select Create package with resource and click Next.
4. Enter "Test" as the resource name.
5. For this sample, you can select either Data Module or Unit.
6. Click Next.
7. Select Get and GetItem and click Finish.

In the Unit added to your project, add the following code:

Create a new function:

• For Delphi:

type
  [ResourceName('Test')]
  TTestResource1 = class(TDataModule)
  private
    // Declare the function
    function MakeJSON(I: Integer): TJSONObject; //It takes an integer as a parameter and returns a JSON Object.
  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);
  end;

• For C++ (in the Unit1.h file):

class TTestResource1 : public TDataModule
{
__published:
private:
	TJSONObject* MakeJSON(int I);
public:
	__fastcall TTestResource1(TComponent* Owner);
	void Get(TEndpointContext* AContext, TEndpointRequest* ARequest, TEndpointResponse* AResponse);
	void GetItem(TEndpointContext* AContext, TEndpointRequest* ARequest, TEndpointResponse* AResponse);
};

Use class completion by pressing CTRL-SHIFT-C to create a stub for this function in the implementation section.

Write code for the function you just added:

• For Delphi:

function TTestResource1.MakeJSON(I: Integer): TJSONObject;
begin
  Result := TJSONObject.Create; 
  Result.AddPair('index', TJSONNumber.Create(I)); //Adds to the JSON object a pair {"index": I}, the index number.
  Result.AddPair('value', TJSONString.Create(TestValues[I])); //Adds to the the JSON object a pair {"value":String}, the string corresponding to the index number. 
end;

• For C++ (in the Unit1.cpp file):

TJSONObject* TTestResource1::MakeJSON(int I) {
	TJSONObject *result = new TJSONObject();
	result->AddPair(new TJSONPair("index", new TJSONNumber(I)));
	result->AddPair(new TJSONPair("value", new TJSONString(TestValues[I])));
	return result;
}

Include the constants under a uses statement in the implementation section:

• For Delphi:

const
  TestValues: array [0 .. 2] of string = ('a', 'b', 'c'); // It creates an array of string values.

• For C++ (in the Unit1.cpp file):

 const char* TestValues[] = { "a", "b", "c" };

Write code for the Get endpoint:

• For Delphi:

procedure TTestResource1.Get(const AContext: TEndpointContext;
  const ARequest: TEndpointRequest; const AResponse: TEndpointResponse);
var
  LJSON: TJSONArray;
  I: Integer;
begin
  LJSON := TJSONArray.Create; 
  for I := Low(TestValues) to High(TestValues) do 
    LJSON.Add(MakeJSON(I)); //[{"index":0,"value":"a"},{"index":1,"value":"b"},{"index":2,"value":"c"}]
  AResponse.Body.SetValue(LJSON, True) // True causes AResponse to free JSON

end;

• For C++ (in the Unit1.cpp file):

void TTestResource1::Get(TEndpointContext* AContext, TEndpointRequest* ARequest, TEndpointResponse* AResponse) {
	int I;
	TJSONArray *LJSON = new TJSONArray();
	int TestValuesSize = sizeof(TestValues) / sizeof(TestValues[0]);
	for (I = 0; I < TestValuesSize; I++) {
		LJSON->Add(MakeJSON(I));
	}
	AResponse->Body->SetValue(LJSON, true);
}

Write code for the GetItem endpoint:

• For Delphi:

procedure TTestResource1.GetItem(const AContext: TEndpointContext;
  const ARequest: TEndpointRequest; const AResponse: TEndpointResponse);
var
  I: Integer;
begin
  if not TryStrToInt(ARequest.Params.Values['item'], I) then //{"index":I,"value":value}
    AResponse.RaiseBadRequest('Index expected');
  if (I < 0) or (I >= Length(TestValues)) then
    AResponse.RaiseBadRequest('Index out of range');
  AResponse.Body.SetValue(MakeJSON(I), True);
  // True causes AResponse to free JSON
end;

• For C++ (in the Unit1.cpp file):

void TTestResource1::GetItem(TEndpointContext* AContext, TEndpointRequest* ARequest, TEndpointResponse* AResponse) {
	String item;
	int I = 0;
	int TestValuesSize = sizeof(TestValues) / sizeof(TestValues[0]);
	item = ARequest->Params->Values["item"];
	if (!(TryStrToInt(item, I))) {
		AResponse->RaiseBadRequest("Index expected");
	}
	else {
		if ((I < 0) || (I >= TestValuesSize))
			AResponse->RaiseBadRequest("Index out of range");
		else
			AResponse->Body->SetValue(MakeJSON(I), true);
	}

}

Testing the New Resource

To test your project on a developer environment:

1. Go to Run > Parameters
2. Check the Host application field to see if the path to the EMS Server executable is correct. The path is C:\Program Files (x86)\Embarcadero\Studio\17.0\bin\EMSDevServer.exe
3. Run the project and the Server window opens.

On a browser, introduce the following URL's:

  http://localhost:8080/test/  //It uses the Get() endpoint to get all the JSON array
  http://localhost:8080/test/1//It uses the GetItem() endpoint to get the first item of the array.
  http://localhost:8080/test/2
  http://localhost:8080/test/3

  <localhost>:<port_number>/resource/parameter
  <ip_address>:<port_number>/resource/parameter

See Also

• Creating an EMS Package
• EMS Resource Overview
• Extending the EMS Server‎
• EMS Server