The Merge Engine and Event Deltas

In order to streamline publish/subscribe applications it is possible to deliver only the portion of an event's data that has changed rather than the entire event. These event deltas minimise the amount of data sent from the publisher and ultimately delivered to the subscribers.

The publisher simply registers an event and can then publish changes to individual keys within the event. The subscriber will receive a full event on initial subscription, which contains the most up to date state of the event. After the initial message, only the key/value pairs which have changed since the last message will be sent to the client.

In order to publish event deltas the publisher uses the Registered Event facility available on a Universal Messaging Channel. Please note that the channel must have been created with the Merge Engine and it must have a single Publish Key. The publish key represents the primary key for the channel and the registered events. So for example if you are publishing currency rates you would setup a channel as such

nChannelAttributes* cattr
= new nChannelAttributes("RatesChannel", 0, 0, nChannelAttributes.SIMPLE_TYPE);
//
// This next line tells the server to Merge incoming events based on the publish
// key name and the name of the registered event
//
cattr->useMergeEngine(true);
//
// Now create the Publish Key (See publish Keys for a full description
//
nChannelPublishKeys** pks = new nChannelPublishKeys[1];
pks[0] = new nChannelPublishKeys("ccy", 1);
cattr->setPublishKeys(pks);
//
// Now create the channel
//
myChannel = mySession->createChannel(cattr);

At this point the server will have a channel created with the ability to merge incoming events from Registered Events. The next step is to create the Registered events at the publisher.

nRegisteredEvent* audEvent = myChannel->createRegisteredEvent("AUD");
nEventProperties* props = audEvent->getProperties();
props->put("bid", 0.8999);
props->put("offer", 0.9999);
props->put("close", "0.8990");
audEvent->commitChanges();

You now have a nRegisteredEvent called audEvent which is bound to a ccy value of "AUD". We then set the properties relevant to the application, finally we call commitChanges(), this will send the event, as is, to the server. At this point if the bid was to change then that individual field can be published to the server as follows:

props->put("bid", 0.9999);
audEvent->commitChanges();

This code will send only the new "bid" change to the server. The server will modify the event internally so that any new client subscribing will receive all of the data, yet any existing subscribers will only receive the change.

The subscriber doesn't need to do anything different to receive these events. The standard nEventListener will appear to receive full events with all keys and data even though only the changed keys were transmitted. The events are reassembled on the client and are updated locally such that the subscriber receives the usual callback from the server.

If the client only wants to process the changes then they can choose to implement the nRegisteredEventListener interface rather than the nEventListener interface. The nRegisteredEventListener, has an update() method in addition to the usual go() method. The update method will be called whenever an update has been published.