To configure clustering, configure JGroups by using the jgroups-tcp.xml file, and configure LiveCycle Data Services ES by using the services-config.xml file.

Configuring JGroups

LiveCycle Data Services ES uses JGroups, an open source clustering platform to implement clustering. By default, a LiveCycle Data Services ES web application is not configured to support JGroups. The jgroups.jar file and the jgroups-*.xml properties files are located in the resources/clustering folder of the LiveCycle Data Services ES installation. Before you can run an application that uses JGroups, copy the jgroups.jar file to the WEB-INF/lib, and copy the jgroups-*.xml files to the WEB-INF/flex directory.

The JGroups configuration file determines how a clustered data service destination on one server broadcasts changes to corresponding destinations on other servers. JGroups supports UDP multicast or TCP multicast to a list of configured peer server addresses. Adobe recommends using the TCP option (TCP and TCPPING options in jgroups-tcp.xml). A unique version of this file is required for each server in the cluster. In the TCP element, use the bind_addr attribute to reference the current server by domain name or IP. In the TCPPING element, you reference the other peer servers.

For example, if the cluster contains four servers, the elements in the first jgroups-tcp.xml config file would look like the following example:

Modified 12/12/2008: Changed data1xd, data2xd, and data3xd to data1, data2, data3.

<TCP bind_addr="64.13.226.47" start_port="7800" loopback="false"/>
<TCPPING timeout="3000" 
    initial_hosts="data1.com[7800],data2.com[7800],data3.com[7800]" 
    port_range="1"
    num_initial_members="3"/>
<FD_SOCK/>
<FD timeout="10000" max_tries="5" shun="true"/>
<VERIFY_SUSPECT timeout="1500" down_thread="false" up_thread="false"/>
<MERGE2 max_interval="10000" min_interval="2000"/>
<pbcast.NAKACK gc_lag="100" retransmit_timeout="600,1200,2400,4800"/>
<pbcast.STABLE stability_
    delay="1000" desired_avg_gossip="20000" down_thread="false"
    max_bytes="0" up_thread="false"/>
<pbcast.GMS 
    print_local_addr="true" join_timeout="5000" join_retry_timeout="2000" shun="true"/>

• The TCP bind_addr and initial_hosts attributes vary for each server in the cluster. The bind_addr property must be set to the IP or DNS name depending on how the /etc/hosts file is set up on that computer.
• The TCPPING initial_hosts setting lists all other nodes in the cluster, not including the node corresponding to the configuration file. Set the num_initial_members to the number of other nodes in the cluster.
• The FD (Failure Detection) setting specifies to use sockets to other nodes for failure detection. This node does not consider other nodes to be out of the cluster unless the socket to the node is closed.

For information about JGroups, see http://www.jgroups.org/javagroupsnew/docs/index.html.

Configuring LiveCycle Data Services ES

Define one or more software clusters in the clusters section of the services-config.xml file. Each cluster element must have an id attribute, and a properties attribute that points to a JGroups properties file. The following example shows the definition of a cluster in the services-config.xml file:

<?xml version="1.0"?>
<services-config>
    ...
    <clusters>
        <cluster id="default-cluster" properties="jgroups-tcp.xml"/>
    </clusters>
    ...
</services-config>

The cluster element can take the following attributes:

• id Identifier of the cluster definition. Use the same id value across all members of a cluster.
• properties The name of a JGroups properties file.
• default A value of true sets a cluster definition as the default cluster. All destinations use this cluster unless otherwise specified by the cluster property in the destination definition. The default attribute lets you enable clustering for all destinations without having to modify your destination definitions.
• url-load-balancing The server gathers the endpoint URLs from all servers in the cluster and sends them to clients during the initial connection handshake. Therfore, clients can implement failover between servers with different domain names. If you are using hardware load balancing for HTTP and RTMP connections, you can disable this logic by setting the url-load-balancing attribute to false. In this mode, the client connects to each channel using the same URL and the load balancer routes you to an available server. When url-load-balancing is true (the default), you cannot use {server.name} and {server.port} tokens in channel endpoint URLs. Instead, specify the unique server name and port clients use to reach each server.

