Managing DataGroup Membership
DataGroups are extremely lightweight from both client and server perspectives; a back-end process, such as a Complex Event Processing engine, can simply create DataGroups and then add or remove users (or even entire nested DataGroups) based on bespoke business logic. A user who is removed from one DataGroup and added to another will continue to receive events without any interruption to service, or indeed explicit awareness that any DataGroup change has occurred.
This page details some of the typical operations that DataGroup management process would carry out.
Please see our C++ sample apps for more detailed examples of DataGroup management.
Tracking Changes to DataGroup Membership (DataGroupListener)
The nDataGroupListener interface is used to provide asynchronous notifications when nDataGroup membership changes occur. Each time a user (nDataStream ) or nDataGroup is added or removed from a nDataGroup a callback will be received.
public class datagroupListener : public nDataGroupListener {
nSession* mySession;
public datagroupListener(nSession session){
mySession = session;
//add this class as a listener for all nDataGroups on this Universal
// Messaging realm
mySession->getDataGroups(this);
}
////
//DataGroupListener Implementation
///
public void addedGroup (nDataGroup* to, nDataGroup* group, int count){
//Called when a group has been added to the 'to' data group.
//count is the number of nDataStreams that will receive any events
//published to this nDataGroup
}
public void addedStream (nDataGroup* group, nDataStream* stream, int count){
//Called when a new stream has been added to the data group.
}
public void createdGroup (nDataGroup* group){
//Called when a group has been created.
}
public void deletedGroup (nDataGroup* group){
//Called when a group has been deleted.
}
public void deletedStream (nDataGroup* group, nDataStream* stream, int count,
bool serverRemoved){
//Called when a stream has been deleted from the data group.
//serverRemoved is true if the nDataStream was removed because of flow control
}
public void removedGroup (nDataGroup* from, nDataGroup* group, int count){
//Called when a group has been removed from the 'from' data group.
}
}
There are three ways in which the nDataGroupListener can be used:
Listening to an individual DataGroup
Listeners can be added to individual DataGroups when they are created or at any time after creation. The code snippets illustrate both approaches:
mySession->createDataGroup(dataGroupName, datagroupListener);
myDataGroup->addListener(datagroupListener);
Listening to the Default DataGroup
The Default nDataGroup is a DataGroup to which all nDataStreams are added by default. If you add a DataGroupListener to the default DataGroup then callbacks will be received when:
a nDataStream is connected/disconnected
a nDataGroup is created or deleted
Listening to all DataGroups on a Universal Messaging Realm
The code snippet below will listen on all nDataGroups (including the default DataGroup).
mySession->getDataGroups(datagroupListener);
Adding and Removing DataGroup Members
The nDataGroup class provides various methods for adding and removing nDataStreams and nDataGroups. Please see the nDataGroup API documentation for a full list of methods. Examples of some of these are provided below:
//Add a nDataStream (user) to a nDataGroup
public void addStreamToDataGroup(nDataGroup* group, nDataStream* user){
group->add(user);
}
//Remove a nDataStream (user) from a nDataGroup
public void removeStreamFromDataGroup(nDataGroup* group, nDataStream* user){
group->remove(user);
}
//Add a nDataGroup to a nDataGroup
public void addNestedDataGroup(nDataGroup* parent, nDataGroup* child){
parent->add(child);
}
//Remove a nDataGroup from a nDataGroup
public void removeNestedDataGroup(nDataGroup* parent, nDataGroup* child){
parent->remove(child);
}