net.jini.lease
Interface LeaseRenewalSet

public interface LeaseRenewalSet

A collection of leases being managed by a lease renewal service.

Clients of the renewal service organize the leases they wish to have renewed into lease renewal sets (or sets, for short). These sets are represented by objects implementing this interface. The LeaseRenewalService.createLeaseRenewalSet method is provided to create sets. Sets are populated by methods on the sets themselves. Two leases in the same set need not be granted by the same service or have the same expiration time; in addition, they can be added or removed from the set independently.

This 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 a LeaseRenewalService and all the LeaseRenewalSet instances created by that server) 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.

The term client lease is used to refer to a lease that has been placed into a renewal set. Client leases are distinct from the leases that the renewal service grants on renewal sets it has created.

Each client lease has two expiration related times associated with it: the desired expiration time for the lease, and the actual expiration time granted when the lease was 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. When a client lease's desired expiration arrives, the lease will be removed from the set without further client intervention.

Each client lease also has two other associated attributes: a desired renewal duration and a remaining desired duration. The desired renewal duration is specified by the client (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 client lease is renewed, the renewal service 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.

If a client lease's actual expiration is later than its desired expiration, the renewal service will not renew the lease; the lease will remain in the set until its desired expiration is reached, the set is destroyed, or it is removed by the client.

Each set is leased from the renewal service. If the lease on a set expires or is cancelled, the renewal service will destroy the set and take no further action with regard to the client leases in the set. Each lease renewal set has associated with it an expiration warning event that occurs at a client-specified time before the lease on the set expires. Clients can register for warning events using methods provided by the set. A registration for warning events does not have its own lease, but instead is covered by the same lease under which the set was granted.

The term definite exception is used to refer to an exception that could be thrown by an operation on a client lease (such as a remote method call) that would be indicative of a permanent failure of the client lease. For purposes of this document, all bad object exceptions, bad invocation exceptions, and LeaseExceptions are considered to be definite exceptions.

Each lease renewal set has associated with it a renewal failure event that will occur in either of two cases: if any client lease in the set reaches its actual expiration before its desired expiration is reached, or if the renewal service attempts to renew a client lease and gets a definite exception. Clients can register for failure events using methods provided by the set. A registration for failure event does not have its own lease, but instead is covered by the same lease under which the set was granted.

Once placed in a set, a client lease will stay there until one or more of the following occurs:

• The lease on the set itself expires or is cancelled, causing destruction of the set
• The client lease is removed by the client
• The client lease's actual or desired expiration is reached
• A renewal attempt on the client lease results in a definite exception

Each client lease in a set will be renewed as long as it is in the set. If a renewal call throws an indefinite exception, the renewal service should retry the lease renewal until the lease would otherwise be removed from the set. The renewal service will never cancel a client lease. The preferred method of cancelling a client lease is for the client to first remove the lease from the set and then call cancel on it. It is also permissible for the client to cancel the lease without first removing the lease from the set, although this is likely to result in additional network traffic.

Client leases get returned to clients in a number of ways (via remove and getLeases calls, as components of events, etc.). In general, they should have their serial format set to Lease.DURATION before being transferred to the client's virtual machine. In some exceptional circumstances, this may not be possible (for example, the client lease was recovered from persistent storage and could not be deserialized in the server's virtual machine). In these cases, it is acceptable to transfer the lease to the client using the Lease.ABSOLUTE serial format.

Whenever a client lease gets returned to a client, its actual expiration should reflect either:

• The result of the last successful renewal call that the renewal service made or
• The expiration time the lease originally had when it was added to the set, if the renewal service has not yet successfully renewed the lease

Author:

Sun Microsystems, Inc.

See Also:

LeaseRenewalService

Field Summary

static long	EXPIRATION_WARNING_EVENT_ID The event id for all ExpirationWarningEvent objects.
static long	RENEWAL_FAILURE_EVENT_ID The event id for all RenewalFailureEvent objects.

Method Summary

void	clearExpirationWarningListener() Remove the listener currently registered for expiration warning events.
void	clearRenewalFailureListener() Remove the listener currently registered for renewal failure events.
Lease[]	getLeases() Returns all the leases currently in the set.
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 desiredDuration) Include a client lease in the set for a specified duration.
void	renewFor(Lease leaseToRenew, long desiredDuration, long renewDuration) Include a client lease in the set for a specified duration and with a specified renewal duration.
EventRegistration	setExpirationWarningListener(RemoteEventListener listener, long minWarning, MarshalledObject handback) Register for the expiration warning event associated with this set.
EventRegistration	setRenewalFailureListener(RemoteEventListener listener, MarshalledObject handback) Register for the renewal failure event associated with this set.

