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.

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.

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 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.

Note:
If the realm configuration property ClusterMode (available in the Cluster Config property group) is specified as "Replication", the system property FollowTheMaster on the client side will be ignored. See the section Cluster Modes below for details.

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.

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".

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.

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.

If you are using C# or C++ client version 10.3 or 10.5, make sure that the client is upgraded with the latest client libraries before enabling Replication mode. Also, C#/C++ clients in v10.1 and earlier cannot make use of the feature.

Universal Messaging client APIs for C# and C++ in v10.3 and v10.5 will require an upgrade to the following fix levels to be able to work properly in the Replication cluster mode:

Java clients in versions earlier than v10.7 can connect to a server where the Replication cluster mode is configured. However, we recommend upgrading to the fix levels mentioned above since they have some optimizations with regard to the feature.

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 at Realm Configuration in the Administration Guide.