Rio Project 4.2 API Documentation

org.rioproject.resources.client
Class JiniClient

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

public class JiniClient
extends Object

The JiniClient class is a helper class that Jini clients (or something that wants to act like a Jini client) uses to create DiscoveryManagement instances to discover services

Author:

Dennis Reedy

Nested Class Summary

class

JiniClient.Listener

Field Summary

static String	GROUPS_PROPERTY_NAME
JiniClient.Listener	listener
static String	LOCATOR_PROPERTY_NAME

Constructor Summary

JiniClient()
Create an instance of a JiniClient

JiniClient(DiscoveryManagement dm)
Create an instance of a JiniClient providing a DiscoveryManagement reference

Method Summary

void	addLocator(String locator) Add a Locator to discover.
void	addLocator(String host, int port) Add a Locator to discover.
void	addRegistrarGroups(String[] gAdd) Add a list of groups to be discovered If a DiscoveryManagement is provided to JiniClient and does not implement the DiscoveryGroupManagement interface, no action is taken
void	discardRegistrar(ServiceRegistrar registrar) Discard a ServiceRegistrar that had been previously discovered
static DiscoveryManagement	getDiscoveryManagement(ServiceElement sElem) Get a DiscoveryManagement instance from service attributes in a ServiceElement
DiscoveryManagement	getDiscoveryManager() Get the DiscoveryManagement instance
LookupLocator[]	getLocators() Get the array of known locators
static LookupCache	getLookupCache(ServiceBeanContext context) Get a LookupCache instance from service attributes in a ServiceBeanContext
static LookupCache	getLookupCache(ServiceBeanContext context, ClassLoader cl) Get a LookupCache instance from service attributes in a ServiceBeanContext
String[]	getRegistrarGroups() Get the known set of groups
ServiceRegistrar[]	getRegistrars() Get all ServiceRegistrar instances that have been discovered
static ServiceTemplate	getServiceTemplate(AssociationDescriptor aDesc) Create a ServiceTemplate from an AssociationDescriptor
static ServiceTemplate	getServiceTemplate(AssociationDescriptor aDesc, ClassLoader cl) Create a ServiceTemplate from an AssociationDescriptor
static ServiceTemplate	getServiceTemplate(ServiceElement sElem) Create a ServiceTemplate from a ServiceElement
static ServiceTemplate	getServiceTemplate(ServiceElement sElem, ClassLoader cl) Create a ServiceTemplate from a ServiceElement
static String[]	parseGroups(String groupNames) Parse a comma or space delimited string of group names
static LookupLocator[]	parseLocators(String locatorUrls) Parse a comma or space delimited string of locator urls
void	removeLocators(LookupLocator[] locators) Deletes a set of locators from the managed set of locators, and discards any already-discovered lookup service that corresponds to a deleted locator.
void	removeRegistrarGroups(String[] gRemove) Remove a list of groups from discovery management
void	terminate() Stop this JiniClient and terminate discovery management.
static String[]	transformGroupNames(String[] groups) Returns an array consisting of the names of the groups whose members are the lookup services to discover from an array of group names that may not map to Jini technology specific group name nuances

Methods inherited from class java.lang.Object

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

Field Detail

GROUPS_PROPERTY_NAME

public static final String GROUPS_PROPERTY_NAME

See Also:

Constant Field Values

LOCATOR_PROPERTY_NAME

public static final String LOCATOR_PROPERTY_NAME

See Also:

Constant Field Values

listener

public JiniClient.Listener listener

Constructor Detail

JiniClient

public JiniClient()
           throws Exception

Create an instance of a JiniClient

Throws:

Exception - if any errors occur

JiniClient

public JiniClient(DiscoveryManagement dm)
           throws Exception

Create an instance of a JiniClient providing a DiscoveryManagement reference

Parameters:

dm - The DiscoveryManagement instance to use. If the DiscoveryManagement object is null, JiniClient will look for 2 system properties to construct a DiscoveryManagement object:

