Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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 `LeaseException`s 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

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

    public static final long RENEWAL_FAILURE_EVENT_ID

  The event id for all `RenewalFailureEvent` objects.

  See Also:
    `RenewalFailureEvent`, Constant Field Values

### EXPIRATION_WARNING_EVENT_ID

    public static final long EXPIRATION_WARNING_EVENT_ID

  The event id for all `ExpirationWarningEvent` objects.

  See Also:
    `ExpirationWarningEvent`, Constant Field Values

Method Detail

### renewFor

    public 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

    public 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

    public 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

    public 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

    public 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

    public 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

    public 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

    public 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

    public 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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2004 Sun Microsystems, Inc. All rights reserved