LM.4. The Semantics

The term client is used in this specification to refer to the local entity that is using the LeaseRenewalManager to manage a collection of leases on its behalf. This collection is referred to as the managed set.

The LeaseRenewalManager distinguishes between two time values associated with lease expiration: the desired expiration time for the lease and the actual expiration time granted when the lease is created or last renewed. The desired expiration represents when the client would like the lease to expire. The actual expiration represents when the lease is going to expire if it is not renewed. Both time values are absolute times, not relative time durations. The desired expiration time can be retrieved using the renewal manager’s getExpiration method, which is described below. The actual expiration time of a lease object can be retrieved by invoking the getExpiration method directly on the lease (see the Lease interface defined in The Jini Technology Core Platform Specification, “Distributed Leasing”).

Each lease in the managed set also has two other associated attributes: a renewal duration and a remaining desired duration. The remaining desired duration is always the desired expiration less the current time. The renewal duration is usually a positive number and is the new duration that will be requested when the renewal manager renews the lease, unless the renewal duration is greater than the remaining desired duration. If the renewal duration is greater than the remaining desired duration, then the remaining desired duration will be requested when renewing the lease. One exception is that when the desired expiration is Lease.FOREVER, the renewal duration may be Lease.ANY, in which case Lease.ANY will be requested when renewing the client lease, regardless of the value of the remaining desired duration.

For example, if the renewal duration associated with a given lease is 360,000 milliseconds, then when the renewal manager renews the lease, it will ask for a new duration of 360,000 milliseconds—unless the lease is going to reach its desired expiration in less than 360,000 milliseconds. If the lease’s desired expiration is within 360,000 milliseconds, the renewal manager will ask for the difference between the current time and the desired expiration. If the renewal duration had been Lease.ANY, the renewal manager would have asked for a new duration of Lease.ANY.

The term definite exception is used to refer to exceptions that result from operations on a lease (such as a renewal attempt) that are indicative of a permanent failure of the lease. For the purposes of this document, all bad object exceptions, bad invocation exceptions, and LeaseException s are considered to be definite exceptions (see Introduction to Helper Utilities and Services, Section US.2.6, “What Exceptions Imply about Future Behavior”).

The LeaseRenewalManager generates two kinds of local events. The first kind is a renewal failure event that is generated when the renewal manager finds that it can’t renew a lease. The second kind is a desired expiration reached event, which is generated when a lease’s desired expiration is reached. Each event signals that the renewal manager has removed a lease from the managed set without an explicit request by the client. When placing a lease in the managed set, the client can provide either a LeaseListener object that will receive any renewal failure events associated with the lease, or a DesiredExpirationListener (a subinterface of LeaseListener) object that will receive both renewal failure and desired expiration reached events associated with the lease. Both kinds of event are represented by LeaseRenewalEvent objects.

The LeaseRenewalManager makes a concurrency guarantee. When the LeaseRenewalManager makes a remote call (for example, when requesting the renewal of a lease), any invocations made on the methods of the LeaseRenewalManager will not be blocked. Because of these concurrency guarantees, it is not possible for the various methods that remove leases from the managed set (for example, remove, cancel, and clear) to guarantee that the renewal manager will not attempt to renew leases that have just been removed. Similarly, it is not possible for the methods that change the desired expiration or renewal duration associated with a lease (for example, renewUntil, renewFor, and setExpiration) to guarantee that the next renewal of the lease will request a duration that is consistent with the new desired expiration and/or renewal duration (it will be consistent with either the old pair or the new pair). However, implementations should keep the window where such renewals could occur as small as possible.

The LeaseRenewalManager makes a similar reentrancy guarantee with respect to LeaseListener and DesiredExpirationListener objects registered with the LeaseRenewalManager. Should the LeaseRenewalManager invoke a method on a registered listener (a local call), calls from that method to any method of the LeaseRenewalManager are guaranteed not to result in a deadlock condition. One implication of this guarantee is that the delivery of events is asynchronous with respect to any call (or sequence of calls) made on the renewal manager after the event occurs; this allows events to be delivered after they have been made moot by intervening calls on the renewal manager. For example, the renewal manager 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:

• The first form of the constructor takes no arguments. This form of the constructor instantiates a LeaseRenewalManager object that initially manages no leases.

• The second form of the constructor creates a LeaseRenewalManager 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 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 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 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 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 LeaseListener object that will receive notification of events associated with this lease. The LeaseListener argument may be null.

If null is passed as the lease parameter, a NullPointerException 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 IllegalArgumentException 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 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 renewal failure event.

• 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 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 argument 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 renewDuration parameter is interpreted as the renewal duration, in milliseconds, to associate with the lease.

If a nonnull 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 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 LeaseRenewalEvent 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 successfully, a renewal attempt results in a 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 and either (1) the last renewal attempt succeeded or (2) there have been no renewal attempts, a LeaseRenewalEvent 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 LeaseListener parameter, then no notifications will be delivered.

Calling the three-argument form of renewUntil with a desiredExpiration 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, desiredExpiration, Lease.FOREVER, 
                 listener); 

The renewFor method adds a 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 representing 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 being used for the value of the desiredExpiration parameter of renewUntil. 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 parameter is exactly Lease.FOREVER.

This method tests for arithmetic overflow in the desired expiration time computed from the value of desiredDuration parameter (desiredDuration+ current 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:

     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 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 getExpiration 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 reference to the lease object. If the lease is not in the set of managed leases, an UnknownLeaseException will be thrown.

The setExpiration 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 listener 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 UnknownLeaseException.

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

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