com.sun.enterprise.ee.cms.spi
Interface GroupCommunicationProvider

All Known Implementing Classes:
GroupCommunicationProviderImpl

public interface GroupCommunicationProvider

Provides a plugging interface for integrating group communication providers(GCP). Acts as a bridge between GCP packages and GMS. Implementation of this API allows GMS objects to delegate interaction with the underlying GCP through commonly executed calls. GCPs should have a notion of grouping members and allow for messaging. GCPs should be capable of notifying group events. GCP should provide interfaces for programmatic configuration of their group communication and membership protocols.

Version:
$Revision: 1.20 $
Author:
Shreedhar Ganapathy Date: Jun 26, 2006

Method Summary
 void announceClusterShutdown(GMSMessage gmsMessage)
          Sends an announcement to the group that a cluster wide shutdown is impending
 void announceGroupStartup(String groupName, GMSConstants.groupStartupState startupState, List<String> memberTokens)
          Invoked indirectly by a controlling parent application that has a static preconfiguration of all members of the group to announce that the parent application is "initiating" and then that it has "completed" startup of all preconfigured members of this group.
 void announceWatchdogObservedFailure(String serverToken)
          Allow for enhanced GMS failure detection by external control entities (one example is NodeAgent of Glassfish Application Server.) Only a GMS MemberType of WATCHDOG is allowed to broadcast to all members of a group that this serverToken has failed.
 void assumeGroupLeadership()
          Provides for this instance to become a group leader explicitly.
 String getGroupLeader()
          Returns the Group Leader as defined by the underlying Group Communication Provider.
 List<String> getMembers()
          returns a list of members that are currently alive in the group.
 MemberStates getMemberState(String memberIdentityToken)
          Returns the member state as defined in the Enum MemberStates
 MemberStates getMemberState(String member, long threshold, long timeout)
          Returns the state of the member.
 void initializeGroupCommunicationProvider(String memberName, String groupName, Map<String,String> identityMap, Map configProperties)
          Initializes the Group Communication Service Provider with the requisite values of group identity, member(self) identity, and a Map containing recognized and valid configuration properties that can be set/overriden by the employing application.
 boolean isDiscoveryInProgress()
           
 boolean isGroupLeader()
          Returns true if this peer is the leader of the group
 void join()
          Joins the group using semantics specified by the underlying GCP system
 void leave(boolean isClusterShutdown)
          Leaves the group as a result of a planned administrative action to shutdown.
 void reportJoinedAndReadyState()
          This API is provided for the parent application to report to the group its joined and ready state to begin processing its operations.
 void sendMessage(Serializable message)
          Sends a message to the entire group using the underlying group communication provider's APIs.
 void sendMessage(String targetMemberIdentityToken, Serializable message, boolean synchronous)
          Sends a message using the underlying group communication providers'(GCP's) APIs.
 void setGroupStoppingState()
          Can be used especially to inform the HealthMonitoring service that the group is shutting down.
 

Method Detail

initializeGroupCommunicationProvider

void initializeGroupCommunicationProvider(String memberName,
                                          String groupName,
                                          Map<String,String> identityMap,
                                          Map configProperties)
Initializes the Group Communication Service Provider with the requisite values of group identity, member(self) identity, and a Map containing recognized and valid configuration properties that can be set/overriden by the employing application. The valid property keys must be specified in a datastructure that is available to the implementation and to GMS.

Parameters:
memberName - member name
groupName - name of group
identityMap - - additional member identity params specified through key-value pairs.
configProperties - - properties that the employing applications likes to configure in the underlying GCP.

join

void join()
Joins the group using semantics specified by the underlying GCP system


announceClusterShutdown

void announceClusterShutdown(GMSMessage gmsMessage)
Sends an announcement to the group that a cluster wide shutdown is impending

Parameters:
gmsMessage - an object that encapsulates the application's Message

leave

void leave(boolean isClusterShutdown)
Leaves the group as a result of a planned administrative action to shutdown.

Parameters:
isClusterShutdown - - true if we are leaving as part of a cluster wide shutdown

sendMessage

void sendMessage(String targetMemberIdentityToken,
                 Serializable message,
                 boolean synchronous)
                 throws GMSException,
                        MemberNotInViewException
Sends a message using the underlying group communication providers'(GCP's) APIs. Requires the users' message to be wrapped into a GMSMessage object.

