Show/Hide Toolbars

TMS XData Documentation

Here we describe common tasks you would do to get started implementing your TMS XData server logic.

 

1. (Optional) Reserve your server root URL in Windows

2. Create and run the server

3. Create (or use existing) Aurelius classes and mapping in your server application

4. Create additional server-side logic using service operations

5. Send requests to the server

 

 

1. (Optional) Reserve your server root URL in Windows

 

Any XData HTTP server is based on the TMS Sparkle framework. According to the Sparkle documentation, you must first reserve the URL your service will process its requests from. If you have installed TMS Sparkle on your computer, the URL "http://+:2001/tms" is already reserved, so you can create your XData server under that address (all examples in this documentation use the base address "http://server:2001/tms/xdata"). That is why this item is "optional": it is only required if you choose a different base URL.

 

2. Create and run the server

 

Run one of the "XData Server Wizards" to create the server application with a few clicks. Alternatively, you can create the server manually.

 

 

3. Create (or use existing) Aurelius classes and mapping in your server application

 

This Quick Start guide assumes you have existing, basic knowledge about TMS Aurelius and your application already has some objects mapped to the database. Please refer to the TMS Aurelius documentation, "Quick Start" section for a brief introduction. Consider, for example, that your application has the following classes mapped to the database:

 

uses {...}, Aurelius.Mapping.Attributes;

 

type  

  [Entity, Automapping]  

  TCountry = class  

  private  

    FId: integer;  

    FName: string;  

  public  

    property Id: integer read FId write FId;  

    property Name: string read FName write FName;  

  end;  

  

  [Entity, Automapping]  

  TCustomer = class  

  private  

    FId: integer;  

    FName: string;  

    FCountry: TCountry;  

  public  

    property Id: integer read FId write FId;  

    property Name: string read FName write FName;  

    property Country: TCountry read FCountry write FCountry;  

  end;  

 

Do not forget that you have to use those classes anywhere in your server application otherwise they will be removed by the linker. You could do something as simple as "TCountry.Create.Free" or just manually register the entity classes using TMS Aurelius mapping setup.

 

4. Create additional server-side logic using service operations

 

TMS XData already publishes all your mapped objects through a REST-ful interface, which is accessible through URL conventions. There is no need to write a single line of code.

But if you want to add additional, custom server-side logic or if you want to implement a REST-ful interface without a database connection, you can use Service Operations. For that, just declare an interface with methods and an implementation class that implements the methods on the server side, and all you need to do is mark those types with the custom attributes [ServiceContract] and [ServiceImplementation]. XData also offers a wizard to create a new service interface and implementation.

 

Service interface:

unit MyServiceInterface;

uses {...}, XData.Service.Common;
 
type
  [ServiceContract]
  IMyService = interface(IInvokable)
  ['{BAD477A2-86EC-45B9-A1B1-C896C58DD5E0}']
    function CustomerByName(const Name: string): TCustomer;
  end;
 
initialization
  RegisterServiceType(TypeInfo(IMyService));
end.

 

Service implementation (you can easily use Aurelius on the server side to receive or send objects automatically):

uses {...}, XData.Service.Common, XData.Server.Module, Aurelius.Criteria.Linq;
 
type
  [ServiceImplementation]
  TMyService = class(TInterfacedObject, IMyService)
  private
    function CustomerByName(const Name: string): TCustomer;
  end;
 
function TMyService.CustomerByName(const Name: string): TCustomer;
begin
  Result := TXDataOperationContext.Current.GetManager.Find<TCustomer>
    .Where(TLinq.Eq('Name', Name)).UniqueResult;
end;
 
initialization
  RegisterServiceType(TMyService);
end.

 

5. Send requests to the server

 

Once your server is running, Aurelius entities are accessible through a REST/JSON architecture. The XData server defines URL conventions so you know how to build the URL to access the resources you need. The message payload in HTTP requests and responses must be in JSON format that also follows an XData specification. Then, XData clients can retrieve Aurelius entities by requesting data from the server or request data modification on Aurelius entities. You can also invoke service operations.

 

To illustrate this, given the classes used in step 1 in this quick start guide, here are some valid URL addresses that access resources:

 

http://server:2001/tms/xdata/Customer (lists all TCustomer entities)

http://server:2001/tms/xdata/Country (lists all TCountry entities)

http://server:2001/tms/xdata/Customer(1) (retrieves TCustomer entity with id = 1)

http://server:2001/tms/xdata/Customer(2)/Country (retrieves the TCountry object associated to the customer with id = 2 via Country property)

http://server:2001/tms/xdata/Customer?$filter=Country/Name eq 'USA'&$orderby=Name&$top=10 HTTP/1.1 (retrieves top 10 customers in the USA, ordered by name)

 

Furthermore, you can perform GET requests to retrieve entities, POST to create new entities, PUT/PATCH to update existing entities, and DELETE to remove entities.

 

You can also easily execute service operations from Delphi code through the service interfaces using a TXDataClient object instance:

 

uses {...},  MyServiceInterface, XData.Client;
 
var
  Client: TXDataClient;
  MyService: IMyService;
  Customer: TCustomer;
begin
  Client := TXDataClient.Create;
  Client.Uri := 'http://server:2001/tms/xdata';
  MyService := Client.Service<IMyService>;
  Customer := Client.CustomerByName('Joe');
  {...}
end;