LM.5. Supporting Interfaces and Classes

The LeaseRenewalManager utility class depends on the interfaces LeaseListener and DesiredExpirationListener. Both of these interfaces reference one class, LeaseRenewalEvent.

LM.5.1. The LeaseListener Interface

The public methods specified by the LeaseListener interface are as follows:

package net.jini.lease; 

public interface LeaseListener extends EventListener 
{
    void notify(LeaseRenewalEvent e); 
} 

The LeaseListener interface defines the mechanism through which the client receives notification of renewal failure events generated by the renewal manager. These events are delivered using the notify method. Renewal failure events are generated when the LeaseRenewalManager has failed to renew one of the leases that it is managing. Such renewal failures typically occur because one of the following conditions is met:

• After successfully renewing a lease any number of times and experiencing no failures, the LeaseRenewalManager determines—prior to the next renewal attempt—that the actual expiration time of the lease has passed; implying that any further attempt to renew the lease would be fruitless.

• An indefinite exception occurs during each attempt to renew a lease from the point that the first such exception occurs until the point when the LeaseRenewalManager determines that lease’s actual expiration time has passed.

• A definite exception occurs during a lease renewal attempt.

It is the responsibility of the client to pass into the LeaseRenewalManager a reference to an object that implements the LeaseListener interface, which defines the actions to take upon receipt of a renewal failure event notification. When one of the above conditions occurs, the LeaseRenewalManager will send an instance of LeaseRenewalEvent to that listener object.

LM.5.1.1. The Semantics

The notify method is invoked by the LeaseRenewalManager when it fails to renew a lease because one of the conditions described above has occurred. This method takes one parameter, an instance of the LeaseRenewalEvent class, which contains information about the lease on which the failed renewal attempt was made and information on what caused the failure.

Note that prior to invoking the notify method, the LeaseRenewalManager removes the lease that could not be renewed from the managed set of leases. Note also that because of the reentrancy guarantee made by the LeaseRenewalManager, new leases can be added safely from within the notify method.

LM.5.2. The DesiredExpirationListener Interface

The public methods specified by the DesiredExpirationListener interface are as follows:

package net.jini.lease; 

public interface DesiredExpirationListener 
    extends LeaseListener 
{
    void expirationReached(LeaseRenewalEvent e); 
} 

The expirationReached method receives desired expiration reached events. These are generated when the LeaseRenewalManager removes a lease from the managed set because the lease’s desired expiration has been reached. Note that any object that has been registered to receive desired expiration reached events will also receive renewal failure events.

It is the responsibility of the client to pass into the LeaseRenewalManager a reference to an object that implements the DesiredExpirationListener inter face, which defines the actions to take upon receipt of a desired expiration reached event notification.

LM.5.2.1. The Semantics

The expirationReached method is invoked by the LeaseRenewalManager when a lease in the managed set reaches its desired expiration. This method takes one parameter: an instance of the LeaseRenewalEvent class, which contains information about the lease who’s desired expiration has been reached.

Note that prior to invoking the expirationReached method, the LeaseRenewalManager removes the affected lease from the managed set of leases. Note also that because of the reentrancy guarantee made by the LeaseRenewalManager, callbacks into the renewal manager can be made safely from within the expirationReached method.

LM.5.3. The LeaseRenewalEvent Class

This class defines the local event that is sent by the LeaseRenewalManager to the client’s registered listener when the LeaseRenewalManager generates a renewal failure event or desired expiration reached event. As previously stated, a renewal failure event typically occurs because the actual expiration time of a lease has been reached before a successful renewal request could be made, or a renewal request resulted in a definite exception. A desired expiration reached event occurs when a lease reaches its desired expiration time at or before its actual expiration. The LeaseRenewalEvent class encapsulates information about the lease on which such an event occurs and, if it is a renewal failure, the cause.

package net.jini.lease; 

public class LeaseRenewalEvent extends EventObject 
{
    public LeaseRenewalEvent(LeaseRenewalManager source, 
                             Lease lease, 
                             long expiration, 
                             Throwable ex) {...} 
    public Lease getLease() {...} 
    public long getExpiration() {...} 
    public Throwable getException() {...} 
} 

The LeaseRenewalEvent class is a subclass of the EventObject class, adding the following additional items of abstract state: a reference to the associated Lease object; a long value representing the desired expiration of the lease; and the exception (if any) that caused the event to be sent. In addition to the methods of the EventObject class, this class defines methods through which this additional state may be retrieved.

LM.5.3.1. The Semantics

The constructor of the LeaseRenewalEvent class takes the following parameters as input:

• A reference to the instance of the LeaseRenewalManager that generated the event

• The lease associated with this event

• The desired expiration time of the lease

• The Throwable associated with the last renewal attempt (if any)

The getLease method returns a reference to the Lease object associated with the event. This method takes no arguments.

The getExpiration method returns a long value representing the desired expiration of the Lease object associated with the event. This method takes no arguments.

The getException method returns the exception, if any, that is associated with the event. This method takes no arguments. If the LeaseRenewalEvent represents a desired expiration reached event this method will return null.

If the LeaseRenewalEvent represents a renewal failure event the getException method will return the exception that caused the event to be sent. The conditions under which a renewal failure event may be sent, and the related values returned by this method, are as follows:

• When any lease in the managed set has passed its actual expiration time, and either the most recent renewal attempt was successful or there have been no renewal attempts, the LeaseRenewalManager will cease any further attempts to renew the lease, and will send a LeaseRenewalEvent with no associated exception. In this case, invoking this method will return null.

• For any lease from the managed set for which the most recent renewal attempt was unsuccessful because of the occurrence of a indefinite exception, the LeaseRenewalManager will continue to attempt to renew the affected lease at the appropriate times until: the renewal succeeds, the lease’s actual expiration time has passed, or a renewal attempt throws a definite exception. If a definite exception is thrown or the lease expires, the LeaseRenewalManager will cease any further attempts to renew the lease, and will send a LeaseRenewalEvent containing the exception associated with the last renewal attempt.

• If, while attempting to renew a lease from the managed set, a definite exception is encountered, the LeaseRenewalManager will cease any further attempts to renew the lease, and will send a LeaseRenewalEvent containing the particular exception that occurred.

LM.5.4. Serialized Forms