com.h3c.dist.groups

Interface Groups

public interface Groups

A Group designates a set of application instances [instances of same application] that are running across a controller cluster. Group Name uniquely identifies a group. Groups makes use of distributed services to synchronise the group detail across the controller cluster instances. Groups service interface can be used to create/join/leave a group, implement heart beat retrieving group and members info and running election to (re)elect group leader. Application that wishes to be part of a Group should implement Listener GroupListener interface to receive group status change notifications.

Method Summary

Methods

Modifier and Type	Method and Description
void	createGroup(String groupName, GroupInfo gInfo) Create a Group with specified name and configuration.
GroupInfo	getGroupInfo(String groupName) Query for the information [attributes] of a group
List<String>	getGroupMembers(String groupName) Query for the list of instanceIds of the group members.
GroupMemberInfo	getMemberInfo(String groupName, String instacneId) Retrieve the information about a member of the group identified by the instanceId.
void	heartBeat(String groupName, String instanceId) Application invokes this routine to periodically notify the groups service that it is alive.
String	joinGroup(String groupName, String instanceId, GroupListener listener) Application instance to join a group.
void	leaveGroup(String groupName, String instacneId) Application instance to leave a group.
void	runElection(String groupName) Trigger leader election for a group.

Method Detail

createGroup

void createGroup(String groupName,
               GroupInfo gInfo)
                 throws GroupsException,
                        ServiceNotAvailableException,
                        InterruptedException

Create a Group with specified name and configuration. If a group with the same name already exists and the configuration is same, create succeeds.

Parameters:

groupName - Name of the group

gInfo - group configuration

Throws:

GroupsException - On Error

InterruptedException - Operation interrupted exception

ServiceNotAvailableException - Groups service is not Up

GroupsException.GroupConfigMismatchException - if tried to create an existing group with different configuration

GroupsException.DistributedServicesException - Distributed services exception

joinGroup

String joinGroup(String groupName,
               String instanceId,
               GroupListener listener)
                 throws GroupsException,
                        ServiceNotAvailableException,
                        InterruptedException

Application instance to join a group. Application is allowed to use its own instanceId. If null is passed, Groups service allocates instanceId. If bAutoRunElection is property is not set for the group, this method triggers leader election.

Parameters:

groupName - group name

instanceId - instance id, if non null, Groups attempts to join with this id

listener - group listener for listening to changes to group

Returns:

instance id of the joined member

Throws:

GroupsException - On Error

InterruptedException - Operation interrupted exception

ServiceNotAvailableException - Group service is not Up

GroupsException.MemberExistsException - A member with provided instanceId exists

GroupsException.GroupNotFoundException - Group not found

GroupsException.DistributedServicesException - Distributed services exception

leaveGroup

void leaveGroup(String groupName,
              String instacneId)
                throws GroupsException,
                       ServiceNotAvailableException,
                       InterruptedException

Application instance to leave a group.

Parameters:

groupName - group name

instacneId - instance id

Throws:

GroupsException - On Error

InterruptedException - Operation interrupted exception

ServiceNotAvailableException - Groups service is not Up

GroupsException.MemberNotFoundException - No member corresponding to instanceId

GroupsException.DistributedServicesException - Distributed services exception

runElection

void runElection(String groupName)
                 throws GroupsException,
                        ServiceNotAvailableException,
                        InterruptedException

Trigger leader election for a group. Application is entitled to trigger the election only if bAutoRunElection is not set in the GroupInfo.

Parameters:

groupName - group name

Throws:

GroupsException - On Error

InterruptedException - Operation interrupted exception

ServiceNotAvailableException - Groups service is not Up

GroupsException.GroupNotFoundException - group doesn't exist

GroupsException.GroupChangedException - Group changed from the last state

GroupsException.DistributedServicesException - Distributed services exception

getGroupInfo

GroupInfo getGroupInfo(String groupName)
                       throws GroupsException,
                              ServiceNotAvailableException,
                              InterruptedException

Query for the information [attributes] of a group

Parameters:

groupName - group name

Returns:

Group info object

Throws:

GroupsException - On Error

InterruptedException - Operation interrupted exception

ServiceNotAvailableException - Group service is not Up

GroupsException.GroupNotFoundException - group doesn't exist

GroupsException.DistributedServicesException - Distributed services exception

getGroupMembers

List<String> getGroupMembers(String groupName)
                             throws GroupsException,
                                    ServiceNotAvailableException,
                                    InterruptedException

Query for the list of instanceIds of the group members.

Parameters:

groupName - group name

Returns:

List of members

Throws:

GroupsException - On Error

InterruptedException - Operation interrupted exception

ServiceNotAvailableException - Group service is not Up

GroupsException.GroupNotFoundException - group doesn't exist

GroupsException.DistributedServicesException - Distributed services exception

getMemberInfo

GroupMemberInfo getMemberInfo(String groupName,
                            String instacneId)
                              throws GroupsException,
                                     ServiceNotAvailableException,
                                     InterruptedException

Retrieve the information about a member of the group identified by the instanceId.

Parameters:

groupName - group name

instacneId - instance id

Returns:

Group member info object

Throws:

GroupsException - On Error

InterruptedException - Operation interrupted exception

ServiceNotAvailableException - Group service is not Up

GroupsException.MemberNotFoundException - member not found

heartBeat

void heartBeat(String groupName,
             String instanceId)
               throws GroupsException

Application invokes this routine to periodically notify the groups service that it is alive.

Parameters:

groupName - group name

instanceId - instance id

Throws:

GroupsException - On Error

GroupsException.MemberNotFoundException - member not found