AtomicArrayKVStore (JSimpleDB Array Key/Value Store 2.1.7 API)

java.lang.Object
- org.jsimpledb.kv.AbstractKVStore
- - org.jsimpledb.kv.array.AtomicArrayKVStore

All Implemented Interfaces:

KVStore, AtomicKVStore
```
@ThreadSafe
public class AtomicArrayKVStore
extends AbstractKVStore
implements AtomicKVStore
```
AtomicKVStore based on ArrayKVStore with background compaction.
This implementation is designed to maximize the speed of reads and minimize the amount of memory overhead per key/value pair. It is optimized for relatively infrequent writes.
A (read-only) ArrayKVStore is the basis for the database; the array files are mapped into memory. As mutations are applied, they are added to an in-memory change set, and appended to a mutation log file for persistence. On restart, the mutation log file (if any) is read to reconstruct the in-memory change set.
Compaction
Instances periodically compact outstanding changes into new array files (and truncate the mutation log file) in a background thread. A compaction is scheduled whenever:
- The size of mutation log file exceeds the compaction space low-water mark
- The oldest uncompacted modification is older than the compaction maximum delay
- The scheduleCompaction() method is invoked
In order to prevent compaction from getting hopelessly behind when there is high write volume, a compaction space high-water mark is also used. When the size of the mutation log file exceeds the half-way point between the low-water and high-water marks, new write attempts start being artificially delayed, and this delay amount increases to infinity as the high-water mark is approached, so that as long as the high-water mark is exceeded, new writes are blocked completely until the current compaction cycle completes.
The number of bytes occupied by the in-memory change set and the length of the outstanding mutations log file are related. Therefore, the compaction high-water mark loosely correlates to a maximum amount of memory required by the in-memory change set.
Hot Backups
"Hot" backups may be created in parallel with normal operation via hotCopy(). Hard links are used to make this operation fast; only the mutation log file (if any) is actually copied.
The database directory is a required configuration property.
Key and value data must not exceed 2GB (each separately).
Instances may be stopped and (re)started multiple times.

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`DEFAULT_COMPACTION_HIGH_WATER` Default compaction space high-water mark in bytes (1073741824 bytes).
`static int`	`DEFAULT_COMPACTION_LOW_WATER` Default compaction space low-water mark in bytes (65536 bytes).
`static int`	`DEFAULT_COMPACTION_MAX_DELAY` Default compaction maximum delay in seconds (90 seconds).

Constructor Summary

Constructors
Constructor and Description

AtomicArrayKVStore()

Constructors
Constructor and Description
`AtomicArrayKVStore()`

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`adjustCounter(byte[] key, long amount)`
`protected long`	`calculateCompactionPressureDelay(float windowRatio)` Calculate the maximum amount of time that a thread attempting to `mutate()` must wait for a background compaction to complete as we start nearing the high water mark.
`long`	`decodeCounter(byte[] bytes)`
`byte[]`	`encodeCounter(long value)`
`protected void`	`finalize()` Finalize this instance.
`byte[]`	`get(byte[] key)`
`KVPair`	`getAtLeast(byte[] minKey)`
`KVPair`	`getAtMost(byte[] maxKey)`
`File`	`getDirectory()` Get the filesystem directory containing the database.
`Iterator<KVPair>`	`getRange(byte[] minKey, byte[] maxKey, boolean reverse)`
`void`	`hotCopy(File target)` Create a filesystem atomic snapshot, or "hot" copy", of this instance in the specified destination directory.
`void`	`mutate(Mutations mutations, boolean sync)`
`void`	`put(byte[] key, byte[] value)`
`void`	`remove(byte[] key)`
`void`	`removeRange(byte[] minKey, byte[] maxKey)`
`Future<?>`	`scheduleCompaction()` Schedule a new compaction cycle, unless there is one already scheduled or running, or there are no outstanding uncompacted modifications.
`void`	`setCompactHighWater(int compactHighWater)` Configure the compaction space high-water mark in bytes.
`void`	`setCompactLowWater(int compactLowWater)` Configure the compaction space low-water mark in bytes.
`void`	`setCompactMaxDelay(int compactMaxDelay)` Configure the compaction time maximum delay.
`void`	`setDirectory(File directory)` Configure the filesystem directory containing the database.
`void`	`setScheduledExecutorService(ScheduledExecutorService scheduledExecutorService)` Configure the `ScheduledExecutorService` used to schedule background compaction.
`CloseableKVStore`	`snapshot()`
`void`	`start()`
`void`	`stop()`
`String`	`toString()`

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

