The Data Module

The item of most interest created by the new project wizard is the DataModule in fClientDataModule.pas.

Data Abstract Controls

The DataModule contains a number of new Data Abstract controls linked together. You do not need to worry right now about what every control does in detail, but it is probably worth spending a few minutes getting a brief overview of each.

ClientChannel

The Client Channel performs low-level communication with Relativity Server. The Client Channel also handles the OnLoginNeeded event raised when Relativity Server requests user authentication.

The ClientChannel_OnLoginNeeded event will attempt to first log in using the credentials you provided in the new project wizard, which it has stored in the Data Module code.

var
  gUserId: string = 'Alex';
  gPassword: string = '111';

It will try to log in by calling its own LogOn method (described later), using the stored credentials. If that fails, it will then call the Login function in fLoginForm.pas to show the Log on form and ask the user to enter their credentials.

procedure TClientDataModule.ClientChannel_OnLoginNeeded(Sender: TROTransportChannel; anException: Exception; var aRetry: Boolean);
var
  lUserId: String;
  lPassword: String;
  lStorePassword: Boolean;
begin
  // Performing login
  if (Self.LogOn(gUserId, gPassword))  then  begin
    aRetry := true;
//    e.LoginSuccessful := true;
    Exit;
  end;

  lUserId := '';
  lPassword := '';
  lStorePassword := gStorePassword;
  if not Login(lUserId,lPassword, lStorePassword) then ShowMessage('Login cancelled');
  gUserId := lUserId;
  if lStorePassword then gPassword := lPassword else gPassword := '';
  gStorePassword := lStorePassword;

  if Self.LogOn(lUserId, lPassword)  then  begin
    aRetry := true;
//    e.LoginSuccessful := true;
  end
  else begin
    ShowMessage('Login failed');
  end;
end

Although it might be convenient to have the event try to log in with stored credentials, it is not very secure to store user names and password in the code. If you really need the application to log in automatically, consider storing the credentials somewhere more secure and have the application retrieve them first.

In this case however, you really don't need the app to log in automatically, and asking the user for their credentials is perfectly acceptable, so set both the gUserId and the gPassword variables to empty strings.

var
  gUserId: string = '';
  gPassword: string = '';

Message

The Message component performs protocol-specific data serialization and deserialization. For now, just trust it is doing an important job and then forget about it.

RemoteDataAdapter

The TDARemoteDataAdapter component forms the center of communication from the client to the Relativity Server. It provides all the logic for retrieving data into TDADataTables (see below), applying changes (Deltas) back to the Relativity Server, and handling any other data-related communication with the Relativity Server, such as retrieving business rules scripts or schema information.

RemoteService

This component receives data requests from the RemoteDataAdapter instance and sends them to the Relativity Server using ClientChannel and Message. Again, that's all you need to know. You can now forget about it.

DataStreamer

The Data Streamer serializes and deserializes the data that is sent to and received from the Relativity Server.

Tables

For each table you selected from the schema in the new project wizard, you should also see the following controls. NOTE: You should have controls for the Priorities table and the Tasks table.

sp_tbl_tableName

This is an optional Business Rules Scripting API support component. You only get this control if you selected to Add support for Business Rules Scripting in the final step of the new project wizard.

tbl_tableName

This is a Data Tables component of type TDAMemDataTable.

TDAMemDataTable descends from the abstract base class TDADataTable mentioned above. Data Tables can be filled from Relativity Server using a TDARemoteDataAdapter that coordinates the connection to the Relativity Server. Data Tables maintain a local history of changes (Deltas) and can apply those changes back to the database using the TDARemoteDataAdapter.

ds_tableName

This is a special Data Abstract data source component used for linking visual components like TDBGrid with Data Tables components.

Methods

In its code, the Data Module also exposes a number of methods.

LogOn

The LogOn method performs the logging on to the Relativity Server using the provided username and password and returns true on success.

function TClientDataModule.LogOn(user, password: String): Boolean;
begin
  Result := False;
  // Note that if your application uses more than 1 Schema in this Domain, you should
  // make this Schema active before retrieving data (see the SetActiveSchema method)
  if user = '' then Exit;
  fIsLoggedOn := (TBaseLoginService_Proxy.Create('LoginService', Message, ClientChannel) as IBaseLoginService).LoginEx(UTF8Encode(CreateConnectionString(user,password)));
  if fIsLoggedOn then fUserId := user;
  Result := fIsLoggedOn;
end;

LogOff

The LogOff method performs the logging off from the Relativity Server.

procedure TClientDataModule.LogOff;
begin
  if (not fIsLoggedOn) then exit;

  (TBaseLoginService_Proxy.Create('LoginService',Message, ClientChannel) as IBaseLoginService).Logout;
  fIsLoggedOn := false;
end;