JINI LEASE UTILITIES SPECIFICATION, version 1.1
`
`81
`
`mootby intervening calls on the renewal manager. For example, the renewal man-
`ager may deliver events regarding leases that were removed from the managedset
`after the calls that removed the leases in question completed. Implementations
`should keep the window wheresuchnotifications could occur as small as possible.
`The equals method for this 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 ofthis class
`if and only if x == y has the value true.
`The constructor has two forms:
`
`Thefirst form of the constructor takes no arguments. This form of the con-
`structor instantiates a LeaseRenewalManager object that initially manages
`no leases.
`
`@ The second form of the constructor creates a LeaseRenewalManager that
`initially managesa single lease. This form of the constructor requires that a
`reference to the initial lease be supplied as an argument. This form of the
`constructor also takes a desiredExpiration argument that represents the
`desired expiration time for the lease and a reference to a LeaseListener
`object that should receive notifications of events associated with the lease.
`
`Creating a LeaseRenewalManager using the second form of the constructoris
`equivalent to invoking the no-argumentconstructor followed by an invocation of
`the three-argument form of the renewUnti1 method (describedlater).
`The renewUntil method addsa lease to the set of leases being managed by
`the LeaseRenewalManager. There are two versions of this method: a four-argu-
`ment form that allows the client to specify the renewal duration directly, and a
`three-argument form that infers the renewal duration from the desired expiration
`argument. The four-argument form will be describedfirst.
`This method takes as arguments: a reference to the lease to manage, the
`desired expiration time of the lease, the renewal duration time for the lease, and a
`reference to the LeaseListener object that will receive notification of events
`associated with this lease. The LeaseListener argument may be nu11.
`If nu11 is passed as the lease parameter, a Nul11PointerException will be
`thrown.
`If
`the desiredExpiration parameter
`is Lease.FOREVER,
`the
`renewDuration parameter may be Lease.ANY or any positive value; otherwise,
`the renewDuration parameter must be a positive value. If the renewDuration
`parameter does not meet these requirements, an I1]legalArgumentException
`will be thrown.
`If the lease passed to this methodis already in the set of managed leases, the
`listener object, the desired expiration, and the renewal duration associated with
`
`A COLLECTION OF JINI™ TECHNOLOGYHELPER UTILITIES AND SERVICES SPECIFICATIONS
`
`91
`
`91
`
`

`

`THE SEMANTICS
`
`that lease will be replaced with the new listener, desired expiration, and renewal
`duration.
`A lease will remain in the set of managed leases until one of the following
`occurs:
`
`@ The lease’s desired expiration time is reached; this will generate a desired
`expiration reached event.
`@ An explicit removal of the lease from the set is requested via a cancel,
`clear, or remove call on the renewal manager.
`@ The lease’s actual expiration time is reached before its desired expiration;
`this will generate a renewalfailure event.
`@ The renewal managertries to renew the lease and gets a definite exception;
`this will generate a renewalfailure event.
`
`The renewUntil method interprets the value of the desiredExpiration
`parameter as the desired absolute system time after which the lease is no longer
`valid. This argument provides the ability to indicate an expiration time that
`extends beyond the actual expiration of the lease. If the value passed for this argu-
`ment does indeed extend beyondthe lease’s actual expiration time, then the lease
`will be systematically renewed at appropriate times until one of the conditions
`listed above occurs.If the value is less than or equal to the actual expiration time,
`nothing will be done to modify the time when the lease actually expires. Thatis,
`the lease will not be renewed with an expiration time that is less than the actual
`expiration time of the lease at the time ofthe call.
`The renewDuration parameteris interpreted as the renewal duration, in milli-
`seconds, to associate with the lease.
`If a non-nu11 object reference is passed in as the LeaseListener parameter,
`this object will receive notification of exceptional conditions occurring upon a
`renewal attempt of the lease. In particular, exceptional conditions include the
`reception of a definite exception or the lease’s actual expiration being reached
`before
`its desired expiration.
`If
`the
`listener
`implements
`the
`interface
`DesiredExpirationListener it will also receive notification if the lease’s
`desired expiration is reached while theleaseisstill in the set.
`If a definite exception occurs during a lease renewal request, the exception
`will be wrapped in an instance of the LeaseRenewalEvent class (describedlater)
`and sent to the listener’s notify method.
`If an indefinite exception (see Introduction to Helper Utilities and Services,
`Section US.2.6, “What Exceptions Imply about Future Behavior”) occurs during a
`renewal request for a particular lease, renewal requests will continue to be made
`for that lease until: the lease is renewed successfully, a renewal attemptresults in a
`
`92
`
`92
`
`

