JINI LEASE UTILITIES SPECIFICATION, version 1.1
`
`81
`
`moot by intervening calls on the renewal manager. For example, the renewal man-
`ager may deliver events regarding leases that were removed from the managed set
`after the calls that removed the leases in question completed. Implementations
`should keep the window where such notifications 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 of this class
`if and only if x == y has the value true.
`The constructor has two forms:
`
`9 The first form of the constructor takes no arguments. This form of the con-
`structor instantiates a LeaseRenewal Manager object that initially manages
`no leases.
`
`o The second form of the constructor creates a LeaseRenewal Manager that
`
`initially manages a 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 desi red Expi ration argument that represents the
`desired expiration time for the lease and a reference to a LeaseLi stener
`object that should receive notifications of events associated with the lease.
`
`Creating a LeaseRenewal Manager using the second form of the constructor is
`equivalent to invoking the no-argument constructor followed by an invocation of
`the three-argument form of the renewUntil method (described later).
`The renewUntil method adds a lease to the set of leases being managed by
`the LeaseRenewal Manager. 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 described first.
`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 LeaseLi stener object that will receive notification of events
`associated with this lease. The LeaseLi stener argument may be null.
`If null is passed as the lease parameter, a Null PointerException will be
`thrown.
`If
`the desi redExpi ration parameter
`is Lease. FOREVER,
`the
`renewDu ration parameter may be Lease .ANY or any positive value; otherwise,
`the renewDu ration parameter must be a positive value. If the renewDu ration
`parameter does not meet these requirements, an IllegalArgumentExcepti on
`will be thrown.
`
`If the lease passed to this method is already in the set of managed leases, the
`listener object, the desired expiration, and the renewal duration associated with
`
`A COLLECTION OF JINITM TECHNOLOGY HELPER UTILITIES AND SER VICES SPECIFICA TIONS
`
`91
`
`91
`
`

