Rio Project 4.2 API Documentation

org.rioproject.resources.client
Class DiscoveryManagementPool

java.lang.Object
  org.rioproject.resources.client.DiscoveryManagementPool

public class DiscoveryManagementPool
extends Object

A strategy has been taken in an attempt to conserve resources in a multi-service JVM environment as it relates to DiscoveryManagement. The DiscoveryManagementPool class provides an approach that enables a caller to get an existing DiscoveryManagement instance from a pool of previously created DiscoveryManagement instances, instead of creating a new DiscoveryManagement instance, and going through the overhead of DiscoveryManagement creation and performing discovery each time a service is initialized.

The criteria for pooling of created DiscoveryManagement instances is to match groups, locators and a shared name. The default behavior for ServiceBeans is to use the OperationalString name as the shared name. Therefore all services instantiated in the same Cybernode, that are in the same OperationalString, which have the same DiscoveryManagement groups and locators, will share the same DiscoveryManagement instance.

Of course use of shared DiscoveryManagement instances must be used with care as changing the settings of a shared DiscoveryManagement instance may present problems for other users of that DiscoveryManagement instance.

As a deployer, if you want DiscoveryManagement sharing turned off for services, declaring the following will turn it off:

<ServiceBean Name="Does not share well" DiscoveryManagementPooling="no">

Author:

Dennis Reedy

Nested Class Summary

static class	DiscoveryManagementPool.DiscoveryControl Maintains a collection of LookupDiscoveryManager instances
static class	DiscoveryManagementPool.SharedDiscoveryManager The SharedDiscoveryManager extends LookupDiscoveryManager and maintains a reference counter for how many clients are sharing the instance.

Method Summary

DiscoveryManagement	getDiscoveryManager(String sharedName) This method will return an instance of DiscoveryManagement based on matching the shared name, groups and locators as criteria.
DiscoveryManagement	getDiscoveryManager(String sharedName, String[] groups, LookupLocator[] locators) This method will return an instance of DiscoveryManagement based on matching the shared name, groups and locators as criteria.
DiscoveryManagement	getDiscoveryManager(String sharedName, String[] groups, LookupLocator[] locators, DiscoveryListener listener, Configuration config) This method will return an instance of DiscoveryManagement based on matching the shared name, groups and locators as criteria.
static DiscoveryManagementPool	getInstance() Get the singleton instance of the DiscoveryManagementPool
void	setConfiguration(Configuration conf) Set the Configuration property
void	terminate() For all DiscoveryManagement instances this utility has created, terminate them and set the singleton instance to null;

Methods inherited from class java.lang.Object

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

Method Detail

getInstance

public static DiscoveryManagementPool getInstance()

Get the singleton instance of the DiscoveryManagementPool

Returns:

The singleton DiscoveryManagementPool instance

setConfiguration

public void setConfiguration(Configuration conf)

Set the Configuration property

Parameters:

conf - The Configuration to use when creating DiscoveryManagementPool instances

getDiscoveryManager

public DiscoveryManagement getDiscoveryManager(String sharedName)
                                        throws IOException

This method will return an instance of DiscoveryManagement based on matching the shared name, groups and locators as criteria. If there is an existing instance of DiscoveryManagement instantiated by this utility, that instance will be returned. Otherwise a new DiscoveryManagement instance will be created and returned

Note: Use of returned DiscoveryManagement instances must be used with care as changing the settings of the returned DiscoveryManagement instance may present problems for other users of DiscoveryManagement instance and is not advised.

Parameters:

sharedName - The name the DiscoveryManagement instances are shared across

Returns:

A DiscoveryManagement object suitable for lookup discovery management using the following system properties:

• org.rioproject.groups: a comma separated list of groups to use. If this property is not found LookupDiscoveryGroups will be set to LookupDiscovery.NO_GROUPS. Additionally, the value of "all" will be set to LookupDiscovery.ALL_GROUPS
• org.rioproject.locators: a comma separated list of LookupLocator formatted URLs
  Throws:
  IOException - If the DiscoveryManagement instance cannot be created

getDiscoveryManager

public DiscoveryManagement getDiscoveryManager(String sharedName,
                                               String[] groups,
                                               LookupLocator[] locators)
                                        throws IOException

This method will return an instance of DiscoveryManagement based on matching the shared name, groups and locators as criteria. If there is an existing instance of DiscoveryManagement instantiated by this utility, that instance will be returned. Otherwise a new DiscoveryManagement instance will be created and returned

Note: Use of returned DiscoveryManagement instances must be used with care as changing the settings of the returned DiscoveryManagement instance may present problems for other users of DiscoveryManagement instance and is not advised.

Parameters:

sharedName - The name the DiscoveryManagement instances are shared across

groups - An array of String objects indicating the Jini Lookup Service groups to discover

locators - An array of LookupLocator objects indicating specific Jini Lookup Service instances to discover

Returns:

A DiscoveryManagement object suitable for lookup discovery management based on provided parameters

Throws:

IOException - If the DiscoveryManagement instance cannot be created

getDiscoveryManager

public DiscoveryManagement getDiscoveryManager(String sharedName,
                                               String[] groups,
                                               LookupLocator[] locators,
                                               DiscoveryListener listener,
                                               Configuration config)
                                        throws IOException

This method will return an instance of DiscoveryManagement based on matching the shared name, groups and locators as criteria. If there is an existing instance of DiscoveryManagement instantiated by this utility, that instance will be returned. Otherwise a new DiscoveryManagement instance will be created and returned

Note: Use of returned DiscoveryManagement instances must be used with care as changing the settings of the returned DiscoveryManagement instance may present problems for other users of DiscoveryManagement instance and is not advised.

Parameters:

sharedName - The name the DiscoveryManagement instances are shared across

groups - An array of String objects indicating the Jini Lookup Service groups to discover

locators - An array of LookupLocator objects indicating specific Jini Lookup Service instances to discover

listener - A instance of a DiscoveryListener which will be notified when targeted Jini Lookup Services are discovered or discarded. If this parameter is not null, then it will be added to either the created or existing DiscoveryManagement instance

config - If a DiscoveryManagement instance needs to be created, the Configuration to use when creating the DiscoveryManagement instance

Returns:

A DiscoveryManagement object suitable for lookup discovery management based on provided parameters

Throws:

IOException - If the DiscoveryManagement instance cannot be created

terminate

public void terminate()

For all DiscoveryManagement instances this utility has created, terminate them and set the singleton instance to null;