JU.4. The Semantics

The JoinManager helper utility class defines a number of public methods in addition to the constructor. This utility defines an accessor method that allows the entity to retrieve the set of lookup services with which the entity has been registered (by the JoinManager), as well as methods that allow the entity to retrieve references to the objects the JoinManager uses for discovery management and lease renewal management. Additionally, the JoinManager class defines methods the entity may use to manage the attributes associated with the entity, and a method that allows the entity to terminate the join processing being performed on its behalf.

The equals method for the JoinManager class returns true if and only if two instances of this class refer to the same object. That is, x and y are equal instances of this class if and only if x==y has the value true.

The constructor of the JoinManager class has two forms. Each form of the constructor throws IOException because construction of a JoinManager may initiate the multicast discovery process, which can throw IOException.

The first form of the constructor takes the following parameters as input:

• A reference to the service requesting the services of the JoinManager

• An array containing the service’s attributes

• A reference to an object that implements the ServiceIDListener interface (belonging to the package net.jini.lookup)

• A reference to an object that implements the DiscoveryManagement interface

• An instance of the LeaseRenewalManager utility class

Passing null as the value of the attrSets parameter is equivalent to passing an empty Entry array.

The assignment of a service ID to the service will result in an event notification being sent to the listener object that was passed as the ServiceIDListener argument (callback). If a null value is passed in through this argument, then no such notification will be sent.

To use the JoinManager, the service supplies an object through which notifications that indicate a lookup service has been discovered or discarded will be received. At a minimum, this object must satisfy the contract defined in the DiscoveryManagement interface. That is, this object must provide the JoinManager with the ability to set discovery listeners and to discard previously discovered lookup services when they are found to be unavailable.

The DiscoveryManagement argument may be set to a value of null. If null is the value of this argument, then an instance of the LookupDiscoveryManager utility class will be constructed to listen for events announcing the discovery of only those lookup services that are members of the public group.

The LeaseRenewalManager argument may be set to a value of null. If null is the value of this argument, an instance of the LeaseRenewalManager class will be created, initially managing no Lease objects. This feature allows a service that employs the JoinManager either to 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 and that are accessible only within the JoinManager.

The first form of the constructor is typically used by services that have not yet been assigned a service ID, but that have been pre-configured to join lookup services that the service identifies through the initialization of a discovery manager.

The second form of the constructor takes the same arguments as the first, except that an instance of the ServiceID replaces an instance of the ServiceIDListener interface. Note that the ServiceID class is defined in The Jini Technology Core Platform Specification, “Lookup Service”, and the ServiceIDListener interface is described later.

The second form of the constructor applies the same semantics to the attrSets, discoveryMgr, and leaseMgr arguments as is applied by the first form of the constructor.

The second form of the constructor should be used by services that have already been assigned a service ID (possibly by the service provider or as a result of a prior registration with some lookup service), and that may or may not have been pre-configured to join lookup services identified by group or by specific location.

The getDiscoveryManager method returns the instance of DiscoveryManagement that was either passed into the constructor by the entity or that was created as a result of null being passed as that parameter. This method takes no arguments as input.

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.

The getLeaseRenewalManager method returns an instance of the LeaseRenewalManager class. This method takes no arguments as input.

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 the JoinManager has made with each lookup service the service wishes to join.

The getJoinSet method 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 takes no arguments as input and will return a new array upon each invocation.

The getAttributes method 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 takes no arguments as input and will return a new array upon each invocation.

Note that although a new array is returned by getAttributes, the elements of that array are not copies. Thus, it important that the elements of the array returned by getAttributes not be modified; doing so could cause the state of the JoinManager to become corrupted or inconsistent. This potential for corruption or inconsistency is why the effects of modifying the elements of the array returned by getAttributes are undefined.

The addAttributes method 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. This propagation must be performed asynchronously, so 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.

The set of attributes consisting of the union of the new set with the old set will be associated with the service in all future join processing.

