5.6.2.2. Configuring Interaction between Middleware Servers

Middleware servers can maintain shared lists of user sessions and other objects and coordinate invalidation of caches. The cuba.cluster.enabled property should be enabled on each server to achieve this. An example of the app_home/local.app.properties file is shown below:

cuba.cluster.enabled = true

cuba.webHostName = host3
cuba.webPort = 8080

For the Middleware servers, correct values of the cuba.webHostName and cuba.webPort properties should be specified to form a unique Server ID.

Interaction mechanism is based on JGroups. The platform provides two configuration files for JGroups:

  • jgroups.xml - a UDP-based stack of protocols which is suitable for local network with enabled broadcast communication. This configuration is used by default when the cluster is turned on.

  • jgroups_tcp.xml - TCP-based stack of protocols which is suitable for any network. It requires explicit setting of cluster members addresses in TCP.bind_addr and TCPPING.initial_hosts parameters. In order to use this configuration, set cuba.cluster.jgroupsConfig application property.

    If there is a firewall between your middleware servers, don’t forget to open firewall ports according to your JGroups configuration.

In order to set up JGroups parameters for your environment, copy the appropriate jgroups.xml file from the root of cuba-core-<version>.jar to the source root of your project’s core module (the src folder) or to tomcat/conf/app-core and modify it.

ClusterManagerAPI bean provides the program interface for interaction between servers in the Middleware cluster. It can be used in the application – see JavaDocs and usages in the platform code.

Synchronous replication of user sessions

By default all JGroups messages are sent to the cluster asynchronously. It means that middleware code returns response to the client layer before the moment when the cluster message is received by other cluster members.

Such behavior improves response time of the system, however it can cause problems with load balancers that route requests between client layers and middleware and use round-robin strategy (such as NGINX or Kubernetes). That is: login request from web client returns earlier than new user session is fully replicated to other cluster members. Subsequent middleware call from web client layer can be directed by the round-robin strategy to the other middleware node where it will fail with NoUserSessionException because the user session hasn’t been received by this cluster member yet.

To avoid NoUserSessionException errors when using round-robin balancer with middleware cluster, new user sessions created on login should be replicated synchronously. Set these properties in the app.properties (or app_home/local.app.properties on the target server) file:

cuba.syncNewUserSessionReplication = true

# also if you use REST API add-on
cuba.rest.syncTokenReplication = true