Orbeon Forms
Search…
Replication

Availability

This is an Orbeon Forms PE feature.
This feature is available since Orbeon Forms 2017.2. It has been tested with the following software:
  • Apache Tomcat 8.0.45
  • HAProxy 1.7.4
We also have reports of this feature working with OpenLiberty and Hazelcast session replication.

Introduction

The purpose of replication is to provide high-availability of Orbeon Forms with as little disruption as possible to users currently filling out forms. This is achieved by replicating state between servers.
Consider a simple scenario of load balancing with two servers, with sticky sessions (that is, a given user's requests always reach the same server). If one of the servers fails, new users will be assigned to the other server. So the system remains operational from that point of view. However, users with active sessions will have their current work lost, as the content will still in the failed server-memory.
Replication changes that by replicating state to one or more additional servers. So if a server goes down, the load balancer can redirect users with active sessions to other servers, and because state was replicated there, users can continue their work.

Architecture

Orbeon Forms achieves replication by enabling the replication of servlet sessions and of caches. All current state in memory, whether in the session or relevant caches, is replicated so that work can be resumed on replica servers when needed.
Sessions are still sticky for performance reasons. Because Orbeon Forms stores a lot of information in memory, and there are data structures associated with that information, there is a cost to recreate all necessary data structures at each request. Therefore, requests for a given user must constantly reach the same server. However, if a server fails, then there is a one-time cost to recreating data structures on the new server for the given user (in fact, for a given form in use by that user).
Servers must be able to communicate via IP multicast. This means that they must typically be on the same network, physical or virtual.
A load balancer is required. It is in charge of proxying client requests to specific servers, detect which servers might have failed or are being brought back, and ensuring session affinity.
Replication architecture

Configuration

Orbeon Forms configuration

Properties

Orbeon Forms has a single property enabling replication:
1
<property
2
as="xs:boolean"
3
name="oxf.xforms.replication"
4
value="true"/>
Copied!
By default, this property is set to false, because there is a cost to serializing the state of forms after each update in memory.
In addition you might need to set the following property to point to the local Orbeon Forms instance without going through the load balancer:
1
<property
2
as="xs:anyURI"
3
name="oxf.url-rewriting.service.base-uri"
4
value="http://localhost:8080/orbeon"/>
Copied!

web.xml

The application's web.xml must contain:
1
<distributable/>
Copied!
In addition, the ReplicationServletContextListener must be enabled. This is the case by default in the web.xml that ships with Orbeon Forms.

Ehcache

The Orbeon Forms WEB-INF/resources/config/ehcache.xml must be modified to included replication settings, which are turned off by default. This is similar to Tomcat session replication.
NOTE: There isn't as single set of settings to replicate the Tomcat servlet session and Ehcache, as the two products use different libraries for replication. But the idea is that both configuration should behave as closely as possible from each other.
The keys to this configuration are:
  • for relevant caches
    • RMICacheReplicatorFactory as <cacheEventListenerFactory>
    • RMIBootstrapCacheLoaderFactory as <bootstrapCacheLoaderFactory>
  • global
    • RMICacheManagerPeerProviderFactory as <cacheManagerPeerProviderFactory>
    • RMICacheManagerPeerListenerFactory as <cacheManagerPeerListenerFactory>
Here is an example configuration:
1
<ehcache updateCheck="false" monitoring="off" dynamicConfig="true">
2
3
<!-- Where the disk store will go -->
4
<diskStore path="java.io.tmpdir/orbeon/cache"/>
5
6
<!-- Default cache (not used by Orbeon) -->
7
<defaultCache
8
maxElementsInMemory="10000"
9
eternal="false"
10
timeToIdleSeconds="120"
11
timeToLiveSeconds="120"
12
overflowToDisk="true"
13
diskSpoolBufferSizeMB="30"
14
maxElementsOnDisk="10000000"
15
diskPersistent="false"
16
diskExpiryThreadIntervalSeconds="120"
17
memoryStoreEvictionPolicy="LRU"
18
statistics="false"/>
19
20
<!-- XForms state store configuration. Only modify if you know what you are doing! -->
21
<!-- NOTE: We set this as a disk cache, but follow the Ehcache doc and set maxElementsInMemory to 1 instead of 0. -->
22
<cache name="xforms.state"
23
maxElementsInMemory="1"
24
memoryStoreEvictionPolicy="LFU"
25
overflowToDisk="true"
26
diskSpoolBufferSizeMB="10"
27
eternal="false"
28
timeToLiveSeconds="0"
29
timeToIdleSeconds="18000"
30
diskPersistent="false"
31
maxElementsOnDisk="0"
32
diskExpiryThreadIntervalSeconds="120">
33
34
<cacheEventListenerFactory
35
class="net.sf.ehcache.distribution.RMICacheReplicatorFactory"
36
properties="replicateAsynchronously=false"/>
37
38
<bootstrapCacheLoaderFactory
39
class="net.sf.ehcache.distribution.RMIBootstrapCacheLoaderFactory"
40
properties="bootstrapAsynchronously=false"/>
41
</cache>
42
43
<!-- XForms resources. Only modify if you know what you are doing! -->
44
<cache name="xforms.resources"
45
maxElementsInMemory="200"
46
memoryStoreEvictionPolicy="LFU"
47
overflowToDisk="true"
48
diskSpoolBufferSizeMB="1"
49
eternal="true"
50
timeToLiveSeconds="0"
51
timeToIdleSeconds="0"
52
diskPersistent="false"
53
maxElementsOnDisk="0"
54
diskExpiryThreadIntervalSeconds="120">
55
56
<cacheEventListenerFactory
57
class="net.sf.ehcache.distribution.RMICacheReplicatorFactory"
58
properties="replicateAsynchronously=false"/>
59
60
<bootstrapCacheLoaderFactory
61
class="net.sf.ehcache.distribution.RMIBootstrapCacheLoaderFactory"
62
properties="bootstrapAsynchronously=false"/>
63
64
</cache>
65
66
<cacheManagerPeerProviderFactory
67
class="net.sf.ehcache.distribution.RMICacheManagerPeerProviderFactory"
68
properties="
69
peerDiscovery=automatic,
70
multicastGroupAddress=228.0.0.5,
71
multicastGroupPort=4446,
72
timeToLive=1"
73
/>
74
75
<cacheManagerPeerListenerFactory
76
class="net.sf.ehcache.distribution.RMICacheManagerPeerListenerFactory"/>
77
78
</ehcache>
Copied!
When using a firewall:
  1. 1.
    The multicastGroupPort port might need an UDP firewall unlock.
  2. 2.
    If you don't specify ports for <cacheManagerPeerListenerFactory>, the ports are chosen at random and might be blocked by the firewall. You can specify explicit ports to address this:
    1
    <cacheManagerPeerListenerFactory
    2
    class="net.sf.ehcache.distribution.RMICacheManagerPeerListenerFactory"
    3
    properties="
    4
    port=4501,
    5
    remoteObjectPort=4502"
    6
    />
    Copied!

Servlet container configuration

The servlet container must be configured to replicate the session information.
With Tomcat, this is done in server.xml within the <Engine> element:
1
<Cluster
2
className="org.apache.catalina.ha.tcp.SimpleTcpCluster"
3
channelSendOptions="6">
4
5
<Manager
6
className="org.apache.catalina.ha.session.DeltaManager"
7
expireSessionsOnShutdown="false"
8
notifyListenersOnReplication="true"/>
9
10
<Channel className="org.apache.catalina.tribes.group.GroupChannel">
11
<Membership
12
className="org.apache.catalina.tribes.membership.McastService"
13
address="228.0.0.4"
14
port="45564"
15
frequency="500"
16
dropTime="3000"/>
17
18
<Receiver
19
className="org.apache.catalina.tribes.transport.nio.NioReceiver"
20
address="auto"
21
port="5000"
22
selectorTimeout="100"
23
maxThreads="6"/>
24
25
<Sender className="org.apache.catalina.tribes.transport.ReplicationTransmitter">
26
<Transport className="org.apache.catalina.tribes.transport.nio.PooledParallelSender"/>
27
</Sender>
28
29
<Interceptor className="org.apache.catalina.tribes.group.interceptors.TcpFailureDetector"/>
30
<Interceptor className="org.apache.catalina.tribes.group.interceptors.MessageDispatchInterceptor"/>
31
<Interceptor className="org.apache.catalina.tribes.group.interceptors.ThroughputInterceptor"/>
32
</Channel>
33
34
<Valve
35
className="org.apache.catalina.ha.tcp.ReplicationValve"
36
filter=".*\.gif|.*\.js|.*\.jpeg|.*\.jpg|.*\.png|.*\.htm|.*\.html|.*\.css|.*\.txt"/>
37
38
<ClusterListener className="org.apache.catalina.ha.session.ClusterSessionListener"/>
39
</Cluster>
Copied!
In that configuration, the following can be changed:
  • the IP multicast address, here address="228.0.0.4"
  • the IP multicast port, here port="45564
For details about the Tomcat configuration, see Clustering/Session Replication HOW-TO.

Load balancer configuration

With HAProxy, a simple configuration looks like this:
1
global
2
daemon
3
maxconn 256
4
debug
5
6
defaults
7
mode http
8
timeout connect 5000ms
9
timeout client 50000ms
10
timeout server 50000ms
11
12
frontend http-in
13
bind *:8080
14
default_backend servers
15
16
backend servers
17
cookie JSESSIONID prefix nocache
18
server s1 127.0.0.1:8888 maxconn 32 cookie s1 check
19
server s2 127.0.0.1:8889 maxconn 32 cookie s2 check
Copied!
This configuration round-robins between two servers, s1 and s2, on two ports, 8888 and 8889.
In this example, the servers are accessed at address 127.0.0.1, but in practice they might be on different physical servers.
For testing, you can start HAProxy with the following command:
1
haproxy -db -f haproxy.conf
Copied!
For details about the HAProxy configuration, see the HAProxy Configuration Manual.

Other considerations

Individual server load

Consider a scenario where you have two servers with replication enabled, and one of them fails. This means that users from the failed server are redirected by the load balancer to the server which is still working. If, at the time of failure, both servers were nearing their full capacity, then suddenly the only remaining server will have to handle all the load.
This means that the load balanced servers should not be allowed to reach full capacity so that, in case of failure of a single server, the remaining server can handle all the load. Theoretically, this means that each server, in normal use, should be at under 50 % of total capacity.
Using more than 2 replicated servers allows using more of the available capacity of all servers in the case of a single server failure.

Limitations

Uploaded files

Uploaded files which are not yet saved to a database are currently not replicated. If a use is switched from one server to another, Form Runner:
  • checks all unsaved attachments
  • if there are any
    • clears the associated temporary file path
    • shows an alert to the user
This requires users with unsaved attachments to re-upload their attachments. This is not ideal but it is likely that the user still have the attachment or attachments available.

Loss of state

If a server fails instantly before it had the chance to replicate the latest modifications to a form, and after an Ajax response has been sent to the client, then state might be lost. The user is redirected by the load balancer to another server, but state will be missing from that server. In such cases, the user will see an error, and won't be able to continue working with the form. Unsaved data will be lost.
In such cases, enabling the autosave feature can alleviate the issue.
The ehcache.xml configuration provided above attempts to minimize this kind of issues by adding replicateAsynchronously=false.
NOTE: We have feedback from customers that if manual peer discovery (RMI TCP unicast) is enabled, setting replicateAsynchronously="true" works and helps reduce latency.

See also

Last modified 1mo ago