Extending the Interface of the Application Server

From RAD Studio
Jump to: navigation, search

Go Up to Creating the Server Application

Client applications interact with the application server by creating or connecting to an instance of the data module. They use its interface as the basis of all communication with the application server. You can extend your data module's interface to provide additional support for your client applications. This interface is a descendant of IAppServer, and is created for you automatically by the wizard when you create the data module.

To add to the data module's interface, you can

  • Choose the Add to Interface command from the Edit menu in the IDE. Indicate whether you are adding a procedure, function, or property, and enter its syntax. When you click OK, you will be positioned in the code editor on the implementation of your new interface member.
  • Use the type library editor. Select the interface for your application server in the type library editor, and click the tool button for the type of interface member (method or property) that you are adding. Give your interface member a name in the Attributes page, specify parameters and type in the Parameters page, and then refresh the type library. For more information about using the type library editor, see Working with type libraries .

Note: Neither of these approaches works if you are implementing TSoapDataModule. For TSoapDataModule descendants, you must edit the server interface directly.

When you add to a COM interface, your changes are added to your unit source code and to the type library file (.TLB).

Note: You must explicitly save the TLB file by choosing Refresh in the type library editor, and then saving the changes from the IDE.

Once you have added the interface to your remote data module, locate the properties and methods that were added to your remote data module's implementation. Add code to finish this implementation by filling in the bodies of the new methods.

If you are not writing a SOAP data module, client applications call your interface extensions using the AppServer property of their connection component. With SOAP data modules, they call the connection component's GetSOAPServer method. For more information on how to call your interface extensions, see Calling server interfaces.

  • Adding callbacks to the application server's interface

You can allow the application server to call your client application by introducing a callback. To do this, the client application passes an interface to one of the application server's methods, and the application server later calls this method as needed. However, if your extensions to the remote data module's interface include callbacks, you can't use an HTTP or SOAP-based connection. Datasnap.Win.SConnect.TWebConnection and Soap.SOAPConn.TSoapConnection do not support callbacks. If you are using a socket-based connection, client applications must indicate whether they are using callbacks by setting the SupportCallbacks property. All other types of connection automatically support callbacks.

  • Extending a transactional application server's interface

When using transactions or just-in-time activation, you must be sure all new methods call SetComplete to indicate when they are finished. This allows transactions to complete and permits the remote data module to be deactivated.

Furthermore, you can't return any values from your new methods that allow the client to communicate directly with objects or interfaces on the application server unless they provide a safe reference. If you are using a stateless MTS data module, neglecting to use a safe reference can lead to crashes because you can't guarantee that the remote data module is active.

See Also