net.jini.lease
Interface LeaseRenewalSet

public abstract interface LeaseRenewalSet

Defines the interface to lease renewal sets. The interface is not a remote interface; each implementation of the renewal service exports proxy objects that implement the LeaseRenewalSet interface that use an implementation-specific protocol to communicate with the actual remote server. All of the proxy methods obey normal RMI remote interface semantics except where explicitly noted. Two proxy objects are equal if they are proxies for the same set created by the same renewal service. Every method invocation (on both LeaseRenewalService and LeaseRenewalSet) is atomic with respect to other invocations. A number of the methods in this class throw RemoteException, each of these may throw the java.rmi.NoSuchObjectException subclass. If a client receives a NoSuchObjectException when calling a method on a renewal set the client can infer that the set has been destroyed; however, it should not infer that the renewal service has been destroyed.

See Also:

LeaseRenewalSet

Method Summary

void	clearExpirationWarningListener() Remove the listener currently registered for the expiration warning.
void	clearRenewalFailureListener() Remove the listener currently registered for the renewal failure event.
Lease	getRenewalSetLease() Returns the lease that controls the lifetime of this set.
Lease	remove(Lease leaseToRemove) Removes the specified lease from set.
void	renewFor(Lease leaseToRenew, long membershipDuration) Add a lease to the set.
EventRegistration	setExpirationWarningListener(RemoteEventListener listener, long minWarning, java.rmi.MarshalledObject handback) Register for the expiration warning event associated with this set.
EventRegistration	setRenewalFailureListener(RemoteEventListener listener, java.rmi.MarshalledObject handback) Register for the renewal failure event associated with this set.

Method Detail

renewFor

public void renewFor(Lease leaseToRenew,
                     long membershipDuration)
              throws java.rmi.RemoteException

Add a lease to the set. The renewal service will renew the lease until the membership duration expires or a renewal attempt results in a definite exception. Each renewal will use the time reaming in the membership duration for the renewal duration. If Lease.ANY is passed for membership duration the set will continue to renew the lease until it receives a definite exception, each time it will use Lease.ANY for the duration. If Lease.FOREVER is passed for the membership duration the set will continue to renew the lease until it receives a definite exception each time it will use Lease.FOREVER for the duration.

If the passed lease is already in the set this call will have the effect of associating the old lease with the new membership duration.

Parameters:

leaseToRenew - The lease to be added to the renewal set

membershipDuration - Value for membership duration in milliseconds

Throws:

java.lang.IllegalArgumentException - if membershipDuration is not positive, Lease.ANY, or Lease.FOREVER. Will also throw IllegalArgumentException if leaseToRenew is in another set created by the same renewal server.

NullPointerException - if leaseToRenew is null.

java.rmi.RemoteException -

remove

public Lease remove(Lease leaseToRemove)
             throws java.rmi.RemoteException

Removes the specified lease from set. If the lease is currently in the set it will be returned, otherwise null will be returned.

Parameters:

leaseToRemove - Lease to be removed from the set.

Returns:

The removed lease if it was in the set or null if it was not

Throws:

NullPointerException - if leaseToRemove is null.

java.rmi.RemoteException -

setExpirationWarningListener

public EventRegistration setExpirationWarningListener(RemoteEventListener listener,
                                                      long minWarning,
                                                      java.rmi.MarshalledObject handback)
                                               throws java.rmi.RemoteException

Register for the expiration warning event associated with this set. The expiration warning event is sent at a client specified time before the lease on the set is to expire.

If there is already a listener registered for this event, the new listener will replace it. Events sent the new listener will be in the same sequence and have the same event type id as those sent to the old listener.

Parameters:

listener - The listener to be notified when this event occurs.

minWarning - How long be for the lease on the expires should the event be sent.

handback - An object to be handed back to the listener when the warning event occurs.

Returns:

A EventRegistration describing the event registration.

Throws:

java.lang.IllegalArgumentException - if minWarning negative.

NullPointerException - if listener is null.

java.rmi.RemoteException -

clearExpirationWarningListener

public void clearExpirationWarningListener()
                                    throws java.rmi.RemoteException

Remove the listener currently registered for the expiration warning. It is safe to call this method even if no listener is currently registered.

Throws:

java.rmi.RemoteException -

setRenewalFailureListener

public EventRegistration setRenewalFailureListener(RemoteEventListener listener,
                                                   java.rmi.MarshalledObject handback)
                                            throws java.rmi.RemoteException

Register for the renewal failure event associated with this set. The renewal failure event is sent when the renewal service attempts to renew a lease in a given set and receives a definite exception or if a lease in a given set expires before its membership duration elapses.

If there is already a listener registered for this event, the new listener will replace it. Events sent the new listener will be in the same sequence and have the same event type id as those sent to the old listener.

Parameters:

listener - The listener to be notified when this event occurs.

handback - An object to be handed back to the listener when the warning event occurs.

Returns:

A EventRegistration describing the event registration.

Throws:

NullPointerException - if listener is null.

java.rmi.RemoteException -

clearRenewalFailureListener

public void clearRenewalFailureListener()
                                 throws java.rmi.RemoteException

Remove the listener currently registered for the renewal failure event. It is safe to call this method even if no listener is currently registered.

Throws:

java.rmi.RemoteException -

getRenewalSetLease

public Lease getRenewalSetLease()

Returns the lease that controls the lifetime of this set. Can be used to extend or end the sets lifetime. Note that this does not make a remote call.

Returns:

the lease that controls lifetime of this set