`

`JINI LEASE UTILITIES SPECIFICATION, version 1.1
`
`83
`
`definite exception, or the lease’s actual expiration time has been exceeded.If the
`lease cannot be successfully renewed before its actual expiration is reached, the
`exception associated with the most recent renewal attempt will be wrapped in an
`instance of the LeaseRenewalEvent class and sent to the listener’s notify
`method.
`If the lease’s actual expiration is reached before the lease’s desired expiration
`time andeither (1) the last renewal attempt succeeded or (2) there have been no
`renewalattempts, a LeaseRenewalEvent containing a nu11 exception will be sent
`to the listener’s notify method. Case 1 can occurif the extension granted by the
`last renewal was very short. Case 2 can occur if the client adds a lease that has
`already expired (or is about to) to the managedsetof leases.
`If nu11 is passed as the value of the LeaseListener parameter, then no noti-
`fications will be delivered.
`Calling the three-argument form of renewUntil with a desiredExpiration
`of Lease. ANY is equivalent to making the followingcall:
`
`renewUntil(lease, Lease.FOREVER, Lease.ANY, listener);
`
`Otherwise, the three-argument form is equivalentto:
`
`renewUntil(lease, desiredExpiration, Lease.FOREVER,
`listener);
`
`
`Usage Note: Unless an application has a good reason for doing otherwise, it should
`use Lease. ANY or Lease. FOREVER for the renewal duration of a given lease.
`Using these values gives the grantor of the lease the mostflexibility in the length of
`time for which it grants renewals. In most cases, the grantor of a leaseis in a better
`position than the lease holder to make trade-offs between renewal frequency and the
`risk of holding on to resources longer than necessary. Specifying a value for the
`renewal duration of a lease might make sense if the holder of the lease has more
`information on the value of the leased resource than the grantor, or if the holder needs
`to ensure that there is an upper bound on how longthe lease will remain valid.
`
`The renewFor methodaddsa lease to the set of leases being managed by the
`LeaseRenewalManager. Like renewUntil this method has both three- and four-
`argument forms. The four-argument form of this method takes as parameters:
`lease, a reference to the lease to manage; desiredDuration, a long represent-
`ing the desired duration of lease; renewDuration, a long representing the
`renewal duration; and listener, a reference to a LeaseListener object that will
`receive notifications of events associated with this lease. Both desiredDuration
`and renewDuration are expressed in milliseconds.
`The semantics of the four-argument form of renewFor are similar to those of
`the four-argument form of renewUntil, with desiredDuration + current time
`
`A COLLECTION OF JINI™ TECHNOLOGYHELPER UTILITIES AND SERVICES SPECIFICATIONS
`
`93
`
`93
`
`

`

`84
`
`THE SEMANTICS
`
`being used for the value of the desiredExpiration parameter of renewUnti1.
`The only exception is that,
`in the context of renewFor,
`the value of the
`renewDuration parameter may be Lease.ANY only if the value of the
`desiredDuration parameteris exactly Lease. FOREVER.
`This methodtests for arithmetic overflow in the desired expiration time com-
`puted from the value of desiredDuration parameter (desi redDuration + cur-
`rent time). Should such overflow bepresent, a value of Lease. FOREVERis used to
`represent the lease’s desired expiration time.
`The three-argument form of this method is equivalent to the following call:
`
`renewFor(lease, desiredDuration, Lease.FOREVER,
`listener);
`
`Note that for both versions of renewFor, a value of Lease.ANY for the
`desiredDuration parameter does not have any special semantics associated with
`it. Calling either version of renewFor with a desiredDuration of Lease.ANY
`will result in the lease having a desired expiration one millisecond in the past,
`causing the lease to be immediately dropped from the managed set. The method
`will not throw an exception in this circumstance. A renewalfailure event will be
`generated if the actual expiration is before the desired expiration; otherwise a
`desired expiration reached event will be generated.
`The getExpiration method returns the current desired expiration time
`requested for a particular lease, not the actual expiration that was granted when
`the lease wascreated or last renewed. The only argumentto this methodis the ref-
`erence to the lease object. If the lease is not in the set of managed leases, an
`UnknownLeaseException will be thrown.
`The setExpiration methodreplacesthe current desired expiration of a given
`lease contained in the set of managed leases with a new desired expiration time.
`The only arguments to this method are the reference to the lease object and the
`new expiration time.
`An invocation of this method with a lease that is currently a memberof the
`managed set is equivalent to an invocation of the renewUntil method with the
`lease’s current listener input to the 1istener parameter. In particular, if the value
`of the expiration parameter is less than or equal to the lease’s current actual
`expiration, this methodtakes no action.
`An invocation of this method with a lease that is not in the set of managed
`leases will result in an UnknownLeaseException.
`The remove method removes a given lease from the set of managedleases.
`The only argument to this method is the reference to the lease object. If the lease
`is not in the set of managed leases, an UnknownLeaseException will be thrown.
`Note that this method does not cancel the given lease; activities such as lease
`cancellation are left the for the client to manage.
`
`94
`
`94
`
`

`

`JINI LEASE UTILITIES SPECIFICATION, version 1.1
`
`85
`
`The cancel method both removes a given lease from the set of managed
`leases and cancels the given lease. The only argumentto this method is the refer-
`ence to the lease object. If the lease is not in the set of managed leases, an
`UnknownLeaseException will be thrown.
`Any exception (definite or otherwise) occurring during the cancellation of the
`lease will have no effect on the removalof the lease from the managedset. Thatis,
`even if an exception occurs during the cancel operation, the lease will have been
`removed from the managedset upon return from this method.
`Any exception thrown by the cancel method of the lease object itself may
`also be thrown bythis method.
`The clear method removesall leases from the set of managedleases. It does
`not request the cancellation of those leases. This method takes no arguments.
`
`A COLLECTION OF JINI™ TECHNOLOGYHELPER UTILITIES AND SERVICES SPECIFICATIONS
`
`95
`
`95
`
`

`

`86
`
`THE SEMANTICS
`
`96
`
`96
`
`

`

`JINI LEASE UTILITIES SPECIFICATION, version 1.1
`
`87
`
`
`
`
`LM.5 Supporting Interfaces and Classes
`
`interfaces
`the
`on
`depends
`class
`utility
`Tue LeaseRenewalManager
`LeaseListener and DesiredExpirationListener. Both ofthese interfaces ref-
`erence one class, LeaseRenewalEvent.
`
`LM.5.1 The LeaseListener Interface
`
`The public methodsspecified by the LeaseListener interface are as follows:
`
`package net.jini. lease;
`
`public interface LeaseListener extends EventListener
`{
`
`void notify(LeaseRenewalEvent e);
`
`} T
`
`he LeaseListener interface defines the mechanism through whichthecli-
`ent receives notification of renewal failure events generated by the renewal man-
`ager. These events are delivered using the notify method. Renewalfailure events
`are generated when the LeaseRenewalManager has failed to renew one of the
`leases that it is managing. Such renewalfailures typically occur because one of
`the following conditions is met:
`
`@ After successfully renewing a lease any numberoftimes and experiencing
`no failures,
`the LeaseRenewalManager determines—prior to the next
`renewal attempt—that the actual expiration time of the lease has passed;
`implying that any further attempt to renew the lease would befruitless.
`@ An indefinite exception occurs during each attemptto renew a lease from the
`point
`that
`the first such exception occurs until
`the point when the
`LeaseRenewalManager determines that lease’s actual expiration time has
`passed.
`@ A definite exception occurs during a lease renewal attempt.
`
`A COLLECTION OF JINI™ TECHNOLOGYHELPER UTILITIES AND SERVICES SPECIFICATIONS
`
`97
`
`97
`
`

`

`88
`
`SUPPORTING INTERFACES AND CLASSES
`
`It is the responsibility of the client to pass into the LeaseRenewalManager a
`reference to an object that
`implements the LeaseListener interface, which
`defines the actions to take upon receipt of a renewal failure event notification.
`Whenone of the above conditions occurs, the LeaseRenewalManager will send
`an instance of LeaseRenewalEvent to that listener object.
`
`LM.5.1.1 The Semantics
`
`The notify method is invoked by the LeaseRenewalManager whenit fails to
`renew a lease because one of the conditions described above has occurred. This
`method takes one parameter, an instance of the LeaseRenewalEvent class, which
`contains information about the lease on which the failed renewal attempt was
`made and information on what causedthefailure.
`Note that prior to invoking the notify method, the LeaseRenewalManager
`removesthe lease that could not be renewed from the managedset of leases. Note
`also
`that
`because
`of
`the
`reentrancy
`guarantee made
`by
`the
`LeaseRenewalManager, new leases can be addedsafely from within the notify
`method.
`
`LM.5.2 The DesiredExpirationListener Interface
`
`The public methodsspecified by the Desi redExpirationListener interface
`are as follows:
`
`package net.jini. lease;
`
`public interface DesiredExpirationListener
`extends LeaseListener
`
`void expirationReached(LeaseRenewalEvent e);
`
`} T
`
`he expirationReached methodreceives desired expiration reached events.
`These are generated when the LeaseRenewalManager removesa lease from the
`managed set because the lease’s desired expiration has been reached. Note that
`any object that has been registered to receive desired expiration reached events
`will also receive renewalfailure events.
`It is the responsibility of the client to pass into the LeaseRenewalManager a
`reference to an object that implements the DesiredExpirationListener inter-
`
`98
`
`98
`
`

