Universal Messaging 10.3 | Concepts | Clustered Server Concepts | Working with an Active/Active Cluster | Client Connection
 
Client Connection
A Universal Messaging client, whether using the Universal Messaging API or JMS, accesses Universal Messaging realms and their resources through a custom URL called an RNAME. When accessing resources in a cluster, clients use a comma separated array of RNAMEs. This comma separated array can be given to the client dynamically when the client connects to any member of a cluster. If a connection is terminated unexpectedly, the Universal Messaging client automatically uses the next RNAME in its array to carry on.
For example, if we have a cluster consisting of 3 realms, your nSession object can be constructed using the 3 RNAME URLs associated with each of the realms in the cluster.
Once connected to a realm in a cluster, you can then obtain references to nChannel and nQueue objects (or in JMS, create a Session followed by a topic or queue).
Each event/message within Universal Messaging is uniquely identified by an event ID regardless of whether it is stored on a channel, topic or queue. A clustered channel, topic or queue guarantees that every event published to it via any realm within the cluster will be propagated to every other realm in the cluster and will be identified with the same unique event ID. This enables clients to seamlessly move from realm to realm after disconnection and ensure that they begin from the last event consumed based on this unique event ID.
For scenarios where failover is handled at the network level, Universal Messaging sessions can be moved to alternate realms transparently without the use of multiple RNAMEs.
Client Failover Using Multiple RNAMEs
Using an array of RNAME URLs allows client applications to seamlessly fail over to different cluster realms without the use of any third party failover software.
For example, in a three realm clustered scenario, a client's RNAME string may contain the following RNAME URLs:
nsp://host1:9000,nsp://host2:9000,nsp://host3:9000
When we first connect, the first RNAME (in this example, nsp://host1:9000) will be used by the session, and the client application will connect to this realm. However, should we disconnect from this realm, for example if host1 crashes, the client API will automatically reconnect the client application to the cluster member found at the next RNAME in the list (in this example, nsp://host2:9000).
The "Follow the Master" feature
The follow the master feature allows you to configure a client session so that it is always connected to the master realm in a cluster (the client will follow the master). This means that if a client is initially connected to the master realm, and then the master realm becomes unavailable, the client API will automatically reconnect the client application to the new master realm of the cluster.
Using the Universal Messaging client API for Java, this behavior can be configured through the method setFollowTheMaster of the nSessionAttributes class (Universal Messaging client API), or in the JMS ConnectionFactory. The default configuration is that the client will not follow the master.
You can also configure the client to follow the master by setting the system property FollowTheMaster on the client side when you start your client application. To do this, use "-DFollowTheMaster=true" on the command line. Alternatively, you can invoke java.lang.System.setProperty("FollowTheMaster", "true") in your client application code.
When a realm (let's call it realm A), that is currently not the master, receives a client connection request with follow the master enabled, realm A will request the current master (let's call it realm B) to send a list of interfaces that the client can use to connect to realm B. When realm B builds the list of interfaces that the client can connect to, it checks that each such interface has the attributes Advertise Interface and Allow Client Connections enabled before adding it to the list being sent back to the client. The combination of these two attributes on an interface allows clients to access the realm via the interface.
If you have an interface that you want to use exclusively for realm-to-realm communication in the cluster (thereby disabling client-to-cluster communication on the interface), it is recommended to disable the Allow Client Connections attribute, as this will stop all connections except for realm-to-realm communication. This setup leads to added transparency about which client or realm is connected to which interface. You might also want to consider adding firewall rules that protect connections using non-SSL interfaces, so that only known clients (and the other cluster realms) can use such interfaces.
Note:
If a client has activated the "Follow the Master" behavior by use of any of the above mentioned techniques, the protocols (nsp, nsps, etc.) in the RNAME list used by the client for the initial connection will not necessarily be the same protocols that will be offered following a redirect to a newly elected master realm. For example, if the realms in the cluster all offer both nsp and nsps interfaces, it is possible for a client to be offered an nsp interface of a newly elected master realm even if the RNAME list the client used only contained nsps RNAMEs. This may not be what the client intended and in some cases may open a potential security risk.
See the section Interface Configuration in the Administration Guide for information about interface attributes. See also Separating Client and Cluster Communication for related information.