Channel Joins

Joining a channel to another channel or queue allows you to set up content routing so that events published to the source channel will be passed on to the destination channel/queue automatically. Joins also support the use of filters, thus enabling dynamic content routing.

Please note that while channels can be joined to both channels and queues, queues cannot be used as the source of a join.

Channels can be joined using the Enterprise Manager GUI or programmatically.

When creating a join there is one compulsory option and two optional ones. The compulsory option is the destination channel. The optional parameters are the maximum join hops and a filter to be applied to the join.

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

Joins have an associated hop count, which can optionally be defined when the join is created. The hop count allows a limit to be put on the number of subsequent joins an event can pass through if published over this join. If a hop count is not defined for a join, it will default to 10.

The hop count is the number of intermediate stores between the source channel and the final destination. As an example, imagine we have 10 channels named "channel0" to "channel9" and all these channels are joined sequentially. When we publish to channel 0, if the join from channel0 to channel1 has a hop count of 5 then the event will be found on channel0 (the source channel), channels 1 to 5 (the intermediate channels) and channel6 (the endpoint).

Joins allow the possibility of defining a loop of joined channels. To prevent channels receiving multiple copies of the same event, Universal Messaging implements loop detection on incoming events. To illustrate this, imagine a simple example with two channels (channel0 and channel1) and we create a loop by joining channel0 to channel1 and channel1 to channel0. If we publish to channel0 the event will also be published to channel1 over the join. But channel1 is joined to channel0 too, so now the event would get published to channel0 again. Without loop detection, this cycle would repeat until the maximum hop count has been reached.

To prevent this, Universal Messaging detects when a message which has already been published to a channel or queue and will not publish it a second time.

Universal Messaging users can define multiple paths over different network protocols between the same places in Universal Messaging. Universal Messaging guarantees that the data always gets delivered once and once only.

Channel joins can be created using the nmakechanjoin join sample application which is provided in the bin directory of the Universal Messaging installation. For further information on using this example please see the Make Channel Join example page.

Universal Messaging joins are created as follows:

//Obtain a reference to the source channel
nChannel mySrcChannel = mySession.findChannel( nca );

//Obtain a reference to the destination channel
nChannel myDstChannel = mySession.findChannel( dest );

//create the join
mySrcChannel.joinChannel( myDstChannel, true, jhc, SELECTOR );

Channel joins can also be deleted. Please see the Delete Channel Join example for more information.

It is possible to archive messages from a given channel by using an archive join. To perform an archive join, the destination must be a queue in which the archived messages will be stored. An example of this can be seen below:

Since this is an archive join, all events matching the optional selector parameter(all events if no selector is specified) will be put into the archive queue, by design this includes all duplicate events published to the source.

nChannelAttributes archiveAtr = new nChannelAttributes();
archiveAtr.setName(rchanName);
nQueue archiveQueue = mySession.findQueue(archiveAtr);
mySrcChannel.joinChannelToArchive(archiveQueue);

Inter-cluster joins are added and deleted in almost exactly the same way as normal joins. The only differences are that the two clusters must have an inter-cluster connection in place, and that since the clusters do not share a namespace, ech channel must be retrieved from nodes in their respective clusters, rather than through the same node. For example :

nChannel cluster1chan1 = realmNode1.findChannel(channelattributes1);
nChannel cluster2chan1 = realmNode4.findChannel(channelattributes2);
cluster1chan1.joinChannel(cluster2chan1);

Inter-Cluster joins can also be created through the Enterprise Manager.

Universal Messaging offers the ability to forward data received on one independent realm or cluster to many other independent realms or clusters, which may reside in geographically distinct locations. Traditionally this is done using the Join mechanism, which will forward all events from one channel to another.

There is an alternative mechanism, namely Interest Propagation. This mechanism expands upon the functionality provided by joins by providing the ability to forward events only when there are subscribers to a channel of the same name on the remote realm or cluster. Forwarding only events which have an active subscription reduces the number of events and bandwidth used on these links.

Realms and clusters keep track of interest on remote realms that they have a direct connection to. This means that beyond the initial setup of a channel, no further configuration is required.

Managing interest on a remote realm is done programmatically using the Universal Messaging Administrative API. Each channel present on a realm or cluster can be linked to a pair of attributes canSend and canReceive.

Enabling the canReceive attribute on a channel of a realm or cluster will enable this realm or cluster to receive information on the given channel from other directly connected realms or clusters that have a channel of the same name. The realm or cluster notifies all connected realms when this attribute changes for a given channel.

Data is only forwarded from a realm or cluster to a remote realm or cluster if all of the following conditions are met:

Enabling the canSend attribute on a channel in a realm or cluster will enable this realm or cluster to begin forwarding data to other realms or clusters it is aware of. Data is forwarded to every realm which the source realm is aware of that has a channel with the same name and is able to receive the event (it has the canReceive flag enabled and has an interested subscriber).

All installations of Universal Messaging come with a sample application called interestmanagerutility. This is an application which takes a series of commands to manage the interest properties for a given set of realms.