net.jini.lease
Class LeaseRenewalManager

java.lang.Object
  net.jini.lease.LeaseRenewalManager

public class LeaseRenewalManager
extends Object

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.

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.

Note that 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 will be 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 will ask 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 will ask for an extension equal to the lease's remaining desired duration.

Once a lease is given to a lease renewal manager, the manager will continue 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 operation. 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 will not be 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.

Author:

Sun Microsystems, Inc.

See Also:

Lease, LeaseException, LeaseRenewalEvent

Constructor Summary

LeaseRenewalManager()
No-argument constructor that creates an instance of this class that initially manages no leases.

LeaseRenewalManager(Configuration config)
Constructs an instance of this class that initially manages no leases and that uses config to control implementation-specific details of the behavior of the instance created.

LeaseRenewalManager(Lease lease, long desiredExpiration, LeaseListener listener)
Constructs an instance of this class that will initially manage a single lease.

LeaseRenewalManager(long renewalRTT, long renewBatchTimeWindow)

Method Summary

void	cancel(Lease lease) Removes a given lease from the managed set, and cancels it.
void	clear() Removes all leases from the managed set of leases.
long	getExpiration(Lease lease) Returns the current desired expiration time associated with a particular lease, (not the actual expiration that was granted when the lease was created or last renewed).
void	remove(Lease lease) Removes a given lease from the managed set of leases; but does not cancel the given lease.
void	renewFor(Lease lease, long desiredDuration, LeaseListener listener) Include a lease in the managed set for a specified duration.
void	renewFor(Lease lease, long desiredDuration, long renewDuration, LeaseListener listener) Include a lease in the managed set for a specified duration and with specified renewal duration.
void	renewUntil(Lease lease, long desiredExpiration, LeaseListener listener) Include a lease in the managed set until a specified time.
void	renewUntil(Lease lease, long desiredExpiration, long renewDuration, LeaseListener listener) Include a lease in the managed set until a specified time and with a specified renewal duration.
void	setExpiration(Lease lease, long expiration) Replaces the current desired expiration of a given lease from the managed set with a new desired expiration time.
void	terminate()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

LeaseRenewalManager

public LeaseRenewalManager()

No-argument constructor that creates an instance of this class that initially manages no leases.

LeaseRenewalManager

public LeaseRenewalManager(long renewalRTT,
                           long renewBatchTimeWindow)

LeaseRenewalManager

public LeaseRenewalManager(Configuration config)
                    throws ConfigurationException

Constructs an instance of this class that initially manages no leases and that uses config to control implementation-specific details of the behavior of the instance created.

Parameters:

config - supplies entries that control the configuration of this instance

Throws:

ConfigurationException - if a problem occurs when obtaining entries from the configuration

NullPointerException - if the configuration is null

LeaseRenewalManager

public LeaseRenewalManager(Lease lease,
                           long desiredExpiration,
                           LeaseListener listener)

Constructs an instance of this class that will initially manage a single lease. Employing this form of the constructor is equivalent to invoking the no-argument form of the constructor followed by an invocation of the three-argument form of the renewUntil method. See renewUntil for details on the arguments and what exceptions may be thrown by this constructor.

Parameters:

lease - reference to the initial lease to manage

desiredExpiration - the desired expiration for lease

listener - reference to the LeaseListener object that will receive notifications of any exceptional conditions that occur during renewal attempts. If null no notifications will be sent.

Throws:

NullPointerException - if lease is null

See Also:

LeaseListener, renewUntil(net.jini.core.lease.Lease, long, net.jini.lease.LeaseListener)

Method Detail

renewUntil

public void renewUntil(Lease lease,
                       long desiredExpiration,
                       LeaseListener listener)

Include a lease in the managed set until a specified time.

If desiredExpiration is Lease.ANY calling this method is equivalent the following call:

     renewUntil(lease, Lease.FOREVER, Lease.ANY, listener)
 

otherwise it is equivalent to this call:

     renewUntil(lease, desiredExpiration, Lease.FOREVER, listener)
 

Parameters:

lease - the Lease to be managed

desiredExpiration - when the client wants the lease to expire, in milliseconds since the beginning of the epoch

listener - reference to the LeaseListener object that will receive notifications of any exceptional conditions that occur during renewal attempts. If null no notifications will be sent.

Throws:

NullPointerException - if lease is null

See Also:

renewUntil(net.jini.core.lease.Lease, long, net.jini.lease.LeaseListener)

renewUntil

public void renewUntil(Lease lease,
                       long desiredExpiration,
                       long renewDuration,
                       LeaseListener listener)

Include a lease in the managed set until a specified time and with a specified renewal duration.

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 exceptional conditions when attempting to renew this lease. The LeaseListener argument may be null.

If the lease argument is null, a NullPointerException will be thrown. If the desiredExpiration argument is Lease.FOREVER, the renewDuration argument may be Lease.ANY or any positive value; otherwise, the renewDuration argument must be a positive value. If the renewDuration argument 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.

The lease will remain in the set 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.

This method will interpret the value of the desiredExpiration argument 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.

If the LeaseListener argument is a non-null object reference, it will receive notification of exceptional conditions occurring upon a renewal attempt of the lease. In particular, exceptional conditions include the reception of a LeaseException, bad object exception, or bad invocation exception (collectively these are referred to as definite exceptions) during a renewal attempt or the lease's actual expiration being reached before its desired expiration.

