org.sfj

Class ChiseledMap<K,V>

java.lang.Object

java.util.AbstractMap<K,V>

org.sfj.ChiseledMap<K,V>

All Implemented Interfaces:

ConcurrentMap<K,V>, Map<K,V>

public class ChiseledMap<K,V>
extends AbstractMap<K,V>
implements ConcurrentMap<K,V>

Dead simple persistent ordered map. It is thread safe, via coarse synchronization on writes. Reads are unsynchronized, though the underlying FileChannel is shared. Deletes do not reclaim file space; they simply stop referencing the block. Writes are CRC checked on restart, file is truncated to match the valid length.

This class is useful for prototyping when you need a persistent store and don't want to bother much. You provide a file, and optionally an encoder and decoder, and you can shove Objects in a sorted map structure that will serve get()s from disk, and save mutations to disk. Basically, every change is written to a log, with crc. Old entries are just left there; no garbage collection is done. So it is not useful for massive stores, or fast changing ones, but for prototyping it's quite useful.

Null values are not allowed. An in-memory sorted list keeps keys/disk addresses for lookup. On restart, the entire log file is traversed, rebuilding the in memory picture of keys to locations.

The core methods are ioGet(), ioSet(), and ioUnset(); these throw IOExceptions on ... IO exceptions. The Map methods wrap these methods and throw the unchecked RuntimeIOException.

Author:

cschanck

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	ChiseledMap.Decoder<KK,VV> Decode a byte array into a key/value pair.
static interface	ChiseledMap.Encoder<KK,VV> Encode a key/value (here you must handle null values) into a ByteBuffer.
static class	ChiseledMap.OpenOption Open methods.
static class	ChiseledMap.RuntimeIOException For the map methods, IOExceptions are wrapped in this.

Nested classes/interfaces inherited from class java.util.AbstractMap

AbstractMap.SimpleEntry<K,V>, AbstractMap.SimpleImmutableEntry<K,V>

Nested classes/interfaces inherited from interface java.util.Map

Map.Entry<K,V>

Field Summary

Fields

Modifier and Type	Field and Description
static ChiseledMap.Decoder	DECODE_JAVA_SER Default java deserialization.
static int	DIGEST_MASK
static ChiseledMap.Encoder	ENCODE_JAVA_SER Default java serialization.
static byte[]	HDR

Constructor Summary

Constructors

Constructor and Description
ChiseledMap(File file, ChiseledMap.OpenOption open, Comparator<K> comp)
ChiseledMap(File file, ChiseledMap.OpenOption open, Comparator<K> comp, ChiseledMap.Encoder<K,V> encoder, ChiseledMap.Decoder<K,V> decoder) Constructor.

Method Summary

Modifier and Type	Method and Description
long	bytesOnDisk() File footprint on disk.
void	clear()
void	close() Close this TinyKVMap.
V	compute(K key, BiFunction<? super K,? super V,? extends V> remappingFunction)
V	computeIfAbsent(K key, Function<? super K,? extends V> mappingFunction)
V	computeIfPresent(K key, BiFunction<? super K,? super V,? extends V> remappingFunction)
boolean	containsKey(Object key)
Iterable<Map.Entry<K,V>>	entries() Entry iterator.
long	entriesOnDisk() Number of entries actually on the disk, even if invalid.
Set<Map.Entry<K,V>>	entrySet()
void	flush() Flush any buffered changes to disk, fsync.
V	get(Object key)
File	getFile() File being used.
V	ioGet(Object key) Retrieve the value associated with a specified key.
boolean	ioSet(K key, V v) Associate a key to a value
V	ioUnset(K key) Clear a value.
V	merge(K key, V value, BiFunction<? super V,? super V,? extends V> remappingFunction)
V	put(K key, V value)
V	putIfAbsent(K key, V value)
V	remove(Object key)
boolean	remove(Object key, Object value)
V	replace(K key, V value)
boolean	replace(K key, V oldValue, V newValue)
boolean	set(K key, V value) Unchecked verson of ioSet()
int	size()
ChiseledMap<K,V>	snapshot(File f) Copy only live entries to another file.
String	toString()

Methods inherited from class java.util.AbstractMap

clone, containsValue, equals, hashCode, isEmpty, keySet, putAll, values

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.concurrent.ConcurrentMap

forEach, getOrDefault, replaceAll

Methods inherited from interface java.util.Map

containsValue, equals, hashCode, isEmpty, keySet, putAll, values

Field Detail

DIGEST_MASK

public static final int DIGEST_MASK

See Also:

Constant Field Values

HDR

public static final byte[] HDR

ENCODE_JAVA_SER

public static ChiseledMap.Encoder ENCODE_JAVA_SER

Default java serialization. Good enough.

DECODE_JAVA_SER

public static ChiseledMap.Decoder DECODE_JAVA_SER

Default java deserialization. Good enough.

Constructor Detail

ChiseledMap

public ChiseledMap(File file,
                   ChiseledMap.OpenOption open,
                   Comparator<K> comp)
            throws IOException

Throws:

IOException

ChiseledMap

