hydra

Class DistributedSystemHelper

java.lang.Object

hydra.DistributedSystemHelper

public class DistributedSystemHelper
extends Object

Helps hydra clients manage locators for and connections to a distributed system. Methods are thread-safe.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	DistributedSystemHelper.Endpoint Represents the endpoint for a locator.

Field Summary

Fields

Modifier and Type	Field and Description
static String	DISCOVERY_FILE_NAME Name of the file containing locator or multicast endpoints

Constructor Summary

Constructors

Constructor and Description
DistributedSystemHelper()

Method Summary

Modifier and Type	Method and Description
static String	adminToString(com.gemstone.gemfire.admin.AdminDistributedSystem ads) Returns the given admin distributed system as a string.
static void	cleanupAfterAutoDisconnect() Cleans up disconnect-related variables in this helper class so that the JVM can use it to reconnect.
static com.gemstone.gemfire.admin.DistributedSystemConfig	configureAdmin(String adminConfig) Returns the configuration for an admin distributed system, using the AdminDescription corresponding to the given admin configuration from AdminPrms.names.
static com.gemstone.gemfire.distributed.DistributedSystem	connect() Connects to a distributed system using properties from the GemFireDescription corresponding to the logical gemfire configuration name from the system property GemFirePrms.GEMFIRE_NAME_PROPERTY.
static void	connectAdmin(com.gemstone.gemfire.admin.AdminDistributedSystem ads) Connects the admin distributed system.
static com.gemstone.gemfire.admin.AdminDistributedSystem	connectAdmin(String adminConfig) Configures, creates and connects an admin distributed system, using the AdminDescription corresponding to the given admin configuration from AdminPrms.names.
static com.gemstone.gemfire.distributed.DistributedSystem	connectWithXml(String cacheXmlFile) Connects to a distributed system using properties from the GemFireDescription corresponding to the logical gemfire configuration name from the system property GemFirePrms.GEMFIRE_NAME_PROPERTY.
static com.gemstone.gemfire.admin.AdminDistributedSystem	createAdmin(com.gemstone.gemfire.admin.DistributedSystemConfig dsConfig) Creates an unconnected admin distributed system from the given configuration.
static com.gemstone.gemfire.admin.AdminDistributedSystem	createAdmin(String adminConfig) Configures and creates an unconnected admin distributed system, using the AdminDescription corresponding to the given admin configuration from AdminPrms.names.
static void	createLocator() Creates a locator endpoint that this VM and other locator VMs in its distributed system can use when configuring their locator lists.
static void	disconnect() Disconnects the distributed system if it is connected.
static void	disconnectAdmin() Disconnects the admin distributed system if it is connected.
static String	endpointsToString(List endpoints) Converts a list of locator endpoints to a locator string, or the empty string if the list is null.
static String	endpointToString(DistributedSystemHelper.Endpoint endpoint) Converts a locator endpoint to a locator string, or the empty string if the endpoint is null.
static AdminDescription	getAdminDescription(String adminConfig) Returns the AdminDescription with the given configuration name from AdminPrms.names.
static com.gemstone.gemfire.admin.AdminDistributedSystem	getAdminDistributedSystem() Returns the admin distributed system if it is connected, otherwise null.
static Set	getAdminMembers() Returns a collection of the current admin distribution members.
static List	getContacts() Returns all contacts (server locator endpoints) from the DistributedSystemBlackboard map, a possibly empty list.
static List<String>	getContacts(List<String> distributedSystemNames) Returns all contacts (server locator endpoints) for the specified distributed systems from the DistributedSystemBlackboard map, a possibly empty list.
static List	getContacts(String distributedSystemName) Returns all contacts (server locator endpoints) for the specified distributed system from the DistributedSystemBlackboard map, a possibly empty list.
static com.gemstone.gemfire.distributed.DistributedSystem	getDistributedSystem() Returns the distributed system if it is connected, otherwise null.
static Integer	getDistributedSystemId() Returns the distributed system id.
static int	getDistributedSystemId(String distributedSystemName) Returns the distributed system id for the given distributed system name.
static String	getDistributedSystemName() Returns the distributed system name.
static String	getDistributedSystemName(int distributedSystemId) Returns the distributed system name for the given distributed system id.
static Properties	getDistributedSystemProperties(String cacheXmlFile) Returns distributed system properties using the optional cache XML file.
static List	getEndpoints() Returns all peer locator endpoints from the DistributedSystemBlackboard map, a possibly empty list.
static List	getEndpoints(String distributedSystemName) Returns all peer locator endpoints for the specified distributed system from the DistributedSystemBlackboard map, a possibly empty list.
static GemFireDescription	getGemFireDescription() Returns the GemFireDescription for this VM, as specified by the system property GemFirePrms.GEMFIRE_NAME_PROPERTY.
static com.gemstone.gemfire.distributed.Locator	getLocator() Returns the currently running locator, or null if no locator exists.
static Set	getMembers() Returns a collection of the current distribution members.
static List	getSystemContacts() Returns all contacts (server locator endpoints) for this VM's distributed system from the DistributedSystemBlackboard map, a possibly empty list.
static List	getSystemEndpoints() Returns all peer locator endpoints for this VM's distributed system from the DistributedSystemBlackboard map, a possibly empty list.
static String	locatorToString(com.gemstone.gemfire.distributed.Locator locator) Returns the given locator as a string.
static com.gemstone.gemfire.distributed.Locator	startLocatorAndAdminDS() Starts the locator whose endpoint was created by createLocator() and connects it to an admin distributed system (it cannot create a cache).
static com.gemstone.gemfire.distributed.Locator	startLocatorAndDS() Starts the locator whose endpoint was created by createLocator() and connects it to a non-admin distributed system (it can create a cache).
static void	stopLocator() Stops the currently running locator, if it exists.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DISCOVERY_FILE_NAME