The following example shows a channel definition with a valid server name:

<channel-definition id="my-streaming-amf" 
    class="mx.messaging.channels.StreamingAMFChannel">
    <endpoint 
        url="http://companyserver:8400/lcds-samples/messagebroker/streamingamf"
        class="flex.messaging.endpoints.StreamingAMFEndpoint"/>
</channel-definition>

Notice that the channel endpoint omits the {server.name} and {server.port} tokens in the endpoint URL.

Reference the cluster in the network section of a destination. The value of the ref attribute must match the value of the id attribute of the cluster, as the following example shows:

<destination id="MyDestination">
    ...
    <properties>
        <network>
            <cluster ref="default-cluster"/>
        </network>
    </properties>
    ...
</destination>

If you do not specify a ref value, the destination uses the default cluster definition, if one is defined.

Configuring cluster message routing

For publish-subscribe messaging, you have the option of using the server-to-server messaging feature to route messages sent on any publish-subscribe messaging destination. Set server-to-server messaging in a configuration property on a messaging destination definition to make each server store the subscription information for all clients in the cluster. When you enable server-to-server messaging, data messages are routed only to the servers with active subscriptions, but subscribe and unsubscribe messages are broadcast across the cluster.

Server-to-server messaging provides the same functionality as the default messaging adapter, but improves the scalability of the messaging system for many use cases in a clustered environment. In many messaging applications, the number of subscribe and unsubscribe messages is much lower than the number of data messages that are sent. To enable server-to-server messaging, you set the value of the cluster-message-routing property in the server section of a messaging destination to server-to-server. The default value is broadcast. The following example shows a cluster-message-routing property set to server-to-server:

<destination id="MyTopic">
    <properties>
        ...
        <server>
            ...
            <cluster-message-routing>server-to-server</cluster-message-routing>
        </server>
    </properties>
    ...
</destination>

Configuring a shared back-end system

In addition to providing client failover, a cluster sometimes process one message on all nodes. This situation usually occurs when no back-end resource is available to coordinate the common cluster state. When no shared back-end system is available, a cluster node directs the other node to reprocess and broadcast a message. When a shared back-end system is available, a node directs the other nodes to broadcast the message to connected clients, but it does not direct the other nodes to reprocess the message.

When the shared-backend property is set to true, a cluster node directs the other nodes to broadcast messages to connected clients, but it does not direct the other nodes to reprocess the message. The shared-backend attribute is optional and is relevant only for Data Management Service destinations.

<destination id="MyDestination">
    ...
    <properties>
        <network>
            <cluster ref="default-cluster" shared-backend="true"/>
        </network>
    </properties>
    ...
</destination>

Using the shared-backend="false" configuration attribute does not guarantee a single consistent view of the data across the cluster. When two clients are connected to different servers in the cluster, if they perform conflicting updates to the same data value, each server applies these changes in a different order. The result is that clients connected to one server see one view of the data, while clients connected to other servers see a different view. The conflict detection mechanism does not detect these changes as conflicts. If you require a single consistent view of data where two clients are updating the same data values at roughly the same time, use a database or other mechanism to ensure that the proper locking is performed when updating data in the back-end system.

Viewing cluster information in the server-side log

The server-side logging mechanism captures log messages from the LiveCycle Data Services ES server. You can set the pattern attribute in the services-config.xml file to the wildcard character (*) to get all logging messages, including clustering. Alternatively, you can use the pattern parameter to filter messages. The following example filters log messages to write out only clustering and endpoint messages:

<logging>
    <target class="flex.messaging.log.ConsoleTarget" level="Debug">
        <properties>
            <prefix>[LCDS]</prefix>
            <includeDate>false</includeDate>
            <includeTime>false</includeTime>
            <includeLevel>false</includeLevel>
            <includeCategory>false</includeCategory>
        </properties>
        <filters>
            <pattern>Service.Cluster</pattern>
            <pattern>Endpoint.*</pattern>
        </filters>
    </target>
</logging>

For more information on logging, see Logging.