jgroup.jini
Class JoinManager

java.lang.Object
  |
  +--jgroup.jini.JoinManager

public class JoinManager
extends java.lang.Object

A goal of any well-behaved service is to advertise the facilities and functions it provides by requesting residency within at least one lookup service. Making such a request of a lookup service is known as registering with, or "joining", a lookup service. To demonstrate this good behavior, a service must comply with both the multicast discovery protocol and the unicast discovery protocol in order to discover the lookup services it is interested in joining. The service must also comply with the join protocol to register with the desired lookup services.

In order for a service to maintain its residency in the lookup services it has joined, the service must provide for the coordination, systematic renewal, and overall management of all leases on that residency. In addition to handling all discovery and join duties, as well as managing all leases on lookup service residency, the service must also provide for the coordination and management of any attribute sets with which it may have registered with the lookup services in which it resides.

This class performs all of the functions related to discovery, joining, service lease renewal, and attribute management which is required of a well-behaved service. Each of these activities is intimately involved with the maintenance of a service's residency in one or more lookup services (the service's join state), thus the name JoinManager.

This class should be employed by services, not clients. The use of this class in a wide variety of services can help minimize the work resulting from having to repeatedly implement this required functionality in each service. Note that this class is not remote. Services that wish to use this class will create an instance of this class in the service's address space to manage the entity's join state locally.

Author:
Zane Pan
See Also:
net.jini.discovery.DiscoveryManagement, net.jini.lease.LeaseRenewalManager

Inner Class Summary
private  class JoinManager.addAttributesTask
           
private  class JoinManager.DiscardProxyTask
           
private  class JoinManager.DiscMgrListener
           
private  class JoinManager.LeaseExpireNotifyTask
           
private  class JoinManager.modifyAttributesTask
           
private  class JoinManager.ProxyReg
           
private  class JoinManager.RegisterTask
           
private  class JoinManager.setAttributesTask
           
private static interface JoinManager.Task
           
private  class JoinManager.TaskThread
           
 
Field Summary
private  boolean bCreateDiscMgr
           
private  boolean bTerminated
           
private  net.jini.lookup.ServiceIDListener callback
           
private  jgroup.jini.DiscoveryManagement discMgr
           
private  JoinManager.DiscMgrListener discMgrListener
           
private  java.util.ArrayList joinSet
           
private  jgroup.jini.LeaseRenewalManager leaseRenewalMgr
           
private  java.util.ArrayList listeners
           
private  net.jini.core.entry.Entry[] lookupAttr
           
private  jgroup.jini.ServiceItem serviceItem
           
private  java.util.ArrayList task
           
private  JoinManager.TaskThread taskThread
           
 
Constructor Summary
JoinManager(java.lang.Object obj, net.jini.core.entry.Entry[] attrSets, jgroup.jini.ServiceID serviceID, jgroup.jini.DiscoveryManagement discoverMgr, jgroup.jini.LeaseRenewalManager leaseMgr)
          Constructs an instance of this class that will register the service, using the supplied service ID, with the lookup services indicated through the discoveryMgr parameter.
JoinManager(java.lang.Object obj, net.jini.core.entry.Entry[] attrSets, net.jini.lookup.ServiceIDListener callback, jgroup.jini.DiscoveryManagement discoverMgr, jgroup.jini.LeaseRenewalManager leaseMgr)
          Constructs an instance of this class that will notify the service when a service ID is assigned by a lookup service with which the service is registered.
 
Method Summary
 void addAttributes(net.jini.core.entry.Entry[] attrSets)
          Associates a new set of attributes with the service, in addition to the service's current set of attributes.
 void addAttributes(net.jini.core.entry.Entry[] attrSets, boolean checkSC)
          Associates a new set of attributes with the service, in addition to the service's current set of attributes.
private  void addJoinSet(JoinManager.ProxyReg reg)
           
private  net.jini.core.lookup.ServiceRegistrar[] buildServiceRegistrar(java.util.ArrayList set)
           
private  void createJoinManager(jgroup.jini.ServiceID serviceID, java.lang.Object obj, net.jini.core.entry.Entry[] attrSets, net.jini.lookup.ServiceIDListener callback, jgroup.jini.LeaseRenewalManager leaseMgr)
           
