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. Subscribers can be configured to get callbacks which contain either the entire event or just the changed key(s). Either way, only the key(s) that have changed are delivered to the subscribing 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 implements nEventListener in the usual way and does not need to do anything different in order to receive either event deltas or snapshots containing the result of one or more merge operations. The standard nEventListener will receive a full event when the subscription is initiated. Thereafter it will receive only deltas. If at any time the user is disconnected then it will receive a fresh update of the full event on reconnection - followed by a resumption of delta delivery.

If you wish to differentiate between snapshot events and delta events then the nConsumeEvent attributes can be used as follows: