LeaseRegistry

java.lang.Object
- info.pppc.base.lease.LeaseRegistry

All Implemented Interfaces:

ILeaseRegistry, IOperation
```
public class LeaseRegistry
extends java.lang.Object
implements IOperation, ILeaseRegistry
```
The lease registry can be used to observe objects on another system using local listeners. The lease registry tries to bundle lease update requests and thus it is more efficient than to establish single update protocols that work independently. In order to leverage the registries, the server system will create a lease with a specified timeout and it will hook up a listener to this lease. The registry will return a lease that can be passed to a remote system. The remote system in turn will hook up a listener to the lease which will start the update protocol between the lease hosting and the lease observing system. If the last observing listener is removed, the system can immediately notify the remote system that the lease is no longer needed on this system. If no more listeners are registered or if no update has been issued by a system for the specified timeout period all listeners (on the lease hosting as well as on the lease observing system) will be removed and they will receive a lease expired event. Note that it is perfectly allowed to register multiple observing listeners on the same system for the same lease and it is also possible to observe the same lease from multiple systems. In this case the hosting listner will not receive an expired event before all listners have been removed. Note that the lease registry does not perform any cycle checks, thus it is possible to create cyclic referencing leases which will eventually lead to a memory hole. Thus users of the registry should ensure that they always maintain DAGs if they use the registry to maintain remote state.

Author:

Mac

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`EVENT_LEASE_EXPIRED` This event is fired whenever the lease that is observed by a listener is expired.
`static long`	`PERIOD_DEFAULT` The default timeout period.
`static long`	`PERIOD_GRACE` This is the grace period that is automatically added to the timeout period whenever lease is registered for the first time.
`static long`	`PERIOD_MAXIMUM` The maximum timeout period.
`static long`	`PERIOD_MINIMUM` The minimum timeout period.
`static long`	`PERIOD_REFRESH` The estimated period required to perform a refresh call.
`static long`	`PERIOD_WAIT` This is the time that lies between two calls to a system when the first call produced an invocation exception.

Fields inherited from interface info.pppc.base.lease.ILeaseRegistry
REGISTRY_ID

Method Summary

Methods
Modifier and Type	Method and Description
`Lease`	`create(IListener listener)` Creates a new local lease with the default timeout period.
`Lease`	`create(IListener listener, long timeout)` Creates a new local lease with the specified timeout period.
`static LeaseRegistry`	`getInstance()` Creates, registers and returns the local instance of the lease registry.
`void`	`hook(Lease lease, IListener listener)` Hooks up a listener to the specified lease that maintains the lease.
`void`	`perform(IMonitor monitor)` This operation checks whether locally created leases are no longer of interest to any remote system.
`boolean`	`remove(Lease lease)` Removes a specified lease that has been created locally and informs all remote listeners about the removal.
`boolean`	`remove(Lease lease, boolean notify)` Removes a specified lease that has been created locally.
`void`	`remove(SystemID system, Lease lease)` Called by a remote lease registry to signal that a certain lease created by this registry has been removed due to a call to the remove method.
`boolean`	`unhook(Lease lease, IListener listener)` Unhooks a previously registered listener for a specified lease from the registry.
`boolean`	`unhook(Lease lease, IListener listener, boolean notify)` Unhooks a previously registered listener for a specified lease from the registry.
`void`	`unhook(SystemID system, Lease lease)` Called by a remote lease registry whenever the remote system is no longer interested in a local lease.
`java.util.Vector`	`update(SystemID system, java.util.Vector leases)` Called by a remote system that is interested on a number of leases created by this lease registry.

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - PERIOD_MINIMUM
```
public static final long PERIOD_MINIMUM
```
    The minimum timeout period. If an observer or lease is registered with a smaller timeout period, the timeout period is automatically set to the minimum period.
    
    See Also:
    Constant Field Values
  - PERIOD_DEFAULT
```
public static final long PERIOD_DEFAULT
```
    The default timeout period. If an observer or lease is registered without a timeout period, this period is automatically taken.
    
    See Also:
    Constant Field Values
  - PERIOD_MAXIMUM
```
public static final long PERIOD_MAXIMUM
```
    The maximum timeout period. If an observer or lease is registered with a timeout period that is larger than the maximum period, the maximum period is automatically taken (maximum 2 hours).
    
    See Also:
    Constant Field Values
  - PERIOD_GRACE
```
public static final long PERIOD_GRACE
```
    This is the grace period that is automatically added to the timeout period whenever lease is registered for the first time. This will enable a remote system to register its
    
    See Also:
    Constant Field Values
  - PERIOD_REFRESH
```
public static final long PERIOD_REFRESH
```
    The estimated period required to perform a refresh call. This is used to determine the set of lease updates that need to be performed during the next call.
    
    See Also:
    Constant Field Values
  - PERIOD_WAIT
```
public static final long PERIOD_WAIT
```
    This is the time that lies between two calls to a system when the first call produced an invocation exception. This should be smaller than the refresh period if multiple refresh calls should be emittet whenever a call fails.
    
    See Also:
    Constant Field Values
  - EVENT_LEASE_EXPIRED
```
public static final int EVENT_LEASE_EXPIRED
```
    This event is fired whenever the lease that is observed by a listener is expired. This might either occur if the remove method is called and the corresponding registered listeners are notified or if the timeout for a certain lease is expired. After this event has been issued, the listener will no longer be registered at the registry. The source of the event will be the lease registry. The data object will be the lease that has expired.
    
    See Also:
    Constant Field Values
- Method Detail
  - getInstance
```
public static LeaseRegistry getInstance()
```
    Creates, registers and returns the local instance of the lease registry.
    
    Returns:
    The instance of the local lease registry.
  - create