• 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:

Exception - if any errors occur

Method Detail

parseGroups

public static String[] parseGroups(String groupNames)

Parse a comma or space delimited string of group names

Parameters:

groupNames - The string of group names to parse

Returns:

A string array of parsed group names as follows:

• If the group names parameter is null, return LookupDiscovery.NO_GROUPS.
• If the groupNames value is "all", return LookupDiscovery.ALL_GROUPS.
• If one of the groupNames value is "public", replace "public" with an empty string "".
• Otherwise add the groupName value as a element in the string array

parseLocators

public static LookupLocator[] parseLocators(String locatorUrls)
                                     throws MalformedURLException

Parse a comma or space delimited string of locator urls

Parameters:

locatorUrls - The string of locator urls to parse

Returns:

A LookupLocator array of parsed locator urls. If the locatorUrls parameter is null, return null

Throws:

MalformedURLException - If the locatorUrls contains a value that has an illegal format

transformGroupNames

public static String[] transformGroupNames(String[] groups)

Returns an array consisting of the names of the groups whose members are the lookup services to discover from an array of group names that may not map to Jini technology specific group name nuances

Parameters:

groups - String[] of group names to transform. Transformation is determined as follows:

• If the groups property is null or has a zero length, then the returned value is LookupDiscovery.NO_GROUPS
• If an element has the value of "all", that value will be transformed to LookupDiscovery.ALL_GROUPS
• If an element has the value of "public", that value is transformed to an empty string ""

Returns:

String array of groups

getServiceTemplate

public static ServiceTemplate getServiceTemplate(ServiceElement sElem)
                                          throws Exception

Create a ServiceTemplate from a ServiceElement

Parameters:

sElem - A ServiceElement

Returns:

A ServiceTemplate which can be used to discover the service

Throws:

Exception - If the interface class in the ServiceElement export bundle cannot be loaded

getServiceTemplate

public static ServiceTemplate getServiceTemplate(ServiceElement sElem,
                                                 ClassLoader cl)
                                          throws Exception

Create a ServiceTemplate from a ServiceElement

Parameters:

sElem - A ServiceElement

cl - The ClassLoader to use to load the interface class. If null, the threads context classloader will be used

Returns:

A ServiceTemplate which can be used to discover the service

Throws:

Exception - If the interface class in the ServiceElement export bundle cannot be loaded

getDiscoveryManagement

public static DiscoveryManagement getDiscoveryManagement(ServiceElement sElem)
                                                  throws IOException

Get a DiscoveryManagement instance from service attributes in a ServiceElement

Parameters:

sElem - A ServiceElement

Returns:

A DiscoveryManagement instance based on service discovery attributes

Throws:

IOException - If DiscoveryManagement cannot be created

getServiceTemplate

public static ServiceTemplate getServiceTemplate(AssociationDescriptor aDesc)
                                          throws Exception

Create a ServiceTemplate from an AssociationDescriptor

Parameters:

aDesc - The AssociationDescriptor

Returns:

A ServiceTemplate which can be used to discover the service

Throws:

Exception - If the interface class in the AssociationDescriptor cannot be loaded

getServiceTemplate

public static ServiceTemplate getServiceTemplate(AssociationDescriptor aDesc,
                                                 ClassLoader cl)
                                          throws Exception

Create a ServiceTemplate from an AssociationDescriptor

Parameters:

aDesc - The AssociationDescriptor

cl - The ClassLoader to use to load the interface class. If null, the threads context classloader will be used

Returns:

A ServiceTemplate which can be used to discover the service

Throws:

Exception - If the interface class cannot be loaded

getLookupCache

public static LookupCache getLookupCache(ServiceBeanContext context,
                                         ClassLoader cl)
                                  throws Exception

Get a LookupCache instance from service attributes in a ServiceBeanContext

Parameters:

context - A ServiceBeanContext

cl - The classloader to use. If null use the current context classloader

