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 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.
@throws NullPointerException if leaseToRenew
isnull
@throws RemoteException if a communication-related exceptionoccurs