MutableView (Permazen 4.1.8 API)

java.lang.Object
- io.permazen.kv.AbstractKVStore
- - io.permazen.kv.mvcc.MutableView

All Implemented Interfaces:

KVStore, ReadTracking, Cloneable

Direct Known Subclasses:

ReadWriteSpannerView
```
@ThreadSafe
public class MutableView
extends AbstractKVStore
implements ReadTracking, Cloneable
```
Provides a mutable view of an underlying, read-only KVStore.
Instances intercept all operations to the underlying KVStore, recording mutations in a Writes instance instead of applying them to the KVStore. Instances then provide a view of the mutated KVStore based those mutations. Mutations that overwrite previous mutations are consolidated.
Unlike writes, reads are passed through to the underlying KVStore, except where they intersect a previous write.
In all cases, the underlying KVStore is never modified.
Instances ensure that counter adjustment mutations never overlap put or remove mutations.
Read Tracking
During construction, instances may be configured to record all keys read into a Reads object (this is typically used for MVCC conflict detection). When reads are being tracked, tracking may temporarily be paused and resumed via getReadTrackingControl(). Read tracking may be permanently disabled (and any recorded reads discarded) via disableReadTracking().
Instances are thread safe; however, directly accessing the associated Reads or Writes is not thread safe without first locking the containing instance.

Constructor Summary

Constructors
Constructor and Description
`MutableView(KVStore kv)` Constructor.
`MutableView(KVStore kv, Reads reads, Writes writes)` Constructor using caller-provided `Reads` (optional) and `Writes`.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`adjustCounter(byte[] key, long amount)` Adjust the counter at the given key by the given amount.
`void`	`apply(Mutations mutations)` Apply all the given `Mutations` to this instance.
`MutableView`	`clone()` Clone this instance.
`long`	`decodeCounter(byte[] bytes)` Decode a counter value previously encoded by `encodeCounter()`.
`void`	`disableReadTracking()` Permanently disable read tracking and discard the `Reads` associated with this instance.
`byte[]`	`encodeCounter(long value)` Encode a counter value into a `byte[]` value suitable for use with `decodeCounter()` and/or `adjustCounter()`.
`byte[]`	`get(byte[] key)` Get the value associated with the given key, if any.
`KVStore`	`getKVStore()` Get the underlying `KVStore` associated with this instance.
`CloseableIterator<KVPair>`	`getRange(byte[] minKey, byte[] maxKey, boolean reverse)` Iterate the key/value pairs in the specified range.
`Reads`	`getReads()` Get the `Reads` associated with this instance.
`AtomicBoolean`	`getReadTrackingControl()` Get an `AtomicBoolean` that can be used to temporarily pause/un-pause read tracking.
`Writes`	`getWrites()` Get the `Writes` associated with this instance.
`void`	`put(byte[] key, byte[] value)` Set the value associated with the given key.
`void`	`remove(byte[] key)` Remove the key/value pair with the given key, if it exists.
`void`	`removeRange(byte[] minKey, byte[] maxKey)` Remove all key/value pairs whose keys are in a given range.
`void`	`setKVStore(KVStore kv)` Swap out the underlying `KVStore` associated with this instance.
`void`	`setReadOnly()` Configure this instance as read-only.
`String`	`toString()`

Methods inherited from class io.permazen.kv.AbstractKVStore
getAtLeast, getAtMost

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

Methods inherited from interface io.permazen.kv.KVStore
getAtLeast, getAtMost, getRange, getRange, removeRange

- Constructor Detail
  - MutableView
```
public MutableView(KVStore kv)
```
    Constructor.
    The instance will use a new, empty Reads instance for read tracking.
    
    Parameters:
    
    kv - underlying KVStore
    
    Throws:
    
    IllegalArgumentException - if kv is null
  - MutableView
```
public MutableView(KVStore kv,
                   Reads reads,
                   Writes writes)
```
    Constructor using caller-provided Reads (optional) and Writes.
    
    Parameters:
    
    kv - underlying KVStore
    
    reads - recorded reads, or null for none
    
    writes - recorded writes
    
    Throws:
    
    IllegalArgumentException - if kv is null
    
    IllegalArgumentException - if writes is null
- Method Detail
  - getKVStore