Returns:

A LookupCache instance from a pool of LookupCache instances based on ServiceBeanContext attributes

Throws:

Exception - If the LookupCache cannot be obtained

getLookupCache

public static LookupCache getLookupCache(ServiceBeanContext context)
                                  throws Exception

Get a LookupCache instance from service attributes in a ServiceBeanContext

Parameters:

context - A ServiceBeanContext

Returns:

A LookupCache instance from a pool of LookupCache instances based on ServiceBeanContext attributes

Throws:

Exception - If the LookupCache cannot be obtained

getDiscoveryManager

public DiscoveryManagement getDiscoveryManager()

Get the DiscoveryManagement instance

Returns:

Returns the instance of DiscoveryManagement that was either passed into the constructor, or that was created as a result of null being input to that parameter.

getRegistrars

public ServiceRegistrar[] getRegistrars()

Get all ServiceRegistrar instances that have been discovered

Returns:

An array of all discovered ServiceRegistrar instances

addLocator

public void addLocator(String locator)
                throws MalformedURLException

Add a Locator to discover. The method will construct a new LookupLocator object, set up to perform discovery to the given URL.

If a DiscoveryManagement is provided to JiniClient and does not implement the DiscoveryLocatorManagement interface, no action is taken

The URL in question must be of the form jini://host/ or jini://host:port/

Parameters:

locator - The locator url to add

Throws:

MalformedURLException - the URL passed in could not be parsed

addLocator

public void addLocator(String host,
                       int port)

Add a Locator to discover. The method will construct a new LookupLocator object, set to perform unicast discovery to the given host and port

If a DiscoveryManagement is provided to JiniClient and does not implement the DiscoveryLocatorManagement interface, no action is taken

Parameters:

host - The hostname part of the locator

port - The port name part of the locator

getLocators

public LookupLocator[] getLocators()

Get the array of known locators

Returns:

Returns an array consisting of the elements of the managed set of locators; that is, instances of LookupLocator in which each instance corresponds to a specific lookup service to discover. The returned set will include both the set of LookupLocators corresponding to lookup services that have already been discovered as well as the set of those that have not yet been discovered. If the managed set of locators is empty, this method will return the empty array. This method returns a new array upon each invocation.

If a DiscoveryManagement is provided to JiniClient and does not implement the DiscoveryLocatorManagement interface, this method will return null

removeLocators

public void removeLocators(LookupLocator[] locators)

Deletes a set of locators from the managed set of locators, and discards any already-discovered lookup service that corresponds to a deleted locator.

If a DiscoveryManagement is provided to JiniClient and does not implement the DiscoveryLocatorManagement interface, no action is taken

Parameters:

locators - Array of LookupLocator instances to remove

addRegistrarGroups

public void addRegistrarGroups(String[] gAdd)
                        throws IOException

Add a list of groups to be discovered

If a DiscoveryManagement is provided to JiniClient and does not implement the DiscoveryGroupManagement interface, no action is taken

Parameters:

gAdd - Array of group names to add

Throws:

IOException - if the groups could not be added

getRegistrarGroups

public String[] getRegistrarGroups()

Get the known set of groups

Returns:

Returns an array consisting of the elements of the managed set of groups; that is, the names of the groups whose members are the lookup services to discover. If the managed set of groups is empty, this method will return the empty array. If there is no managed set of groups, or network then null is returned; indicating that all groups are to be discovered. If for some reason network errors occur, null is returned.

removeRegistrarGroups

public void removeRegistrarGroups(String[] gRemove)

Remove a list of groups from discovery management

Parameters:

gRemove - The array of groups to remove

discardRegistrar

public void discardRegistrar(ServiceRegistrar registrar)

Discard a ServiceRegistrar that had been previously discovered

Parameters:

registrar - The ServiceRegistrar to discard

terminate

public void terminate()

Stop this JiniClient and terminate discovery management. This method will also terminate all ServiceCache instances that it has created