net.jini.lookup

Class JoinManager

java.lang.Object

net.jini.lookup.JoinManager

public class JoinManager
extends 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:

Sun Microsystems, Inc.

See Also:

DiscoveryManagement, LeaseRenewalManager, Level, Logger

Implementation Specifics:

The following implementation-specific items are discussed below:

• Configuring JoinManager
• Logging

Configuring JoinManager

This implementation of JoinManager supports the following configuration entries; where each configuration entry name is associated with the component name net.jini.lookup.JoinManager. Note that the configuration entries specified here are specific to this implementation of JoinManager. Unless otherwise stated, each entry is retrieved from the configuration only once per instance of this utility, where each such retrieval is performed in the constructor.

•	discoveryManager
	Type:	DiscoveryManagement
	Default:	new LookupDiscoveryManager( new java.lang.String[] {""}, new LookupLocator[0], null, config)
	Description:	The object used to manage the discovery processing performed by this utility. This entry will be retrieved from the configuration only if no discovery manager is specified in the constructor. Note that this object should not be shared with other components in the application that employs this utility.

•	leaseManager
	Type:	LeaseRenewalManager
	Default:	new LeaseRenewalManager(config)
	Description:	The object used to manage each service lease returned to this utility when the service is registered with the the various discovered lookup services. This entry will be retrieved from the configuration only if no lease renewal manager is specified in the constructor.

•	maxLeaseDuration
	Type:	long
	Default:	Lease.FOREVER
	Description:	The maximum lease duration (in milliseconds) that is requested from each discovered lookup service on behalf of the service; both when the lease is initially requested, as well as when renewal of that lease is requested. Note that as this value is made smaller, renewal requests will be made more frequently while the service is up, and lease expiration will occur sooner when the service goes down.

•	registrarPreparer
	Type:	ProxyPreparer
	Default:	new BasicProxyPreparer()
	Description:	Preparer for the proxies to the lookup services that are discovered and used by this utility. The following methods of the proxy returned by this preparer are invoked by this utility: register

•	registrationPreparer
	Type:	ProxyPreparer
	Default:	new BasicProxyPreparer()
	Description:	Preparer for the proxies to the registrations returned to this utility upon registering the service with each discovered lookup service. The following methods of the proxy returned by this preparer are invoked by this utility: getServiceID getLease addAttributes modifyAttributes setAttributes

•	serviceLeasePreparer
	Type:	ProxyPreparer
	Default:	new BasicProxyPreparer()
	Description:	Preparer for the leases returned to this utility through the registrations with each discovered lookup service with which this utility has registered the service. Currently, none of the methods on the service lease returned by this preparer are invoked by this implementation of the utility.

•	executorService
	Type:	ExecutorService
	Default:	new ThreadPoolExecutor( 15, 15, 15, TimeUnit.SECONDS, new LinkedBlockingQueue(), new NamedThreadFactory("JoinManager executor thread", false))
	Description:	The object that pools and manages the various threads executed by this utility. This object should not be shared with other components in the application that employs this utility.

•	wakeupManager
	Type:	WakeupManager
	Default:	new WakeupManager(new WakeupManager.ThreadDesc(null,true))
	Description:	Object that pools and manages the various tasks that are initially executed by the object corresponding to the executorService entry of this component, but which fail during that initial execution. This object schedules the re-execution of such a failed task - in the executorService object - at various times in the future, until either the task succeeds or the task has been executed the maximum number of allowable times, corresponding to the wakeupRetries entry of this component. This object should not be shared with other components in the application that employs this utility.

•	wakeupRetries
	Type:	int
	Default:	6
	Description:	The maximum number of times a failed task is allowed to be executed by the object corresponding to the wakeupManager entry of this component.

Logging

This implementation of JoinManager uses the Logger named net.jini.lookup.JoinManager to log information at the following logging levels:

net.jini.lookup.JoinManager

