LE.2. Basic Leasing Interfaces

The basic concept of leasing is that access to a resource or the request for some action is not open ended with respect to time, but granted only for some particular interval. In general (although not always), this interval is determined by some negotiation between the object asking for the leased resource (which we will call the lease holder) and the object granting access for some period (which we will call the lease grantor).

In its most general form, a lease is used to associate a mutually agreed upon time interval with an agreement reached by two objects. The kinds of agreements that can be leased are varied and can include such things as agreements on access to an object (references), agreements for taking future action (event notifications), agreements to supplying persistent storage (file systems, JavaSpaces systems), or agreements to advertise availability (naming or directory services).

While it is possible that a lease can be given that provides exclusive access to some resource, this is not required with the notion of leasing being offered here. Agreements that provide access to resources that are intrinsically sharable can have multiple concurrent lease holders. Other resources might decide to grant only exclusive leases, combining the notion of leasing with a concurrency control mechanism.

LE.2.1. Characteristics of a Lease

There are a number of characteristics that are important for understanding what a lease is and when it is appropriate to use one. Among these characteristics are:

• A lease is a time period during which the grantor of the lease ensures (to the best of the grantor’s abilities) that the holder of the lease will have access to some resource. The time period of the lease can be determined solely by the lease grantor, or can be a period of time that is negotiated between the holder of the lease and the grantor of the lease. Duration negotiation need not be multi-round; it often suffices for the requestor to indicate the time desired and the grantor to return the actual time of grant.

• During the period of a lease, a lease can be cancelled by the entity holding the lease. Such a cancellation allows the grantor of the lease to clean up any resources associated with the lease and obliges the grantor of the lease to not take any action involving the lease holder that was part of the agreement that was the subject of the lease.

• A lease holder can request that a lease be renewed. The renewal period can be for a different time than the original lease, and is also subject to negotiation with the grantor of the lease. The grantor may renew the lease for the requested period or a shorter period or may refuse to renew the lease at all. However, when renewing a lease the grantor cannot, unless explicitly requested to do so, shorten the duration of the lease so that it expires before it would have if it had not been renewed. A renewed lease is just like any other lease and is itself subject to renewal.

• A lease can expire. If a lease period has elapsed with no renewals, the lease expires, and any resources associated with the lease may be freed by the lease grantor. Both the grantor and the holder are obliged to act as though the leased agreement is no longer in force. The expiration of a lease is similar to the cancellation of a lease, except that no communication is necessary between the lease holder and the lease grantor.

Leasing is part of a programming model for building reliable distributed applications. In particular, leasing is a way of ensuring that a uniform response to failure, forgetting, or disinterest is guaranteed, allowing agreements to be made that can then be forgotten without the possibility of unbounded resource consumption, and providing a flexible mechanism for duration-based agreement.

LE.2.2. Basic Operations

The Lease interface defines a type of object that is returned to the lease holder and issued by the lease grantor. The basic interface may be extended in ways that offer more functionality, but the basic interface is:

package net.jini.core.lease; 

import java.rmi.RemoteException; 

public interface Lease {
    long FOREVER = Long.MAX_VALUE; 
    long ANY = -1; 
    int DURATION = 1; 
    int ABSOLUTE = 2; 

    long getExpiration(); 
    void cancel() throws UnknownLeaseException, 
                         RemoteException; 
    void renew(long duration) throws LeaseDeniedException, 
                                     UnknownLeaseException, 
                                     RemoteException; 
    void setSerialFormat(int format); 
    int getSerialFormat(); 
    LeaseMap createLeaseMap(long duration); 
    boolean canBatch(Lease lease); 
} 

Particular instances of the Lease type will be created by the grantors of a lease and returned to the holder of the lease as part of the return value from a call that allocates a leased resource. The actual implementation of the object, including the way (if any) in which the Lease object communicates with the grantor of the lease, is determined by the lease grantor and is hidden from the lease holder.

The interface defines two constants that can be used when requesting a lease. The first, FOREVER, can be used to request a lease that never expires. When granted such a lease, the lease holder is responsible for ensuring that the leased resource is freed when no longer needed. The second constant, ANY, is used by the requestor to indicate that no particular lease time is desired and that the grantor of the lease should supply a time that is most convenient for the grantor.

If the request is for a particular duration, the lease grantor is required to grant a lease of no more than the requested period of time. A lease may be granted for a period of time shorter than that requested.

A second pair of constants is used to determine the format used in the serialized form for a Lease object; in particular, the serialized form that is used to represent the time at which the lease expires. If the serialized format is set to the value DURATION, the serialized form will convert the time of lease expiration into a duration (in milliseconds) from the time of serialization. This form is best used when transmitting a Lease object from one address space to another (such as via an RMI call) where it cannot be assumed that the address spaces have sufficiently synchronized clocks. If the serialized format is set to ABSOLUTE, the time of expiration will be stored as an absolute time, calculated in terms of milliseconds since the beginning of the epoch.

