com.tibco.ftl.group

## Interface Group

-     public interface Group

  The group facility can coordinate fault-tolerant operation, or distribute operating roles among application process instances.

  A group object represents the membership or potential membership of an application process in a group.

  A group server tracks group members, and assigns an ordinal to each member. The group facility raises advisories to inform the member of its current ordinal. Based on its ordinal, each member operates in a particular application-specific role.

  The group server also reports the group status as members join and leave the group, or disconnect from the server. The group facility raises advisories to inform members and observers of such changes in status.

  This class defines the public API of the group facility.

  To join a group, call `GroupFactory.join`.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static class` | `Group.GroupMemberEvent` Group member event; enumeration.
    `static class` | `Group.GroupMemberServerConnection` Group member connection to group server; enumeration.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `ADVISORY_FIELD_GROUP` Group name (field name).
    `static java.lang.String` | `ADVISORY_FIELD_ORDINAL` Group member ordinal (field name).
    `static java.lang.String` | `ADVISORY_MODULE_GROUP` The advisory message pertains to the group library implementation code (module).
    `static java.lang.String` | `ADVISORY_NAME_GROUP_STATUS` The advisory message reports a group status update.
    `static java.lang.String` | `ADVISORY_NAME_ORDINAL_UPDATE` The advisory message reports an ordinal update.
    `static java.lang.String` | `FIELD_GROUP_MEMBER_DESCRIPTOR` Group member descriptor (field name).
    `static java.lang.String` | `FIELD_GROUP_MEMBER_EVENT` Group member event (field name).
    `static java.lang.String` | `FIELD_GROUP_MEMBER_LIST` Group member list (field name).
    `static java.lang.String` | `FIELD_GROUP_MEMBER_STATUS_LIST` Group member status list (field name).
    `static java.lang.String` | `FIELD_GROUP_SERVER_AVAILABLE` Group member connection to group server (field name).
    `static java.lang.String` | `PROPERTY_BOOLEAN_OBSERVER` Property name to monitor a group as an observer.
    `static java.lang.String` | `PROPERTY_DOUBLE_ACTIVATION_INTERVAL` Property name for group activation interval.
    `static java.lang.String` | `PROPERTY_LONG_MEMBER_WEIGHT` Property name to set the weight for a group member
    `static java.lang.String` | `PROPERTY_MESSAGE_MEMBER_DESCRIPTOR` Property name for group member descriptor.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `Message` | `getMembers()` Returns the active members of group.
    `java.lang.String` | `getName()` Return the group name.
    `long` | `getOrdinal()` Returns the current ordinal of this member of group.
    `long` | `getWeight()` Returns the weight for this member.
    `void` | `leave()` Leave a group, and destroy the group object.
    `void` | `setWeight(long weight)` Set the weight for this group member.

- - ### Field Detail

    - #### PROPERTY_DOUBLE_ACTIVATION_INTERVAL

          static final java.lang.String PROPERTY_DOUBLE_ACTIVATION_INTERVAL

      Property name for group activation interval.

      Supply this (optional) property to `GroupFactory.join`, which derives heartbeat and timeout intervals from this property value (in seconds). When absent, the default value is 5 seconds.

      See Also:
        Constant Field Values

    - #### ADVISORY_MODULE_GROUP

          static final java.lang.String ADVISORY_MODULE_GROUP

      The advisory message pertains to the group library implementation code (module).

      This string value can appear in the `module` field.

      See Also:
        `Advisory.FIELD_MODULE`, Constant Field Values

    - #### ADVISORY_NAME_ORDINAL_UPDATE

          static final java.lang.String ADVISORY_NAME_ORDINAL_UPDATE

      The advisory message reports an ordinal update.

      This string value can appear in the `name` field.

      See Also:
        `Advisory.FIELD_NAME`, `ADVISORY_FIELD_GROUP`, `ADVISORY_FIELD_ORDINAL`, `Advisory.SEVERITY_INFO`, Constant Field Values

    - #### ADVISORY_FIELD_GROUP

          static final java.lang.String ADVISORY_FIELD_GROUP

      Group name (field name).

      The string value of the `group` name field is the name of the group to which the advisory pertains.

      See Also:
        Constant Field Values

    - #### ADVISORY_FIELD_ORDINAL

          static final java.lang.String ADVISORY_FIELD_ORDINAL

      Group member ordinal (field name).

      The positive long value of the `ordinal` field represents the new ordinal of the group member.

      The value -1 indicates that the group object is disconnected from the group server. The group object automatically attempts to reconnect, and continues until the program explicitly destroys it. Meanwhile, the group server could reassign the member's previous ordinal to another group member.

      Zero is a reserved value.

      See Also:
        Constant Field Values

    - #### PROPERTY_MESSAGE_MEMBER_DESCRIPTOR

          static final java.lang.String PROPERTY_MESSAGE_MEMBER_DESCRIPTOR

      Property name for group member descriptor.

      To identify a group member to the other members, supply this optional property to `GroupFactory.join`.

      The application programmer determines the content of the descriptor message. In best practice, each group member process supplies a unique descriptor.

      See Also:
        Constant Field Values

    - #### PROPERTY_BOOLEAN_OBSERVER

          static final java.lang.String PROPERTY_BOOLEAN_OBSERVER

      Property name to monitor a group as an observer.

      To monitor a group as an observer, supply this optional property with value `true` to `GroupFactory.join`.

      An observer never receives an ordinal, and does not trigger group member events.

      See Also:
        Constant Field Values

    - #### PROPERTY_LONG_MEMBER_WEIGHT

          static final java.lang.String PROPERTY_LONG_MEMBER_WEIGHT

      Property name to set the weight for a group member

      To set weight for a group member, supply this optional property to `GroupFactory.join`.

      Acceptable values are positive integers. When absent, the default value is 100. Zero is reserved value. FTL group service uses relative weight values to determine the ordinals of the group member; members with higher weight take precedence.

      See Also:
        Constant Field Values

    - #### ADVISORY_NAME_GROUP_STATUS

          static final java.lang.String ADVISORY_NAME_GROUP_STATUS

      The advisory message reports a group status update.

      This string value can appear in the `name` field.

      See Also:
        `Advisory.FIELD_NAME`, `ADVISORY_FIELD_GROUP`, `FIELD_GROUP_MEMBER_STATUS_LIST`, `FIELD_GROUP_MEMBER_DESCRIPTOR`, `FIELD_GROUP_MEMBER_EVENT`, `FIELD_GROUP_SERVER_AVAILABLE`, `Advisory.SEVERITY_INFO`, Constant Field Values

    - #### FIELD_GROUP_MEMBER_STATUS_LIST

          static final java.lang.String FIELD_GROUP_MEMBER_STATUS_LIST

      Group member status list (field name).

      This field can appear in group status advisory messages. Its value is an array of member status submessages. Each submessage reports the status of one group member.

      See Also:
        Constant Field Values

    - #### FIELD_GROUP_MEMBER_LIST

          static final java.lang.String FIELD_GROUP_MEMBER_LIST

      Group member list (field name).

      This field can appear in response message of 'getMembers' call. Its a message array field where each element is a message containing following field at the most: `FIELD_GROUP_MEMBER_DESCRIPTOR`

      See Also:
        Constant Field Values

    - #### FIELD_GROUP_MEMBER_DESCRIPTOR

          static final java.lang.String FIELD_GROUP_MEMBER_DESCRIPTOR

      Group member descriptor (field name).

      This field can can appear in a member status submessage. Its value is a group member descriptor, that is, a message that identifies a group member.

      See Also:
        Constant Field Values

    - #### FIELD_GROUP_MEMBER_EVENT

          static final java.lang.String FIELD_GROUP_MEMBER_EVENT

      Group member event (field name).

      This field can appear in a member status submessage. Its value is a `Group.GroupMemberEvent`, that is, a long value that indicates the group member's current state or recent state change.

      See Also:
        Constant Field Values

    - #### FIELD_GROUP_SERVER_AVAILABLE

          static final java.lang.String FIELD_GROUP_SERVER_AVAILABLE

      Group member connection to group server (field name).

      This field can appear in a group status message. Its value is a `Group.GroupMemberServerConnection`, that is, a long value that indicates whether the application process is connected to the group server.

      See Also:
        Constant Field Values

  - ### Method Detail

    - #### leave

          void leave()
              throws FTLException

      Leave a group, and destroy the group object.

      This call informs the group server that the member is leaving the group. In response, the group server revises the ordinals of the remaining group members appropriately.

      This call releases all resources held by the group object.

      Before your program calls `Realm.close`, it must first destroy all the group objects that it has created.

      Throws:
        `FTLException`

    - #### getOrdinal

          long getOrdinal()
                   throws FTLException

      Returns the current ordinal of this member of group.

      This call returns current ordinal of this member of the provided group.

      Returns:
        The value of ordinal of this member for the group.
      Throws:
        `FTLException`

    - #### getMembers

          Message getMembers()
                      throws FTLException

      Returns the active members of group.

      This call returns all the members of group that are connected to group server.

      Returns:
        Message contains a message array field where each element refers to the active member of this group.
      Throws:
        `FTLException`

    - #### getName

          java.lang.String getName()

      Return the group name.

      This call returns the group name string that your program supplied to `GroupFactory.join`.

      Returns:
        Group name string.

    - #### getWeight

          long getWeight()
                  throws FTLException

      Returns the weight for this member.
      Returns:
        This call returns the weight for this member.
      Throws:
        `FTLException`

    - #### setWeight

          void setWeight(long weight)
                  throws FTLException

      Set the weight for this group member. Acceptable values are positive integers. Zero is reserved value. Programs can adjust their weight at any time to reflect changing conditions on the host. Adjusting weights causes each member to recompute their relative weights of all the members of the group. For large groups this recomputation can affect performance.
      Throws:
        `FTLException`