Level	Description
INFO	when a task is stopped because of a definite exception
INFO	when a task is stopped because it has exceeded the maximum number of times the task is allowed to be tried/re-tried
INFO	when any exception occurs while attempting to prepare a proxy
FINER	when any exception (other than the more serious exceptions logged at higher levels) occurs in a task
FINEST	when an IllegalStateException occurs upon attempting to discard a lookup service
FINEST	whenever any task is started
FINEST	whenever any task completes successfully
FINEST	whenever a proxy is prepared

Constructor Summary

Constructors

Constructor and Description
JoinManager(Object serviceProxy, Entry[] attrSets, ServiceID serviceID, DiscoveryManagement discoveryMgr, LeaseRenewalManager leaseMgr) Constructs an instance of this class that will register the service with all discovered lookup services, using the supplied ServiceID.
JoinManager(Object serviceProxy, Entry[] attrSets, ServiceID serviceID, DiscoveryManagement discoveryMgr, LeaseRenewalManager leaseMgr, Configuration config) Constructs an instance of this class, configured using the items retrieved through the given Configuration, that will register the service with all discovered lookup services, using the supplied ServiceID.
JoinManager(Object serviceProxy, Entry[] attrSets, ServiceIDListener callback, DiscoveryManagement discoveryMgr, LeaseRenewalManager leaseMgr) Constructs an instance of this class that will register the given service reference with all discovered lookup services and, through an event sent to the given ServiceIDListener object, communicate the service ID assigned by the first lookup service with which the service is registered.
JoinManager(Object serviceProxy, Entry[] attrSets, ServiceIDListener callback, DiscoveryManagement discoveryMgr, LeaseRenewalManager leaseMgr, Configuration config) Constructs an instance of this class, configured using the items retrieved through the given Configuration object, that will register the given service reference with all discovered lookup services and, through an event sent to the given ServiceIDListener object, communicate the service ID assigned by the first lookup service with which the service is registered.

Method Summary

