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.
@param leaseToRenew the lease to be added to the renewal set
@param desiredDuration the maximum length of time in millisecondsthe 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
@param renewDuration the lease duration to request when renewingthe lease, unless renewDuration is greater than the remainder of the desiredDuration
@throws IllegalArgumentException if desiredDurationis 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.
@throws NullPointerException if leaseToRenew isnull
@throws RemoteException if a communication-related exceptionoccurs