Field Detail

RENEWAL_FAILURE_EVENT_ID

static final long RENEWAL_FAILURE_EVENT_ID

The event id for all RenewalFailureEvent objects.

See Also:

RenewalFailureEvent, Constant Field Values

EXPIRATION_WARNING_EVENT_ID

static final long EXPIRATION_WARNING_EVENT_ID

The event id for all ExpirationWarningEvent objects.

See Also:

ExpirationWarningEvent, Constant Field Values

Method Detail

renewFor

void renewFor(Lease leaseToRenew,
              long desiredDuration,
              long renewDuration)
              throws RemoteException

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

The leaseToRenew argument specifies the lease to be added to the set. An IllegalArgumentException must be thrown if the lease was granted by the renewal service itself. If leaseToRenew is null, a NullPointerException must be thrown.

The desiredDuration argument is the number of milliseconds the client would like the lease to remain in the set. It is used to calculate the lease's initial desired expiration by adding desiredDuration to the current time (as viewed by the service). If this causes an overflow, a desired expiration of Long.MAX_VALUE will be used. Unlike a lease duration, the desired duration is unilaterally specified by the client, not negotiated between the client and the service. Note, a negative value for desiredDuration (including Lease.ANY) will result in a desired expiration that is in the past, causing leaseToRenew to be dropped from the set; this action will neither result in an exception or an event.

If the actual expiration time of leaseToRenew is less than the current time (as viewed by the renewal service) and the current time is less than the desired expiration time for leaseToRenew, the method will return normally. However, leaseToRenew will be dropped from the set and a renewal failure event will be generated.

The renewDuration is the initial renewal duration to associate with leaseToRenew (in milliseconds). If desiredDuration is exactly Long.MAX_VALUE, the renewDuration may be any positive number or Lease.ANY; otherwise it must be a positive number. If these requirements are not met, the renewal service must throw an IllegalArgumentException.

Calling this method with a lease that is equivalent to a client lease already in the set will associate the existing client lease in the set with the new desired duration and renew duration. The client lease is not replaced because it is more likely that the renewal service, rather than the client, has an up-to-date lease expiration. The service is more likely to have an up-to-date expiration because the client should not be renewing a lease that it has passed to a lease renewal service unless the lease is removed first. These semantics also allow renewFor to be used in an idempotent fashion.

Parameters:

leaseToRenew - the lease to be added to the renewal set

desiredDuration - the maximum length of time in milliseconds the leaseToRenew should remain in the set, or Lease.FOREVER which implies there is no pre-specified time when the lease should be removed from the set

renewDuration - the lease duration to request when renewing the lease, unless renewDuration is greater than the remainder of the desiredDuration

Throws:

IllegalArgumentException - if desiredDuration is Lease.FOREVER, renewDuration is not a positive value, Lease.FOREVER, or Lease.ANY. If desiredDuration is not Lease.FOREVER, IllegalArgumentException will be thrown if renewDuration is not a positive value or Lease.ANY. IllegalArgumentException will also be thrown if leaseToRenew was granted by this renewal service.

NullPointerException - if leaseToRenew is null

RemoteException - if a communication-related exception occurs

renewFor

void renewFor(Lease leaseToRenew,
              long desiredDuration)
              throws RemoteException

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

Calling this method is equivalent to making the following call on this set:

     renewFor(leaseToRenew, desiredDuration, Lease.FOREVER)
 

Parameters:

leaseToRenew - the lease to be added to the renewal set

desiredDuration - the maximum length of time in milliseconds the leaseToRenew should remain in the set, or Lease.FOREVER which implies there is no pre-specified time when the lease should be removed from the set

Throws:

IllegalArgumentException - if leaseToRenew was granted by this renewal service

NullPointerException - if leaseToRenew is null

RemoteException - if a communication-related exception occurs

remove

Lease remove(Lease leaseToRemove)
             throws RemoteException

Removes the specified lease from set. If the lease is currently in the set it will be returned, otherwise null will be returned. leaseToRemove will not be canceled by this call.

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

