getLease()
of the ServiceRegistration object.
Leasing is the mechanism used between applications to give access to resources in an agreed manner
Leases are requested for a period of time. In Jini, the major use
is for a service to request that a copy be kept on a lookup locator
for a certain length of time for
delivery to clients on request. The service requests a time in the
ServiceRegistrar's method register().
Two special values of the time are
Lease.ANY - the service lets the locator decide on the time
Lease.FOREVER - the request is for a lease that never expires
The locator acts as the granter of the lease,
and decides how long it will actually create the lease for.
(The lookup locator from Sun typically sets the lease time as
only five seconds.)
Once it has done that, it will attempt to ensure that the request
is honoured for that period of time. The lease is returned to the
service, and is accessible through the method getLease()
of the ServiceRegistration object.
ServiceRegistration reg = registrar.register();
Lease lease = reg.getLease();
The principal methods
of the Lease object are
package net.jini.core;
public interface Lease {
void cancel() throws
UnknownLeaseException,
java.rmi.RemoteException;
long getExpiration();
void renew(long duration) throws
LeaseDeniedException,
UnknownLeaseException,
java.rmi.RemoteException;
}
getExpiration() is the time in milliseconds
since the beginning of the epoch
(the same as in System.currentTimeMillis()).
The time from now is then
long duration = lease.getExpiration() - System.currentTimeMillis();
A service can cancel its lease by using cancel().
The lease that the service sees is a proxy which communicates
back to the lookup locator and cancels the lease there.
When a lease expires, it does so silently. That is, the lease granter
(the lookup locator) will not inform the lease holder (the service)
that it has expired. It is upto the service to call renew()
before the lease expires if it wishes the lease to continue. This is a
bit of a nuisance for the programmer, because you will need to call
renew() sufficiently in advance of expiration to allow
for network and scheduling delays.
Jini supplies a class LeaseRenewalManager that looks after
the process of calling renew() at suitable times.
package com.sun.jini.lease;
public Class LeaseRenewalManager {
public LeaseRenewalManager();
public LeaseRenewalManager(Lease lease,
long expiration,
LeaseListener listener);
public void renewFor(Lease lease, long duration,
LeaseListener listener);
public void renewUntil(Lease lease,
long expiration,
LeaseListener listener);
// etc
}
renewFor() or renewUntil().
The time requested in these is in thousands of milliseconds.
The expiration time is since the epoch, whereas the
duration time is from now.
Generally leases will be renewed and the manager will function
quietly. However, the lookup locator may decide not to renew a
lease and will cause an exception to be thrown. This will be caught
by the renewal manager and will cause the listener's notify()
method to be called with a LeaseRenewalEvent as
parameter. This will allow the application to take corrective
action if its lease is denied.
The listener may be null.
You have to be careful about setting the duration in
renewFor() (in Jini v1.0).
If you want the service to be registered
forever, it is tempting to use Lease.FOREVER.
However, the current implementation just adds this to
System.currentTimeMillis() which overflows to a
negative value which is not checked. So it never does any renewals.
Strictly, you need to check that
duration + System.currentTimeMillis() > 0
renewFor(). This will be fixed in later
versions. The method renewUntil() can use
Lease.FOREVER with no problems.
When a service registers with a lookup locator, the locator
returns a Lease object. This can be examined for
lease duration, and requests for renewal may be made with it.
Timing is a bit of a nuisance, so a LeaseRenewalManager
can be used to handle renewal of leases.