LeaseRenewalService Requirements

 

ID

LeaseRenewalService Requirement

Section

Comments
  1.  

Two proxy objects are equal (using the equals method) if they are proxies for the same renewal service.

9.4

 
  1.  

After the membership duration expires, the lease will be removed from the set without further client intervention.

 

 
  1.  

The renewal service will never renew a lease for a period that extends beyond its current membership duration expiration.

 

 
  1.  

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 leases in the set.

 

 
  1.  

There is an event associated with each set that occurs at a client-specified time before the lease on the set expires.

 

 
  1.  

A registration for this event does not have its own lease, but instead is bundled into the same lease under which the set was granted.

 

 
  1.  

Each lease renewal set has a renewal failure event associated with it that will occur if any lease in the set expires before its membership duration runs out,

 

 
  1.  

Each lease renewal set has a renewal failure event associated with it that will occur … if the renewal service attempts to renew a lease and gets a definite exception.

 

 
  1.  

A registration for this event does not have its own lease, but instead is bundled into the same lease under which the set was granted.

 

 
  1.  

Once placed in a set, a lease will stay there until … The lease on the set itself expires or is cancelled, causing destruction of the set

 

 
  1.  

Once placed in a set, a lease will stay there until … The lease is removed by the client

 

 
  1.  

Once placed in a set, a lease will stay there until … The lease expires

 

 
  1.  

Once placed in a set, a lease will stay there until …  The lease’s membership duration expires

 

 
  1.  

Once placed in a set, a lease will stay there until …  A renewal call results in a definite exception

 

 
  1.  

The renewal service will never cancel a lease.

 

 
  1.  

the createLeaseRenewalSet method … leaseDuration argument specifies how long (in milliseconds) the client wants the set's initial lease duration to be. The initial duration of the set's lease will be equal to or shorter than this request; it will not be longer.

 

 
  1.  

This duration must be positive, Lease.FOREVER,or Lease.ANY; otherwise an IllegalArgumentException must be thrown.

 

 
  1.  

The proxy objects for two sets are equal (using the equals method) if they are proxies for the same set created by the same renewal service.

 

 
  1.  

Any method that communicates with the remote server should throw a NoSuchObjectException if the set no longer exists.

 

 
  1.  

… addLease method. The leaseToRenew argument specifies the lease to be renewed.

 

 
  1.  

An IllegalArgumentException must be thrown if the lease was granted by the renewal service itself.

 

 
  1.  

An IllegalArgumentException must also be thrown if the lease is currently a member of another set allocated by the same renewal service.

 

 
  1.  

The membershipDuration is the initial membership duration for the lease.

 

 
  1.  

The duration must have a value between 1 and Long.MAX_VALUE, inclusive; otherwise the renewal service must throw an IllegalArgumentException.

 

 
  1.  

Calling addLease with a lease that is already in the set will associate the existing lease in the set with the new membership duration. The lease is not replaced …

 

 
  1.  

Leases are removed from the set using the removeLease method.

 

 
  1.  

The expiration time of the returned lease will 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, if the renewal service has not yet successfully renewed the lease

 

 
  1.  

If the lease is not in the set, null will be returned.

 

 
  1.  

The getLease method returns the lease associated with the set itself. (Note this method does not make a remote call.)

 

 
  1.  

The setExpirationWarningListener method allows the client to register for notification of the approaching expiration of the set’s lease.

 

 
  1.  

The listener argument specifies what listener should be notified when the lease is about to expire.

 

 
  1.  

The method must throw a NullPointerException if listener is null.

 

 
  1.  

The minWarning argument specifies in milliseconds how long before lease expiration the event should be generated.

 

 
  1.  

This must be zero or a positive number. If it is not, an IllegalArgumentException must be thrown.

 

 
  1.  

If the current expiration of the set’s lease is sooner than minWarning, the event will occur immediately (though it will take time to propagate to the handler).

 

 
  1.  

The handback argument to setExpirationWarningListener specifies an object that will be part of the expiration warning event notification. This mechanism is detailed in the Jini™ Distributed Event Specification.

 

 
  1.  

The setExpirationWarningListener method returns the event registration for this event. This registration has the same lease as the lease renewal set.

 

 
  1.  

The event ID returned by the event registration is unique, at least with respect to all other active event registrations created by the given renewal service.

 

 
  1.  

If an event handler has already been specified for this event the current registration is replaced with the new one.

 

 
  1.  

The returned event registration must have the same event ID as the replaced registration.

 

 
  1.  

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.

 

 
  1.  

The clearExpirationWarningListener method removes the event registration currently associated with the approaching expiration of the set’s lease.

 

 
  1.  

It is acceptable to call this method even if there is no active registration.

 

 
  1.  

The setRenewalFailureListener method allows the client to register for the event associated with the failure to renew a lease in the set. These events are generated when a lease expires while it is still in the set, or the service attempted to renew the lease and gets a definite exception.

 

 
  1.  