If a definite exception occurs during a lease renewal request, the exception will be wrapped in an instance of the LeaseRenewalEvent class and sent to the listener.

If an indefinite exception occurs during a renewal request for the 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.

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.

Parameters:

lease - the Lease to be managed

desiredExpiration - when the client wants the lease to expire, in milliseconds since the beginning of the epoch

renewDuration - the renewal duration to associate with the lease, in milliseconds

listener - reference to the LeaseListener object that will receive notifications of any exceptional conditions that occur during renewal attempts. If null, no notifications will be sent.

Throws:

NullPointerException - if lease is null

IllegalArgumentException - if renewDuration is invalid

See Also:

LeaseRenewalEvent, LeaseException

renewFor

public void renewFor(Lease lease,
                     long desiredDuration,
                     LeaseListener listener)

Include a lease in the managed set for a specified duration.

Calling this method is equivalent the following call:

     renewFor(lease, desiredDuration, Lease.FOREVER, listener)
 

Parameters:

lease - reference to the new lease to manage

desiredDuration - the desired duration (relative time) that the caller wants lease to be valid for, in milliseconds

listener - reference to the LeaseListener object that will receive notifications of any exceptional conditions that occur during renewal attempts. If null, no notifications will be sent.

Throws:

NullPointerException - if lease is null

See Also:

renewFor(net.jini.core.lease.Lease, long, net.jini.lease.LeaseListener)

renewFor

public void renewFor(Lease lease,
                     long desiredDuration,
                     long renewDuration,
                     LeaseListener listener)

Include a lease in the managed set for a specified duration and with specified renewal duration.

The semantics of this method are similar to those of the four-argument form of renewUntil, with desiredDuration + current time being used for the value of the desiredExpiration argument of renewUntil. The only exception to this is that, in the context of renewFor, the value of the renewDuration argument may only be Lease.ANY if the value of the desiredDuration argument is exactly Lease.FOREVER.

This method tests for arithmetic overflow in the desired expiration time computed from the value of desiredDuration argument (desiredDuration + current time). Should such overflow be present, a value of Lease.FOREVER is used to represent the lease's desired expiration time.

Parameters:

lease - reference to the new lease to manage

desiredDuration - the desired duration (relative time) that the caller wants lease to be valid for, in milliseconds

renewDuration - the renewal duration to associate with the lease, in milliseconds

listener - reference to the LeaseListener object that will receive notifications of any exceptional conditions that occur during renewal attempts. If null, no notifications will be sent.

Throws:

NullPointerException - if lease is null

IllegalArgumentException - if renewDuration is invalid

See Also:

renewUntil(net.jini.core.lease.Lease, long, net.jini.lease.LeaseListener)

getExpiration

public long getExpiration(Lease lease)
                   throws UnknownLeaseException

Returns the current desired expiration time associated with a particular lease, (not the actual expiration that was granted when the lease was created or last renewed).

Parameters:

lease - the lease the caller wants the current desired expiration for

Returns:

a long value corresponding to the current desired expiration time associated with lease

Throws:

UnknownLeaseException - if the lease passed to this method is not in the set of managed leases

See Also:

UnknownLeaseException, setExpiration(net.jini.core.lease.Lease, long)

setExpiration

public void setExpiration(Lease lease,
                          long expiration)
                   throws UnknownLeaseException

Replaces the current desired expiration of a given lease from the managed set with a new desired expiration time.

Note that 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 as that method's listener argument. Specifically, if the value of the expiration argument is less than or equal to the lease's current desired expiration, this method takes no action.

Parameters:

lease - the lease whose desired expiration time should be replaced

expiration - long value representing the new desired expiration time for the lease argument

Throws:

UnknownLeaseException - if the lease passed to this method is not in the set of managed leases

See Also:

renewUntil(net.jini.core.lease.Lease, long, net.jini.lease.LeaseListener), UnknownLeaseException, getExpiration(net.jini.core.lease.Lease)

cancel

public void cancel(Lease lease)
            throws UnknownLeaseException,
                   RemoteException

Removes a given lease from the managed set, and cancels it.

Note that even if an exception is thrown as a result of the cancel operation, the lease will still have been removed from the set of leases managed by this class. Additionally, any exception thrown by the cancel method of the lease object itself may also be thrown by this method.

Parameters:

lease - the lease to remove and cancel

Throws:

UnknownLeaseException - if the lease passed to this method is not in the set of managed leases

RemoteException - typically, this exception occurs when there is a communication failure between the client and the server. When this exception does occur, the lease may or may not have been successfully cancelled, (but the lease is guaranteed to have been removed from the managed set).

See Also:

Lease.cancel(), UnknownLeaseException

remove

public void remove(Lease lease)
            throws UnknownLeaseException

Removes a given lease from the managed set of leases; but does not cancel the given lease.

Parameters:

lease - the lease to remove from the managed set

Throws:

UnknownLeaseException - if the lease passed to this method is not in the set of managed leases

See Also:

UnknownLeaseException

clear

public void clear()

Removes all leases from the managed set of leases. This method does not request the cancellation of the removed leases.

terminate

public void terminate()