Spec Index A Collection of Jini Technology Helper Utilities and Services Specifications

Version 1.0

LM - JiniTM Lease Utilities Specification

LM.1 Introduction

This specification defines helper utility classes, along with supporting interfaces and classes, that encapsulate functionality which provides for the coordination, systematic renewal, and overall management of a set of leases associated with some object on behalf of another object. Currently, this specification defines only one helper utility class:

LM.2 The LeaseRenewalManager

The LeaseRenewalManager class (belonging to the package net.jini.lease) encapsulates functionality that provides for the systematic renewal and overall management of a set of leases associated with one or more remote entities on behalf of a local entity.

The concept of leased resources is fundamental to the Jini technology programming model. Providing a leasing mechanism helps to prevent the accumulation of outdated and unwanted resources in time-based distributed systems, such as the Jini technology infrastructure. The leasing model for Jini network technology (Jini technology), defined in the Jini Distributed Leasing Specification, Section LE.1.1, "Leasing and Distributed Systems", requires renewed proof of interest to continue the existence of a leased resource. Thus, any Jini technology-enabled client (Jini client) or Jini technology-enabled service (Jini service) that requests the use of the leased resources provided by another Jini service may be granted access to those resources for a negotiated period of time, and must continue to request renewal of the lease on each resource for as long as the client or service wishes to have access to the resource.

For example, the Jini lookup service leases two resources: residency in its database and registration with its event notification mechanism. Thus, if a service that is registered with a Jini lookup service wishes to continue its residency beyond the length of the current lease, the service must request a lease renewal from that lookup service. This renewal process must be repeated for as long as the service wishes to maintain its residency in the lookup service. Similarly, if a client has requested that a lookup service notify it of events of interest, then prior to the expiration of the lease on the event registration, the client must request that the lookup service continue to send such events. As with residency in the lookup service, these renewal requests must be repeated for as long as the client wishes to receive event notifications.

Another example of a Jini service providing leased resources would be a service that implements the Jini Transaction Specification to manage transactions on behalf of registered participants. That specification requires that a transaction must be a leased resource. Therefore, any entity that creates such a transaction object is required to negotiate (with an entity referred to as a transaction manager) a lease on that object, repeatedly requesting lease renewals prior to the lease's expiration, for as long as the transaction is to remain in effect.

The LeaseRenewalManager class is designed to be a simple mechanism that provides for the systematic renewal and overall management of leases granted on resources that are provided by Jini services and for which a Jini client or service has registered interest. The LeaseRenewalManager is a utility class, not a remote service. In order to use this utility, an entity must create, in its own address space, an instance of the LeaseRenewalManager to manage the entity's leases locally.

LM.2.1 Other Types

The types defined in the specification of the LeaseRenewalManager utility class are in the net.jini.lease package. The following types may be referenced in this specification. Whenever referenced, these types will be referenced in unqualified form: 

net.jini.config.Configuration
net.jini.config.ConfigurationException
net.jini.core.lease.Lease
net.jini.core.lease.UnknownLeaseException
net.jini.core.lease.LeaseDeniedException
java.rmi.RemoteException
java.rmi.NoSuchObjectException
java.util.EventObject
java.util.EventListener

LM.3 The Interface

The public methods provided by the LeaseRenewalManager class are: 

package net.jini.lease;

public class LeaseRenewalManager
{
    public LeaseRenewalManager() {...}
    public LeaseRenewalManager(Configuration config)
        throws ConfigurationException {...}
    public LeaseRenewalManager(Lease lease,
                               long desiredExpiration,
                               LeaseListener listener) {...}
    public void renewUntil(Lease lease,
                           long desiredExpiration,
                           long renewDuration,
                           LeaseListener listener) {...}
    public void renewUntil(Lease lease,
                           long desiredExpiration,
                           LeaseListener listener) {...}
    public void renewFor(Lease lease,
                         long desiredDuration, 
                         long renewDuration,
                         LeaseListener listener) {...}
    public void renewFor(Lease lease,
                         long desiredDuration,
                         LeaseListener listener) {...}
    public long getExpiration(Lease lease)
        throws UnknownLeaseException {...}
    public void setExpiration(Lease lease, 
                              long  desiredExpiration)
        throws UnknownLeaseException {...}
    public void remove(Lease lease) 
        throws UnknownLeaseException {...}
    public void cancel(Lease lease)
        throws UnknownLeaseException, RemoteException {...}
    public void clear() {...}
}

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 Distributed Leasing Specification).

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. The term indefinite exception refers to exceptions that do not imply anything about the probability of success of any future lease operations. The algorithm used to classify exceptions as definite or indefinite is implementation-specific.

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 three forms:

Creating a LeaseRenewalManager using the third 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-argument 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 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 non-null 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 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);
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 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 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.

LM.5 Supporting Interfaces and Classes

The LeaseRenewalManager utility class depends on the interfaces LeaseListener and DesiredExpirationListener. Both of these interfaces reference one class, LeaseRenewalEvent.

LM.5.1 The LeaseListener Interface

The public methods specified by the LeaseListener interface are as follows: 

package net.jini.lease;

public interface LeaseListener extends EventListener
{
    void notify(LeaseRenewalEvent e);
}

The LeaseListener interface defines the mechanism through which the client receives notification of renewal failure events generated by the renewal manager. These events are delivered using the notify method. Renewal failure events are generated when the LeaseRenewalManager 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:

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. When one 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 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 LeaseRenewalEvent 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 LeaseRenewalManager 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 LeaseRenewalManager, new leases can be added safely from within the notify method.

LM.5.2 The DesiredExpirationListener Interface

The public methods specified by the DesiredExpirationListener interface are as follows: 

package net.jini.lease;

public interface DesiredExpirationListener
    extends LeaseListener
{
    void expirationReached(LeaseRenewalEvent e);
}

The expirationReached method receives desired expiration reached events. These are generated when the LeaseRenewalManager 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 LeaseRenewalManager a reference to an object that implements the DesiredExpirationListener interface, which defines the actions to take upon receipt of a desired expiration reached event notification.

LM.5.2.1 The Semantics

The expirationReached method is invoked by the LeaseRenewalManager when a lease in the managed set reaches its 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.

Note that prior to invoking the expirationReached method, the 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 made safely from within the expirationReached 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 when a lease reaches its desired expiration time at 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() {...}
}

The LeaseRenewalEvent class is a subclass of the EventObject class, adding 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 additional state may be retrieved.

LM.5.3.1 The Semantics

The constructor of the LeaseRenewalEvent class takes the following parameters as input:

The getLease method returns 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 represents a desired expiration reached event this method will return null.

If the LeaseRenewalEvent represents a renewal failure event the getException 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:

LM.5.4 Serialized Forms

Class
 serialVersionUID
 Serialized Fields
LeaseRenewalEvent
 -626399341646348302L
 Lease lease
long expiration
Throwable ex

LM.6 History
Version Description
v1.0 Initial release of this specification.

License

Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Spec Index A Collection of Jini Technology Helper Utilities and Services Specifications
Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.