`

`82
`
`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:
`
`9 The lease’s desired expiration time is reached; this will generate a desired
`expiration reached event.
`
`0 An explicit removal of the lease from the set is requested via a cancel,
`clear, or remove call on the renewal manager.
`
`0 The lease’s actual expiration time is reached before its desired expiration;
`this will generate a renewal failure event.
`
`0 The renewal manager tries to renew the lease and gets a definite exception;
`this will generate a renewal failure event.
`
`The renewUntil method interprets the value of the desi redExpi ration
`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 beyond the 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. That is,
`the lease will not be renewed with an expiration time that is less than the actual
`expiration time of the lease at the time of the call.
`The r‘enewDu ration parameter is interpreted as the renewal duration, in milli-
`seconds, to associate with the lease.
`
`If a non-null object reference is passed in as the LeaseLi stener‘ 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
`Desi r'edExpi rat1' onL1' stener it will also receive notification if the lease’s
`
`desired expiration is reached while the lease is still in the set.
`If a definite exception occurs during a lease renewal request, the exception
`will be wrapped in an instance of the LeaseRenewal Event class (described later)
`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 successfiilly, a renewal attempt results 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 LeaseRenewal Event class and sent to the listener’s notify
`method.
`
`If the lease’s actual expiration is reached before the lease’s desired expiration
`time and either (1) the last renewal attempt succeeded or (2) there have been no
`renewal attempts, a LeaseRenewal Event containing a null exception will be sent
`to the listener’s notify method. Case 1 can occur if 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 managed set of leases.
`If null is passed as the value of the LeaseLi stener parameter, then no noti-
`fications will be delivered.
`
`Calling the three-argument form of renewUntil with a desi redExpi ration
`of Lease . ANY is equivalent to making the following call:
`
`renewUntil (lease, Lease. FOREVER, Lease .ANY, listener);
`
`Otherwise, the three-argument form is equivalent to:
`
`renewUntil (lease, desi redExpi ration, 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 most flexibility in the length of
`time for which it grants renewals. In most cases, the grantor of a lease is 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 long the lease will remain valid.
`
`The renewFor method adds a lease to the set of leases being managed by the
`LeaseRenewal Manager. 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; desi redDu rati on, a long represent-
`ing the desired duration of lease;
`renewDu rati on, a long representing the
`renewal duration; and listener, a reference to a LeaseLi stener object that will
`receive notifications of events associated with this lease. Both desi redDu rati on
`
`and renewDu rati on 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 desi redDu ration + current time
`
`A COLLECTION OF JINITM TECHNOLOGY HELPER UTILITIES AND SER VICES SPECIFICA TIONS
`
`93
`
`93
`
`

`

`84
`
`THE SEMANTICS
`
`being used for the value of the desi redExpi ration parameter of renewUnti 1.
`The only exception is that,
`in the context of renewFo r,
`the value of the
`renewDu rati on parameter may be Lease.ANY only if the value of the
`desi redDu rat1' on parameter is exactly Lease. FOREVER.
`This method tests for arithmetic overflow in the desired expiration time com-
`puted from the value of desi redDu rati on parameter (des1' redDu rat1' on + cur-
`rent time). Should such overflow be present, a value of Lease. FOREVER is used to
`represent the lease’s desired expiration time.
`The three-argument form of this method is equivalent to the following call:
`
`renewForClease, des1' redDuration, Lease.FOREVER,
`
`listener);
`
`Note that for both versions of renewFo r, a value of Lease .ANY for the
`
`desi redDu ration parameter does not have any special semantics associated with
`it. Calling either version of renewFor with a desi redDu ration 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 renewal failure event will be
`generated if the actual expiration is before the desired expiration; otherwise a
`desired expiration reached event will be generated.
`The getExpi ration method returns the current desired expiration time
`requested for a particular lease, not the actual expiration that was granted when
`the lease was created or last renewed. The only argument to this method is the ref-
`erence to the lease object. If the lease is not in the set of managed leases, an
`Unknown LeaseExcepti on will be thrown.
`
`The setExpi ration method replaces the 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 member of the
`managed set is equivalent to an invocation of the renewUntil method with the
`lease’s current listener input to the 11' stene r parameter. In particular, if the value
`of the expiration parameter is less than or equal to the lease’s current actual
`expiration, this method takes no action.
`An invocation of this method with a lease that is not in the set of managed
`leases will result in an UnknownLeaseExcepti on.
`
`The remove method removes a given lease from the set of managed leases.
`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 Unknown LeaseExcepti on 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 argument to this method is the refer-
`ence to the lease object. If the lease is not in the set of managed leases, an
`Unknown LeaseExcepti on will be thrown.
`
`Any exception (definite or otherwise) occurring during the cancellation of the
`lease will have no effect on the removal of the lease from the managed set. That is,
`even if an exception occurs during the cancel operation, the lease will have been
`removed from the managed set upon return from this method.
`Any exception thrown by the cancel method of the lease object itself may
`also be thrown by this method.
`The clear method removes all leases from the set of managed leases. It does
`not request the cancellation of those leases. This method takes no arguments.
`
`A COLLECTION OF JINITM TECHNOLOGY HELPER UTILITIES AND SER VICES SPECIFICA TIONS
`
`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
`THE LeaseRenewalManager
`LeaseLi stener and Desi redExpi rati onLi stene r. Both of these interfaces ref-
`
`erence one class, LeaseRenewa'l Event.
`
`LM.5.1 The LeaseLi stener Interface
`
`The public methods specified by the LeaseLi stener interface are as follows:
`
`package net .ji ni .lease;
`
`public interface LeaseLi stener extends EventListener
`
`{
`
`void noti fyCLeaseRenewal Event e);
`
`} T
`
`he LeaseLi stener interface defines the mechanism through which the cli-
`ent receives notification of renewal failure events generated by the renewal man-
`ager. These events are delivered using the notify method. Renewal failure events
`are generated when the LeaseRenewal Manager has failed to renew one of the
`leases that it is managing. Such renewal failures typically occur because one of
`the following conditions is met:
`
`9 After successfully renewing a lease any number of times and experiencing
`no failures,
`the LeaseRenewal Manager 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 be fruitless.
`
`9 An indefinite exception occurs during each attempt to renew a lease from the
`point
`that
`the first such exception occurs until
`the point when the
`LeaseRenewal Manager determines that lease’s actual expiration time has
`passed.
`
`9 A definite exception occurs during a lease renewal attempt.
`
`A COLLECTION OF JINITM TECHNOLOGY HELPER UTILITIES AND SER VICES SPECIFICA TIONS
`
`97
`
`97
`
`

`

