Realm Federation

A Universal Messaging Realm is an instance of the server and a container for resources. Each Universal Messaging Realm defines a namespace of its own but it is possible to merge the namespaces of multiple Realms into one large one. This is known as realm federation.

Note: Clustering and Realm Federation are mutually exclusive. If a realm is a member of a cluster, you cannot use the realm for federation. Similarly, if a realm is part of a federation, the realm cannot be used for clustering.

While adding a Universal Messaging Realm into the namespace of another, there is one compulsory options and two optional. The compulsory option is the RNAME of that Realm. The optional parameter is the mount point that the Realm should be added in the existing Realm.

If you are specifying the name of the Realm you are adding it should be specified exactly as it appears in the Enterprise Manager. It appears adjacent to the globe icon specifying the realm to which this realm is being added.

A Universal Messaging Realm can also be added to another Realm's namespace using the Enterprise Manager (see Realm Federation).

A Realm is added into the namespace of another programmatically as follows.

//Create an instance of the Universal Messaging Realm object to be added
String rname = "nsp://remoteHost:9002";
nRealm nr = new nRealm( realmName, rname);

//Set the mountpoint in the local realm's Namespace
nr.setMountPoint( mountPnt );

//Add the remote realm to the local one.
//assuming mySession has already been connected to your local realm
mySession.addRealm( nr );

//Create an instance of the Universal Messaging Realm object to be added
string rname = "nsp://remoteHost:9002";
nRealm* nr = new nRealm( realmName, rname);

//Set the mountpoint in the local realm's Namespace
nr->setMountPoint( mountPnt );

//Add the remote realm to the local one.
//assuming mySession has already been connected to your local realm
mySession->addRealm( nr );

You can then provide filters for channel joins across the multiple realms you have added to the namespace. This allows you to ensure that events are routed to the correct channel based on the content of the event.

Note: For a description of the general principles involved in creating channel joins, see the section Creating Channel Joins. The description details the usage based on the Enterprise Manager, but the same general principles apply if you are using the API.

For example, if channel1 on Realm1 is joined to channels channel2, channel3, channel4, channel5 on realms Realm2, Realm3, Realm4, Realm5, and each event is published using an nEventProperties dictionary that contains a key called 'DESTINATION'.

If each channel join from channel1 is created with a filter, for example for the join from channel1 to channel2 on Realm2 the filter would be:

DESTINATION='realm2'

This guarantees only those events that are published to channel1 and that contain 'realm2' in the 'DESTINATION' key will be published to channel2 on Realm2.

For further example code demonstrating adding Universal Messaging Realms to a names space please see the addRealm example.