private  void createTaskThread(JoinManager.Task t)
           
private  void discardedNotifyListener(net.jini.core.lookup.ServiceRegistrar proxy, java.util.ArrayList notifies)
           
private  void discoveredNotifyListener(net.jini.discovery.DiscoveryListener l, java.util.ArrayList set)
           
private  void discoveredNotifyListener(net.jini.core.lookup.ServiceRegistrar proxy, java.util.ArrayList notifies)
           
(package private)  JoinManager.ProxyReg findReg(net.jini.core.lookup.ServiceRegistrar proxy)
           
 net.jini.core.entry.Entry[] getAttributes()
          Returns an array containing the set of attributes currently associated with the service.
 jgroup.jini.DiscoveryManagement getDiscoveryManager()
          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.
 net.jini.core.lookup.ServiceRegistrar[] getJoinSet()
          Returns an array of ServiceRegistrar objects, each corresponding to a lookup service with which the service is currently registered (joined).
 jgroup.jini.LeaseRenewalManager getLeaseRenewalManager()
          Returns the instance of the LeaseRenewalManager class that was either passed into the constructor, or that was created as a result of null being input to that parameter.
 void modifyAttributes(net.jini.core.entry.Entry[] attrSetTemplates, net.jini.core.entry.Entry[] attrSets)
          Changes the service's current set of attributes using the same semantics as the modifyAttributes method of the ServiceRegistration class.
 void modifyAttributes(net.jini.core.entry.Entry[] attrSetTemplates, net.jini.core.entry.Entry[] attrSets, boolean checkSC)
          Changes the service's current set of attributes using the same semantics as the modifyAttributes method of the ServiceRegistration class.
private  void notifyListener(net.jini.core.lookup.ServiceRegistrar proxy, java.util.ArrayList notifies, boolean bDiscovered)
           
private  void removeJoinSet(JoinManager.ProxyReg reg)
           
 void setAttributes(net.jini.core.entry.Entry[] attrSets)
          Replaces the service's current set of attributes with a new set of attributes.
 void terminate()
          Performs cleanup duties related to the termination of the lookup service discovery event mechanism, as well as the lease and thread management performed by the JoinManager.
 
Methods inherited from class java.lang.Object
, clone, equals, finalize, getClass, hashCode, notify, notifyAll, registerNatives, toString, wait, wait, wait
 

Field Detail

callback

private net.jini.lookup.ServiceIDListener callback

lookupAttr

private net.jini.core.entry.Entry[] lookupAttr

serviceItem

private jgroup.jini.ServiceItem serviceItem

joinSet

private final java.util.ArrayList joinSet

listeners

private final java.util.ArrayList listeners

task

private final java.util.ArrayList task

taskThread

private JoinManager.TaskThread taskThread

leaseRenewalMgr

private jgroup.jini.LeaseRenewalManager leaseRenewalMgr

discMgr

private jgroup.jini.DiscoveryManagement discMgr

discMgrListener

private JoinManager.DiscMgrListener discMgrListener

bTerminated

private boolean bTerminated

bCreateDiscMgr

private boolean bCreateDiscMgr
Constructor Detail

JoinManager

public JoinManager(java.lang.Object obj,
                   net.jini.core.entry.Entry[] attrSets,
                   net.jini.lookup.ServiceIDListener callback,
                   jgroup.jini.DiscoveryManagement discoverMgr,
                   jgroup.jini.LeaseRenewalManager leaseMgr)
            throws java.io.IOException
