7.2. The Lease Object

A Lease object must implement the Lease interface, presented in its entirety in Figure 7.1, which contains a set of methods for dealing with leases. In discussing the interface, we will ignore a few constants and methods that are not typically used in space-based programming; the full details of leasing can be found in the Jini™ Distributed Leasing Specification.

Figure 7.1. The Lease interface.

package net.jini.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);
}

7.2.1. Lease Expiration

Every lease object provides a getExpiration method that you can use to determine the expiration time of the lease. For instance, consider the following code:

Lease lease = space.write(entry, null, Lease.ANY);
long expirationTime = lease.getExpiration();

Here, we first call write with a lease length of Lease.ANY, which means we let the space choose the lease duration. Next we call getExpiration, which returns the lease's expiration time (in the fashion of the Java platform, measured in milliseconds since midnight, January 1, 1970).

The time returned from getExpiration is measured according to the local clock of the calling process (not the remote space's clock). This means that we can determine the time remaining in a lease by calling the Java platform's System.currentTimeMillis method (which returns the current local machine time in milliseconds) and compare its result to the value returned from getExpiration. Here is an example:

long currentTime = System.currentTimeMillis();
long delta = expirationTime - currentTime;

Here, delta contains the number of milliseconds before the lease will expire.

7.2.2. Renewing a Lease

To extend a lease's expiration time, we call its renew method, which is defined as follows:

void renew(long duration)
  throws LeaseDeniedException, UnknownLeaseException,
     RemoteException;

The renew method takes one parameter that specifies the amount of time (in milliseconds) desired for the new lease. If the renewal is granted for that duration, the existing lease object's expiration time is updated to expire after duration milliseconds. For instance, if we request a duration of 60,000 milliseconds on a lease that has 10,000 milliseconds remaining, then the updated lease expiration will reflect 60,000 milliseconds remaining (not 10,000 plus 60,000 milliseconds). It's important to point out that there is no guarantee a renewal request will be granted at all. If a renewal is granted, the space determines the actual lease time, which may be shorter than the time we requested.

The renew method can throw three exceptions: LeaseDeniedException, UnknownLeaseException, and RemoteException. A LeaseDeniedException is thrown if the space cannot renew the lease at all. The reasons a lease might be denied are dependent on the implementation and runtime characteristics of the space; for instance, a space might lack the resources (such as disk space) to renew the lease at that time. When a LeaseDeniedException occurs, the lease is left unchanged, and has the expiration time it had before the renew call. The UnknownLeaseException is thrown if the lease object isn't known to the space. This can happen if the lease has already expired, or has been cancelled (as we'll see in the next section) or if the entry has been taken from the space by another process. Finally, the RemoteException is thrown when a communication problem occurs between the process and the remote space.

Here is an example of how we would request a renewal of an existing lease on an entry:

try {
   long duration = 1000 * 60;     // 1 minute
   lease.renew(duration);
   System.out.println("lease now ends at " +
     new Date(lease.getExpiration()));
} catch (LeaseDeniedException e) {
  // handle exception here
} catch (UnknownLeaseException e2) {
  // handle exception here
} catch (RemoteException e3) {
  // handle exception here
}

Here, we request that a lease object be renewed for one minute, in effect asking to extend the entry's lifetime in the space. To see if the renewal request was granted for the full duration, we print the lease's new expiration time.

7.2.3. Cancelling a Lease

A lease can be terminated before the end of its lease time by calling its cancel method, which has the following signature:

void cancel() throws UnknownLeaseException, RemoteException;

The cancel method may throw two exceptions: UnknownLeaseException and RemoteException. The UnknownLeaseException is thrown when the lease has already been cancelled, or has expired. The RemoteException is thrown whenever there is a communication problem between the calling process and the remote space.

Here's how we would cancel an existing lease:

try {
   lease.cancel();
} catch (UnknownLeaseException e) {
  // handle exception here
} catch (RemoteException e2) {
  // handle exception here
}

In the case of a leased entry, calling cancel terminates the lease and results in the entry's removal from the space—just as if the lease had expired.