NexusDB

Now that NexusRemoting is generally available as part of NexusDB V3 Public Beta 1 I'll demonstrate how everything comes together in a simple example.

For a fully working NexusRemoting example the following parts are needed:

• An class/interface definition that is shared between client and server.
• An implementation of these classes.
• A server application which hosts these implementation classes and makes them available via one or more NexusDB Transports.
• A client application which connects to this server and makes use of the exposed classes.

For this example I'll be implementing a simple calculator.

Shared Class and Interface Definition

With NexusRemoting this definition comes in form of a simple unit. This unit will be compiled into both the server and the client application.

nxllTypes is required because it defines TnxGuid. nxivTypes defines InxInvokable and the nxInvokeRegistry.

NexusRemoting uses GUIDs to identify classes. When the client wants to create a server-side class it will use this GUID in it's CreateInstance call.

To generate a new GUID directly in the Delphi IDE you can press Shift+Ctrl+G. For the assignment to a TnxGuid like shown above it's necessary to remove the [ ] that the IDE automatically put around it.

This is the interface that the Calc class will be implementing. It derives from InxInvokeable which signals the compiler that it needs to generate RTTI information for this interface.

The required GUID can again be simply created using Shift+Ctrl+G.

It is on purpose designed so that performing calculations and getting the final result will take multiple calls to demonstrate the stateful nature of NexusRemoting.

By registering the interface with the Invoke Registry NexusRemoting is able to create internal data structures with required information to create proxies and stubs on the fly.

Implementation

The next step is a unit containing the class that implements the actual functionality. This unit will only be compiled into the server application, but the client application will be able to create instances of it and make calls against this instance through NexusRemoting.

nxrdClass contains TnxClass and TnxClassFactory.

CalcIntf is the unit that contains the interface definition that's shared between client and server.

While it is not strictly necessary for all classes exposed through NexusRemoting to derive from TnxClass, doing so simplifies the code.

In this example our new class only implements a single interface, InxCalc. But there is no restriction on how many interfaces a class can implement or that a specific interface can only be implemented by a single class.

There is also no restriction that all interfaces implemented by a class need to be supported NexusRemoting. Any interface for which no common proxy/stub implementation can be found between client and server is simply not visible to a remote client.

nxrbTypes contains InxClassFactoryControl.

The actual implementation of the class is very straight forward and is no different from a class that would be used directly in-process.

The Class Factory is the link between the CreateInstance call with a specific GUID and this actual class. There are different types of class factories which will be explored in more detail in a future post. TnxClassFactory is the simplest one which creates an returns a new instance of the class for every CreateInstance request.

Control is an out parameter which returns a reference to an InxClassFactoryControl. This interface is used to control the lifetime of the class factory registration. By releasing the last reference to it the class factory registration is revoked.

Server Application

For the server application a couple of components are required

TnxRemotingServer is a very simple implementation of InxClassActivator which passes calls straight through to the Class Factory Registry.

TnxRemotingCommandHandler is a Plugin Command Handler which is a part of the NexusDB Transport Architecture. It takes messages from the Command Handler it's attached to and translates them into method calls against the attached PluginEngine, in this case, the RemotingServer.

The job of the Command Handler is to process messages it gets handed by a Transport. Any messages it can't process itself are handed of to the attached Plugin Command Handlers for processing.

TnxSimpleCommandHandler is one of 2 different Command Handlers that ship with NexusDB. As the name implies, it is very simple and does not recognize any messages of it's own. All messages just get forwarded to attached Plugin Command Handlers.

The other Command Handler would be TnxCommandHandler which can be attached to a TnxServerEngine and is used to implement a fully functional NexusDB Database Server.

As this example is only focused on NexusRemoting a TnxSimpleCommandHandler is all that's needed.

One or more transports in Listen Mode can then be connected to the Command Handler, completing the required change of components:

• Transport (Winsock, NamedPipe, SharedMemory, ...)
• Command Handler (Simple or Full)
• Plugin Command Handler (RemotingCommandHandler)
• Plugin Engine (RemotingServer)

While this might appear rather complex at first glance, the system is very flexible and easy to extend with additional Transports or Plugins and it's only necessary to setup this chain of components once for a Server Application.

All that's now missing for a simple server application are 2 buttons to start and stop the server:

And making sure that CalcImpl gets compiled into the application:

Client Application

On the client side 3 components are needed:

• TnxRemotingClient: An implementation of InxClassActivator which sends a message over the Session object it's attached to.
• TnxSimpleSession: The client-side counterpart to TnxSimpleCommandHandler which sends messages to the Command Handler via the the Transport it's attached to.
• A Transport (matching to whatever transport the server is using)

With these 3 components in place it's now easy to call CreateInstance on the RemotingClient to create instances of registered Classes in the Server and retrieve an interface reference to it:

The last missing part is the TfrmCalc which presents a user interface to interact with this interface:

TfrmCalc

As can be seen, this code is very straight forward and does not in any way have to know that the InxCalc it's operating on is a remoted reference to a Class instance in a different process.

Trying it out

The complete example can be found either in in the folder "NexusDB3\Examples\Remoting\Basic" or downloaded for here. There is a project group which directly opens both the Server and Client project.

As the projects are setup to use the Shared Memory Transport it is important under Vista (or newer) to run them elevated. This is a current limitation of the Shared Memory Transport and does not affect the Winsock or Named Pipe transport.

After compiling both Server and Client, first start the Server.exe and click on "Start Server", then start Client.exe and click on "Open Calc".

It is now possible to enter numbers in the edit on the left and perform one of the 4 operations by clicking one of the buttons on the right of the edit. The button labeled "Result" retrieves the current result and displays it in the edit on the right of it.

As the Calculator Form has not been opened modal, it is possible to click "Open Calc" multiple times, each time a new instance of TnxCalc will be created and a new TfrmCalc will be opened. It is possible to clearly see that the different Calculator Forms are each connected to an independent instance by performing operations in different Forms and seeing that only the result of that specific Form is affected.

More to come...

This post demonstrated the structure of a basic remoting server and client application. In future posts I'll explore the possibilities of two-way communication and the effect of using different types of Class Factories.