Constructs an instance of this class that will notify the service when a service ID is assigned by a lookup service with which the service is registered. This constructor is typically used by services that have not yet been assigned a service ID, but which have been pre-configured to join lookup services that the service identifies through the initialization of a discovery manager.
Parameters:
obj - a reference to the service requesting the services of this class.
attrSets - array of Entry consisting of the attribute sets with which to register the service.
callback - a reference to an object that implements the ServiceIDListener interface, which will be sent an event containing the service ID assigned to the service by the lookup service.
discoverMgr - a reference to an object that implements the DiscoveryManagement interface which this class will use to manage the service's discovery duties. If null is input to this argument, an instance of the utility class LookupDiscoveryManager will be used to listen for events announcing the discovery of only those lookup services that are members of the public group.
leaseMgr - an instance of the LeaseRenewalManager utility class. If null is input to this argument, an instance of the LeaseRenewalManager class will be created, initially managing no leases. This feature allows a service that employs the JoinManager to use either a single entity to manage all of its leases, or to use separate entities: one to manage the leases unrelated to the join process, and one to manage the leases that result from the join process and which are accessible only within the
Throws:
java.io.IOException - because construction of this class may initiate the discovery process, which can throw an IOException when socket allocation occurs.
See Also:
ServiceIDListener, net.jini.discovery.DiscoveryManagement, net.jini.discovery.LookupDiscoveryManager, net.jini.lease.LeaseRenewalManager

JoinManager

public JoinManager(java.lang.Object obj,
                   net.jini.core.entry.Entry[] attrSets,
                   jgroup.jini.ServiceID serviceID,
                   jgroup.jini.DiscoveryManagement discoverMgr,
                   jgroup.jini.LeaseRenewalManager leaseMgr)
            throws java.io.IOException
Constructs an instance of this class that will register the service, using the supplied service ID, with the lookup services indicated through the discoveryMgr parameter. This constructor is typically used by services that have already been assigned a service ID (possibly by the service provider itself or as a result of a prior registration with some lookup service), and which may or may not have been pre-configured to join lookup services identified by group or by specific location.

Note that this form of the constructor applies the same semantics to the attrSets, discoveryMgr, and leaseMgr parameters as is applied by the first form of the constructor.

Parameters:
obj - a reference to the service requesting the services of this class.
attrSets - array of Entry consisting of the attribute sets with which to register the service.
serviceID - an instance of ServiceID with which to register the service with all desired lookup services
discoverMgr - a reference to an object that implements the DiscoveryManagement interface which this class will use to manage the service's discovery duties. If null is input to this argument, an instance of the utility class LookupDiscoveryManager will be used to listen for events announcing the discovery of only those lookup services that are members of the public group.
leaseMgr - an instance of the LeaseRenewalManager utility class. If null is input to this argument, an instance of the LeaseRenewalManager class will be created, initially managing no leases. This feature allows a service that employs the JoinManager to use either a single entity to manage all of its leases, or to use separate entities: one to manage the leases unrelated to the join process, and one to manage the leases that result from the join process and which are accessible only within the
Throws:
java.io.IOException - because construction of this class may initiate the discovery process, which can throw an IOException when socket allocation occurs.
See Also:
net.jini.core.lookup.ServiceID, net.jini.discovery.DiscoveryManagement, net.jini.discovery.LookupDiscoveryManager, net.jini.lease.LeaseRenewalManager
Method Detail

discoveredNotifyListener

private void discoveredNotifyListener(net.jini.discovery.DiscoveryListener l,
                                      java.util.ArrayList set)

buildServiceRegistrar

private net.jini.core.lookup.ServiceRegistrar[] buildServiceRegistrar(java.util.ArrayList set)

createJoinManager

private void createJoinManager(jgroup.jini.ServiceID serviceID,
                               java.lang.Object obj,
                               net.jini.core.entry.Entry[] attrSets,
                               net.jini.lookup.ServiceIDListener callback,
                               jgroup.jini.LeaseRenewalManager leaseMgr)
                        throws java.io.IOException

getDiscoveryManager

public jgroup.jini.DiscoveryManagement getDiscoveryManager()
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.

The object returned by this method encapsulates the mechanism by which either the JoinManager or the entity itself can set discovery listeners and discard previously discovered lookup services when they are found to be unavailable.

Returns:
the instance of the DiscoveryManagement interface that was either passed into the constructor, or that was created as a result of null being input to that parameter.
See Also:
net.jini.discovery.DiscoveryManagement, net.jini.discovery.LookupDiscoveryManager

getLeaseRenewalManager

public jgroup.jini.LeaseRenewalManager getLeaseRenewalManager()
Returns the instance of the LeaseRenewalManager class that was either passed into the constructor, or that was created as a result of null being input to that parameter.

