Design

The next diagrams provide 1) the classes and their relations and 2) the sequence in which classes interact in certain functional flows. It is possible to size the diagrams up when hovering over them with the mouse.

Please make contact in case details are missing.

Messages overview

RpcRequest, RpcResponse and RpcNotification are used at the higher level rpc functionality. Instances of these classes are converted to and from the messages which are used for the communication between the client and the service. The MessageConverter is responsible for this task.

The RpcRequest contains the TargetService which identifies the service at which the request needs to be executed. The TargetMethod contains the method which needs to be executed on the identified service.

The RpcResponse contains the ProcessingResult which provides the result of the processing of the corresponding request.

The RpcNotification contains the CallbackReceiver which identifies the receiver for the notification (also called callback). The CallbackOperation identifies the operation which is invoked on the custom class registered as receiver (more details in the following sequence diagrams).

Client side overview

The ClientManager is the main actor at the client side. It is responsible for getting the requests to the remote side, it manages the pending requests and guards them to ensure they do not time out.

The ServiceAdapterBase is an abstract class providing a way to manage the interaction with one specific service. It provides triggers related to changes in the connection with the remote side which allows related functionality to kick in, for example to subscribe for callbacks automatically when the connection with the service is made or recovered. It also provides a mechanism to automatically retry the call for the remote action or method when the connection is severed.

The EndPoint is used to identify the location of the remote side. It is possible to inherit from this abstract class for a custom implementation. The TcpEndPoint is provided by the framework.

The CommunicationBinding is used to manage the communication channel with the remote side. It is possible to create a custom implementation by inheriting from this abstract class.

The MessageConverter is used to convert the requests, responses and notifications into a binary format which can be communicated back and forth. It is possible to create a custom implementation by inheriting from this abstract class. The DataDictionaryMessageConverter is provided by the framework, it (de)serializes the rpc types via a DataContract serializer.

Service side overview

The RpcServiceHost is responsible for coordinating the rpc functionality and for managing the entry points with which clients can connect. Pending rpc requests (which are being executed on a service) are monitored here to ensure they do not exceed a preconfigured timeout. When this occurs a response is sent back to the original requestor.

The RpcService is an abstract class which can be inherited for the custom service implementation(s).

The CallbackRegistrations is used to manage the remote subscribers for specific callbacks. When a remote subscriber disconnects (either gracefully or forcefully) it is automatically removed from the administration. More details are available in the following sequence diagrams.

Register RPC service

The RpcServiceHost is responsible for managing the provided services. Each available RPC service needs to be registered before it is available for the clients.

Register client endpoint

To provide a point of entry for the clients it is necessary to register an endpoint with which the clients can connect.

TcpEndPoint; used to configure the point of entry (in this case we provide an ip address and a port number).

TcpCommunicationBinding; used for managing the communication channels via TCP/IP with the clients.

DataDictionaryMessageConverter; used for converting the messages back and forth into a format which can be transmitted with the clients.

When RegisterEndPoint is called with these parameters the RpcServiceHost can be reached via this endpoint. It is possible to register multiple endpoints each with a different type of endpoint, communication binding and message converter.

Client requests operation from remote side

The ServiceAdapterBase is provided in the library and it provides some helper mechanisms (for example a retry mechanism when the request fails due to a failure in the communication). It is however possible to directly use the ClientManager. It is possible to create a derived service adapter containing specific operations as they are provided by the remote service. The ClientManager provides a mechanism to call either an action (without actual result from the service) or a method. With this mechanism it is possible to identify the service, the operation and optionally the parameters which need to be passed. Note that ref and out parameters are not supported.

Client requests operation from remote side

To receive callbacks originating from the service side one has to create a class, preferrably implementing an interface in which the callbacks are defined. An instance of this class can then be registered with the ClientManager while providing the type as identifier (preferrably also the before mentioned interface). Information passed with this notification should be packaged in the CallbackArgs class from the framework.

Client configures callback receiver

To receive callbacks originating from the service side one has to create a class, preferrably implementing an interface in which the callbacks are defined. An instance of this class can then be registered with the ClientManager while providing the type as identifier (preferrably also the before mentioned interface). Information passed with this notification should be packaged in the CallbackArgs class from the framework.

Client requests operation from remote side

The client needs to inform the remote side that it wants to receive callbacks. To do that a call has to be made to the remote side (Subscribe is used in this case). This request is received at the remote side after which the service can call Add on the managed instance of the CallbackRegistrations class from the framework. The framework manages (fully transparent) that the corresponding client is added as receiver for the specific callbacks. It is possible to remove a client via the Remove call. The framework also automatically removes subscribers when they disconnect (gracefully and forcefully).

Service fires a callback

When a service needs to fire a callback, for example to report a certain change it used the local instance of the CallbackRegistrations. The identifier for the callback is provided and the argument which needs to be passed onto the subscriber(s). For each client which is subscribed the corresponding client manager receives the callback. The corresponding method on the registered CallbackReceiver is called and the provided CallbackArgs is passed.