Show/Hide Toolbars

TMS XData Documentation

After setting up the connection, you can use TXDataWebClient component to communicate with the TMS XData Server from a TMS Web Core application. Note that the TXDataWebConnection must be previously connected. Performing operations with TXDataWebClient won't automatically setup the connection.

 

TXDataWebClient perform operations similar to the ones performed by TXDataClient, used in Delphi desktop and mobile applications. It means you can retrieve single and multipe entities (GET), insert (POST), update (PUT), delete (DELETE) and also invoke service operations.

 

However, there are several differences. The first and main one is that all requests are performed asynchronously. This means that when you call TXDataWebClient methods, you won't have a function result provided immediately to you, but instead you have to use event or callback to receive the result. Here is, for example, how to retrieve an entity (GET request) from server, more specifically retrieve an object artist, from entity set "Artist", with id 1:

 

procedure TForm1.GetArtistWithId1;
begin
  XDataWebClient1.Connection := XDataWebConnection1;
  XDataWebClient1.OnLoad := XDataWebClient1Load;

  XDataWebClient1.Get('Artist'1);
end;

 
procedure TForm1.XDataWebClient1Load(Response: TXDataClientResponse);
var
  Artist: TJSObject;
begin

  // Both lines below are equivalent.
  Artist := TJSObject(Response.Result); 
  Artist := Response.ResultAsObject; 

 

  // Use Artist object
end;

 

First, associate the TXDataWebClient component to an existing TXDataWebConnection component which will has the connection settings. This can be also done at design-time.

 

Second, set the OnLoad event of the component and add the code there to be executed when request is completed. Also can be done at design-time.

 

Finally, execute the method that perform the operation. In this case, Get method, passing the entity set name (Artist) and the id (1).

 

When the request is complete, the OnLoad event will be fired, and the result of the request (if it does return one) will be available in the Response.Result property. That property is of type JSValue, which can be any valid value. You will have to interpret the result depending on the request, if you are retrieving a single entity, that would be a TJSObject. If you are retrieving a list of objects, then the value can be a TJSArray, for example. You can alternatively use ResultAsObject or ResultAsArray.

 

TXDataWebClient component is very lightweight, so you can use as many components as you want. That means that you can drop one TXDataWebClient component in the form for each different request you want to perform, so that you will have one OnLoad event handler separated for each request. This is the more RAD and straightforward way to use it. In the case you want to use a single web client component for many requests, you can differentiate each request by the request id.

 

Using RequestId

 

Each response in the OnLoad event will have a request id. By default the request id is the name of the performed operation, in lowercase. So it will be "get" for get requests, "list" for list requests, etc.:

 

procedure TForm1.XDataWebClient1Load(Response: TXDataClientResponse);
var
  Artist: TJSObject;
begin
  if Response.RequestId = 'get' then
  begin
    Artist := TJSObject(Response.Result);
  end;
end;

 

If you want to change the default request id, you can pass a different one as an extra parameter to the request, and check for it in the OnLoad event:

 

  XDataWebClient1.Get('Artist'1'get artist');

 

Handling errors

 

If you don't specify anything, all request errors that might happen will fire the OnError event of the associated TXDataWebConnection component. This way you can have a centralized place to handle all request errors for that XData server.

 

But if you want to add error-handling code that is specific to a TXDataWebClient connection, TXDataWebClient also provides an OnError event:

 

procedure TForm1.XDataWebClient1Error(Error: TXDataClientError);
begin
  WriteLn('Error on request: ' + Error.ErrorMessage);
end;

 

Using callbacks

 

Alternatively to using OnLoad and OnError events, you can use the request methods passing callback as parameter. You can pass a callback for successful response, and optionally an extra callback for error response (if you don't pass the error callback, it will fallback to the OnError event).

 

procedure TForm1.GetArtistWithId1;
 
  procedure OnSuccess(Response: TXDataClientResponse);
  var
    Artist: TJSObject;
  begin
    Artist := TJSObject(Response.Result);
    // Use Artist object
  end;
 
  procedure OnError(Error: TXDataClientError);
  begin
    WriteLn('Error on request: ' + Error.ErrorMessage);
  end;
 
begin
  XDataWebClient1.Get('Artist'1, @OnSuccess, @OnError);
end;

 

Available request methods

 

The following is a list of available request methods in TXDataWebClient. Remember that the method signatures in this list include only the required parameters. You can always also use either RequestId parameter or the callback parameters, as previously explained.

 

Name

Description

procedure Get(const EntitySet: string; Id: JSValue);

Retrieves a single entity from the server (GET request), from the specified entity set and with the specified id. Result will be a TJSObject value.

procedure Get(const EntitySet, QueryString: string; Id: JSValue);

Retrieves a single entity from the server (GET request), from the specified entity set and with the specified id. Optionally you can provide a QueryString parameter that must contain query options to added to the query part of the request. For get requests you would mostly use this with $expand query option. Result will be a TJSObject value.

procedure List(const EntitySet: string; const Query: string = '');

Retrieves a collection of entities from the specified entity set in the server (GET request). You can provide a QueryString parameter that must contain query options to added to the query part of the request, like $filter, $orderby, etc.. Result will be a TJSArray value.

procedure Post(const EntitySet: string; Entity: TJSObject);

Inserts a new entity in the entity set specified by the EntitySet parameter. The entity to be inserted is provided in the Entity parameter.

procedure Put(const EntitySet: string; Entity: TJObject);

Updates an existing entity in the specified entity set. You don't need to provide an id separately since the Entity parameter should already contain all the entity properties, including the correct id.

procedure Delete(const EntitySet: string; Entity: TJObject);

Deletes an entity from the entity set. The id of the entity will be retrieved from the Entity parameter. Since this is a remove operation, only the id properties are relevant, all the other properties will be ignored.

procedure RawInvoke(const OperationId: string; Args: array of JSValue);

Invokes a service operation in the server. The OperationId identifies the operation and Args contain the list of parameters. More info below.

 
Invoking service operations

 

You can invoke service operations using RawInvoke methods. Since you can't use the service contract interfaces in TMS Web Core yet, the way to invoke is different from TXDataClient. The key parameter here is OperationId, which identifies the service operation to be invoked. By default, it's the interface name plus dot plus method name.

 

For example, if in your server you have a service contract which is an interface named "IMyService" which contains a method "Hello", that receives no parameter, you invoke it this way:

 

XDataWebClient1.RawInvoke('IMyService.Hello', []);

 

If the service operation provides a result, you can get it the same way as described above: either using OnLoad event, or using callbacks:

 

procedure TForm2.WebButton1Click(Sender: TObject);
 
  procedure OnResult(Response: TXDataClientResponse);
  var 
    GreetResult: string;
  begin
    GreetResult := string(TJSObject(Response.Result)['value']);
  end;
 
begin
  Client.RawInvoke('IMyService.Greet', ['My name'], @OnResult);
end;

 

Since we're in the web/JavaScript world, you must know in more details how results are returned by service operations in JSON format.

 

As the example above also illustrates, you can pass the operation parameters using an array of JSValue values. They can be of any type, inculding TJSObject and TJSArray values.

 

Other properties

 

Name

Description

property ReferenceSolvingMode: TReferenceSolvingMode

Specifies how $ref occurrences in server JSON response will be handled.

 

rsAll: Will replace all $ref occurrences by the instance of the referred object. This is default behavior and will allow dealing with objects easier and in a more similar way as the desktop/mobile TXDataClient. It adds a small overhead to solve the references.

 

rsNone: $ref occurrences will not be processed and stay as-id.