The first method in the Lease interface, getExpiration, returns a long that indicates the time, relative to the current clock, that the lease will expire. Follow ing the usual convention in the Java programming language, this time is represented as milliseconds from the beginning of the epoch and can be used to compare the expiration time of the lease with the result of a call to obtain the current time, java.lang.System.currentTimeMillis.

The second method, cancel, can be used by the lease holder to indicate that it is no longer interested in the resource or information held by the lease. If the leased information or resource could cause a callback to the lease holder (or some other object on behalf of the lease holder), the lease grantor should not issue such a callback after the lease has been cancelled. The overall effect of a cancel call is the same as lease expiration, but instead of happening at the end of a pre-agreed duration, it happens immediately. If the lease being cancelled is unknown to the lease grantor, an UnknownLeaseException is thrown. The method can also throw a RemoteException if the implementation of the method requires calling a remote object that is the lease holder.

The third method, renew, is used to renew a lease for an additional period of time. The length of the desired renewal is given, in milliseconds, in the parameter to the call. This duration is not added to the original lease, but is used to determine a new expiration time for the existing lease. This method has no return value; if the renewal is granted, this is reflected in the lease object on which the call was made. If the lease grantor is unable or unwilling to renew the lease, a LeaseDeniedException is thrown. If a renewal fails, the lease is left intact for the same duration that was in force prior to the call to renew. If the lease being renewed is unknown to the lease grantor, an UnknownLeaseException is thrown. The method can also throw a RemoteException if the implementation of the method requires calling a remote object that is the lease holder.

As with a call that grants a lease, the duration requested in a renew call need not be honored by the entity granting the lease. A renewal may not be for longer than the duration requested, but the grantor may decide to renew a lease for a period of time that is shorter than the duration requested. However, the new lease cannot have a duration that is shorter than the duration remaining on the lease being renewed unless a shorter duration is specifically requested.

Two methods are concerned with the serialized format of a Lease object. The first, setSerialFormat, takes an integer that indicates the appropriate format to use when serializing the lease. The current supported formats are a duration format which stores the length of time (from the time of serialization) before the lease expires, and an absolute format, which stores the time (relative to the current clock) that the lease will expire. The duration format should be used when serializing a Lease object for transmission from one machine to another; the absolute format should be used when storing a Lease object on stable store that will be read back later by the same process or machine. The default serialization format is durational. The second method, getSerialFormat, returns an integer indicating the format that will be used to serialize the Lease object.

The last two methods are used to aid in the batch renewal or cancellation of a group of Lease objects. The first of these, createLeaseMap, creates a Map object that can contain leases whose renewal or cancellation can be batched and adds the current lease to that map. The current lease will be renewed for the duration indicated by the argument to the method when all of the leases in the LeaseMap are renewed. The second method, canBatch, returns a boolean value indicating whether or not the lease given as an argument to the method can be batched (in renew and cancel calls) with the current lease. Whether or not two Lease objects can be batched is an implementation detail determined by the objects. However, if a Lease object can be batched with any other Lease object, the set of objects that can be batched must form an equivalence class. That is, the canBatch relationship must be reflexive, symmetric, and associative. This means that, for any three Lease objects x, y, and z that return true for any instance of the canBatch call, it will be the case that:

• x.canBatch(x) is true

• if x.canBatch(y) is true then y.canBatch(x) is true

• if x.canBatch(y) is true andy.canBatch(z) is true, then x.canBatch(z) is true

In addition to the above methods, an object that implements the Lease interface will probably need to override the equals and hashcode methods inherited from Object. It is likely that such leases, while appearing as local objects, will in fact contain remote references—either explicitly copied or passed via a method call—to implementation-specific objects in the address space of the lease grantor. These local references may even include their own state (such as the expiration time of the lease) that may, over time, vary from the actual expiration time of the lease to which they refer. Two such references should evaluate as equal (and have the same hashcode value) when they refer to the same lease in the grantor, which will not be reflected by the default implementation of the equals method.

Three types of Exception objects are associated with the basic lease interface. All of these are used in the Lease interface itself, and two can be used by methods that grant access to a leased resource.

The RemoteException is imported from the package java.rmi. This exception is used to indicate a problem with any communication that might occur between the lease holder and the lease grantor if those objects are in separate virtual machines. The full specification of this exception can be found in the Java Remote Method Invocation Specification.

The UnknownLeaseException is used to indicate that the Lease object used is not known to the grantor of the lease. This can occur when a lease expires or when a copy of a lease has been cancelled by some other lease holder. This exception is defined as:

package net.jini.core.lease; 

public class UnknownLeaseException extends LeaseException {
    public UnknownLeaseException() {
        super(); 
    } 
    public UnknownLeaseException(String reason) {
        super(reason); 
    } 
} 

