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:
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:
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:
| |