public static final String DISCOVERY_FILE_NAME

Name of the file containing locator or multicast endpoints

See Also:

Constant Field Values

Constructor Detail

DistributedSystemHelper

public DistributedSystemHelper()

Method Detail

connect

public static com.gemstone.gemfire.distributed.DistributedSystem connect()

Connects to a distributed system using properties from the GemFireDescription corresponding to the logical gemfire configuration name from the system property GemFirePrms.GEMFIRE_NAME_PROPERTY. Returns the existing distributed system if it is currently connected.

Throws:

HydraRuntimeException - if an attempt is made to reconfigure an existing distributed system.

connectWithXml

public static com.gemstone.gemfire.distributed.DistributedSystem connectWithXml(String cacheXmlFile)

Connects to a distributed system using properties from the GemFireDescription corresponding to the logical gemfire configuration name from the system property GemFirePrms.GEMFIRE_NAME_PROPERTY. Returns the existing distributed system if it is currently connected.

Subsequent cache creation will use the configuration in the XML file.

Throws:

HydraRuntimeException - if an attempt is made to reconfigure an existing distributed system.

getDistributedSystem

public static com.gemstone.gemfire.distributed.DistributedSystem getDistributedSystem()

Returns the distributed system if it is connected, otherwise null.

getDistributedSystemName

public static String getDistributedSystemName()

Returns the distributed system name.

getDistributedSystemId

public static Integer getDistributedSystemId()

Returns the distributed system id.

disconnect

public static void disconnect()

Disconnects the distributed system if it is connected.

cleanupAfterAutoDisconnect

public static void cleanupAfterAutoDisconnect()

Cleans up disconnect-related variables in this helper class so that the JVM can use it to reconnect.

NOTE: For use only after the product has automatically disconnected the JVM from the distributed system. The test is responsible for verifying this.

connectAdmin