The final exception defined is the LeaseDeniedException, which can be thrown by either a call to renew or a call to an interface that grants access to a leased resource. This exception indicates that the requested lease has been denied by the resource holder. The exception is defined as:

package net.jini.core.lease; 

public class LeaseDeniedException extends LeaseException {
    public LeaseDeniedException() {
        super(); 
    } 
    public LeaseDeniedException(String reason) {
        super(reason); 
    } 
} 

The LeaseException superclass is defined as:

package net.jini.core.lease; 

public class LeaseException extends Exception {
    public LeaseException() {
        super(); 
    } 
    public LeaseException(String reason) {
        super(reason); 
    } 
} 

The final basic interface defined for leasing is that of a LeaseMap, which allows groups of Lease objects to be renewed or cancelled by a single operation. The LeaseMap interface is:

package net.jini.core.lease; 

import java.rmi.RemoteException; 

public interface LeaseMap extends java.util.Map {
    boolean canContainKey(Object key); 
    void renewAll() throws LeaseMapException, RemoteException; 
    void cancelAll() throws LeaseMapException,RemoteException; 
} 

A LeaseMap is an extension of the java.util.Map interface that associates a Lease object with a Long. The Long is the duration for which the lease should be renewed whenever it is renewed. Lease objects and associated renewal durations can be entered and removed from a LeaseMap by the usual Map methods. An attempt to add a Lease object to a map containing other Lease objects for which Lease.canBatch would return false will cause an IllegalArgumentException to be thrown, as will attempts to add a key that is not a Lease object or a value that is not a Long.

The first method defined in the LeaseMap interface, canContainKey, takes a Lease object as an argument and returns true if that Lease object can be added to the Map and false otherwise. A Lease object can be added to a Map if that Lease object can be renewed in a batch with the other objects in the LeaseMap. The requirements for this depend on the implementation of the Lease object. However, if a LeaseMap object, m, contains a Lease object, n, then for some Lease object o, n.canBatch(o) returns true if and only if m.canContainKey(o) returns true.

The second method, renewAll, will attempt to renew all of the Lease objects in the LeaseMap for the duration associated with the Lease object. If all of the Lease objects are successfully renewed, the method will return nothing. If some Lease objects fail to renew, those objects will be removed from the LeaseMap and will be contained in the thrown LeaseMapException.

The third method, cancelAll, cancels all the Lease objects in the LeaseMap. If all cancels are successful, the method returns normally and leaves all leases in the map. If any of the Lease objects cannot be cancelled, they are removed from the LeaseMap and the operation throws a LeaseMapException.

The LeaseMapException class is defined as:

package net.jini.core.lease; 

import java.util.Map; 

public class LeaseMapException extends LeaseException {
    public Map exceptionMap; 
    public LeaseMapException(String s, Map exceptionMap) {
        super(s); 
        this.exceptionMap = exceptionMap; 
    } 
} 

Objects of type LeaseMapException contain a Map object that maps Lease objects (the keys) to Exception objects (the values). The Lease objects are the ones that could not be renewed or cancelled, and the Exception objects reflect the individual failures. For example, if a LeaseMap.renew call fails because one of the leases has already expired, that lease would be taken out of the original LeaseMap and placed in the Map returned as part of the LeaseMapException object with an UnknownLeaseException object as the corresponding value.

LE.2.3. Leasing and Time

The duration of a lease is determined when the lease is granted (or renewed). A lease is granted for a duration rather than until some particular moment of time, since such a grant does not require that the clocks used by the client and the server be synchronized.

The difficulty of synchronizing clocks in a distributed system is well known. The problem is somewhat more tractable in the case of leases, which are expected to be for periods of minutes to months, as the accuracy of synchronization required is expected to be in terms of minutes rather than nanoseconds. Over a particular local group of machines, a time service could be used that would allow this level of synchronization.

However, leasing is expected to be used by clients and servers that are widely distributed and might not share a particular time service. In such a case, clock drift of many minutes is a common occurrence. Because of this, the leasing specification has chosen to use durations rather than absolute time.

The reasoning behind such a choice is based on the observation that the accuracy of the clocks used in the machines that make up a distributed system is matched much more closely than the clocks on those systems. While there may be minutes of difference in the notion of the absolute time held by widely separated systems, there is much less likelihood of a significant difference over the rate of change of time in those systems. While there is clearly some difference in the notion of duration between systems (if there were not, synchronization for absolute time would be much easier), that difference is not cumulative in the way errors in absolute time are.

This decision does mean that holders of leases and grantors of leases need to be aware of some of the consequences of the use of durations. In particular, the amount of time needed to communicate between the lease holder and the lease grantor, which may vary from call to call, needs to be taken into account when renewing a lease. If a lease holder is calculating the absolute time (relative to the lease holder’s clock) at which to ask for a renewal, that time should be based on the sum of the duration of the lease plus the time at which the lease holder requested the lease, not on the duration plus the time at which the lease holder received the lease.

LE.2.4. Serialized Forms