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

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