```
public Lease create(IListener listener)
```
    Creates a new local lease with the default timeout period. When the lease expires, the listener will be informed by the corresponding event. If the lease is removed by a call to the remove method, the listener will be removed silently. After the lease has been expired, it is no longer registered at the registry.
    
    Parameters:
    listener - The listener that is notified whenever the lease is expired. The listener must not be null.
    
    Returns:
    The lease that has been created. This lease can be passed to remote systems so that they can hook an observing listener.
  - create
```
public Lease create(IListener listener,
           long timeout)
```
    Creates a new local lease with the specified timeout period. If the period lies not between the maximum and minimum period, it will be adjusted automatically. Whenever the lease expires, the listener will receive a corresponding event. If the lease is manually removed by the remove method, the listener will be removed silently.
    
    Parameters:
    listener - The listener that is called whenever the lease is expired. The listener must not be null.
    timeout - The timeout of the lease.
    
    Returns:
    The lease that has been created. This lease can be passed to remote systems so that they can hook up an observing listener.
  - remove
```
public boolean remove(Lease lease)
```
    Removes a specified lease that has been created locally and informs all remote listeners about the removal. The remote listeners will immediately receive a lease expired event. Note that the local listener that is registered for the lease will not be notified of the removal.
    
    Parameters:
    lease - The lease that should be removed. The lease must not be null.
    
    Returns:
    True if the lease has been removed, false if the lease has not been created by this registry or if it was not registered.
  - remove
```
public boolean remove(Lease lease,
             boolean notify)
```
    Removes a specified lease that has been created locally. If the notify flag is set to true, all remote listeners that have observed this lease will be informed about the removal. If the notify flag is set to false, the lease will be removed silently for remote listeners.
    
    Parameters:
    lease - The lease that should be removed. The lease must not be null.
    notify - True to indicate that all remote listeners should be notified, false to indicate that the lease should be removed silently for remote listeners.
    
    Returns:
    True if the lease has been removed, false if the lease has not been created by the registry or if it was not registered.
  - hook
```
public void hook(Lease lease,
        IListener listener)
```
    Hooks up a listener to the specified lease that maintains the lease. If the lease is removed or if the remote system that hosts the lease can no longer be contacted, the lease registry will call the specified listener with an expired event and it will remove the listener. Note that it is possible to register a number of listeners for the same lease. They will be informed about the status of the lease.
    
    Parameters:
    lease - The lease that should be registered. The lease must not be null.
    listener - The listener that will listen to lease expiration events. The listener must not be null.
  - unhook
```
public boolean unhook(Lease lease,
             IListener listener)
```
    Unhooks a previously registered listener for a specified lease from the registry. If the listener is the last listner for the specified lease, this method will inform the system that hosts the lease that the last member on this system has been removed.
    
    Parameters:
    lease - The lease for which the listener has been created. The lease must not be null.
    listener - The listener that should be removed. The listener must not be null.
    
    Returns:
    True if the listener has been unhooked, false if the listener was not registered at the registry.
  - unhook
```
public boolean unhook(Lease lease,
             IListener listener,
             boolean notify)
```
    Unhooks a previously registered listener for a specified lease from the registry. If the listener is the last listner for the specified lease and the notify flag is set to true, this method will inform the system that hosts the lease that the last member on this system has been removed. If the notify flag is set to false, the listener will be removed silently.
    
    Parameters:
    lease - The lease for which the listener has been created. The lease must not be null.
    listener - The listener that should be removed. The listener must not be null.
    notify - A flag that indicates whether the remote system that hosts the lease should be notified of the removal. If the flag is set to true, it will be notified if the lease is removed completely, otherwise the lease will be removed silently.
    
    Returns:
    True if the listener has been unhooked, false if the listener was not registered at the registry.
  - perform
```
public void perform(IMonitor monitor)
             throws java.lang.Exception
```
    This operation checks whether locally created leases are no longer of interest to any remote system. If this happens it removes the leases and notifies the corresponding listeners.
    
    Specified by:
    
    perform in interface IOperation
    
    Parameters:
    monitor - The monitor used to stop the operation.
    
    Throws:
    
    java.lang.Exception - Should never be thrown.
  - unhook
```
public void unhook(SystemID system,
          Lease lease)
```
    Called by a remote lease registry whenever the remote system is no longer interested in a local lease.
    
    Specified by:
    
    unhook in interface ILeaseRegistry
    
    Parameters:
    system - The remote system that is no longer observing a certain lease.
    lease - The lease that is no longer observed.
  - update
```
public java.util.Vector update(SystemID system,
                      java.util.Vector leases)
```
    Called by a remote system that is interested on a number of leases created by this lease registry.
    
    Specified by:
    
    update in interface ILeaseRegistry
    
    Parameters:
    system - The system that is interested in the local leases.
    leases - The leases of interest stored in a vector.
    
    Returns:
    A vector of leases that is no longer available in this registry.
  - remove
```
public void remove(SystemID system,
          Lease lease)
```
    Called by a remote lease registry to signal that a certain lease created by this registry has been removed due to a call to the remove method.
    
    Specified by:
    
    remove in interface ILeaseRegistry
    
    Parameters:
    system - The system that has removed a lease.
    lease - The lease that has been removed.

Class LeaseRegistry

Field Summary

Fields inherited from interface info.pppc.base.lease.ILeaseRegistry

Method Summary

Methods inherited from class java.lang.Object

Field Detail

PERIOD_MINIMUM

PERIOD_DEFAULT

PERIOD_MAXIMUM

PERIOD_GRACE

PERIOD_REFRESH

PERIOD_WAIT

EVENT_LEASE_EXPIRED

Method Detail

getInstance

create

create

remove

remove

hook

unhook

unhook

perform

unhook

update

remove