`88
`
`SUPPORTING INTERFA CES AND CLASSES
`
`It is the responsibility of the client to pass into the LeaseRenewa'l Manager a
`reference to an object that
`implements the LeaseListener interface, which
`defines the actions to take upon receipt of a renewal failure event notification.
`When one of the above conditions occurs, the LeaseRenewalManager will send
`
`an instance of LeaseRenewal Event to that listener object.
`
`LM.5.1.1 The Semantics
`
`The notify method is invoked by the LeaseRenewalManager when it fails to
`renew a lease because one of the conditions described above has occurred. This
`
`method takes one parameter, an instance of the LeaseRenewal Event class, which
`contains information about the lease on which the failed renewal attempt was
`made and information on what caused the failure.
`
`Note that prior to invoking the notify method, the LeaseRenewal Manager
`removes the lease that could not be renewed from the managed set of leases. Note
`also
`that
`because
`of
`the
`reentrancy
`guarantee made
`by
`the
`LeaseRenewa'l Manager, new leases can be added safely from within the notify
`method.
`
`LM.5.2 The Desi redExpi ration Li stener Interface
`
`The public methods specified by the Desi red Expi rati on Li stener interface
`are as follows:
`
`package net.jini.1ease;
`
`public interface Desi redExpi rati onLi stener
`extends LeaseListener
`
`void expi rationReachedCLeaseRenewalEvent e);
`
`} T
`
`he expi rati onReached method receives desired expiration reached events.
`These are generated when the LeaseRenewal Manager removes a 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 renewal failure events.
`
`It is the responsibility of the client to pass into the LeaseRenewa'l Manager a
`reference to an object that implements the Desi redExpi rationLi stener inter-
`
`98
`
`98
`
`

`

`JINI LEASE UTILITIES SPECIFICATION, version 1.1
`
`89
`
`face, which defines the actions to take upon receipt of a desired expiration reached
`event notification.
`
`LM.5.2.1 The Semantics
`
`The expi rationReached method is invoked by the LeaseRenewal Manager
`when a lease in the managed set reaches its desired expiration. This method takes
`one parameter: an instance of the LeaseRenewal Event class, which contains
`information about the lease who’s desired expiration has been reached.
`the
`Note
`that prior
`to
`invoking the
`expi rationReached method,
`LeaseRenewalManager removes the affected lease from the managed set of
`leases. Note also that because of the reentrancy guarantee made by the
`LeaseRenewal Manager, callbacks into the renewal manager can be made safely
`from within the expi rati onReached method.
`
`LM.5.3 The LeaseRenewal Event Class
`
`This class defines the local event that is sent by the LeaseRenewal Manager to the
`client’s registered listener when the LeaseRenewal Manager 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
`when a lease reaches its desired expiration time at or before its actual expiration.
`The LeaseRenewal Event class encapsulates information about the lease on which
`such an event occurs and, if it is a renewal failure, the cause.
`
`package net .ji ni .lease;
`
`public class LeaseRenewal Event extends EventObject
`
`{
`
`}
`
`public LeaseRenewalEvent(LeaseRenewalManager source,
`
`Lease lease,
`
`long expiration,
`
`Throwable ex)
`
`{m}
`
`public Lease getLeaseC) {m}
`
`public long getExpirationC) {m}
`
`public Throwable getExceptionC) {m}
`
`A COLLECTION OF JINITM TECHNOLOGY HELPER UTILITIES AND SER VICES SPECIFICA TIONS
`
`99
`
`99
`
`

`

`90
`
`SUPPORTING INTERFA CES AND CLASSES
`
`The LeaseRenewa'I Event 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 be retrieved.
`
`LM.5.3.1 The Semantics
`
`The constructor of the LeaseRenewa'I Event class takes the following parameters
`as input:
`
`9 A reference to the instance of the LeaseRenewa'I Manage r that generated the
`event
`
`9 The lease associated with this event
`
`9 The desired expiration time of the lease
`
`0 The Th rowabl e associated with the last renewal attempt (if any)
`
`The getLease method returns a reference to the Lease object associated with
`the event. This method takes no arguments.
`The getExp1' ration 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 LeaseRenewa'I Event rep-
`resents a desired expiration reached event this method will return nu11.
`the
`event
`If
`the LeaseRenewa1 Event
`represents
`a
`renewal
`failure
`getExcepti on method will return the exception that caused the event to be sent.
`The conditions under which a renewal failure event may be sent, and the related
`values returned by this method, are as follows:
`
`9 When any lease in the managed set has passed its actual expiration time, and
`either the most recent renewal attempt was successful or there have been no
`renewal attempts,
`the LeaseRenewa1 Manager will cease any further
`attempts to renew the lease, and will send a LeaseRenewa1 Event with no
`associated exception. In this case, invoking this method will return nu] 1 .
`
`o 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 LeaseRenewa'I Manager will continue to attempt to renew the
`
`100
`
`100
`
`

`

