com.sun.enterprise.ee.cms.core
Class GMSFactory

java.lang.Object
  extended by com.sun.enterprise.ee.cms.core.GMSFactory

public class GMSFactory
extends Object

This is the entry point to GMS for the parent application that is initiating GMS module and by client components in the parent app that need to interact with GMS for group events or send or receive messages.

GMSFactory is the interface for starting GMS module through the startGMSModule() api which returns a GroupManagementService instance, and for retrieving the said GroupManagementService instance by any client components.

The GroupManagementService instance provides APIs for registering clients who wish to be notified of Group Events and Message Events, and in addition provides a reference to GroupHandle, and and api for announcing the impending shutdown of this parent process.

Example for parent lifecycle module to start GMS:
final Runnable gms = GMSFactory.startGMSModule(serverName, groupName, memberType, properties);
final Thread gservice = new Thread(gms, "GMSThread");
gservice.start();

Example for parent lifecycle module to shutdown GMS:
gms.shutdown(GMSConstants.shutdownType.INSTANCE_SHUTDOWN);
or
gms.shutdown(GMSConstants.shutdownType.GROUP_SHUTDOWN);

Registration Example for clients that want to consume group events and message events:
GroupManagementService gms = GMSFactory.getGMSModule(groupName);
gms.addActionFactory(myfailureNotificationActionFactoryImpl);

Version:
$Revision: 1.6 $
Author:
Shreedhar Ganapathy

Method Summary
static Collection getAllGMSInstancesForMember()
          For the case where there are multiple groups in which this process has become a member.
static GroupManagementService getGMSModule()
          This is to be used only in the case where this process is a member of one and only one group and the group name is unknown to the caller.
static GroupManagementService getGMSModule(String groupName)
          This returns an instance of the GroupManagementService for a given non-null group name.
static boolean isGMSEnabled(String groupName)
          returns true if GMS is enabled for the specified group.
static void removeGMSModule(String groupName)
          removes the GMS instance that is cached from a prior initialization.
static void setGMSEnabledState(String groupName, Boolean value)
          enables an initialization code in the Application layer to set GMS to be enabled or not based on the application's configuration
static Runnable startGMSModule(String serverToken, String groupName, GroupManagementService.MemberType memberType, Properties properties)
          starts and returns the GMS module object as a Runnable that could be started in a separate thread.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

startGMSModule

public static Runnable startGMSModule(String serverToken,
                                      String groupName,
                                      GroupManagementService.MemberType memberType,
                                      Properties properties)
starts and returns the GMS module object as a Runnable that could be started in a separate thread. This method is only used to create an instance of GroupManagementService and sets up the configuration properties in appropriate delegate objects. To actually create a group or join an existing group, one has to either pass in the GroupManagementService Object in a new Thread and start it or call the GroupManagementService.join() method. The startGMSModule method is expected to be called by the parent module's lifecycle management code to initiate GMS module. Invocation of this method assumes that GMS is enabled in the parent application's configuration. Calls to GMSFactory.getGMSModule() made before any code calls this method will result in GMSNotEnabledException to be thrown.

Parameters:
serverToken - a logical name or identity given the member that is repeatable over lifetimes of the server
groupName - name of the group
memberType - The member type corresponds to the MemberType specified in GroupManagementService.MemberType
properties - Key-Value pairs of entries that are intended to configure the underlying group communication provider's protocols such as address, failure detection timeouts and retries, etc. Allowable keys are specified in GMSConfigConstants
Returns:
java.lang.Runnable

getGMSModule

public static GroupManagementService getGMSModule(String groupName)
                                           throws GMSNotEnabledException,
                                                  GMSException,
                                                  GMSNotInitializedException
This returns an instance of the GroupManagementService for a given non-null group name.

Parameters:
groupName - groupName
Returns:
GroupManagementService
Throws:
GMSException - - if the groupName is null
GMSNotEnabledException - - If GMS is not enabled
GMSNotInitializedException - - If GMS is not initialized

getGMSModule

public static GroupManagementService getGMSModule()
                                           throws GMSException
This is to be used only in the case where this process is a member of one and only one group and the group name is unknown to the caller.

Returns:
GroupManagementService
Throws:
GMSException - - wraps a throwable GMSNotInitializedException if there are no GMS instances found.

getAllGMSInstancesForMember

public static Collection getAllGMSInstancesForMember()
For the case where there are multiple groups in which this process has become a member.

Returns:
Collection

isGMSEnabled

public static boolean isGMSEnabled(String groupName)
returns true if GMS is enabled for the specified group.

Parameters:
groupName - Name of the group
Returns:
true if GMS is enabled

setGMSEnabledState

public static void setGMSEnabledState(String groupName,
                                      Boolean value)
enables an initialization code in the Application layer to set GMS to be enabled or not based on the application's configuration

Parameters:
groupName - Name of the group
value - a Boolean value

removeGMSModule

public static void removeGMSModule(String groupName)
removes the GMS instance that is cached from a prior initialization. This is typically called only when GMS module is being shutdown by a lifecycle action.

Parameters:
groupName - Name of the Group


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