21.2. Failover Cluster
Overview
A failover cluster in Fuse Fabric is based on an ordered list of WS endpoints that are registered under a particular node in the fabric registry. A client detects the failure of a master endpoint by catching the exception that occurs when it tries to make an invocation. When that happens, the client automatically moves to the next available endpoint in the cluster.
Failover cluster
Figure 21.2, “Fabric Failover for Apache CXF” gives an overview of the fabric failover mechanism for Apache CXF endpoints.
Figure 21.2. Fabric Failover for Apache CXF
In this example, two WS servers are created, with the URIs,
http://localhost:8185/Foo and http://localhost:8186/Foo. In both servers, the failover feature is configured to store the cluster endpoints under the path, demo/fo, in the fabric registry. The cluster endpoints stored under demo/fo are ordered. The first endpoint in the cluster is the master and all of the other endpoints are slaves.
The failover algorithm works as follows:
- When the WS client starts, it is configured to look up the cluster path,
demo/fo, in the fabric registry. The failover feature initially returns the first address registered underdemo/fo(the master). - At some point, the master server could fail. The client determines whether the master has failed by catching the exception that occurs when it tries to make an invocation: if the caught exception matches one of the exceptions in a specified list (by default, just the
java.io.IOException), the master is deemed to have failed and the client now ignores the corresponding address entry underdemo/fo. - The client selects the next address entry under
demo/foand attempts to connect to that server. Assuming that this server is healthy, it is effectively the new master. - At some point in the future, if the failed old master is restarted successfully, it creates a new address entry under
demo/foafter the existing entries, and is then available to clients, in case the other server (or servers) fail.
FabricFailOverFeature
The fabric failover feature is implemented by the following class:
io.fabric8.cxf.FabricFailOverFeature
The
FabricFailOverFeature class exposes the following bean properties:
-
fabricPath - This property specifies a node in the fabric registry (specified relative to the base node,
/fabric/cxf/endpoints) that is used to store the data for a particular endpoint cluster. -
curator - A proxy reference to the OSGi service (of type,
org.apache.curator.framework.CuratorFramework) for the Apache Curator client, which is exposed by the fabric agent. -
maximumConnectionTimeout - The maximum length of time to attempt to connect to the fabric agent, specified in milliseconds. The default is 10000 (10 seconds).
-
connectionRetryTime - How long to wait between connection attempts, specified in milliseconds. The default is 100.
-
exceptions - A semicolon-separated list of exceptions that signal to the client that a server has failed. If not set, this property defaults to
java.io.IOException.For example, you could set theexceptionsproperty to a value like the following:java.io.IOException;javax.xml.ws.soap.SOAPFaultException
Blueprint XML
The configuration of WS servers and WS clients in the failover case is similar to the load balancing case (see Section 21.1.2, “Configure the Server” and Section 21.1.3, “Configure the Client”), except that instead of instantiating and referencing a
FabricLoadBalancerFeature bean, you must instantiate and reference a FabricFailOverFeature bean.
In blueprint XML you can create a
FabricFailOverFeature bean instance as follows:
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
...
xmlns:cxf="http://cxf.apache.org/blueprint/core"
...
>
...
<!-- Reference the fabric agent -->
<reference id="curator"
interface="org.apache.curator.framework.CuratorFramework" />
<!-- Create the Fabric load balancer feature -->
<bean id="failoverFeature"
class="io.fabric8.cxf.FabricFailOverFeature">
<property name="curator" ref="curator" />
<property name="fabricPath" value="ZKPath" />
</bean>
...
</blueprint>
Remember to customise the value of the
fabricPath property and to reference the appropriate bean ID (failoverFeature in the preceding example).
