Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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()

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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