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

Copyright © 2014. All Rights Reserved.