`JINI LEASE UTILITIES SPECIFICATION, version 1.1
`
`9]
`
`affected lease at the appropriate times until: 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
`LeaseRenewal Manager will cease any further attempts to renew the lease,
`and will send a LeaseRenewal Event containing the exception associated
`with the last renewal attempt.
`
`9 If, while attempting to renew a lease from the managed set, a definite excep-
`tion is encountered, the LeaseRenewal Manage r will cease any further
`attempts to renew the lease, and will send a LeaseRenewa1 Event containing
`the particular exception that occurred.
`
`LM.5.4 Serialized Forms
`
`(Hass
`
`serialVersionUID
`
`Seriafized Fields
`
`LeaseRenewal Event
`
`-626399341646348302L Lease 'lease
`
`long expiration
`Throwable ex
`
`A COLLECTION OF JINITM TECHNOLOGY HELPER UTILITIES AND SER VICES SPECIFICA TIONS
`
`101
`
`101
`
`

`

`92
`
`SUPPORTING INTERFA CES AND CLASSES
`
`102
`
`102
`
`

`

`
`
`JU
`
`
`
`Jini Join Utilities
`
`Specification
`
`JU.1 Introduction
`
`THIS 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 helper utility class:
`
`9 The Joi nManage r helper utility
`
`93
`
`103
`
`103
`
`

`

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

`

`JINI JOIN UTILITIES SPECIFICATION, version 1.1
`
`95
`
`
`
`
`JU.2 The JoinManager'
`
`THE 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 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 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
`management of all leases on that residency. In addition to handling all discovery
`and join duties, as well as managing all leases on lookup residency, the service
`must provide for the coordination and management of any attribute sets with
`which it may have registered.
`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
`LookupDi scove ryManager and LeaseRenewal Manager.
`(For information on
`these classes, refer to The Jini Technology Core Platform Specification, “Discov-
`cry 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 301' nManager class from the net. j1' n1' .1ookup package. This utility
`class performs all of the functions related to discovery, joining, service lease
`renewal, and attribute management that 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 lookup ser-
`vices (the service’s join state), hence the name 301' nManager.
`The Joi nManager class provides an implementation of the functionality
`described above. The use of this class in a wide variety of services can help mini-
`
`A COLLECTION OF JINITM TECHNOLOGY HELPER UTILITIES AND SER VICES SPECIFICA TIONS
`
`105
`
`105
`
`

`

`96
`
`THE J01” nManager'
`
`mize the work resulting from having to repeatedly implement this required func-
`tionality in each service.
`The Joi nManager is a utility class, not a remote service. Jini services that
`wish to use this utility will create an instance of the 301' nManager in the service’s
`address space to manage the 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 301' nManage r and avails itself of the public methods of that util-
`ity class.
`
`JU.2.1 Other Types
`
`The types defined in the specification of the Joi nManager utility class are in the
`net. j1' n1" .1ookup 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.1ease.Lease
`
`net.jini.core.entry.Entry
`
`net.jini.core.100kup.ServiceID
`
`net.jini.core.1ookup.ServiceRegistrar
`
`net.j1ni.core.1ookup.ServiceRegistration
`
`net.jini.discovery.DiscoveryListener
`
`net.j1ni.discovery.DiscoveryManagement
`
`net.jini.lookup.entry.ServiceControlled
`
`net.jini.1ease.LeaseRenewaTManager
`
`net.j1ni.discovery.LookupLocatorDiscovery
`
`net.jini.discovery.LookupDiscoveryManager
`
`java.io.IOException
`
`java.rmi.Marsha11ed0bject
`
`java.util.EventListener
`
`106
`
`106
`
`

