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

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:
  1. 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 under demo/fo (the master).
  2. 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 under demo/fo.
  3. The client selects the next address entry under demo/fo and attempts to connect to that server. Assuming that this server is healthy, it is effectively the new master.
  4. At some point in the future, if the failed old master is restarted successfully, it creates a new address entry under demo/fo after 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 the exceptions property 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).