- Field Detail
  - DEFAULT_COMPACTION_MAX_DELAY
```
public static final int DEFAULT_COMPACTION_MAX_DELAY
```
    Default compaction maximum delay in seconds (90 seconds).
    
    See Also:
    Constant Field Values
  - DEFAULT_COMPACTION_LOW_WATER
```
public static final int DEFAULT_COMPACTION_LOW_WATER
```
    Default compaction space low-water mark in bytes (65536 bytes).
    
    See Also:
    Constant Field Values
  - DEFAULT_COMPACTION_HIGH_WATER
```
public static final int DEFAULT_COMPACTION_HIGH_WATER
```
    Default compaction space high-water mark in bytes (1073741824 bytes).
    
    See Also:
    Constant Field Values
- Constructor Detail
  - AtomicArrayKVStore
```
public AtomicArrayKVStore()
```
- Method Detail
  - getDirectory
```
public File getDirectory()
```
    Get the filesystem directory containing the database. If not set, this class functions as an im-memory store.
    
    Returns:
    database directory, or null for none
  - setDirectory
```
public void setDirectory(File directory)
```
    Configure the filesystem directory containing the database. If not set, this class functions as an im-memory store.
    
    Parameters:
    directory - database directory, or null for none
    
    Throws:
    
    IllegalStateException - if this instance is already start()ed
  - setScheduledExecutorService
```
public void setScheduledExecutorService(ScheduledExecutorService scheduledExecutorService)
```
    Configure the ScheduledExecutorService used to schedule background compaction.
    If not explicitly configured, a ScheduledExecutorService will be created automatically during start() using Executors.newSingleThreadScheduledExecutor() and shutdown by stop() (if explicitly configured here, the configured ScheduledExecutorService will not be shutdown by stop()).
    
    Parameters:
    scheduledExecutorService - schduled executor service, or null to have one created automatically
    
    Throws:
    
    IllegalStateException - if this instance is already start()ed
  - setCompactMaxDelay
```
public void setCompactMaxDelay(int compactMaxDelay)
```
    Configure the compaction time maximum delay. Compaction will be automatically triggered whenever there is any uncompacted modification older than this.
    
    Parameters:
    compactMaxDelay - compaction time maximum delay in seconds
    
    Throws:
    
    IllegalArgumentException - if compactMaxDelay is negative
    
    IllegalStateException - if this instance is already start()ed
  - setCompactLowWater
```
public void setCompactLowWater(int compactLowWater)
```
    Configure the compaction space low-water mark in bytes.
    This value is applied to the size of the on-disk modifications file.
    
    Parameters:
    compactLowWater - compaction space low-water mark in bytes
    
    Throws:
    
    IllegalArgumentException - if compactLowWater is negative
    
    IllegalStateException - if this instance is already start()ed
  - setCompactHighWater
```
public void setCompactHighWater(int compactHighWater)
```
    Configure the compaction space high-water mark in bytes.
    This value is applied to the size of the on-disk modifications file.
    If the compaction space high water mark is set smaller than the the compaction space low water mark, then it's treated as if it were the same as the compaction space low water mark.
    
    Parameters:
    compactHighWater - compaction space high-water mark in bytes
    
    Throws:
    
    IllegalArgumentException - if compactHighWater is negative
    
    IllegalStateException - if this instance is already start()ed
  - start
```
@PostConstruct
public void start()
```
    Specified by:
    
    start in interface AtomicKVStore
  - stop
```
@PreDestroy
public void stop()
```
    Specified by:
    
    stop in interface AtomicKVStore
  - get
```
public byte[] get(byte[] key)
```
    Specified by:
    
    get in interface KVStore
    
    Overrides:
    
    get in class AbstractKVStore
  - getAtLeast
```
public KVPair getAtLeast(byte[] minKey)
```
    Specified by:
    
    getAtLeast in interface KVStore
    
    Overrides:
    
    getAtLeast in class AbstractKVStore
  - getAtMost
```
public KVPair getAtMost(byte[] maxKey)
```
    Specified by:
    
    getAtMost in interface KVStore
    
    Overrides:
    
    getAtMost in class AbstractKVStore
  - getRange
```
public Iterator<KVPair> getRange(byte[] minKey,
                        byte[] maxKey,
                        boolean reverse)
```
    Specified by:
    
    getRange in interface KVStore
  - put
