Overview

The space provides a mechanism, called leasing, that keeps the space clean and consistent even if applications disconnect before they erase their temporary data. Leasing is supported both for regular write operations and transactions.

Each time an application writes an object to the space, it must specify the lease time – how long it should remain in memory before the space automatically deletes it.

If the information is of a persistent nature, the lease can be set to FOREVER (and the object is never erased). Otherwise, a limited lease time can be set, such as 5 minutes – after this elapses, if the object is still needed, it is the application's responsibility to renew the lease using the LeaseRenewalManager.

The LeaseRenewalManager provides systematic renewal and overall management of a set of leases associated with one or more remote entities on behalf of a local entity.

This class removes much of the administrative burden associated with lease renewal.

Clients of the renewal manager simply give their leases to the manager and the manager renews each lease as necessary to achieve a desired expiration time (which may be later than the lease's current actual expiration time). Failures encountered while renewing a lease can optionally be reflected to the client via LeaseRenewalEvent instances.

This class is not remote. Entities wishing to use this class must create an instance of this class in their own virtual machine to locally manage the leases granted to them. If the virtual machine that the manager was created in exits or crashes, the renewal manager is destroyed.

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. The actual expiration time of a lease object can be retrieved by invoking the lease's getExpiration method.

Each lease in the managed set also has two other associated attributes: A desired renewal duration, and a remaining desired duration. The desired renewal duration is specified (directly or indirectly) when the lease is added to the set. This duration must normally be a positive number; however, it may be Lease.ANY if the lease's desired expiration is Lease.FOREVER. The remaining desired duration is always the desired expiration less the current time.

Each time a lease is renewed, the renewal manager asks for an extension equal to the lease's renewal duration if the renewal duration is Lease.ANY or less than the remaining desired duration. Otherwise, it asks for an extension equal to the lease's remaining desired duration.

Once a lease is given to a LeaseRenewalManager, the manager continues to renew the lease until one of the following occurs:

• The lease's desired or actual expiration time is reached.
• An explicit removal of the lease from the set is requested via a cancel, clear, or remove call on the renewal manager.
• The renewal manager tries to renew the lease and gets a bad object exception, bad invocation exception, or LeaseException.

The methods of this class are appropriately synchronized for concurrent operations. Additionally, this class makes certain guarantees with respect to concurrency. When this class makes a remote call (for example, when requesting the renewal of a lease), any invocations made on the methods of this class are not blocked. Similarly, this class makes a reentrancy guarantee with respect to the listener objects registered with this class. Should this class invoke a method on a registered listener (a local call), calls from that method to any other method of this class are guaranteed not to result in a deadlock condition.

Below is an example for LeaseRenewalManager usage:

First option:

String className = LeaseRenewalManager.class.getName();
String[] configArgs = new String[2];
configArgs[0] = "-";
configArgs[Look And Feel - ServiceGrid] = className + ".roundTripTime=1000" ;
configArgs[2] = className + ".renewBatchTimeWindow=1000" ; 
Configuration config = ConfigurationProvider.getInstance(configArgs);
LeaseRenewalManager lrm = new LeaseRenewalManager(config);

Second option – use the LeaseRenewalManage.config configuration file:

net.jini.lease.LeaseRenewalManage {
	renewBatchTimeWindow   = new Long(2);
	roundTripTime = new Long(500);
}

Third option:

net.jini.config.Configuration conf=new net.jini.config.Configuration()
{
     public Object getEntry(String component, String name, Class type) throws
      ConfigurationException
     {
	return getEntry(component,name,type,new Long(-1),null);
     }
     public Object getEntry(String component, String name, Class type, Object
     defaultValue) throws
     ConfigurationException
     {
     	return getEntry(component,name,type,defaultValue,null);
     }
     public Object getEntry(String component, String name, Class type, Object
     defaultValue, Object data) throws
ConfigurationException
    {
	if (!component.equals("net.jini.lease.LeaseRenewalManager"))
		return defaultValue;
	if (name.equals("roundTripTime"))
		return new Long(500);                                                    
		// renewalRTT
	if (name.equals("renewBatchTimeWindow"))
		return new Long(2);                                                        
		// renewBatchTimeWindow   
return defaultValue;
    }
);
LeaseRenewalManager lrm = new LeaseRenewalManager(conf);

For an example using the LeaseRenewalManager, refer to the Slow Consumer section. For more details on the LeaseRenewalManager, see Javadoc.