public ChiseledMap(File file,
                   ChiseledMap.OpenOption open,
                   Comparator<K> comp,
                   ChiseledMap.Encoder<K,V> encoder,
                   ChiseledMap.Decoder<K,V> decoder)
            throws IOException

Constructor. Create a TinyKVMap.

Parameters:

file - File to use.

open - Open mode

comp - Comparator to use. If null, Comparator.naturalOrder() is used.

encoder - Encoder to use. If null, default Java serializer is used.

decoder - Decoder to use. If null, default Java deserializer is used.

Throws:

IOException - on exception

Method Detail

entriesOnDisk

public long entriesOnDisk()

Number of entries actually on the disk, even if invalid.

Returns:

number of entries on disk, live and dead.

getFile

public File getFile()

File being used.

Returns:

file

bytesOnDisk

public long bytesOnDisk()
                 throws IOException

File footprint on disk.

Returns:

file size

Throws:

IOException - on exception

close

public void close()
           throws IOException

Close this TinyKVMap.

Throws:

IOException - on exception

size

public int size()

Specified by:

size in interface Map<K,V>

Overrides:

size in class AbstractMap<K,V>

entries

public Iterable<Map.Entry<K,V>> entries()

Entry iterator. Necessary slushy with respect to concurrency.

Returns:

iterator of entries.

entrySet

public Set<Map.Entry<K,V>> entrySet()

Specified by:

entrySet in interface Map<K,V>

Specified by:

entrySet in class AbstractMap<K,V>

flush

public void flush()
           throws IOException

Flush any buffered changes to disk, fsync.

Throws:

IOException - If you get an IOException, literally no guarantees can be made about the on disk state of the data.

ioGet

public V ioGet(Object key)
        throws IOException

Retrieve the value associated with a specified key.

Parameters:

key - key value

Returns:

value

Throws:

IOException - on exception

ioUnset

public V ioUnset(K key)
          throws IOException

Clear a value.

Parameters:

key - key value

Returns:

prior value

Throws:

IOException - on exception

ioSet

public boolean ioSet(K key,
                     V v)
              throws IOException

Associate a key to a value

Parameters:

key - key value

v - value -- cannot be null.

Returns:

true if it replaced a value

Throws:

IOException - on exception

snapshot

public ChiseledMap<K,V> snapshot(File f)
                          throws IOException

Copy only live entries to another file. Blocks writes to this map while snapshotting.

Parameters:

f - dest file

Returns:

new TinyKVMap

Throws:

IOException - on exception

containsKey

public boolean containsKey(Object key)

Specified by:

containsKey in interface Map<K,V>

Overrides:

containsKey in class AbstractMap<K,V>

get

public V get(Object key)

Specified by:

get in interface Map<K,V>

Overrides:

get in class AbstractMap<K,V>

set

public boolean set(K key,
                   V value)

Unchecked verson of ioSet()

Parameters:

key - key value

value - value to associate with key

Returns:

true if it replaced a value

put

public V put(K key,
             V value)

Specified by:

put in interface Map<K,V>

Overrides:

put in class AbstractMap<K,V>

remove

public V remove(Object key)

Specified by:

remove in interface Map<K,V>

Overrides:

remove in class AbstractMap<K,V>

clear

public void clear()

Specified by:

clear in interface Map<K,V>

Overrides:

clear in class AbstractMap<K,V>

putIfAbsent

public V putIfAbsent(K key,
                     V value)

Specified by:

putIfAbsent in interface ConcurrentMap<K,V>

Specified by:

putIfAbsent in interface Map<K,V>

remove

public boolean remove(Object key,
                      Object value)

Specified by:

remove in interface ConcurrentMap<K,V>

Specified by:

remove in interface Map<K,V>

replace

public boolean replace(K key,
                       V oldValue,
                       V newValue)

Specified by:

replace in interface ConcurrentMap<K,V>

Specified by:

replace in interface Map<K,V>

replace

public V replace(K key,
                 V value)

Specified by:

replace in interface ConcurrentMap<K,V>

Specified by:

replace in interface Map<K,V>

computeIfAbsent

public V computeIfAbsent(K key,
                         Function<? super K,? extends V> mappingFunction)

Specified by:

computeIfAbsent in interface ConcurrentMap<K,V>

Specified by:

computeIfAbsent in interface Map<K,V>

computeIfPresent

public V computeIfPresent(K key,
                          BiFunction<? super K,? super V,? extends V> remappingFunction)

Specified by:

computeIfPresent in interface ConcurrentMap<K,V>

Specified by:

computeIfPresent in interface Map<K,V>

compute

public V compute(K key,
                 BiFunction<? super K,? super V,? extends V> remappingFunction)

Specified by:

compute in interface ConcurrentMap<K,V>

Specified by:

compute in interface Map<K,V>

merge

public V merge(K key,
               V value,
               BiFunction<? super V,? super V,? extends V> remappingFunction)

Specified by:

merge in interface ConcurrentMap<K,V>

Specified by:

merge in interface Map<K,V>

toString

public String toString()

Overrides:

toString in class AbstractMap<K,V>