Учебный пример: DataSnap XE - обычные объекты в качестве параметров.

В этой статье мы рассмотрим различные типы параметров, которые можно передавать между клиентами и серверами DataSnap.В ходе выполнения примера мы будем передавать параметры, которые представляют собой обычные классы Delphi. В Java Enterprise Edition существует такая концепция -

"Plain Old Java Objects" -

 для передачи данных между приложениями. Здесь мы собираемся использовать этот же подход для обмена данными между клиентами и серверами, поэтому мы будем назвать их "Plain Old Delphi Objects" или "PODO"!

Введение

Создание сервера

На первой странице мастера оставьте по-умолчанию "VCL Forms Application" в качестве типа приложения.

Снимите "галочку" на опции генерации демонстрационных серверных методов ("sample methods").

Сохраните все значения по-умолчанию для сервера, так что наш сервис будет использовать протокол TCP/IP для взаимодействия без авторизации/аутентификации.

Мы будем реализовывать серверные методы сами.

На третьей странице оставим порт TCP/IP по-умолчанию как 211 и проверим его доступность.

На последней странице оставьте базовый класс для реализации серверных методов и по-умолчанию и кликните на "Finish".

Выберите "File - Save All" для сохранения файлов в новом проекте, созданном мастером. В моем случае я собираюсь создать новую папку "C:\DataSnapLabs\PlainOldDelphiObjectParams\" для своих файлов.