The object returned by this method manages the leases requested and held by the JoinManager. Although it may also manage leases unrelated to the join process that are requested and held by the service itself, the leases with which the JoinManager is concerned are the leases that correspond to the service registration requests made with each lookup service the service wishes to join.

Returns:
the instance of the LeaseRenewalManager class that was either passed into the constructor, or that was created as a result of null being input to that parameter.
See Also:
net.jini.discovery.DiscoveryManagement, net.jini.lease.LeaseRenewalManager

getJoinSet

public net.jini.core.lookup.ServiceRegistrar[] getJoinSet()
Returns an array of ServiceRegistrar objects, each corresponding to a lookup service with which the service is currently registered (joined). If there are no lookup services with which the service is currently registered, this method returns the empty array. This method returns a new array upon each invocation.
Returns:
array of instances of ServiceRegistrar, each corresponding to a lookup service with which the service is currently registered
See Also:
ServiceRegistrar

getAttributes

public net.jini.core.entry.Entry[] getAttributes()
Returns an array containing the set of attributes currently associated with the service. If the service is not currently associated with an attribute set, this method returns the empty array. This method returns a new array upon each invocation.
Returns:
array of instances of Entry consisting of the set of attributes with which the service is registered in each lookup service that it has joined
See Also:
Entry, setAttributes(net.jini.core.entry.Entry[])

addAttributes

public void addAttributes(net.jini.core.entry.Entry[] attrSets)
Associates a new set of attributes with the service, in addition to the service's current set of attributes. The association of this new set of attributes with the service will be propagated to each lookup service with which the service is registered. Note that this propagation is performed asynchronously, thus there is no guarantee that the propagation of the attributes to all lookup services with which the service is registered will have completed upon return from this method.

An invocation of this method with duplicate elements in the attrSets parameter (where duplication means attribute equality as defined by calling the MarshalledObject.equals method on field values) is equivalent to performing the invocation with the duplicates removed from that parameter.

Note that because there is no guarantee that attribute propagation will have completed upon return from this method, services that invoke this method must take care not to modify the contents of the attrSets parameter. Doing so could cause the service's attribute state to be corrupted or inconsistent on a subset of the lookup services with which the service is registered as compared with the state reflected on the remaining lookup services. It is for this reason that the effects of modifying the contents of the attrSets parameter, after this method is invoked, are undefined.

Parameters:
attrSets - array of Entry consisting of the attribute sets with which to augment the service's current set of attributes
Throws:
java.lang.NullPointerException - this exception occurs when either null is input to the attrSets parameter, or one or more of the elements of the attrSets parameter is null.
See Also:
Entry

addAttributes

public void addAttributes(net.jini.core.entry.Entry[] attrSets,
                          boolean checkSC)
Associates a new set of attributes with the service, in addition to the service's current set of attributes. The association of this new set of attributes with the service will be propagated to each lookup service with which the service is registered. Note that this propagation is performed asynchronously, thus there is no guarantee that the propagation of the attributes to all lookup services with which the service is registered will have completed upon return from this method.

An invocation of this method with duplicate elements in the attrSets parameter (where duplication means attribute equality as defined by calling the MarshalledObject.equals method on field values) is equivalent to performing the invocation with the duplicates removed from that parameter.

Note that because there is no guarantee that attribute propagation will have completed upon return from this method, services that invoke this method must take care not to modify the contents of the attrSets parameter. Doing so could cause the service's attribute state to be corrupted or inconsistent on a subset of the lookup services with which the service is registered as compared with the state reflected on the remaining lookup services. It is for this reason that the effects of modifying the contents of the attrSets parameter, after this method is invoked, are undefined.

A service typically employs this version of addAttributes to prevent clients or other services from attempting to add what are referred to as "service controlled attributes" to the service's set. A service controlled attribute is an attribute that implements the ServiceControlled marker interface.

Consider a printer service. With printers, there are often times error conditions, that only the printer can detect (for example, a paper jam or a toner low condition). To report conditions such as these to interested parties, the printer typically adds an attribute to its attribute set, resulting in an event being sent that notifies clients that have registered interest in such events. When the condition is corrected, the printer would then remove the attribute from its set by invoking the modifyAttributes method in the appropriate manner.