Parameters:
targetMemberIdentityToken - The member token string that identifies the target member to which this message is addressed. The implementation is expected to provide a mapping the member token to the GCP's addressing semantics. If null, the entire group would receive this message.
message - a Serializable object that wraps the user specified message in order to allow remote GMS instances to unpack this message appropriately.
synchronous - setting true here will call the underlying GCP's api that corresponds to a synchronous message, if available.
Throws:
GMSException - wraps the underlying exception
MemberNotInViewException

sendMessage

void sendMessage(Serializable message)
                 throws GMSException,
                        MemberNotInViewException
Sends a message to the entire group using the underlying group communication provider's APIs. The Serializable object here is a GMSMessage Object.

Parameters:
message - a Serializable object that wraps the users specified message in order to allow remote GMS instances to unpack this message appropriately
Throws:
GMSException - Underlying exception is wrapped in a GMSException
MemberNotInViewException

getMembers

List<String> getMembers()
returns a list of members that are currently alive in the group. The list should contain the member identity token that GMS understands as member identities.

Returns:
list of current live members

isGroupLeader

boolean isGroupLeader()
Returns true if this peer is the leader of the group

Returns:
boolean true if group leader, false if not.

getMemberState

MemberStates getMemberState(String member,
                            long threshold,
                            long timeout)
Returns the state of the member. The parameters threshold and timeout enable the caller to tune this lookup between accuracy and time it will take to complete the call. It is lowest cost to just return the local computed concept for a member's state. threshold parameter controls this. If the local state is stale, then the timeout parameter enables one to control how long they are willing to wait for more accurate state information from the member itself.

Parameters:
member -
threshold - allows caller to specify how up-to-date the member state information has to be. The larger this value, the better chance that this method just returns the local concept of this member's state. The smaller this value, the better chance that the local state is not fresh enough and the method will find out directly from the instance what its current state is.
timeout - is the time for which the caller instance should wait to get the state from the concerned member via a network call. if timeout and threshold are both 0, then the default values are used if threshold is 0, then a network call is made to get the state of the member if timeout is 0, then the caller instance checks for the state of the member stored with it within the given threshold
Returns:
the state of the member Returns UNKNOWN when the local state for the member is considered stale (determined by threshold value) and the network invocation to get the member state times out before getting a reply from the member of what its state is.

getMemberState

MemberStates getMemberState(String memberIdentityToken)
Returns the member state as defined in the Enum MemberStates

Parameters:
memberIdentityToken - identity of member.
Returns:
MemberStates

getGroupLeader

String getGroupLeader()
Returns the Group Leader as defined by the underlying Group Communication Provider.

Returns:
String

assumeGroupLeadership

void assumeGroupLeadership()

Provides for this instance to become a group leader explicitly. Typically this can be employed by an administrative member to become a group leader prior to shutting down a group of members simultaneously.

For underlying Group Communication Providers who don't support the feature of a explicit leader role assumption, the implementation of this method would be a no-op.


setGroupStoppingState

void setGroupStoppingState()
Can be used especially to inform the HealthMonitoring service that the group is shutting down.


reportJoinedAndReadyState

void reportJoinedAndReadyState()
This API is provided for the parent application to report to the group its joined and ready state to begin processing its operations. The group member that this parent application represents is now ready to process its operations at the time of this announcement to the group. GMS clients in all other group members that are interested in knowing when another member is ready to start processing operations, can subscribe to the event JoinedAndReadyEvent and be notified of this JoinedAndReadyNotificationSignal.


announceWatchdogObservedFailure

void announceWatchdogObservedFailure(String serverToken)
                                     throws GMSException
Allow for enhanced GMS failure detection by external control entities (one example is NodeAgent of Glassfish Application Server.) Only a GMS MemberType of WATCHDOG is allowed to broadcast to all members of a group that this serverToken has failed.

Parameters:
serverToken - failed member
Throws:
GMSException - if called by a member that is not a WATCHDOG member or if serverToken is not currently running in group.

announceGroupStartup

void announceGroupStartup(String groupName,
                          GMSConstants.groupStartupState startupState,
                          List<String> memberTokens)
Invoked indirectly by a controlling parent application that has a static preconfiguration of all members of the group to announce that the parent application is "initiating" and then that it has "completed" startup of all preconfigured members of this group.

Group members in parameter members is interpreted differently based on startupState. All preconfigured members of group are passed in members when INITIATED or COMPLETED_SUCCESS. When startupState is COMPLETED_FAILED, members is a list of the members that failed to start.

Parameters:
groupName -
startupState - demarcate initiation of groupStartup and completion of group startup
memberTokens - list of memberTokens.

isDiscoveryInProgress

boolean isDiscoveryInProgress()


Copyright © 2003 Copyright 2004 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.