public static com.gemstone.gemfire.admin.AdminDistributedSystem connectAdmin(String adminConfig)

Configures, creates and connects an admin distributed system, using the AdminDescription corresponding to the given admin configuration from AdminPrms.names.

Throws:

HydraRuntimeException - if an attempt is made to reconfigure an existing distributed system.

createAdmin

public static com.gemstone.gemfire.admin.AdminDistributedSystem createAdmin(String adminConfig)

Configures and creates an unconnected admin distributed system, using the AdminDescription corresponding to the given admin configuration from AdminPrms.names.

To connect the system, use connectAdmin(AdminDistributedSystem).

Throws:

HydraRuntimeException - if an attempt is made to reconfigure an existing distributed system.

configureAdmin

public static com.gemstone.gemfire.admin.DistributedSystemConfig configureAdmin(String adminConfig)

Returns the configuration for an admin distributed system, using the AdminDescription corresponding to the given admin configuration from AdminPrms.names. This can be mutated as needed before creating and connecting the system.

To create the system, use createAdmin(DistributedSystemConfig). To connect the system, use connectAdmin(AdminDistributedSystem).

Throws:

HydraRuntimeException - if an attempt is made to reconfigure an existing admin distributed system.

createAdmin

public static com.gemstone.gemfire.admin.AdminDistributedSystem createAdmin(com.gemstone.gemfire.admin.DistributedSystemConfig dsConfig)

Creates an unconnected admin distributed system from the given configuration.

To connect the system, use connectAdmin(AdminDistributedSystem).

Throws:

HydraRuntimeException - if an attempt is made to reconfigure an existing admin distributed system.

connectAdmin

public static void connectAdmin(com.gemstone.gemfire.admin.AdminDistributedSystem ads)

Connects the admin distributed system. Returns the existing system if it is currently connected.

getAdminDistributedSystem

public static com.gemstone.gemfire.admin.AdminDistributedSystem getAdminDistributedSystem()

Returns the admin distributed system if it is connected, otherwise null.

disconnectAdmin

public static void disconnectAdmin()

Disconnects the admin distributed system if it is connected.

adminToString

public static String adminToString(com.gemstone.gemfire.admin.AdminDistributedSystem ads)

Returns the given admin distributed system as a string.

getDistributedSystemId

public static int getDistributedSystemId(String distributedSystemName)

Returns the distributed system id for the given distributed system name.

getDistributedSystemName

public static String getDistributedSystemName(int distributedSystemId)

Returns the distributed system name for the given distributed system id.

getMembers

public static Set getMembers()

Returns a collection of the current distribution members. This excludes admin members and locators.

Throws:

HydraRuntimeException - if not currently connected.

See Also:

DistributedMember

getAdminMembers

public static Set getAdminMembers()

Returns a collection of the current admin distribution members.

Throws:

HydraRuntimeException - if not currently connected.

See Also:

DistributedMember

getDistributedSystemProperties

public static Properties getDistributedSystemProperties(String cacheXmlFile)

Returns distributed system properties using the optional cache XML file.

getAdminDescription

public static AdminDescription getAdminDescription(String adminConfig)

Returns the AdminDescription with the given configuration name from AdminPrms.names.

getGemFireDescription

public static GemFireDescription getGemFireDescription()

Returns the GemFireDescription for this VM, as specified by the system property GemFirePrms.GEMFIRE_NAME_PROPERTY. Also verifies that the configured host is local.

createLocator

public static void createLocator()

Creates a locator endpoint that this VM and other locator VMs in its distributed system can use when configuring their locator lists. The endpoint need only be created once.

Upon initial creation, selects a random port and registers the locator DistributedSystemHelper.Endpoint in the DistributedSystemBlackboard map. The locator will always use this port during startup.

All locators associated with a given distributed system must be created before locators are started, so that the locator list is complete. At least one locator must be started before non-locators can connect.