Назовите серверный модуль "FormServerUnit" и оставьте имена для модуля серверных методов и контейнера по-умолчанию (например, "ServerMethodsUnit2" и "ServerContainerUnit2", а имя всего проекта введите как "PODOServer".

Давайте создадим класс Delphi, который мы будем передавать как параметр.

Код проектов как сервера, так и клиента должен знать классы, которые мы будем передавать, поэтому целесообразно выделить для этого отдельный модуль, который будет использоваться в разделе "uses" в обоих проектах.

Добавьте новый модуль в серверный проект и сохраните его как "SharedStuffUnit".

Замените его содержимое на реализацию некого класса "TPerson".

unit SharedStuffUnit;

interface

type
  TPerson = class(TObject)
  private
    FLastName: string;
    FFirstName: string;
    procedure SetFirstName(const Value: string);
    procedure SetLastName(const Value: string);
  public
    constructor Create(const aFirst, aLast: string);
    function ToString: string; override;
    property FirstName: string read FFirstName write SetFirstName;
    property LastName: string read FLastName write SetLastName;
  end;

implementation

{ TPerson }

constructor TPerson.Create(const aFirst, aLast: string);
begin
  FFirstName := aFirst;
  FLastName := aLast;
end;

procedure TPerson.SetFirstName(const Value: string);
begin
  FFirstName := Value;
end;

procedure TPerson.SetLastName(const Value: string);
begin
  FLastName := Value;
end;

function TPerson.ToString: string;
begin
  Result := LastName + ', ' + FirstName;
end;

end.

Теперь нам нужно внести данный модуль в раздел "uses" модуля класса серверных методов.

Войдите в модуль серверных методов и выберите "File - Use Unit" из меню, а новый модуль попадет в раздел "uses" автоматически.

Давайте реализуем серверный метод, названный "GetPerson", который принимает два строковых параметра для имени и фамилии и возвращает экземпляр "TPerson", инициализированный данными значениями.

unit ServerMethodsUnit2;

interface

uses
  SysUtils, Classes, DSServer, 
  SharedStuffUnit; // for "TPerson"

type
{$METHODINFO ON}
  TServerMethods2 = class(TComponent)
  private
    { Private declarations }
  public
    function GetPerson(const aFirst, aLast: string): TPerson;
  end;
{$METHODINFO OFF}

implementation

{ TServerMethods2 }

function TServerMethods2.GetPerson(const aFirst, aLast: string): TPerson;
begin
  Result := TPerson.Create(aFirst, aLast);
end;

end.

Теперь наш сервер готов. Теперь нужно лишь запустить его ("Run - Run Without Debugging" и минимизировать его окно.

Сервер должен быть запущен в течение создания клиентского приложения.

Реализация клиентского приложения

Теперь нам нужно сгенерировать код клиентского прокси DataSnap, чтобы мы могли вызывать серверные методы из клиента.

Самый простой путь сделать это - воспользоваться мастером "DataSnap Client Module".

Вы можете оставить значение по-умолчанию для всех четырех страниц мастера.

На первой странице оставьте размещение сервера как "Local Server" ("локальный сервер").

На второй странице оставим типа серверного приложения как standalone ("независимое, изолированное").

На следующей странице оставьте значение по-умолчанию для протокола связи, которое "TCP/IP".

На последней странице оставьте значения порта 211 и проверьте его доступность кнопкой "Test Connection".

Нажмите на кнопку "Finish".

Мастер добавит два новых модуля к нашему клиентскому проекту: "ClientModuleUnit1" и "ClientClassesUnit1".

Сохраните все новые файлы, оставив имена по-умолчанию.

Давайте изучим содержимое модулей клиентских классов, которые были созданы генератором клиентского прокси DataSnap.

// 
// Created by the DataSnap proxy generator.
// 3/21/2011 9:46:56 PM
// 

unit ClientClassesUnit1;

interface

uses DBXCommon, DBXClient, DBXJSON, DSProxy, Classes, SysUtils, DB, SqlExpr, DBXDBReaders, SharedStuffUnit, DBXJSONReflect;

type
  TServerMethods2Client = class(TDSAdminClient)
  private
    FGetPersonCommand: TDBXCommand;
  public
    constructor Create(ADBXConnection: TDBXConnection); overload;
    constructor Create(ADBXConnection: TDBXConnection; AInstanceOwner: Boolean); overload;
    destructor Destroy; override;
    function GetPerson(aFirst: string; aLast: string): TPerson;
  end;

implementation

function TServerMethods2Client.GetPerson(aFirst: string; aLast: string): TPerson;
begin
  if FGetPersonCommand = nil then
  begin
    FGetPersonCommand := FDBXConnection.CreateCommand;
    FGetPersonCommand.CommandType := TDBXCommandTypes.DSServerMethod;
    FGetPersonCommand.Text := 'TServerMethods2.GetPerson';
    FGetPersonCommand.Prepare;
  end;
  FGetPersonCommand.Parameters[0].Value.SetWideString(aFirst);
  FGetPersonCommand.Parameters[1].Value.SetWideString(aLast);
  FGetPersonCommand.ExecuteUpdate;
  if not FGetPersonCommand.Parameters[2].Value.IsNull then
  begin
    FUnMarshal := TDBXClientCommand(FGetPersonCommand.Parameters[2].ConnectionHandler).GetJSONUnMarshaler;
    try
      Result := TPerson(FUnMarshal.UnMarshal(FGetPersonCommand.Parameters[2].Value.GetJSONValue(True)));
      if FInstanceOwner then
        FGetPersonCommand.FreeOnExecute(Result);
    finally
      FreeAndNil(FUnMarshal)
    end
  end
  else
    Result := nil;
end;

constructor TServerMethods2Client.Create(ADBXConnection: TDBXConnection);
begin
  inherited Create(ADBXConnection);
end;

constructor TServerMethods2Client.Create(ADBXConnection: TDBXConnection; AInstanceOwner: Boolean);
begin
  inherited Create(ADBXConnection, AInstanceOwner);
end;

destructor TServerMethods2Client.Destroy;
begin
  FreeAndNil(FGetPersonCommand);
  inherited;
end;

end.

Прокси-генератор DataSnap автоматически "зацепит" общий модуль и также сгенерирует кода для де-маршализации экземпляра "TPerson" из JSON-представления, использованного для передачи по сети! Великолепно!

Последний шаг - создание простейшего GUI для вызова серверного метода, который возвращает экземпляр "TPerson".

Откроем модуль клиентской формы.

Выберем "File - Use Unit" и добавим неиспользованный доселе модуль в раздел uses секции implementation клиентского модуля.

Добавим на форму два компонента "TEdit" и один "TButton".

Назовите первое поле ввода "edFirstname", а второе - "edLastname".

Поменяйте свойство "Caption" кнопки на "Show Person" в инспекторе объектов.

Кликните два раза на кнопке и реализуйте событие "OnClick", в котором будет вызов серверного метода "GetContact", передавая содержимое полей ввода в качестве параметров, и в котором отобразится результат метода "ToString" экземпляра "TPerson", полученного из сервера.

Ниже представлен листинг клиентского модуля:

unit FormClientUnit;

interface

uses
  Windows, Messages, SysUtils, Variants, Classes, Graphics, Controls, Forms,
  Dialogs, StdCtrls;

type
  TFormClient = class(TForm)
    edtFirstname: TEdit;
    Button1: TButton;
    edtLastname: TEdit;
    procedure Button1Click(Sender: TObject);
  private
    { Private declarations }
  public
    { Public declarations }
  end;

var
  FormClient: TFormClient;

implementation

uses ClientClassesUnit1, ClientModuleUnit1, SharedStuffUnit;

{$R *.dfm}

procedure TFormClient.Button1Click(Sender: TObject);
var p: TPerson;
begin
  p := ClientModule1.ServerMethods2Client.GetPerson(
    edtFirstname.Text, edtLastname.Text);
  ShowMessage(p.ToString);
end;

end.

Если вводятся некие строки типа "имя" и "фамилия", то должны увидеть на экране следующий диалог.

Вот так оно работает! Мы только что создали простой пример, состоящий из сервера и клиента DataSnap, в котором используется метод передачи объекта пользовательского типа.

Это и называется "Plain Old Delphi Object" (обычный объект Delphi).

Управление памятью

procedure TFormClient.Button1Click(Sender: TObject);
var p: TPerson;
begin

  // внутренний экземпляр класса серверных методов "лениво" создается 
  // при первом обращении
  // так что всё нужно сделать перед чтением
  // свойства "ClientModule1.ServerMethods2Client" 
  // а если по-другому, то это не будет иметь эффекта
  ClientModule1.InstanceOwner := False;

  p := ClientModule1.ServerMethods2Client.GetPerson(
    edtFirstname.Text, edtLastname.Text);
  if p <> nil then
  begin
    ShowMessage(p.ToString);
    if not ClientModule1.InstanceOwner then
      p.Free;
  end;
end;

Другой хороший вопрос - как создается ссылка на "TPerson" на клиенте?

Метод "GetPerson", созданный генератором прокси DataSnap, имеет кое-что интересное в своём коде.

//  …

  if not FGetPersonCommand.Parameters[2].Value.IsNull then
  begin
    FUnMarshal := TDBXClientCommand(FGetPersonCommand.Parameters[2].ConnectionHandler).GetJSONUnMarshaler;
    try
      Result := TPerson(FUnMarshal.UnMarshal(FGetPersonCommand.Parameters[2].Value.GetJSONValue(True)));
      if FInstanceOwner then
        FGetPersonCommand.FreeOnExecute(Result);
    finally
      FreeAndNil(FUnMarshal)
    end
  end
  else
    Result := nil;

// …

Этот код генерируется автоматически при взаимодействии с запущенным сервером DataSnap. Впечатляет! Генератор знает, что он должен использовать наш модуль "SharedStuffUnit". Значение, возвращаемое методом "GetPerson" является результатом приведения типа ссылки к "TPerson", возвращаемой методом "TJSONUnMarshal.Unmarshal".

Итог

Первым шагом является создание нового серверного приложения DataSnap с использованием мастера "DataSnap Server".

Запустите Delphi XE.

Выберите в главном меню "File -> New -> Other", а затем в диалоге "New Items" щелкните два раза на иконке "DataSnap Server" в категории "Delphi Projects ->

DataSnap Server".

На первой странице оставьте по-умолчанию опцию "Project type" как "VCL Forms Application".

На второй странице мастера также оставьте уже выбранные опции.

Далее мы заменим демонстрационные методы (Sample Methods) сервера нашими вариантами.

На третьем изображении мы оставим значение по-умолчанию "211" для номера порта TCP/IP.

Старайтесь всегда проводить проверку доступности порта путем нажатия на кнопку "Test Port".

На последней странице мы собираемся также воспользоваться опцией по-умолчанию для выбора базового класса как "TComponent",

от которого будет производиться наш класс, реализующий методы сервера.

Нажмите на кнопку "Finish", а мастер создаст новый проект с тремя модулями.

Сохраните весь проект выбором "File -> Save All".

Создайте новую папку для всех файлов для данного учебного примера "C:\DataSnapLabs\SimpleCalc\".

Сохраните главную форму приложения как "FormServerUnit", а для остальных имен воспользуйтесь стандартными названиями - "ServerContainerUnit1" и "ServerMethodsUnit1" - и сохраните проект как "SimpleCalcServer".

На этой стадии в окне Delphi Project Manager вы видите следующую картину:

Откройте модуль "ServerMethodsUnit1.pas" и реализуйте функциональность простого сервиса, выполняющего арифметические действия.

Замените демонстрационные методы, добавленные мастером ("EchoString" и "ReverseString"), на нужные нам варианты "Add" ("сложить"),

"Subtract" ("вычесть"), "Multiply" ("умножить") и "Divide" ("разделить").

Исходный код для модуля "ServerMethodsUnit1" должен выглядеть следующим образом:

unit ServerMethodsUnit1;

interface

uses
  Classes;

type
{$METHODINFO ON}
  TServerMethods1 = class(TComponent)
  private
    { Private declarations }
  public
    function Add(a, b: double): double;
    function Subtract(a, b: double): double;
    function Multiply(a, b: double): double;
    function Divide(a, b: double): double;
  end;
{$METHODINFO OFF}

implementation

{ TServerMethods1 }

function TServerMethods1.Add(a, b: double): double;
begin
  Result := a + b;
end;

function TServerMethods1.Subtract(a, b: double): double;
begin
  Result := a - b;
end;

function TServerMethods1.Multiply(a, b: double): double;
begin
  Result := a * b;
end;

function TServerMethods1.Divide(a, b: double): double;
begin
  Result := a / b;
end;

end.

Листинг 1: ServerMethodsUnit1.pas.

Вы полностью реализовали наш сервер. Для того чтобы реализовать клиентское приложение, сервер должен быть запущен.

Выберите "Run -> Run Without Debugging" для запуска сервера (вне отладчика) и минимизируйте его окно.

Не завершайте работу серверного приложения до окончания учебного примера.

Создаем простое клиентское приложение

В диалоге "New Items" выберите "VCL Forms Application" из категории "Delphi Projects".

Нажмите "OK". К существующей project group должен добавиться новый проект.

Выполните сохранение нового проекта "File -> Save All".

Выберите папку, которую вы создали для сохранения файлов проекта сервера,

и сохраните туда главную форму клиентского приложения как "FormClientUnit",

сам проект как "SimpleCalcClient", а всю project group как "SimpleCalcGrp".

Теперь окно Project Manager должно выглядеть как:

Проверьте, что проект клиентского приложения активен, затем выберите "File -> New -> Other",

а в появившемся диалоге "New Items" выберите "DataSnap Client Module".

Как и в прошлый раз, пожалуйста, сохраните все опции по умолчанию во время работы с мастером.

На первой странице оставьте "DataSnap server location" как "Local server".

Наш сервер DataSnap является "stand alone" (независимое отдельное приложение), поэтому просто нажмите "Next".

Мы согласились использовать "TCP/IP" в качестве протокола, поэтому сохраним выбранную опцию.

Нажмите на "Test Connection", чтобы проверить, действительно ли сервер "слушает" порт 211, а затем нажмем "Finish".

Мастер добавить два модуля к нашему клиентскому приложению "ClientClassesUnit1" и "ClientModuleUnit1".

Последней задачей в этом учебном примере является реализация интерфейса клиентского приложения.

Начнем с того, что добавим ссылку на модуль "ClientModuleUnit1" в раздел uses главного модуля формы клиента.

Активируем данный модуль в редакторе и выбираем в меню "File -> Use Unit".

Теперь в коде формы клиента нужно правильно использовать методы,

экспонируемые (предлагаемые) через свойство "ClientModule1.ServerMethods1Client".

Эти методы имеют те же имена и сигнатуры, как и методы, реализованные на сервере.

Ниже показана реализация главной формы клиентского приложения.

unit FormClientUnit;

interface

uses
  Windows, Messages, SysUtils, Variants, Classes, Graphics, Controls, Forms,
  Dialogs, StdCtrls;

type
  TForm3 = class(TForm)
    EditA: TEdit;
    ButtonAdd: TButton;
    EditB: TEdit;
    ButtonSub: TButton;
    ButtonMult: TButton;
    ButtonDiv: TButton;
    LabelResult: TLabel;
    procedure ButtonAddClick(Sender: TObject);
    procedure ButtonSubClick(Sender: TObject);
    procedure ButtonMultClick(Sender: TObject);
    procedure ButtonDivClick(Sender: TObject);
  private
    { Private declarations }
  public
    function GetA: double;
    function GetB: double;
    procedure ShowResult(aValue: double);
  end;

var
  Form3: TForm3;

implementation

uses ClientModuleUnit1;

{$R *.dfm}

function TForm3.GetA: double;
begin
  Result := StrToFloat(EditA.Text);
end;

function TForm3.GetB: double;
begin
  Result := StrToFloat(EditB.Text)
end;

procedure TForm3.ShowResult(aValue: double);
begin
  LabelResult.Caption := FloatToStr(aValue);
end;

procedure TForm3.ButtonDivClick(Sender: TObject);
begin
  ShowResult(ClientModule1.ServerMethods1Client.Divide(GetA, GetB));
end;

procedure TForm3.ButtonMultClick(Sender: TObject);
begin
  ShowResult(ClientModule1.ServerMethods1Client.Multiply(GetA, GetB));
end;

procedure TForm3.ButtonSubClick(Sender: TObject);
begin
  ShowResult(ClientModule1.ServerMethods1Client.Subtract(GetA, GetB));
end;

procedure TForm3.ButtonAddClick(Sender: TObject);
begin
  ShowResult(ClientModule1.ServerMethods1Client.Add(GetA, GetB));
end;

end.

Листинг 2 : Реализация главной формы клиента .

Окончательно моя форма выглядит следующим образом:

Наверное, вам не нужно рассказывать, как воспроизвести ее!

Теперь вы видите, как просто создавать сервера и клиенты DataSnap и использованием Delphi XEJ

Итог