```
public KVStore getKVStore()
```
    Get the underlying KVStore associated with this instance.
    
    Returns:
    
    underlying KVStore
  - setKVStore
```
public void setKVStore(KVStore kv)
```
    Swap out the underlying KVStore associated with this instance.
    Note: the new KVStore should have a consistent encoding of counter values as the previous KVStore, otherwise a concurrent thread may read previously written counter values back incorrectly.
    
    Parameters:
    
    kv - new underlying KVStore
    
    Throws:
    
    IllegalArgumentException - if kv is null
  - getReads
```
public Reads getReads()
```
    Get the Reads associated with this instance.
    This includes all keys explicitly or implicitly read by calls to get(), getAtLeast(), getAtMost(), and getRange().
    The returned object is "live" and should only be accessed while synchronized on this instance.
    
    Returns:
    
    reads recorded, or null if this instance is not configured to record reads or read tracking has been permanently disabled via disableReadTracking()
  - getWrites
```
public Writes getWrites()
```
    Get the Writes associated with this instance.
    The returned object should only be accessed while synchronized on this instance.
    
    Returns:
    
    writes recorded
  - disableReadTracking
```
public void disableReadTracking()
```
    Permanently disable read tracking and discard the Reads associated with this instance.
    Can be used to save some memory when read tracking information is no longer needed.
  - getReadTrackingControl