The listener argument specifies the listener to be notified if a lease could not be renewed.

 

 
  1.  

The handback argument to setRenewalFailureListener specifies an object that will be part of the renewal failure event notification.

 

 
  1.  

The setRenewalFailureListener method returns the event registration for this event. This registration has the same lease as the set.

 

 
  1.  

The event ID returned by the event registration is unique at least with respect to all other active event registrations created by the given renewal service.

 

 
  1.  

The method must throw NullPointerException if listener is null.

 

 
  1.  

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.

 

 
  1.  

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.

 

 
  1.  

The clearRenewalFailureListener method removes the event registration currently associated with the event for the failure to renew a lease in the set.

 

 
  1.  

It is acceptable to call this method even if there is no active registration.

 

 
  1.  

ExpirationWarningEvent objects are passed to the event handlers specified in calls to the LeaseRenewalSet method, setExpirationWarningListener. ... the lease which is about to expire. This state is returned by the getLease method.

 

 
  1.  

Its expiration will reflect the expiration the lease had when the event occurred.

 

 
  1.  

Sequence numbers for a given event ID are strictly increasing. If there is no gap between two sequence numbers, no events have been missed; if there is a gap, events might (but might not) have been missed.

 

 
  1.  

RenewalFailureEvent objects are passed to the event handlers specified in calls to the LeaseRenewalSet method, setRenewalFailureListener.

 

 
  1.  

The lease is returned by the getLease method, ...

 

 
  1.  

... and the Throwable by the getThrowable method. .

 

 
  1.  

If the Throwable is null it can be assumed that the renewal service was unable to call renew before the lease expired

 

 
  1.  

If the renewal service was able to renew the lease before the event occurred, the lease’s expiration will reflect the result of the last successful renewal call.

 

 
  1.  

When a renewal failure event is generated for a given lease, that lease is removed from the set.

 

 
  1.  

Sequence numbers for a given event ID are strictly increasing. If there is no gap between two sequence numbers, no events have been missed; if there is a gap, events might (but might not) have been missed.

 

 

 

 
  1.  

If the current time plus the membership duration is larger than Long.MAX_VALUE, the membership expiration will be Long.MAX_VALUE.

9.3

page 108

 
  1.  

If a lease’s current expiration is after the lease’s membership expiration, the renewal service will not renew the lease, it will remain in the set however.

9.3

page 108

 
  1.  

The getLeases method returns all the client leases in the set at the time of the call as an array of type Lease.

9.3

page 112

 
  1.  

If one or more of the leases in the array can not be deserialized a LeaseUnmarshalException is thrown.

9.3

page 113

 
  1.  

The leases that could be successfully deserialized will be returned by the getUnmarshaledLeases method of the exception.

9.3

page 113

 
  1.  

If no leases could be deserialized a zero length array will be returned.

9.3

page 113

 
  1.  

The leases that could not be deserialized will be returned in the form of MarshalledObjects by the getStillMarshalledLeases method of the exception. For each element of the array returned by the getStillMarshalledLeases method, there will be a corresponding element of the array returned by the getExceptions method thay will hold a Throwable that describes why the given lease could not be deserialized.

9.3

page 113

 
  1.  

Each event generated by the lease renewal service has as its source the renewal set that the event is associated with. In the case of an expiration warning event this is the set which is about to expire. In the case of a renewal failure event this is the set the client lease was in when the event occurred.

9.3.1

page 113

 
  1.  

Because a given set will only have one expiration warning event registration at a given time all expiration warning events will have the same event ID, LeaseRenewalSet.EXPIRATION_WARNING_EVENT_ID. Similarly, all renewal failure events have the same event ID, LeaseRenewalSet.RENEWAL_FAILURE_EVENT_ID.

9.3.1

page 113

 
  1.  

If a RemoteListener registered for a renewal failure or an expiration warning event throws an UnknownEventException, this will only clear the specific event registration, it will not cancel  the lease on the renewal set, or affect any other event registration on the set.

9.3.1

page 113

 
  1.  

If an event listener is replaced, and one or more event delivery attempts on the original listener failed or were indeterminate, implementations may choose to send some or all of these events to the new listener.

9.3.1

page 114

 
  1.  

Both the getLease and getThrowable methods are declared to throw IOException and ClassNotFoundException, this delcaration allows implementations to delay unmarshalling this state until it is actually needed. Once either method of a given RenewalFailureEvent object returns normally, future calls on that method must return the same object and may not throw an exception.

9.3.1

page 116

 
  1.  

The RenewalFailureEvent is a subclass of RemoteEvent, adding two additional items of abstract state – the client lease which could not be renewed before expiration and the Throwable object that was thrown by the first failed renewal attempt in the last series of consecutive failures.

9.3.1

page 115