```
public void put(byte[] key,
       byte[] value)
```
    Specified by:
    
    put in interface KVStore
    
    Overrides:
    
    put in class AbstractKVStore
  - remove
```
public void remove(byte[] key)
```
    Specified by:
    
    remove in interface KVStore
    
    Overrides:
    
    remove in class AbstractKVStore
  - removeRange
```
public void removeRange(byte[] minKey,
               byte[] maxKey)
```
    Specified by:
    
    removeRange in interface KVStore
    
    Overrides:
    
    removeRange in class AbstractKVStore
  - adjustCounter
```
public void adjustCounter(byte[] key,
                 long amount)
```
    Specified by:
    
    adjustCounter in interface KVStore
    
    Overrides:
    
    adjustCounter in class AbstractKVStore
  - encodeCounter
```
public byte[] encodeCounter(long value)
```
    Specified by:
    
    encodeCounter in interface KVStore
    
    Overrides:
    
    encodeCounter in class AbstractKVStore
  - decodeCounter
```
public long decodeCounter(byte[] bytes)
```
    Specified by:
    
    decodeCounter in interface KVStore
    
    Overrides:
    
    decodeCounter in class AbstractKVStore
  - snapshot
```
public CloseableKVStore snapshot()
```
    Specified by:
    
    snapshot in interface AtomicKVStore
  - mutate
```
public void mutate(Mutations mutations,
          boolean sync)
```
    Specified by:
    
    mutate in interface AtomicKVStore
  - hotCopy
```
public void hotCopy(File target)
             throws IOException
```
    Create a filesystem atomic snapshot, or "hot" copy", of this instance in the specified destination directory. The copy will be up-to-date as of the time this method is invoked.
    The target directory will be created if it does not exist; otherwise, it must be empty. All files except the uncompacted modifications file are copied into target in constant time using hard links if possible.
    The hot copy operation can proceed in parallel with normal database activity, with the exception that the compaction operation cannot start while there are concurrent hot copies in progress.
    Therefore, for best performance, consider performing a compaction immediately prior to this operation.
    Note: when this method returns, all copied files, and the target directory, have been fsync()'d and therefore may be considered durable in case of a system crash.
    
    Parameters:
    target - destination directory
    
    Throws:
    
    IOException - if an I/O error occurs
    
    IllegalArgumentException - if target exists and is not a directory or is non-empty
    
    IllegalArgumentException - if target is null
  - calculateCompactionPressureDelay
```
protected long calculateCompactionPressureDelay(float windowRatio)
```
    Calculate the maximum amount of time that a thread attempting to mutate() must wait for a background compaction to complete as we start nearing the high water mark.
    The implementation in AtomicArrayKVStore returns -1 for all values below 50%, and then scales according to an inverse power function returning zero at 50%, 100ms at 75%, and Long.MAX_VALUE at 100%.
    
    Parameters:
    windowRatio - the uncompacted mutation size as a fraction of the interval between low and high water marks; always a value value between zero and one (exclusive)
    
    Returns:
    negative value for no delay, zero or positive value to trigger a background compaction (if not already running) and wait up to that many milliseconds for it to complete
  - scheduleCompaction
```
public Future<?> scheduleCompaction()
```
    Schedule a new compaction cycle, unless there is one already scheduled or running, or there are no outstanding uncompacted modifications.
    
    Returns:
    a future for the completion of the next compaction cycle, or null if there are no uncompacted modifications
    
    Throws:
    
    IllegalStateException - if this instance is not started
  - finalize
```
protected void finalize()
                 throws Throwable
```
    Finalize this instance. Invokes stop() to close any unclosed iterators.
    
    Overrides:
    
    finalize in class Object
    
    Throws:
    
    Throwable
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object

Class AtomicArrayKVStore

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_COMPACTION_MAX_DELAY

DEFAULT_COMPACTION_LOW_WATER

DEFAULT_COMPACTION_HIGH_WATER

Constructor Detail

AtomicArrayKVStore

Method Detail

getDirectory

setDirectory

setScheduledExecutorService

setCompactMaxDelay

setCompactLowWater

setCompactHighWater

start

stop

get

getAtLeast

getAtMost

getRange

put

remove

removeRange

adjustCounter

encodeCounter

decodeCounter

snapshot

mutate

hotCopy

calculateCompactionPressureDelay

scheduleCompaction

finalize

toString