```
public AtomicBoolean getReadTrackingControl()
```
    Description copied from interface: ReadTracking
    
    Get an AtomicBoolean that can be used to temporarily pause/un-pause read tracking.
    By default the returned control is true. While set to false, read tracking is disabled; setting back to true re-enables read tracking.
    For re-entrance safety, this should be done as follows:
    final boolean previous = kv.getReadTrackingControl().getAndSet(false); try { // do something without tracking reads... } finally { kv.getReadTrackingControl().set(previous); }
    
    Specified by:
    
    getReadTrackingControl in interface ReadTracking
    
    Returns:
    
    control that enables/disables read tracking
  - setReadOnly
```
public void setReadOnly()
```
    Configure this instance as read-only.
    Any subsequent invocations of put(), remove(), removeRange(), or adjustCounter() will result in an IllegalStateException.
  - get
```
public byte[] get(byte[] key)
```
    Description copied from interface: KVStore
    
    Get the value associated with the given key, if any.
    Modifications to the returned byte[] array do not affect this instance.
    
    Specified by:
    
    get in interface KVStore
    
    Overrides:
    
    get in class AbstractKVStore
    
    Parameters:
    
    key - key
    
    Returns:
    
    value associated with key, or null if not found
  - getRange
```
public CloseableIterator<KVPair> getRange(byte[] minKey,
                                          byte[] maxKey,
                                          boolean reverse)
```
    Description copied from interface: KVStore
    
    Iterate the key/value pairs in the specified range. The returned Iterator's remove() method must be supported and should have the same effect as invoking remove() on the corresponding key.
    If keys starting with 0xff are not supported by this instance, and minKey starts with 0xff, then this method returns an empty iteration.
    If keys starting with 0xff are not supported by this instance, and maxKey starts with 0xff, then this method behaves as if maxKey were null.
    The returned Iterator must not throw ConcurrentModificationException; however, whether or not a "live" Iterator reflects any modifications made after its creation is implementation dependent. Implementations that do make post-creation updates visible in the Iterator, even if the update occurs after some delay, must preserve the order in which the modifications actually occurred.
    The returned Iterator itself is not guaranteed to be thread safe.
    Invokers of this method are encouraged to close() the returned iterators, though this is not required for correct behavior.
    Modifications to the returned KVPair key and value byte[] arrays do not affect this instance.
    
    Specified by:
    
    getRange in interface KVStore
    
    Parameters:
    
    minKey - minimum key (inclusive), or null for no minimum (start at the smallest key)
    
    maxKey - maximum key (exclusive), or null for no maximum (end at the largest key)
    
    reverse - true to return key/value pairs in reverse order (i.e., keys descending)
    
    Returns:
    
    iteration of key/value pairs in the range minKey (inclusive) to maxKey (exclusive)
  - put
```
public void put(byte[] key,
                byte[] value)
```
    Description copied from interface: KVStore
    
    Set the value associated with the given key.
    
    Specified by:
    
    put in interface KVStore
    
    Overrides:
    
    put in class AbstractKVStore
    
    Parameters:
    
    key - key
    
    value - value
  - remove
```
public void remove(byte[] key)
```
    Description copied from interface: KVStore
    
    Remove the key/value pair with the given key, if it exists.
    
    Specified by:
    
    remove in interface KVStore
    
    Overrides:
    
    remove in class AbstractKVStore
    
    Parameters:
    
    key - key
  - removeRange
```
public void removeRange(byte[] minKey,
                        byte[] maxKey)
```
    Description copied from interface: KVStore
    Remove all key/value pairs whose keys are in a given range.
    The minKey must be less than or equal to maxKey; if they equal (and not null) then nothing happens; if they are both null then all entries are deleted.
    If keys starting with 0xff are not supported by this instance, then:
    - If minKey starts with 0xff, then no change occurs
    - If maxKey starts with 0xff, then this method behaves as if maxKey were null
    Specified by:
    
    removeRange in interface KVStore
    
    Overrides:
    
    removeRange in class AbstractKVStore
    
    Parameters:
    
    minKey - minimum key (inclusive), or null for no minimum
    
    maxKey - maximum key (exclusive), or null for no maximum
  - encodeCounter
```
public byte[] encodeCounter(long value)
```
    Description copied from interface: KVStore
    
    Encode a counter value into a byte[] value suitable for use with decodeCounter() and/or adjustCounter().
    
    Specified by:
    
    encodeCounter in interface KVStore
    
    Overrides:
    
    encodeCounter in class AbstractKVStore
    
    Parameters:
    
    value - desired counter value
    
    Returns:
    
    encoded counter value
  - decodeCounter
```
public long decodeCounter(byte[] bytes)
```
    Description copied from interface: KVStore
    
    Decode a counter value previously encoded by encodeCounter().
    
    Specified by:
    
    decodeCounter in interface KVStore
    
    Overrides:
    
    decodeCounter in class AbstractKVStore
    
    Parameters:
    
    bytes - encoded counter value
    
    Returns:
    
    decoded counter value
  - adjustCounter
```
public void adjustCounter(byte[] key,
                          long amount)
```
    Description copied from interface: KVStore
    
    Adjust the counter at the given key by the given amount.
    Ideally this operation should behave in a lock-free manner, so that concurrent transactions can invoke it without conflict. However, when lock-free behavior occurs (if at all) depends on the implementation.
    If there is no value associated with key, or key's value is not a valid counter encoding as would be acceptable to decodeCounter(), then how this operation affects key's value is undefined.
    
    Specified by:
    
    adjustCounter in interface KVStore
    
    Overrides:
    
    adjustCounter in class AbstractKVStore
    
    Parameters:
    
    key - key
    
    amount - amount to adjust counter value by
  - apply
```
public void apply(Mutations mutations)
```
    Description copied from interface: KVStore
    
    Apply all the given Mutations to this instance.
    Mutations are always to be applied in this order: removes, puts, counter adjustments.
    The implementation in KVStore simply iterates over the individual changes and applies them via remove() (for removals of a single key), removeRange(), put(), and/or adjustCounter(). Implementations that can process batch updates more efficiently are encouraged to override this method.
    
    Specified by:
    
    apply in interface KVStore
    
    Parameters:
    
    mutations - mutations to apply
  - clone
```
public MutableView clone()
```
    Clone this instance.
    The clone will have the same underlying KVStore, but its own Reads and Writes, which will themselves be cloned from this instance's copies.
    
    Overrides:
    
    clone in class Object
    
    Returns:
    
    clone of this instance
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object

Class MutableView

Constructor Summary

Method Summary

Methods inherited from class io.permazen.kv.AbstractKVStore

Methods inherited from class java.lang.Object

Methods inherited from interface io.permazen.kv.KVStore

Constructor Detail

MutableView

MutableView

Method Detail

getKVStore

setKVStore

getReads

getWrites

disableReadTracking

getReadTrackingControl

setReadOnly

get

getRange

put

remove

removeRange

encodeCounter

decodeCounter

adjustCounter

apply

clone

toString