There are two forms of the addAttributes method. Both forms of this method take as input an argument (attrSets) representing the set of attributes to associate with the service. This set is represented as an array of Entry objects, none of whose elements may be null. If at least one element of this input set is null, a NullPointerException is thrown.

An invocation of either form 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. If null is passed in as the value of this parameter, a NullPointerException will be thrown.

The second form of this method also takes as input a flag indicating whether or not this method should determine if the attributes in the input set are instances of the ServiceControlled interface, which is a marker interface that is used to control which entities may modify a service’s attribute set. For more information on this interface, refer to Jini Lookup Attribute Schema Specification, Section LS.4.1, “Indicating User Modifiability”. If the value of this flag is true and at least one of the attributes to be added is an instance of the ServiceControlled interface, a SecurityException will be thrown and propagated through this method.

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 input array. 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 input array, after this method is invoked, are undefined.

The setAttributes method replaces the service’s current set of attributes with the given new set of attributes. This method takes a single argument as input: an array of Entry objects, none of whose elements may be null, which represents the set of attributes that will replace the current set of attributes. If at least one element of this input set is null, a NullPointerException is thrown.

The replacement of the service’s current set of attributes with the new set of attributes will be propagated to each lookup service with which the service is registered. This propagation must be performed asynchronously, so 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.

The service’s new set of attributes will be associated with the service in all future join processing.

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. If null is input to setAttributes, a NullPointerException will be thrown.

For the same reason as noted above in the description of the addAttributes method, the effects of modifying the contents of the input array after the method setAttributes is invoked, are undefined.

The modifyAttributes method changes the service’s current set of attributes using the same semantics as the modifyAttributes method of the class ServiceRegistration (see The Jini Technology Core Platform Specification, “Lookup Service”). This method has two forms. The first form takes two arguments, the second form takes three arguments. Both forms will take an array of templates in the first argument and an array of attributes in the second argument. The templates are used to identify which elements to modify from the service’s current set of attributes. The attribute array contains the actual modifications to be made. The additional argument in the signature of the second form of modifyAttributes is a flag indicating whether or not this method should determine if the attributes in the input set are instances of the ServiceControlled interface, which is a marker interface used to control which entities may modify a service’s attribute set (see Jini Lookup Attribute Schema Specification, Section LS.4.1, “Indicating User Modifiability”). If the value of this flag is true and at least one of the attributes to be modified is an instance of the ServiceControlled interface, a SecurityException will be thrown and propagated through this method.

The association of the new set of attributes with the service will be propagated to each lookup service with which the service is registered. This propagation must be performed asynchronously. Because of this asynchronous behavior, 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.

The set of attributes that results after the modifications have been applied will be associated with the service in all future join processing.

The modifyAttributes method throws an IllegalArgumentException if one of the following conditions is satisfied:

• The length of the array containing the templates does not equal the length of the array containing the attributes

• Any element of either array is not an instance of a valid Entry class (for example, the class is not public, does not contain a no-arg constructor, or has at least one public field which is a non-static, non-final primitive)

• The class of attrSets[i ] is neither the same as, nor a super class of, the class of attrSetsTemplate[i ]

For the same reason as that noted above in the description of the addAttributes method, the effects of modifying the contents of the attrSets parameter, after modifyAttributes is invoked, are undefined.

The terminate method performs cleanup duties related to the termination of the lookup service discovery event mechanism, as well as to 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.

If the discovery manager employed by the JoinManager was created by the JoinManager 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.

The JoinManager makes certain concurrency guarantees with respect to an invocation of the terminate method while other method invocations are in progress. The termination process described above will not begin until completion of all invocations of the methods defined in the public interface of the JoinManager. Upon completion of the termination process, the semantics of all current and future method invocations on the current instance of the JoinManager are undefined, although the reference to the LeaseRenewalManager object employed by the JoinManager is still valid.