`

`JINI JOIN UTILITIES SPECIFICATION, version 1.1
`
`97
`
`
`
`
`JU.3 The Interface
`
`THE public methods provided by the Joi nManager class are as follows:
`
`package net.jini.lookup;
`
`public class JoinManager {
`
`public JoinManagerCObject obj,
`
`Entry[] attrSets,
`
`ServiceIDListener callback,
`
`DiscoveryManagement discoveryMgr,
`
`LeaseRenewalManager leaseMgr)
`
`throws IOException {m}
`
`public JoinManagerCObject obj,
`
`Entry[] attrSets,
`
`ServiceID serviceID,
`
`DiscoveryManagement discoveryMgr,
`
`LeaseRenewalManager leaseMgr)
`
`throws IOException {m}
`
`public DiscoveryManagement getDiscoveryManagerC) {m}
`
`public LeaseRenewalManager getLeaseRenewalManagerC) {m}
`
`public ServiceRegistrarE]
`
`getJoinSetC) {m}
`
`public EntryEJ getAttributes(){...}
`
`public void addAttributescEntryEJ attrSetS) {---}
`
`public void addAttributesCEntFYE] attrSets,
`
`boolean checkSC) {m}
`
`public void setAttributesCEntFYEJ attrSets) {m}
`
`public void modifyAttributescEntryt] attr‘SetTemPlatesi
`
`public void modifyAttributescEntryt] attr‘SetTemPlatesi
`
`EntryEJ attrSets) {...}
`
`EntFYE] attrSetS,
`
`A COLLECTION OF JINITM TECHNOLOGY HELPER UTILITIES AND SER VICES SPECIFICA TIONS
`
`107
`
`107
`
`

`

`98
`
`THE INTERFACE
`
`pub1ic void terminateC) {m}
`
`boo1ean checkSC) {m}
`
`108
`
`108
`
`

`

`JINI JOIN UTILITIES SPECIFICATION, version 1.1
`
`99
`
`
`
`
`JU.4 The Semantics
`
`THE 301' nManager 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 regis-
`tered (by the 301' nManager), as well as methods that allow the entity to retrieve
`references to the objects the 301' nManager uses for discovery management and
`lease renewal management. Additionally, the 301' nManager 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 Joi nManager class returns true if and only iftwo
`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 Joi nManager class has two forms. Each form of the
`
`constructor throws IOExcepti on because construction of a 301' nManager may ini-
`tiate the multicast discovery process, which can throw IOExcepti on.
`The first form of the constructor takes the following parameters as input:
`
`9 A reference to the service requesting the services of the 301' nManager
`
`9 An array containing the service’s attributes
`
`o A reference to an object that implements the Se rv1' ceIDL1' stene r interface
`(belonging to the package net. ji m'
`. lookup)
`
`o A reference to an object that implements the D1' scove ryManagement inter-
`face
`
`9 An instance of the LeaseRenewal Manager 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 notifica-
`tion being sent to the listener object that was passed as the Se rv1' ceIDLi stener
`
`A COLLECTION OF JINITM TECHNOLOGY HELPER UTILITIES AND SER VICES SPECIFICA TIONS
`
`109
`
`109
`
`

`

`100
`
`THE SEMANTICS
`
`argument (cal l back). If a null value is passed in through this argument, then no
`such notification will be sent.
`
`To use the Joi nManage r, the service supplies an object through which notifi-
`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
`D1" scove r'yManagement
`interface. That
`is,
`this object must provide the
`301' nManager with the ability to set discovery listeners and to discard previously
`discovered lookup services when they are found to be unavailable.
`The D1' scoveryManagement argument may be set to a value of null. If null
`is the value of this argument, then an instance of the LookupDi scove ryManager
`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 LeaseRenewal Manager argument may be set to a value of null. If null
`is the value of this argument, an instance of the LeaseRenewal Manager class will
`be created, initially managing no Lease objects. This feature allows a service that
`employs the 301' nManager 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 accessi-
`ble only within the Joi nManage r.
`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 ser-
`vices 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 Se rv1' ceID replaces an instance of the
`Serv1' ceIDLi stener interface. Note that the Serv1' ceID class is defined in The
`
`Jim' Technology Core Platform Specification, “Lookup Service”, and the
`Se rv1' ceIDLi stene r interface is described later.
`
`The second form of the constructor applies the same semantics to the attr—
`Sets, d1" scove r'yMg r, 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
`
`getD1' scove ryManager
`
`method
`
`returns
`
`the
`
`instance
`
`of
`
`D1' scove ryManagement 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.
`
`110
`
`110
`
`

`

`JINI JOIN UTILITIES SPECIFICATION, version 1.1
`
`101
`
`The object returned by this method encapsulates the mechanism by which
`either the 301' nManager 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
`
`LeaseRenewa1 Manager class. This method takes no arguments as input.
`The object returned by this method manages the leases requested and held by
`the 301' nManager. Although it may also manage leases unrelated to the join pro-
`cess that are requested and held by the service itself, the leases with which the
`301' nManager is concerned are the leases that correspond to the service registra-
`tion requests the 301' nManager has made with each lookup service the service
`wishes to join.
`The get] 01' nSet method returns an array of Se rvi ceRegi st rar 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.
`T