6 Automatically Manage Dynamic Cluster Membership

Coherence manages cluster membership by automatically adding new servers to the cluster when they start up and automatically detecting their departure when they are shut down or fail. Applications have full access to this information and can sign up to receive event notifications when members join and leave the cluster. Coherence also tracks all the services that each member is providing and consuming. This information is used to plan for service resiliency in case of server failure; to load-balance data management; as well as other responsibilities across all members of the cluster.

Cluster and Service Objects

From any cache, the application can obtain a reference to the local representation of a cache's service. From any service, the application can obtain a reference to the local representation of the cluster.

CacheService service = cache.getCacheService();
Cluster      cluster = service.getCluster();

From the Cluster object, the application can determine the set of services that run in the cluster. This is illustrated in Example 6-1.

Example 6-1 Determining Services Running in the Cluster

...
for (Enumeration enum = cluster.getServiceNames(); enum.hasMoreElements(); )
    {
    String sName = (String) enum.nextElement();
    ServiceInfo info = cluster.getServiceInfo(sName);
    // ...
    }
...

The ServiceInfo object provides information about the service, including its name, type, version and membership.

For more information on this feature, see the API documentation for NamedCache, CacheService, Service, ServiceInfo and Cluster.

Member object

The primary information that an application can determine about each member in the cluster is:

• The Member's IP address

• What date/time the Member joined the cluster

As an example, if there are four servers in the cluster with each server running one copy ("instance") of the application and all four instances of the application are clustered together, then the cluster is composed of four Members. From the Cluster object, the application can determine what the local Member is:

Member memberThis = cluster.getLocalMember();

From the Cluster object, the application can also determine the entire set of cluster members:

Set setMembers = cluster.getMemberSet();

From the ServiceInfo object, the application can determine the set of cluster members that are participating in that service:

ServiceInfo info = cluster.getServiceInfo(sName);
Set setMembers = info.getMemberSet();

For more information on this feature, see the API documentation for Member.

Listener interface and Event object

To listen to cluster and/or service membership changes, the application places a listener on the desired Service. As discussed before, the Service can come from a cache:

Service service = cache.getCacheService();

The Service can also be looked up by its name:

Service service = cluster.getService(sName);

To receive membership events, the application implements a MemberListener. Example 6-2 illustrates a listener implementation that prints out all the membership events that it receives:

Example 6-2 A Sample MemberListener Implementation

public class MemberEventPrinter
        extends Base
        implements MemberListener
    {
    public void memberJoined(MemberEvent evt)
        {
        out(evt);
        }

    public void memberLeaving(MemberEvent evt)
        {
        out(evt);
        }

    public void memberLeft(MemberEvent evt)
        {
        out(evt);
        }
    }

The MemberEvent object carries information about the event type (either joined, leaving, or left), the member that generated the event, and the service that acts as the source of the event. Additionally, the event provides a method, isLocal(), that indicates to the application that it is this member that is joining or leaving the cluster. This is useful for recognizing soft restarts in which an application automatically rejoins a cluster after a failure occurs. Example 6-3 illustrates how information encapsulated in a MemberEvent object can be used.

Example 6-3 Using Event Type Information in a MemberEvent Object

public class RejoinEventPrinter
        extends Base
        implements MemberListener
    {
    public void memberJoined(MemberEvent evt)
        {
        if (evt.isLocal())
            {
            out("this member just rejoined the cluster: " + evt);
            }
        }

    public void memberLeaving(MemberEvent evt)
        {
        }

    public void memberLeft(MemberEvent evt)
        {
        }
    }

For more information on these feature, see the API documentation for Service, MemberListener and MemberEvent.