Attributes representing conditions that only the service can know about or control are good candidates for being defined as service controlled attributes. That is, the service provider (the developer of the printer service for example) would define the attributes that represent conditions such as those just described to implement the ServiceControlled marker interface. Thus, when other entities attempt to add new attributes, services that wish to employ such service controlled attributes should ultimately invoke only this version of addAttributes (with the checkSC parameter set to true), resulting in a SecurityException if any of the attributes being added happen to be service controlled attributes. In this way, only the printer itself would be able to set a "paper jammed" or "toner low" attribute, not some arbitrary client.

Parameters:
attrSets - array of Entry consisting of the attribute sets with which to augment the service's current set of attributes
checkSC - boolean flag indicating whether the elements of the set of attributes to add should be checked to determine if they are service controlled attributes
Throws:
java.lang.NullPointerException - this exception occurs when either null is input to the attrSets parameter, or one or more of the elements of the attrSets parameter is null.
java.lang.SecurityException - this exception occurs when the checkSC parameter is true, and at least one of the attributes to be added is an instance of the ServiceControlled marker interface.
See Also:
Entry, net.jini.lookup.entry.ServiceControlled

setAttributes

public void setAttributes(net.jini.core.entry.Entry[] attrSets)
Replaces the service's current set of attributes with a new set of attributes. The association of this new set of attributes with the service will be propagated to each lookup service with which the service is registered. Note that this propagation is performed asynchronously, thus there is no guarantee that the propagation of the attributes to all lookup services with which the service is registered will have completed upon return from this method.

An invocation of this method with duplicate elements in the attrSets parameter (where duplication means attribute equality as defined by calling the MarshalledObject.equals method on field values) is equivalent to performing the invocation with the duplicates removed from that parameter.

Note that because there is no guarantee that attribute propagation will have completed upon return from this method, services that invoke this method must take care not to modify the contents of the attrSets parameter. Doing so could cause the service's attribute state to be corrupted or inconsistent on a subset of the lookup services with which the service is registered as compared with the state reflected on the remaining lookup services. It is for this reason that the effects of modifying the contents of the attrSets parameter, after this method is invoked, are undefined.

Parameters:
attrSets - array of Entry consisting of the attribute sets with which to replace the service's current set of attributes
Throws:
java.lang.NullPointerException - this exception occurs when at least one of the elements of the attrSets parameter is null.
See Also:
Entry, getAttributes()

modifyAttributes

public void modifyAttributes(net.jini.core.entry.Entry[] attrSetTemplates,
                             net.jini.core.entry.Entry[] attrSets)
Changes the service's current set of attributes using the same semantics as the modifyAttributes method of the ServiceRegistration class.

The association of the new set of attributes with the service will be propagated to each lookup service with which the service is registered. Note that this propagation is performed asynchronously, thus there is no guarantee that the propagation of the attributes to all lookup services with which the service is registered will have completed upon return from this method.

Note that if the length of the array containing the templates does not equal the length of the array containing the modifications, an IllegalArgumentException will be thrown and propagated through this method.

Note also that because there is no guarantee that attribute propagation will have completed upon return from this method, services that invoke this method must take care not to modify the contents of the attrSets parameter. Doing so could cause the service's attribute state to be corrupted or inconsistent on a subset of the lookup services with which the service is registered as compared with the state reflected on the remaining lookup services. It is for this reason that the effects of modifying the contents of the attrSets parameter, after this method is invoked, are undefined.

Parameters:
attrSetTemplates - array of Entry used to identify which elements to modify from the service's current set of attributes
attrSets - array of Entry containing the actual modifications to make in the matching sets found using the attrSetTemplates parameter
Throws:
java.lang.IllegalArgumentException - this exception occurs when the array containing the templates does not equal the length of the array containing the modifications.
See Also:
Entry, net.jini.core.lookup.ServiceRegistration#modifyAttributes

modifyAttributes

public void modifyAttributes(net.jini.core.entry.Entry[] attrSetTemplates,
                             net.jini.core.entry.Entry[] attrSets,
                             boolean checkSC)