To start the locator, use startLocatorAndDS() or startLocatorAndAdminDS().

Throws:

HydraRuntimeException - if the VM already has a locator that did not create its endpoint using this method or if master is managing locators.

startLocatorAndDS

public static com.gemstone.gemfire.distributed.Locator startLocatorAndDS()

Starts the locator whose endpoint was created by createLocator() and connects it to a non-admin distributed system (it can create a cache). The locator is configured using the GemFireDescription corresponding to the logical gemfire configuration name from the system property GemFirePrms.GEMFIRE_NAME_PROPERTY. Returns the existing locator if it is already started.

At least one locator must be started before non-locators can connect.

When starting multiple locators, use synchronization to ensure that one locator starts up before the others, as a workaround for Bug 30341.

Throws:

HydraRuntimeException - if the VM is already connected or an attempt is made to reconfigure an existing locator.

startLocatorAndAdminDS

public static com.gemstone.gemfire.distributed.Locator startLocatorAndAdminDS()

Starts the locator whose endpoint was created by createLocator() and connects it to an admin distributed system (it cannot create a cache). The locator is configured using the GemFireDescription corresponding to the logical gemfire configuration name from the system property GemFirePrms.GEMFIRE_NAME_PROPERTY. Returns the existing locator if it is already started.

At least one locator must be started before non-locators can connect.

When starting multiple locators, use synchronization to ensure that one locator starts up before the others, as a workaround for Bug 30341.

Throws:

HydraRuntimeException - if the VM is already connected or an attempt is made to reconfigure an existing locator.

getLocator

public static com.gemstone.gemfire.distributed.Locator getLocator()

Returns the currently running locator, or null if no locator exists.

Throws:

HydraRuntimeException - if there are multiple locators.

stopLocator

public static void stopLocator()

Stops the currently running locator, if it exists.

locatorToString

public static String locatorToString(com.gemstone.gemfire.distributed.Locator locator)

Returns the given locator as a string.

getEndpoints

public static List getEndpoints()

Returns all peer locator endpoints from the DistributedSystemBlackboard map, a possibly empty list. This includes all peer locators that have ever started, regardless of their distributed system or current active status.

getSystemEndpoints

public static List getSystemEndpoints()

Returns all peer locator endpoints for this VM's distributed system from the DistributedSystemBlackboard map, a possibly empty list. This includes all peer locators that have ever started for this system, regardless of their current active status.

getEndpoints

public static List getEndpoints(String distributedSystemName)

Returns all peer locator endpoints for the specified distributed system from the DistributedSystemBlackboard map, a possibly empty list. This includes all peer locators that have ever started for the system, regardless of their current active status.

getContacts

public static List getContacts()

Returns all contacts (server locator endpoints) from the DistributedSystemBlackboard map, a possibly empty list. This includes all server locators that have ever started, regardless of their distributed system or current active status.

getSystemContacts

public static List getSystemContacts()

Returns all contacts (server locator endpoints) for this VM's distributed system from the DistributedSystemBlackboard map, a possibly empty list. This includes all server locators that have ever started for this system, regardless of their current active status.

getContacts

public static List getContacts(String distributedSystemName)

Returns all contacts (server locator endpoints) for the specified distributed system from the DistributedSystemBlackboard map, a possibly empty list. This includes all server locators that have ever started for the system, regardless of their current active status.

getContacts

public static List<String> getContacts(List<String> distributedSystemNames)

Returns all contacts (server locator endpoints) for the specified distributed systems from the DistributedSystemBlackboard map, a possibly empty list. This includes all server locators that have ever started for the system, regardless of their current active status.

endpointsToString

public static String endpointsToString(List endpoints)

Converts a list of locator endpoints to a locator string, or the empty string if the list is null.

endpointToString

public static String endpointToString(DistributedSystemHelper.Endpoint endpoint)

Converts a locator endpoint to a locator string, or the empty string if the endpoint is null.