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.
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 Basic Attributes for an Interface in the Administration Guide for information about interface attributes. See also Separating Client and Cluster Communication for related information.
Cluster Modes
You can specify whether non-admin clients are allowed to connect to nodes other than the master node in a cluster using a cluster mode configuration that is set by the ClusterMode realm server property. This property can have the value "Replication" or "Active".
Admin clients can connect to both master and non-master nodes, irrespective of the ClusterMode configuration.
- Cluster mode: "Replication"
If ClusterMode is set to "Replication", non-admin client connections can be made to only the master node in the cluster. In this mode, nodes that are not the master node will reject all non-admin connections.
If a non-admin client is initially connected to the master realm, and then the master realm becomes unavailable, the client will be disconnected from the server. If you are using Universal Messaging client APIs to establish the connection, the client will automatically reconnect to the new master realm of the cluster.
In Replication mode, the RNAME list used by the client for connection purposes must contain the RNAMEs corresponding to all of the nodes in the cluster. The client will attempt to form a connection to the first RNAME in the list, and if the connection is refused because the RNAME is not the RNAME of the master node, the client re-connection logic will automatically try the next RNAME from the session's list. This automatic procedure continues until the correct RNAME for the master node is found, and the connection will take place.
The FollowTheMaster setting on the client side will be ignored if you have set ClusterMode to "Replication".
If Replication mode is enabled, you'll not be able to make use of local resources (e.g. local queues, channels, etc.) that exist in the server nodes that are part of the cluster. Client connections can do operations on the local resources in the master node, but the resources are not accessible when the master is changed to a different node.
- Cluster mode: "Active"
If ClusterMode is set to "Active", which is the default value, client connections can be made to both master and non-master nodes in a cluster. The clients can also make use of the FollowTheMaster configuration, which allows specific clients to connect to only the master node in the cluster.
See also the summary of the ClusterMode property in the list of realm server properties in Realm Configuration.