KeyWatchTracker (Permazen 4.1.9 API)

java.lang.Object
- io.permazen.kv.util.KeyWatchTracker

All Implemented Interfaces:

Closeable, AutoCloseable
```
@ThreadSafe
public class KeyWatchTracker
extends Object
implements Closeable
```
Utility class used to track key watches.
To limit memory consumption, instances are configured with a maximum maximum number of key watches supported, as well as a maximum lifetime for each key watch. When these limits are exceeded, one or more key watches is evicted and a corresponding spurious notification occurs.
Instances can optionally be configured to only weakly reference the returned ListenableFuture's. This prevents memory leaks if the user of this class is sloppy and fails to cancel() them when no longer needed; however, it can also lead to missed notifications if the user of this class relies on the listener registration functionality provided in the ListenableFuture interface, because with a listener registration, there is no longer any need to directly reference the ListenableFuture, and so it may be reclaimed before firing. Therefore, by default strong references are used. In any case, ListenableFuture notifications are performed on a separate dedicated notification thread to avoid re-entrancy issues.
For space efficiency, this class does not track the original values associated with a key. Therefore, spurious notifications can also occur if a value is changed, and then changed back to its original value.
Instances are thread safe.

See Also:

KVTransaction.watchKey(byte[])

Field Summary

Fields
Modifier and Type	Field and Description
`static long`	`DEFAULT_CAPACITY` Default capacity (10000L).
`static long`	`DEFAULT_MAXIMUM_LIFETIME` Default maximum lifetime in seconds (2592000L).
`static boolean`	`DEFAULT_WEAK_REFERENCE` Default for the weak reference option (false).

Constructor Summary

Constructors
Constructor and Description
`KeyWatchTracker()` Default constructor.
`KeyWatchTracker(long capacity, long maxLifetime, boolean weakReferences)` Constructor.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`absorb(KeyWatchTracker that)` Absorb all of the watches from the given instance into this one.
`void`	`close()` Close this instance.
`void`	`failAll(Exception e)` Discard all outstanding key watches and fail them with the given exception.
`int`	`getNumKeysWatched()` Count the number of keys being watched.
`ListenableFuture<Void>`	`register(byte[] key)` Register a new watch.
`boolean`	`trigger(byte[] key)` Trigger all watches associated with the given key.
`boolean`	`trigger(Iterable<byte[]> keys)` Trigger all watches associated with the given keys.
`boolean`	`trigger(KeyRange range)` Trigger all watches associated with keys in the given range.
`boolean`	`trigger(Mutations mutations)` Trigger all watches associated with the given mutations.
`boolean`	`triggerAll()` Trigger all watches.

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

- Field Detail
  - DEFAULT_CAPACITY
```
public static final long DEFAULT_CAPACITY
```
    Default capacity (10000L).
    
    See Also:
    
    Constant Field Values
  - DEFAULT_MAXIMUM_LIFETIME
```
public static final long DEFAULT_MAXIMUM_LIFETIME
```
    Default maximum lifetime in seconds (2592000L).
    
    See Also:
    
    Constant Field Values
  - DEFAULT_WEAK_REFERENCE
```
public static final boolean DEFAULT_WEAK_REFERENCE
```
    Default for the weak reference option (false).
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - KeyWatchTracker
```
public KeyWatchTracker()
```
    Default constructor.
    Configures capacity 10000L, lifetime 2592000L seconds, and strong references.
  - KeyWatchTracker
```
public KeyWatchTracker(long capacity,
                       long maxLifetime,
                       boolean weakReferences)
```
    Constructor.
    
    Parameters:
    
    capacity - maximum number of key watches allowed
    
    maxLifetime - maximum lifetime for a key watch in seconds
    
    weakReferences - true to only weakly reference registered ListenableFutures
    
    Throws:
    
    IllegalArgumentException - if capacity or maxLifetime is zero or negative
- Method Detail
  - register
```
public ListenableFuture<Void> register(byte[] key)
```
    Register a new watch.
    If the returned Future is cancel()'ed, the watch is automatically unregistered.
    
    Parameters:
    
    key - the key to watch
    
    Returns:
    
    a ListenableFuture that returns key when the value associated with key is modified
    
    Throws:
    
    IllegalArgumentException - if key is null
  - getNumKeysWatched
```
public int getNumKeysWatched()
```
    Count the number of keys being watched.
    Note that the same key can be watched more than once, so this only counts keys being watched, not total watches.
    
    Returns:
    
    number of keys being watched
  - trigger
```
public boolean trigger(byte[] key)
```
    Trigger all watches associated with the given key.
    
    Parameters:
    
    key - the key that has been modified
    
    Returns:
    
    true if any watches were triggered, otherwise false
    
    Throws:
    
    IllegalArgumentException - if key is null
  - trigger
```
public boolean trigger(Iterable<byte[]> keys)
```
    Trigger all watches associated with the given keys.
    
    Parameters:
    
    keys - keys that have been modified
    
    Returns:
    
    true if any watches were triggered, otherwise false
    
    Throws:
    
    IllegalArgumentException - if keys is null
  - trigger
```
public boolean trigger(KeyRange range)
```
    Trigger all watches associated with keys in the given range.
    
    Parameters:
    
    range - range of keys that have been modified
    
    Returns:
    
    true if any watches were triggered, otherwise false
    
    Throws:
    
    IllegalArgumentException - if range is null
  - trigger
```
public boolean trigger(Mutations mutations)
```
    Trigger all watches associated with the given mutations.
    
    Parameters:
    
    mutations - mutations
    
    Returns:
    
    true if any watches were triggered, otherwise false
    
    Throws:
    
    IllegalArgumentException - if mutations is null
  - triggerAll
```
public boolean triggerAll()
```
    Trigger all watches.
    
    Returns:
    
    true if any watches were triggered, otherwise false
  - failAll
```
public void failAll(Exception e)
```
    Discard all outstanding key watches and fail them with the given exception.
    
    Parameters:
    
    e - failing exception
    
    Throws:
    
    IllegalArgumentException - if e is null
  - absorb
```
public void absorb(KeyWatchTracker that)
```
    Absorb all of the watches from the given instance into this one. On return, this instance will contain all of the given instance's watches, and the given instance will be empty.
    
    Parameters:
    
    that - the instance to absorb into this one
  - close
```
public void close()
```
    Close this instance.
    All outstanding key watches will be canceled as if by failAll().
    
    Specified by:
    
    close in interface Closeable
    
    Specified by:
    
    close in interface AutoCloseable

Class KeyWatchTracker

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_CAPACITY

DEFAULT_MAXIMUM_LIFETIME

DEFAULT_WEAK_REFERENCE

Constructor Detail

KeyWatchTracker

KeyWatchTracker

Method Detail

register

getNumKeysWatched

trigger

trigger

trigger

trigger

triggerAll

failAll

absorb

close