Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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.

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 `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.

  • | `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.

  • | `taskManager`
  --- | ---
  | Type: | `TaskManager`
  | Default: | `new `TaskManager`(15, (15*1000), 1.0f)`
  | Description: | The object that pools and manages the various threads executed by this utility. The default manager creates a maximum of 15 threads, waits 15 seconds before removing idle threads, and uses a load factor of 1.0 when determining whether to create a new thread. 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 `taskManager` entry of this component, but which fail during that initial execution. This object schedules the re-execution of such a failed task - in the `taskManager` 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
`JoinManager(Object obj, 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 service ID.
`JoinManager(Object obj, Entry[] attrSets, ServiceID serviceID, DiscoveryManagement discoveryMgr, LeaseRenewalManager leaseMgr, Configuration config)` Constructs an instance of this class, which is configured using the items retrieved through the given `Configuration`, that will register the service with all discovered lookup services, using the supplied service ID.
`JoinManager(Object obj, Entry[] attrSets, ServiceIDListener callback, DiscoveryManagement discoveryMgr, LeaseRenewalManager leaseMgr)` Constructs an instance of this class that will notify the service when a service ID is assigned by the first lookup service with which the service is registered.
`JoinManager(Object obj, Entry[] attrSets, ServiceIDListener callback, DiscoveryManagement discoveryMgr, LeaseRenewalManager leaseMgr, Configuration config)` Constructs an instance of this class, which is configured using the items retrieved through the given `Configuration`, that will notify the service when a service ID is assigned by the first lookup service with which the service is registered.

Method Summary
`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` | `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 obj,
                       Entry[] attrSets,
                       ServiceIDListener callback,
                       DiscoveryManagement discoveryMgr,
                       LeaseRenewalManager leaseMgr)
                throws IOException

  Constructs an instance of this class that will notify the service when a service ID is assigned by the first lookup service with which the service is registered. This constructor is typically used by services that have not yet been assigned a service ID.

  Note that this form of the constructor applies the same semantics to the `attrSets`, `discoveryMgr`, and `leaseMgr` parameters as is applied by all other forms 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.
  `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.
  `discoveryMgr` - 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 instance of `JoinManager` created by this constructor.
Throws:
  `IOException` - because construction of this class may initiate the discovery process, which can throw an `IOException` when socket allocation occurs.
See Also:
  `ServiceIDListener`, `DiscoveryManagement`, `LookupDiscoveryManager`, `LeaseRenewalManager`

### JoinManager

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

  Constructs an instance of this class, which is configured using the items retrieved through the given `Configuration`, that will notify the service when a service ID is assigned by the first lookup service with which the service is registered. This constructor is typically used by services that have not yet been assigned a service ID.

  Note that this form of the constructor applies the same semantics to the `attrSets`, `discoveryMgr`, and `leaseMgr` parameters as is applied by all other forms 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.
  `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.
  `discoveryMgr` - 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 attempt will first be made to retrieve from the given `Configuration`, a discovery manager entry as described above. If such an object is successfully retrieved, that object will be used to perform the lookup service discovery processing required by this utility. If `null` is input to this argument, and no discovery manager entry can be retrieved from the given `Configuration` (because of failure or non-existence), 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.
  `leaseMgr` - an instance of the `LeaseRenewalManager` utility class. If `null` is input to this argument, an attempt will first be made to retrieve from the given `Configuration`, a lease renewal manager entry as described above. If such an object is successfully retrieved, that object will be used to perform the lease management processing required by this utility. If `null` is input to this argument, and no lease renewal manager entry can be retrieved from the given `Configuration` (because of failure or non-existence), then an instance of the utility class `LeaseRenewalManager` that takes the given `Configuration` will be created and used to perform all required lease renewal management.
  `config` - an instance of `Configuration`, used to obtain the objects needed to configure the current instance of this class
Throws:
  `IOException` - because construction of this class may initiate the discovery process, which can throw an `IOException` when socket allocation occurs.
  `ConfigurationException` - indicates an exception occurred while retrieving an item from the given `Configuration`
  `NullPointerException` - if `null` is input for the configuration
See Also:
  `ServiceIDListener`, `DiscoveryManagement`, `LookupDiscoveryManager`, `LeaseRenewalManager`, `Configuration`, `ConfigurationException`

### JoinManager

    public JoinManager(Object obj,
                       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 service ID. 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).

  Note that this form of the constructor applies the same semantics to the `attrSets`, `discoveryMgr`, and `leaseMgr` parameters as is applied by all other forms 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
  `discoveryMgr` - 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 instance of `JoinManager` created by this constructor.
Throws:
  `IOException` - because construction of this class may initiate the discovery process, which can throw an `IOException` when socket allocation occurs.
See Also:
  `ServiceID`, `DiscoveryManagement`, `LookupDiscoveryManager`, `LeaseRenewalManager`

### JoinManager

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

  Constructs an instance of this class, which is configured using the items retrieved through the given `Configuration`, that will register the service with all discovered lookup services, using the supplied service ID. 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).

  Note that this form of the constructor applies the same semantics to the `attrSets`, `discoveryMgr`, and `leaseMgr` parameters as is applied by all other forms 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
  `discoveryMgr` - 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 attempt will first be made to retrieve from the given `Configuration`, a discovery manager entry as described above. If such an object is successfully retrieved, that object will be used to perform the lookup service discovery processing required by this utility. If `null` is input to this argument, and no discovery manager entry can be retrieved from the given `Configuration` (because of failure or non-existence), 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.
  `leaseMgr` - an instance of the `LeaseRenewalManager` utility class. If `null` is input to this argument, an attempt will first be made to retrieve from the given `Configuration`, a lease renewal manager entry as described above. If such an object is successfully retrieved, that object will be used to perform the lease management processing required by this utility. If `null` is input to this argument, and no lease renewal manager entry can be retrieved from the given `Configuration` (because of failure or non-existence), then an instance of the utility class `LeaseRenewalManager` that takes the given `Configuration` will be created and used to perform all required lease renewal management.
  `config` - an instance of `Configuration`, used to obtain the objects needed to configure the current instance of this class
Throws:
  `IOException` - because construction of this class may initiate the discovery process, which can throw an `IOException` when socket allocation occurs.
  `ConfigurationException` - indicates an exception occurred while retrieving an item from the given `Configuration`
  `NullPointerException` - if `null` is input for the configuration
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` - 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(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` - 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`.
    `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`, `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` - this exception occurs when at least one 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` - this exception occurs when 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` - this exception occurs when the array containing the templates does not equal the length of the array containing the modifications.
    `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`, `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.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2004 Sun Microsystems, Inc. All rights reserved