Changes the service's current set of attributes using the same semantics as the modifyAttributes method of the ServiceRegistration class.

The association of the new set of attributes with the service will be propagated to each lookup service with which the service is registered. Note that this propagation is performed asynchronously, thus there is no guarantee that the propagation of the attributes to all lookup services with which the service is registered will have completed upon return from this method.

Note that if the length of the array containing the templates does not equal the length of the array containing the modifications, an IllegalArgumentException will be thrown and propagated through this method.

Note also that because there is no guarantee that attribute propagation will have completed upon return from this method, services that invoke this method must take care not to modify the contents of the attrSets parameter. Doing so could cause the service's attribute state to be corrupted or inconsistent on a subset of the lookup services with which the service is registered as compared with the state reflected on the remaining lookup services. It is for this reason that the effects of modifying the contents of the attrSets parameter, after this method is invoked, are undefined.

A service typically employs this version of modifyAttributes to prevent clients or other services from attempting to modify what are referred to as "service controlled attributes" in the service's set. A service controlled attribute is an attribute that implements the ServiceControlled marker interface.

Attributes representing conditions that only the service can know about or control are good candidates for being defined as service controlled attributes. When other entities attempt to modify a service's attributes, if the service wishes to employ such service controlled attributes, the service should ultimately invoke only this version of modifyAttributes (with the checkSC parameter set to true), resulting in a SecurityException if any of the attributes being modified happen to be service controlled attributes.

Parameters:
attrSetTemplates - array of Entry used to identify which elements to modify from the service's current set of attributes
attrSets - array of Entry containing the actual modifications to make in the matching sets found using the attrSetTemplates parameter
checkSC - boolean flag indicating whether the elements of the set of attributes to modify should be checked to determine if they are service controlled attributes
Throws:
java.lang.IllegalArgumentException - this exception occurs when the array containing the templates does not equal the length of the array containing the modifications.
java.lang.SecurityException - this exception occurs when the checkSC parameter is true, and at least one of the attributes to be modified is an instance of the ServiceControlled marker interface.
See Also:
Entry, net.jini.core.lookup.ServiceRegistration#modifyAttributes, net.jini.lookup.entry.ServiceControlled

terminate

public void terminate()
Performs cleanup duties related to the termination of the lookup service discovery event mechanism, as well as the lease and thread management performed by the JoinManager. This method will cancel all of the service's managed leases that were granted by the lookup services with which the service is registered, and will terminate all threads that have been created.

Note that if the discovery manager employed by the instance of this class that is being terminated was created by the instance itself, this method will terminate all discovery processing being performed by that manager object on behalf of the service; otherwise, the discovery manager supplied by the service is still valid.

Whether an instance of the LeaseRenewalManager class was supplied by the service or created by the JoinManager itself, any reference to that object obtained by the service prior to termination will still be valid after termination. Note also this class makes certain concurrency guarantees with respect to an invocation of the terminate method while other method invocations are in progress. The termination process will not begin until completion of all invocations of the methods defined in the public interface of this class. Furthermore, once the termination process has begun, no further remote method invocations will be made by this class, and all other method invocations made on this class will not return until the termination process has completed.

Upon completion of the termination process, the semantics of all current and future method invocations on the instance of this class that was just terminated are undefined; although the reference to the LeaseRenewalManager object employed by that instance of JoinManager is still valid.


createTaskThread

private void createTaskThread(JoinManager.Task t)

addJoinSet

private void addJoinSet(JoinManager.ProxyReg reg)

removeJoinSet

private void removeJoinSet(JoinManager.ProxyReg reg)

discoveredNotifyListener

private void discoveredNotifyListener(net.jini.core.lookup.ServiceRegistrar proxy,
                                      java.util.ArrayList notifies)

discardedNotifyListener

private void discardedNotifyListener(net.jini.core.lookup.ServiceRegistrar proxy,
                                     java.util.ArrayList notifies)

notifyListener

private void notifyListener(net.jini.core.lookup.ServiceRegistrar proxy,
                            java.util.ArrayList notifies,
                            boolean bDiscovered)

findReg

JoinManager.ProxyReg findReg(net.jini.core.lookup.ServiceRegistrar proxy)