RemoteException - if a communication-related exception occurs

getLeases

Lease[] getLeases()
                  throws LeaseUnmarshalException,
                         RemoteException

Returns all the leases currently in the set.

Returns:

the leases in the set. Return a zero length array if there are not leases currently in the set.

Throws:

LeaseUnmarshalException - if one or more of the leases can not be unmarshalled. The throwing of a LeaseUnmarshalException represents a, possibly transient, failure in the ability to unmarshal one or more client leases in the set, it does not necessarily imply anything about the state of the renewal service or the set themselves.

RemoteException - if a communication-related exception occurs

setExpirationWarningListener

EventRegistration setExpirationWarningListener(RemoteEventListener listener,
                                               long minWarning,
                                               MarshalledObject handback)
                                               throws RemoteException

Register for the expiration warning event associated with this set.

This method allows the client to register for notification of the approaching expiration of the set's lease. The listener argument specifies what listener should be notified when the lease is about to expire. The minWarning argument specifies a minimum number of milliseconds before lease expiration that the first event delivery attempt should be made by the service. The service may also make subsequent delivery attempts if the first and any subsequent attempts have been indeterminate. The minWarning argument must be zero or a positive number; if it is not, an IllegalArgumentException must be thrown. If the current expiration of the set's lease is less than minWarning milliseconds away, the event will occur immediately (though it will take time to propagate to the listener).

The handback argument to this method specifies an object that will be part of the expiration warning event notification. This mechanism is detailed in the Jini(TM) Distributed Event Specification.

This method returns the event registration for this event. The Lease object associated with the registration will be equivalent (in the sense of equals) to the Lease on the renewal set. Because the event registration shares a lease with the set, clients that want to just remove their expiration warning registration without destroying the set should use the clearExpirationWarningListener method instead of cancelling the registration's lease. The registration's event ID will be LeaseRenewalSet.EXPIRATION_WARNING_EVENT_ID. The source of the registration will be the set. The method must throw a NullPointerException if the listener argument is null. If an event handler has already been specified for this event the current registration is replaced with the new one. Because both registrations are for the same kind of event, the events sent to the new registration must be in the same sequence as the events sent to the old registration.

Parameters:

listener - the listener to be notified when this event occurs

minWarning - how long before the lease on the set expires should the event be sent

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

Returns:

an EventRegistration describing the event registration

Throws:

IllegalArgumentException - if minWarning is negative

NullPointerException - if listener is null

RemoteException - if a communication-related exception occurs

clearExpirationWarningListener

void clearExpirationWarningListener()
                                    throws RemoteException

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

Throws:

RemoteException - if a communication-related exception occurs

setRenewalFailureListener

EventRegistration setRenewalFailureListener(RemoteEventListener listener,
                                            MarshalledObject handback)
                                            throws RemoteException

Register for the renewal failure event associated with this set.

This method allows the client to register for the event associated with the failure to renew a client lease in the set. These events are generated when a client lease expires while it is still in the set, or when the service attempts to renew a client lease and gets a definite exception. The listener argument specifies the listener to be notified if a client lease could not be renewed.

The handback argument specifies an object that will be part of the renewal failure event notification. This mechanism is detailed in the Jini(TM) Distributed Event Specification.

This method returns the event registration for this event. The Lease object associated with the registration will be equivalent (in the sense of equals) to the Lease on the renewal set. Because the event registration shares a lease with the set, clients that want to just remove their expiration warning registration without destroying the set should use the clearRenewalFailureListener method, instead of cancelling the registration's lease. The registration's event ID will be LeaseRenewalSet.RENEWAL_FAILURE_EVENT_ID. The source of the registration will be the set. The method must throw NullPointerException if the listener argument is null. If an event handler has already been specified for this event the current registration is replaced with the new one. The returned event registration must have the same event ID as the replaced registration. Because both registrations are for the same kind of event, the events sent to the new registration must be in the same sequence as the events sent to the old registration.

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:

an EventRegistration describing the event registration

Throws:

NullPointerException - if listener is null

RemoteException - if a communication-related exception occurs

clearRenewalFailureListener

void clearRenewalFailureListener()
                                 throws RemoteException

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

Throws:

RemoteException - if a communication-related exception occurs

getRenewalSetLease

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 method does not make a remote call.

Returns:

the lease that controls the lifetime of this set