Modifier and Type	Method and Description
void	addAttributes(Entry[] attrSets) Associates a new set of attributes with the service, in addition to the service's current set of attributes.
void	addAttributes(Entry[] attrSets, boolean checkSC) Associates a new set of attributes with the service, in addition to the service's current set of attributes.
Entry[]	getAttributes() Returns an array containing the set of attributes currently associated with the service.
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.
ServiceRegistrar[]	getJoinSet() Returns an array of ServiceRegistrar objects, each corresponding to a lookup service with which the service is currently registered (joined).
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(Entry[] attrSetTemplates, Entry[] attrSets) Changes the service's current set of attributes using the same semantics as the modifyAttributes method of the ServiceRegistration class.
void	modifyAttributes(Entry[] attrSetTemplates, Entry[] attrSets, boolean checkSC) Changes the service's current set of attributes using the same semantics as the modifyAttributes method of the ServiceRegistration class.
void	replaceRegistration(Object serviceProxy) Registers a new reference to the service with all current and future discovered lookup services.
void	replaceRegistration(Object serviceProxy, Entry[] attrSets) Registers a new reference to the service with all current and future discovered lookup services, applying semantics identical to the one-argument form of this method, except with respect to the registration of the given attribute sets.
void	setAttributes(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, toString, wait, wait, wait

Constructor Detail

JoinManager

public JoinManager(Object serviceProxy,
                   Entry[] attrSets,
                   ServiceIDListener callback,
                   DiscoveryManagement discoveryMgr,
                   LeaseRenewalManager leaseMgr)
            throws IOException

Constructs an instance of this class that will register the given service reference with all discovered lookup services and, through an event sent to the given ServiceIDListener object, communicate the service ID assigned by the first lookup service with which the service is registered. This constructor is typically used by services which have not yet been assigned a service ID.

The value input to the serviceProxy parameter represents the service reference (proxy) to register with each discovered lookup service. If the Object input to that parameter is not Serializable, an IllegalArgumentException is thrown. If null is input to that parameter, a NullPointerException is thrown.

The value input to the attrSets parameter is an array of Entry objects, none of whose elements may be null, that represents the new set of attributes to associate with the new service reference to be registered. Passing null as the value of the attrSets parameter is equivalent to passing an empty array. If any of the elements of the attrSets array are null, a NullPointerException is thrown. The set of attributes passed in this parameter will be associated with the service in all future join processing until those attributes are changed through an invocation of a method on this class such as, addAttributes, setAttributes, modifyAttributes, or replaceRegistration.

When constructing this utility, the service supplies an object through which notifications that indicate a lookup service has been discovered or discarded will be received. At a minimum, the object supplied (through the discoveryMgr parameter) must satisfy the contract defined in the DiscoveryManagement interface. That is, the object supplied must provide this utility with the ability to set discovery listeners and to discard previously discovered lookup services when they are found to be unavailable. A value of null may be input to the discoveryMgr parameter. When null is input to that parameter, an instance of LookupDiscoveryManager is used to listen for events announcing the discovery of only those lookup services that are members of the public group.

The object input to the leaseMgr parameter provides for the coordination, systematic renewal, and overall management of all leases on the given service reference's residency in the lookup services that have been joined. As with the discoveryMgr parameter, a value of null may be input to this parameter. When null is input to this parameter, an instance of LeaseRenewalManager, initially managing no Lease objects will be used. This feature allows a service to either use 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, that are accessible only within the current instance of the JoinManager.

Parameters:

serviceProxy - the service reference (proxy) to register with all discovered lookup services

attrSets - array of Entry consisting of the attribute sets with which to register the service

callback - reference to the object that should receive the event containing the service ID, assigned to the service by the first lookup service with which the service reference is registered

discoveryMgr - reference to the DiscoveryManagement object this class should use to manage lookup service discovery on behalf of the given service

leaseMgr - reference to the LeaseRenewalManager object this class should use to manage the leases on the given service's residency in the lookup services that have been joined

Throws:

IllegalArgumentException - if the object input to the serviceProxy parameter is not serializable

NullPointerException - if either null is input to the serviceProxy parameter, or at least one of the elements of the attrSets parameter is null

IOException - if initiation of discovery process results in IOException when socket allocation occurs

IllegalStateException - if this method is called on a terminated JoinManager instance. Note that this exception is implementation-specific.

See Also:

ServiceIDListener, DiscoveryManagement, LookupDiscoveryManager, LeaseRenewalManager

JoinManager

public JoinManager(Object serviceProxy,
                   Entry[] attrSets,
                   ServiceIDListener callback,
                   DiscoveryManagement discoveryMgr,
                   LeaseRenewalManager leaseMgr,
                   Configuration config)
            throws IOException,
                   ConfigurationException

Constructs an instance of this class, configured using the items retrieved through the given Configuration object, that will register the given service reference with all discovered lookup services and, through an event sent to the given ServiceIDListener object, communicate the service ID assigned by the first lookup service with which the service is registered. This constructor is typically used by services which have not yet been assigned a service ID, and which wish to allow for deployment-time configuration of the service's join processing.

The items used to configure the current instance of this class are obtained through the object input to the config parameter. If null is input to that parameter, a NullPointerException is thrown.

The object this utility will use to manage lookup service discovery on behalf of the given service can be supplied through either the discoveryMgr parameter or through an entry contained in the given Configuration. If null is input to the discoveryMgr parameter, an attempt will first be made to retrieve from the given Configuration, an entry named "discoveryManager" (described above). If such an object is successfully retrieved from the given Configuration, that object will be used to perform the lookup service discovery management required by this utility.

If null is input to the discoveryMgr parameter, and no entry named "discoveryManager" is specified in the given Configuration, then 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.

As with the discoveryMgr parameter, the object this utility will use to perform lease management on behalf of the given service can be supplied through either the leaseMgr parameter or through an entry contained in the given Configuration. If null is input to the leaseMgr parameter, an attempt will first be made to retrieve from the given Configuration, an entry named "leaseManager" (described above). If such an object is successfully retrieved from the given Configuration, that object will be used to perform the lease management required by this utility.

If null is input to the leaseMgr parameter, and no entry named "leaseManager" is specified in the given Configuration, then an instance of the utility class LeaseRenewalManager that takes the given Configuration will be created (initially managing no leases) and used to perform all required lease renewal management on behalf of the given service.

Except for the config parameter and the additional semantics imposed by that parameter (as noted above), all other parameters of this form of the constructor, along with their associated semantics, are identical to that of the five-argument constructor that takes a ServiceIDListener.

Parameters:

serviceProxy - the service reference (proxy) to register with all discovered lookup services

attrSets - array of Entry consisting of the attribute sets with which to register the service

callback - reference to the ServiceIDListener object that should receive the event containing the service ID assigned to the service by the first lookup service with which the service reference is registered

discoveryMgr - reference to the DiscoveryManagement object this class should use to manage lookup service discovery on behalf of the given service

leaseMgr - reference to the LeaseRenewalManager object this class should use to manage the leases on the given service's residency in the lookup services that have been joined

config - instance of Configuration through which the items used to configure the current instance of this class are obtained

Throws:

IllegalArgumentException - if the object input to the serviceProxy parameter is not serializable

NullPointerException - if null is input to the serviceProxy parameter or the config parameter, or if at least one of the elements of the attrSets parameter is null

IOException - if initiation of discovery process results in IOException when socket allocation occurs

ConfigurationException - if an exception occurs while retrieving an item from the given Configuration object

IllegalStateException - if this method is called on a terminated JoinManager instance. Note that this exception is implementation-specific.

See Also:

ServiceIDListener, DiscoveryManagement, LookupDiscoveryManager, LeaseRenewalManager, Configuration, ConfigurationException

JoinManager

public JoinManager(Object serviceProxy,
                   Entry[] attrSets,
                   ServiceID serviceID,
                   DiscoveryManagement discoveryMgr,
                   LeaseRenewalManager leaseMgr)
            throws IOException

Constructs an instance of this class that will register the service with all discovered lookup services, using the supplied ServiceID. This constructor is typically used by services which 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 do not wish to allow for deployment-time configuration of the service's join processing.

Except that the desired ServiceID is supplied through the serviceID parameter rather than through a notification sent to a ServiceIDListener, all other parameters of this form of the constructor, along with their associated semantics, are identical to that of the five-argument constructor that takes a ServiceIDListener.

Parameters:

serviceProxy - 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

discoveryMgr - reference to the DiscoveryManagement object this class should use to manage the given service's lookup service discovery duties

leaseMgr - reference to the LeaseRenewalManager object this class should use to manage the leases on the given service's residency in the lookup services that have been joined

Throws:

IllegalArgumentException - if the object input to the serviceProxy parameter is not serializable

NullPointerException - if either null is input to the serviceProxy parameter, or at least one of the elements of the attrSets parameter is null

IOException - if initiation of discovery process results in IOException when socket allocation occurs

IllegalStateException - if this method is called on a terminated JoinManager instance. Note that this exception is implementation-specific.

See Also:

ServiceID, DiscoveryManagement, LookupDiscoveryManager, LeaseRenewalManager

JoinManager

public JoinManager(Object serviceProxy,
                   Entry[] attrSets,
                   ServiceID serviceID,
                   DiscoveryManagement discoveryMgr,
                   LeaseRenewalManager leaseMgr,
                   Configuration config)
            throws IOException,
                   ConfigurationException

Constructs an instance of this class, configured using the items retrieved through the given Configuration, that will register the service with all discovered lookup services, using the supplied ServiceID. This constructor is typically used by services which 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 wish to allow for deployment-time configuration of the service's join processing.

The items used to configure the current instance of this class are obtained through the object input to the config parameter. If null is input to that parameter, a NullPointerException is thrown.

Except that the desired ServiceID is supplied through the serviceID parameter rather than through a notification sent to a ServiceIDListener, all other parameters of this form of the constructor, along with their associated semantics, are identical to that of the six-argument constructor that takes a ServiceIDListener.

Parameters:

serviceProxy - 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

discoveryMgr - reference to the DiscoveryManagement object this class should use to manage lookup service discovery on behalf of the given service

leaseMgr - reference to the LeaseRenewalManager object this class should use to manage the leases on the given service's residency in the lookup services that have been joined

config - instance of Configuration through which the items used to configure the current instance of this class are obtained

Throws:

IllegalArgumentException - if the object input to the serviceProxy parameter is not serializable

NullPointerException - if null is input to the serviceProxy parameter or the config parameter, or if at least one of the elements of the attrSets parameter is null

IOException - if initiation of discovery process results in IOException when socket allocation occurs

ConfigurationException - if an exception occurs while retrieving an item from the given Configuration object

IllegalStateException - if this method is called on a terminated JoinManager instance. Note that this exception is implementation-specific.

See Also:

ServiceID, DiscoveryManagement, LookupDiscoveryManager, LeaseRenewalManager, Configuration, ConfigurationException

Method Detail

getDiscoveryManager

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

DiscoveryManagement, LookupDiscoveryManager

getLeaseRenewalManager

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

DiscoveryManagement, LeaseRenewalManager

getJoinSet

public 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 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(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:

NullPointerException - if 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(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:

NullPointerException - if either null is input to the attrSets parameter, or one or more of the elements of the attrSets parameter is null

SecurityException - if 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, ServiceControlled

setAttributes

public void setAttributes(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:

NullPointerException - if either null is input to the attrSets parameter, or one or more of the elements of the attrSets parameter is null.

See Also:

Entry, getAttributes()

modifyAttributes

public void modifyAttributes(Entry[] attrSetTemplates,
                             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:

IllegalArgumentException - if the array containing the templates does not equal the length of the array containing the modifications

See Also:

Entry, ServiceRegistration.modifyAttributes(net.jini.core.entry.Entry[], net.jini.core.entry.Entry[])

modifyAttributes

public void modifyAttributes(Entry[] attrSetTemplates,
                             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:

IllegalArgumentException - if the array containing the templates does not equal the length of the array containing the modifications

SecurityException - if 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, ServiceRegistration.modifyAttributes(net.jini.core.entry.Entry[], net.jini.core.entry.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.

replaceRegistration

public void replaceRegistration(Object serviceProxy)

Registers a new reference to the service with all current and future discovered lookup services. The new service reference will replace the reference that was previously registered as a result of either constructing this utility, or a prior invocation of one of the forms of this method. The new service reference will be registered using the same ServiceID with which previous registrations were made through this utility.

The value input to the serviceProxy parameter represents the new service reference (proxy) to register with each discovered lookup service. If the Object input to that parameter is not Serializable, an IllegalArgumentException is thrown. If null is input to that parameter, a NullPointerException is thrown.

The attribute sets that this method associates with the new service reference are the same attribute sets as those associated with the old registration.

Parameters:

serviceProxy - the new service reference (proxy) to register with all current and future discovered lookup services

Throws:

IllegalArgumentException - if the object input to the serviceProxy parameter is not serializable

NullPointerException - if null is input to the serviceProxy parameter

IllegalStateException - if this method is called on a terminated JoinManager instance. Note that this exception is implementation-specific.

replaceRegistration

public void replaceRegistration(Object serviceProxy,
                                Entry[] attrSets)

Registers a new reference to the service with all current and future discovered lookup services, applying semantics identical to the one-argument form of this method, except with respect to the registration of the given attribute sets.

This form of replaceRegistration takes as its second parameter, an array of Entry objects (attrSets), none of whose elements may be null, that represents the new set of attributes to associate with the new service reference to be registered. As with the constructor to this utility, passing null as the value of the attrSets parameter is equivalent to passing an empty array. If any of the elements of attrSets are null, a NullPointerException is thrown. This new set of attributes will be associated with the service in all future join processing.

Parameters:

serviceProxy - the new service reference (proxy) to register with all current and future discovered lookup services

attrSets - array of Entry consisting of the attribute sets with which to register the new service reference. Passing null as the value of this parameter is equivalent to passing an empty Entry array

Throws:

IllegalArgumentException - if the object input to the serviceProxy parameter is not serializable

NullPointerException - if either null is input to the serviceProxy parameter, or at least one of the elements of the attrSets parameter is null

IllegalStateException - if this method is called on a terminated JoinManager instance. Note that this exception is implementation-specific.