`

`JINI LEASE UTILITIES SPECIFICATION, version 1.1
`
`89
`
`face, which defines the actions to take uponreceipt of a desired expiration reached
`eventnotification.
`
`LM.5.2.1 The Semantics
`
`The expirationReached methodis invoked by the LeaseRenewalManager
`whena lease in the managedset reachesits desired expiration. This method takes
`one parameter: an instance of the LeaseRenewalEvent class, which contains
`information about the lease who’s desired expiration has been reached.
`the
`Note
`that prior
`to
`invoking the expirationReached method,
`LeaseRenewalManager removes the affected lease from the managed set of
`leases. Note also that because of the reentrancy guarantee made by the
`LeaseRenewalManager, callbacks into the renewal manager can be madesafely
`from within the expi rationReached method.
`
`LM.5.3 The LeaseRenewalEvent Class
`
`This class defines the local event that is sent by the LeaseRenewalManager to the
`client’s registered listener when the LeaseRenewalManager generates a renewal
`failure event or desired expiration reached event. As previously stated, a renewal
`failure event typically occurs because the actual expiration time of a lease has
`been reached before a successful renewal request could be made, or a renewal
`request resulted in a definite exception. A desired expiration reached event occurs
`whena lease reachesits desired expiration timeat or before its actual expiration.
`The LeaseRenewalEvent class encapsulates information about the lease on which
`such an event occurs and,if it is a renewal failure, the cause.
`
`package net.jini. lease;
`
`public class LeaseRenewalEvent extends EventObject
`{
`
`public LeaseRenewalEvent(LeaseRenewalManager source,
`Lease lease,
`long expiration,
`Throwable ex)
`{...}
`public Lease getLease() {...}
`public long getExpiration() {...}
`public Throwable getException() {...}
`
`A COLLECTION OF JINI™ TECHNOLOGYHELPER UTILITIES AND SERVICES SPECIFICATIONS
`
`99
`
`99
`
`

`

`90
`
`SUPPORTING INTERFACES AND CLASSES
`
`The LeaseRenewalEvent class is a subclass of the EventObject class, add-
`ing the following additional items of abstract state: a reference to the associated
`Lease object; a long value representing the desired expiration of the lease; and
`the exception (if any) that caused the event to be sent. In addition to the methods
`of the EventObject class, this class defines methods through which this addi-
`tional state may beretrieved.
`
`LM.5.3.1 The Semantics
`
`The constructor of the LeaseRenewalEvent class takes the following parameters
`as input:
`
`A referenceto the instance of the LeaseRenewalManager that generated the
`event
`
`@ The lease associated with this event
`
`@ The desired expiration time of the lease
`@ The Throwable associated with the last renewal attempt(if any)
`
`The getLease methodreturns a reference to the Lease object associated with
`the event. This method takes no arguments.
`The getExpiration method returns a long value representing the desired
`expiration of the Lease object associated with the event. This method takes no
`arguments.
`The getException method returns the exception, if any, that is associated
`with the event. This method takes no arguments. If the LeaseRenewalEvent rep-
`resents a desired expiration reached event this method will return nu11.
`the
`event
`If
`the LeaseRenewalEvent
`represents
`a
`renewal
`failure
`getException method will return the exception that caused the event to be sent.
`The conditions under which a renewalfailure event may be sent, and the related
`values returned by this method,are as follows:
`
`@ Whenanylease in the managedset has passedits actual expiration time, and
`either the most recent renewal attempt was successful or there have been no
`renewal attempts,
`the LeaseRenewalManager will cease any further
`attempts to renew the lease, and will send a LeaseRenewalEvent with no
`associated exception.In this case, invoking this method will return nu11.
`@ For any lease from the managed set for which the most recent renewal
`attempt was unsuccessful because of the occurrence of a indefinite excep-
`tion,
`the LeaseRenewalManager will continue to attempt to renew the
`
`100
`
`100
`
`

`

`JINI LEASE UTILITIES SPECIFICATION, version 1.1
`
`91
`
`affected lease at the appropriate timesuntil: the renewal succeeds,the lease’s
`actual expiration time has passed, or a renewal attempt throws a definite
`exception. If a definite exception is thrown or the lease expires,
`the
`LeaseRenewalManager will cease any further attempts to renew the lease,
`and will send a LeaseRenewalEvent containing the exception associated
`with the last renewal attempt.
`@ If, while attempting to renew a lease from the managedset, a definite excep-
`tion is encountered, the LeaseRenewalManager will cease any further
`attempts to renew the lease, and will send a LeaseRenewalEvent containing
`the particular exception that occurred.
`
`LM.5.4 Serialized Forms
`
`Class
`
`serialVersionUID
`
`Serialized Fields
`
`LeaseRenewalEvent
`
`-626399341646348302L Lease lease
`long expiration
`Throwable ex
`
`A COLLECTION OF JINI™ TECHNOLOGYHELPER UTILITIES AND SERVICES SPECIFICATIONS
`
`101
`
`101
`
`

`

`92
`
`SUPPORTING INTERFACES AND CLASSES
`
`102
`
`102
`
`

`

`
`
`
`JU
`
`Jini Join Utilities
`Specification
`
`JU.1 Introduction
`
`Tus specification defines helper utility classes, along with supporting inter-
`faces and classes, that encapsulate functionality that can help Jini services demon-
`strate good behavior in their discovery and registration related interactions with
`Jini lookup services. In particular, the Jini join utilities perform functions related
`to lookup service discovery and registration (joining), as well as lease renewal and
`attribute management, which the Jini technology programming model requires of
`a well-behaved Jini
`technology-enabled service. Currently,
`this specification
`defines only one helperutility class:
`
`@ The JoinManager helperutility
`
`93
`
`103
`
`103
`
`

`

`94
`
`INTRODUCTION
`
`104
`
`104
`
`

`

`JINI JOIN UTILITIES SPECIFICATION, version 1.1
`
`95
`
`
`
`
`JU.2 The JoinManager
`
`Tz goal of any well-behaved Jini technology-enabled service (Jini service),
`implemented within the bounds defined by the Jini technology programming
`model, is to advertise the service it provides by requesting residency within at
`least one Jini lookup service. Making such a request of a Jini lookup serviceis
`knownasregistering with, orjoining, a lookup service. To demonstrate this good
`behavior, a service must comply with both the multicast discovery protocol and
`the unicast discovery protocol 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. The details of the discovery and join protocols are
`described in, The Jini Technology Core Platform Specification, “Discovery and
`Join”.
`For the service to maintain its residency in the lookup services it has joined,
`the service must provide for the coordination, systematic renewal, and overall
`managementofall leases on that residency. In addition to handling all discovery
`and join duties, as well as managingall leases on lookup residency, the service
`must provide for the coordination and management of any attribute sets with
`which it may haveregistered.
`With respect to the duties described above, a Jini service may perform all but
`the attribute set management duties by using the helper utility classes
`LookupDiscoveryManager and LeaseRenewalManager.
`(For information on
`these classes, refer to The Jini Technology Core Platform Specification, “Discov-
`ery and Join” and Jini Lease Renewal Service Specification).
`Rather than writing a service to use these classes in a coordinated fashion (in
`addition to providing for attribute management), the service may be written to
`employ the JoinManager class from the net. jini. lookup package. This utility
`class performs all of the functions related to discovery, joining, service lease
`renewal, and attribute managementthat the Jini technology programming model
`requires of a well-behaved Jini service. Each of these activities is intimately
`involved with the maintenance of a service’s residency in one or more lookupser-
`vices (the service’sjoin state), hence the name JoinManager.
`The JoinManager class provides an implementation of the functionality
`described above. The useofthis class in a wide variety of services can help mini-
`
`A COLLECTION OF JINI™ TECHNOLOGYHELPER UTILITIES AND SERVICES SPECIFICATIONS
`
`105
`
`105
`
`

`

`96
`
`THE JoinManager
`
`mize the work resulting from having to repeatedly implementthis required func-
`tionality in each service.
`The JoinManager is a utility class, not a remote service. Jini services that
`wishto use this utility will create an instance of the JoinManager in the service’s
`address space to managethe entity’s join state locally.
`Note that when the term service is used,it refers to the object that has created
`an instance of the JoinManager andavailsitself of the public methodsof that util-
`ity class.
`
`JU.2.1 Other Types
`
`The types defined in the specification of the JoinManager utility class are in the
`net.jini. lookup package. The following types may be referenced in this chap-
`ter. Whenever referenced, these object types will be referenced in unqualified
`form:
`
`net.jini.core.lease.Lease
`net.jini.core.entry.Entry
`net.jini.core. lookup.ServiceID
`net.jini.core. lookup.ServiceRegistrar
`net. jini.core. lookup.ServiceRegistration
`net.jini.discovery.DiscoveryListener
`net.jini.discovery.DiscoveryManagement
`net.jini. lookup.entry.ServiceControlled
`net.jini. lease.LeaseRenewalManager
`net.jini.discovery.LookupLocatorDiscovery
`net.jini.discovery.LookupDiscoveryManager
`java.io.IOException
`java.rmi.MarshalledObject
`java.util.EventListener
`
`106
`
`106
`
`

`

`JINI JOIN UTILITIES SPECIFICATION, version 1.1
`
`97
`
`
`
`
`JU.3 The Interface
`
`Tz public methods provided by the JoinManagerclassare as follows:
`
`package net.jini. lookup;
`
`public class JoinManager {
`public
`JoinManager(Object obj,
`Entry[] attrSets,
`ServiceIDListener callback,
`DiscoveryManagement discoveryMgr,
`LeaseRenewalManager leaseMgr)
`throws IOException {...}
`
`public
`
`JoinManager(Object obj,
`Entry[] attrSets,
`ServiceID servicelD,
`DiscoveryManagement discoveryMgr,
`LeaseRenewalManager leaseMgr)
`throws IOException {...}
`
`public
`public
`public
`
`DiscoveryManagement getDiscoveryManager() {...}
`LeaseRenewalManager getLeaseRenewalManager() {...}
`ServiceRegistrar[]
`getJoinSet() {...}
`
`public
`public
`public
`
`public
`public
`
`public
`
`Entry[] getAttributes() {...}
`void addAttributes(Entry[] attrSets) {..}
`void addAttributes(Entry[] attrSets,
`boolean checkSC) {...}
`void setAttributes(Entry[] attrSets) {..}
`void modifyAttributes(Entry[] attrSetTemplates,
`Entry[] attrSets) {..}
`void modifyAttributes(Entry[] attrSetTemplates,
`Entry[] attrSets,
`
`A COLLECTION OF JINI™ TECHNOLOGYHELPER UTILITIES AND SERVICES SPECIFICATIONS
`
`107
`
`107
`
`

`

`98
`
`THE INTERFACE
`
`public void terminate() {...}
`
`boolean checkSC) {...}
`
`108
`
`108
`
`

`

`JINI JOIN UTILITIES SPECIFICATION, version 1.1
`
`99
`
`
`
`
`JU.4 The Semantics
`
`Tz JoinManagerhelperutility class defines a number of public methods in
`addition to the constructor. This utility defines an accessor methodthat allows the
`entity to retrieve the set of lookup services with which the entity has been regis-
`tered (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 methodfor the JoinManager class returns true if and only if two
`instancesofthis 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 mayini-
`tiate 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
`@ Anarray containing the service’s attributes
`@ Areference to an object that implements the ServiceIDListener interface
`(belonging to the package net. jini. lookup)
`@ A reference to an object that implements the DiscoveryManagement inter-
`face
`
`An instance of the LeaseRenewalManager utility class
`
`Passing nu11 as the value of the attrSets parameter is equivalent to passing an
`empty Entry array.
`The assignmentof a service ID to the service will result in an event notifica-
`tion being sent to the listener object that was passed as the ServiceIDListener
`
`A COLLECTION OF JINI™ TECHNOLOGYHELPER UTILITIES AND SERVICES SPECIFICATIONS
`
`109
`
`109
`
`

`

`100
`
`THE SEMANTICS
`
`argument (callback). If a nu11 value is passed in through this argument, then no
`such notification will be sent.
`To use the JoinManager,the service supplies an object through whichnotifi-
`cations 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 maybesetto a value of nu11. If nul]
`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 membersofthe public group.
`The LeaseRenewalManager argument maybesetto a value of nu11. If nu11
`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 manageall ofits leases,
`or to use separate entities: one to manage the leases unrelated to the join process,
`and one to managetheleasesthat result from the join process and that are accessi-
`ble only within the JoinManager.
`Thefirst 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 ser-
`vices that the service identifies through the initialization of a discovery manager.
`The second form of the constructor takes the same arguments as thefirst,
`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 describedlater.
`The second form of the constructor applies the same semantics to the attr-
`Sets, discoveryMgr, and leaseMgr arguments as is applied bythefirst 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 provideror 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.
`of
`instance’
`the
`returns
`method
`getDiscoveryManager
`The
`DiscoveryManagement that was either passed into the constructor by the entity or
`that was created as a result of nul1 being passed as that parameter. This method
`takes no arguments as input.
`
`110
`
`110
`
`

`

`JINI JOIN UTILITIES SPECIFICATION, version 1.1
`
`101
`
`the
`
`The object returned by this method encapsulates the mechanism by which
`either the JoinManager orthe 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
`LeaseRenewalManager class. This method takes no arguments as input.
`The object returned by this method managesthe leases requested and held by
`the JoinManager. Although it may also manageleases unrelated to the join pro-
`cess that are requested and held bythe serviceitself, the leases with which the
`JoinManager is concerned are the leases that correspondto the service registra-
`tion requests the JoinManager has made with each lookup service the service
`wishesto join.
`The getJoinSet method returns an array of ServiceRegistrar objects,
`each corresponding to a lookup service with which the service is currently regis-
`tered (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 argu-
`ments 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 causethestate of the
`JoinManager to becomecorrupted or inconsistent. This p