DataSnap Application Example
Go Up to Creating multi-tiered applications Index
DataSnap technology offers the possibility to create Client-Server applications that communicate through the Internet, the local network, or the local host.
The following example demonstrates the use of DataSnap in creating a local Client-Server application. Both the Client and Server applications are implemented in Delphi. After setting the connection between the Client and Server with DataSnap, the Client is able to call methods defined and implemented on Server.
Creating the Server application
- Choose File > New > VCL Forms Application - Delphi from the main menu.
- Place the following components from the Datasnap Server category of the Tool Palette on the form:
At this point, your Server application should look like this:
The TDSServer component is the logical heart of the DataSnap server application. It contains Start and Stop methods for starting and stopping the server, and also the very handy AutoStart property. By default, the value of the AutoStart property is set to true, so the server starts automatically at the application startup. You only need one TDSServer component per server application.
The TDSTCPServerTransport component implements a multithreaded TCP server listening for incoming client connections on multiple threads. This component does not have any events. The Port property indicates the TCP port to be used. By default, it is set to port 211.
The TDSServerClass component represents a server class.
The DataSnap server automatically creates and destroys instances of server classes. The instancing of a server class is controlled by the LifeCycle property of the TDSServerClass component. The LifeCycle property can have one of the three possible values: Server, Session, and Invocation.
The LifeCycle set to Server means that the DataSnap server creates one instance of a server class that will be used by all clients connected to the server application. This represents a "singleton" pattern. Be careful when using the Server lifecycle, because your server class implementation needs to be thread-safe. You need to proceed with care because it is possible that this singleton object be accessed simultaneously from multiple threads.
The default LifeCycle value is Session. This means that the DataSnap server creates one instance of a server class for every connected client.
The third possible value for LifeCycle property is Invocation. A server class instance is created and destroyed for every method call arriving from a client and the state of a server class is not preserved between method calls.
Follow these steps to link the three components together:
- Select the TDSServerClass component on the form.
- Set the Server property of the TDSServerClass component to the name of your TDSServer component.
- Select the TDSTCPServerTransport component on the form.
- Set the Server property of the TDSTCPServerTransport component to the name of your TDSServer component.
Add a new Unit to your project by selecting File > New > Unit - Delphi in the main menu. This unit contains the implementation of the classes you want to use in the Client application. For example, the following code represents the implementation of a class called MyClass that contains one method (the sum of two Double numbers):
unit MyClass;
interface
uses Classes;
type
{$METHODINFO ON}
TMyClass = class(TComponent)
function Sum(const A, B: Double): Double;
end;
{$METHODINFO OFF}
implementation
{ TMyClass }
function TMyClass.Sum(const A, B: Double): Double;
begin
Result := A + B;
end;
end.
To specify the class you want to call from the Client application, define the OnGetClass event for the TDSServerClass component:
- Select the TDSServerClass component on the form.
- Select the Events tab in the Object Inspector.
- Double-click the value for the OnGetClass event.
- Type the following code (replacing TMyClass with the name of the class you defined at the previous step):
PersistentClass := TMyClass;
If you fail to implement this event, the application immediately after start will raise a TDBXError exception with the OnGetClass event not set or it did not provide a class reference message. The OnGetClass event has the PersistentClass argument that is passed by reference. In the event handler code, the programmer needs to assign to PersistentClass a class reference to a server class (like in the example above). This is probably one single most important concept to understand about the DataSnap architecture. A class reference is assigned to PersistentClass, and not an object reference.
Add the unit defined previously to the list of units used by the Server application.
The Server application is implemented.
Creating the Client application
- To create the Client application in the same project group as the Server application, right-click the name of your project group in the Project Manager and select Add New Project or choose Project > Add New Project from the main menu.
- The New Items dialog window appears. Select the Delphi Projects category, and then select VCL Forms Application.
- Populate the Client form with controls used for introducing the data and writing the result (labels, edit-boxes, and a button for calculating the sum).
- Add a TSQLConnection component from the dbExpress category in the Tool Palette.
- Set the following properties for the TSQLConnection:
- Driver - Datasnap (from the client's perspective, this provider looks like a connection to a database, but in fact provides connectivity to DataSnap servers.)
- LoginPrompt - False (optional, to prevent the username and password dialog to appear every time the client connects to the server.)
The Client form looks like this:
- 6. The most important step in creating the Client-Server application with DataSnap is creating the interface that contains the prototype of all functions implemented on the Server.
To do this:
- Select the Server project by double-clicking the name of the project in Project Manager.
- Choose Run > Run Without Debugging from the main menu.
- While the Server is running, select the Client project by double-clicking its name in the Project Manager.
- Set the Connected property of the TSQLConnection component to true.
- Right-click the TSQLConnection component on the Client form and select Generate DataSnap client classes. A new unit is added to your Client project, containing information about classes implemented on the Server and all the methods contained by these classes.
- Save the new Unit and add it to the list of units used by the Client application.
- 7. Finally, use the desired methods in the Client application. For example, implement the OnClick event for the TButton component and call the Sum method from the Unit automatically generated (saved in the example as MyClassClient):
procedure TClientForm.CalculateClick(Sender: TObject); var Temp: TMyClassClient; A, B: Double; begin Temp := TMyClassClient.Create(SQLConnection1.DBXConnection); try A := StrToFloat(EditA.Text); B := StrToFloat(EditB.Text); EditResult.Text := FloatToStr(Temp.Sum(A, B)); finally Temp.Free; end;
Note: Before closing the Server application, make sure to close all the SQL connections. DataSnap does not warn you about pending connections, so even if the Server seems to close, it does not, until there are no connections to it. Closing all the Client applications does not solve this problem either, because the Delphi IDE can open a connection to the Server automatically and browse for the exposed classes and methods.