org.mapdb
Class BTreeMap<K,V>

java.lang.Object
  java.util.AbstractMap<K,V>
      org.mapdb.BTreeMap<K,V>

All Implemented Interfaces:

ConcurrentMap<K,V>, ConcurrentNavigableMap<K,V>, Map<K,V>, NavigableMap<K,V>, SortedMap<K,V>, Bind.MapWithModificationListener<K,V>

public class BTreeMap<K,V>
extends AbstractMap<K,V>
implements ConcurrentNavigableMap<K,V>, Bind.MapWithModificationListener<K,V>

A scalable concurrent ConcurrentNavigableMap implementation. The map is sorted according to the natural ordering of its keys, or by a Comparator provided at map creation time. Insertion, removal, update, and access operations safely execute concurrently by multiple threads. Iterators are weakly consistent, returning elements reflecting the state of the map at some point at or since the creation of the iterator. They do not throw ConcurrentModificationException, and may proceed concurrently with other operations. Ascending key ordered views and their iterators are faster than descending ones. It is possible to obtain consistent iterator by using snapshot() method. All Map.Entry pairs returned by methods in this class and its views represent snapshots of mappings at the time they were produced. They do not support the Entry.setValue method. (Note however that it is possible to change mappings in the associated map using put, putIfAbsent, or replace, depending on exactly which effect you need.) This collection has optional size counter. If this is enabled Map size is kept in Atomic.Long variable. Keeping counter brings considerable overhead on inserts and removals. If the size counter is not enabled the size method is not a constant-time operation. Determining the current number of elements requires a traversal of the elements. Additionally, the bulk operations putAll, equals, and clear are not guaranteed to be performed atomically. For example, an iterator operating concurrently with a putAll operation might view only some of the added elements. NOTE: there is an optional This class and its views and iterators implement all of the optional methods of the Map and Iterator interfaces. Like most other concurrent collections, this class does not permit the use of null keys or values because some null return values cannot be reliably distinguished from the absence of elements. Theoretical design of BTreeMap is based on paper from Philip L. Lehman and S. Bing Yao. More practical aspects of BTreeMap implementation are based on notes and demo application from Thomas Dinsdale-Young. B-Linked-Tree used here does not require locking for read. Updates and inserts locks only one, two or three nodes. This B-Linked-Tree structure does not support removal well, entry deletion does not collapse tree nodes. Massive deletion causes empty nodes and performance lost. There is workaround in form of compaction process, but it is not implemented yet.

Author:

Jan Kotek, some parts by Doug Lea and JSR-166 group

Nested Class Summary

protected static interface	BTreeMap.BNode common interface for BTree node
protected static class	BTreeMap.BTreeIterator
protected static class	BTreeMap.DescendingMap<K,V>
protected static class	BTreeMap.DirNode
protected static class	BTreeMap.LeafNode
protected static class	BTreeMap.NodeSerializer<A,B>
protected static class	BTreeMap.SubMap<K,V>
protected static class	BTreeMap.ValRef if valsOutsideNodes is true, this class is used instead of values.

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

protected static int	B_TREE_NODE_DIR_C
protected static int	B_TREE_NODE_DIR_L
protected static int	B_TREE_NODE_DIR_LR
protected static int	B_TREE_NODE_DIR_R
protected static int	B_TREE_NODE_LEAF_C
protected static int	B_TREE_NODE_LEAF_L
protected static int	B_TREE_NODE_LEAF_LR
protected static int	B_TREE_NODE_LEAF_R
static Comparator	COMPARABLE_COMPARATOR
protected Comparator	comparator keys are sorted by this
protected Atomic.Long	counter
protected static Object	EMPTY
protected Engine	engine DB Engine in which entries are persisted
protected boolean	hasValues is this a Map or Set? if false, entries do not have values, only keys are allowed
protected BTreeKeySerializer	keySerializer Serializer used to convert keys from/into binary form.
protected List<Long>	leftEdges
protected int	maxNodeSize maximal node size allowed in this BTree
protected Bind.MapListener<K,V>[]	modListeners
protected Object	modListenersLock
protected LongConcurrentHashMap<Thread>	nodeLocks holds node level locks
protected Serializer<BTreeMap.BNode>	nodeSerializer
protected int	numberOfNodeMetas
protected long	rootRecidRef recid under which reference to rootRecid is stored
protected boolean	valsOutsideNodes store values as part of BTree nodes
protected Serializer<V>	valueSerializer Serializer used to convert keys from/into binary form

Constructor Summary

BTreeMap(Engine engine, long rootRecidRef, int maxNodeSize, boolean valsOutsideNodes, long counterRecid, BTreeKeySerializer<K> keySerializer, Serializer<V> valueSerializer, Comparator<K> comparator, int numberOfNodeMetas, boolean disableLocks)
Constructor used to create new BTreeMap.

Method Summary

protected static long[]	arrayLongPut(long[] array, int pos, long value)
protected static Object[]	arrayPut(Object[] array, int pos, Object value) expand array size by 1, and put value at given position.
protected static void	assertNoLocks(LongConcurrentHashMap<Thread> locks)
Map.Entry<K,V>	ceilingEntry(K key)
K	ceilingKey(K key)
void	clear()
void	close() Closes underlying storage and releases all resources.
Comparator<? super K>	comparator()
boolean	containsKey(Object key)
boolean	containsValue(Object value)
protected static long	createRootRef(Engine engine, BTreeKeySerializer keySer, Serializer valueSer, Comparator comparator, int numberOfNodeMetas) creates empty root node and returns recid of its reference
NavigableSet<K>	descendingKeySet()
ConcurrentNavigableMap<K,V>	descendingMap()
Set<Map.Entry<K,V>>	entrySet()
protected int	findChildren(Object key, Object[] keys) Find the first children node with a key equal or greater than the given key.
protected Map.Entry<K,V>	findLarger(K key, boolean inclusive)
protected Fun.Tuple2<Integer,BTreeMap.LeafNode>	findLargerNode(K key, boolean inclusive)
protected Map.Entry<K,V>	findSmaller(K key, boolean inclusive)
Map.Entry<K,V>	firstEntry()
K	firstKey()
Map.Entry<K,V>	floorEntry(K key)
K	floorKey(K key)
V	get(Object key)
protected Object	get(Object key, boolean expandValue)
Engine	getEngine()
ConcurrentNavigableMap<K,V>	headMap(K toKey)
ConcurrentNavigableMap<K,V>	headMap(K toKey, boolean inclusive)
Map.Entry<K,V>	higherEntry(K key)
K	higherKey(K key)
boolean	isEmpty()
NavigableSet<K>	keySet()
Map.Entry<K,V>	lastEntry()
K	lastKey()
protected static void	lock(LongConcurrentHashMap<Thread> locks, long recid)
Map.Entry<K,V>	lowerEntry(K key)
K	lowerKey(K key)
protected Map.Entry<K,V>	makeEntry(Object key, Object value)
void	modificationListenerAdd(Bind.MapListener<K,V> listener) Add new modification listener notified when Map has been updated
void	modificationListenerRemove(Bind.MapListener<K,V> listener) Remove registered notification listener
NavigableSet<K>	navigableKeySet()
protected long	nextDir(BTreeMap.DirNode d, Object key)
protected void	notify(K key, V oldValue, V newValue)
Map.Entry<K,V>	pollFirstEntry()
Map.Entry<K,V>	pollLastEntry()
protected static SortedMap<String,Object>	preinitCatalog(DB db) hack used for DB Catalog
void	printTreeStructure()
V	put(K key, V value)
protected V	put2(K key, V value2, boolean putOnlyIfAbsent)
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)
int	size()
long	sizeLong()
NavigableMap<K,V>	snapshot() Make readonly snapshot view of current Map.
ConcurrentNavigableMap<K,V>	subMap(K fromKey, boolean fromInclusive, K toKey, boolean toInclusive)
ConcurrentNavigableMap<K,V>	subMap(K fromKey, K toKey)
ConcurrentNavigableMap<K,V>	tailMap(K fromKey)
ConcurrentNavigableMap<K,V>	tailMap(K fromKey, boolean inclusive)
protected static void	unlock(LongConcurrentHashMap<Thread> locks, long recid)
protected static void	unlockAll(LongConcurrentHashMap<Thread> locks)
protected V	valExpand(Object ret)
Collection<V>	values()

Methods inherited from class java.util.AbstractMap

clone, equals, hashCode, putAll, toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.Map

equals, hashCode, putAll

Field Detail

COMPARABLE_COMPARATOR

public static final Comparator COMPARABLE_COMPARATOR

EMPTY

protected static final Object EMPTY

B_TREE_NODE_LEAF_LR

protected static final int B_TREE_NODE_LEAF_LR

See Also:

Constant Field Values

B_TREE_NODE_LEAF_L

protected static final int B_TREE_NODE_LEAF_L

See Also:

Constant Field Values

B_TREE_NODE_LEAF_R

protected static final int B_TREE_NODE_LEAF_R

See Also:

Constant Field Values

B_TREE_NODE_LEAF_C

protected static final int B_TREE_NODE_LEAF_C

See Also:

Constant Field Values

B_TREE_NODE_DIR_LR

protected static final int B_TREE_NODE_DIR_LR

See Also:

Constant Field Values

B_TREE_NODE_DIR_L

protected static final int B_TREE_NODE_DIR_L

See Also:

Constant Field Values

B_TREE_NODE_DIR_R

protected static final int B_TREE_NODE_DIR_R

See Also:

Constant Field Values

B_TREE_NODE_DIR_C

protected static final int B_TREE_NODE_DIR_C

See Also:

Constant Field Values

rootRecidRef

protected final long rootRecidRef

recid under which reference to rootRecid is stored

keySerializer

protected final BTreeKeySerializer keySerializer

Serializer used to convert keys from/into binary form.

valueSerializer

protected final Serializer<V> valueSerializer

Serializer used to convert keys from/into binary form

comparator

protected final Comparator comparator

keys are sorted by this

nodeLocks

protected final LongConcurrentHashMap<Thread> nodeLocks

holds node level locks

maxNodeSize

protected final int maxNodeSize

maximal node size allowed in this BTree

engine

protected final Engine engine

DB Engine in which entries are persisted

hasValues

protected final boolean hasValues

is this a Map or Set? if false, entries do not have values, only keys are allowed

valsOutsideNodes

protected final boolean valsOutsideNodes

store values as part of BTree nodes

leftEdges

protected final List<Long> leftEdges

counter

protected final Atomic.Long counter

numberOfNodeMetas

protected final int numberOfNodeMetas

nodeSerializer

protected final Serializer<BTreeMap.BNode> nodeSerializer

modListenersLock

protected final Object modListenersLock

modListeners

protected Bind.MapListener<K,V>[] modListeners

Constructor Detail

BTreeMap

public BTreeMap(Engine engine,
                long rootRecidRef,
                int maxNodeSize,
                boolean valsOutsideNodes,
                long counterRecid,
                BTreeKeySerializer<K> keySerializer,
                Serializer<V> valueSerializer,
                Comparator<K> comparator,
                int numberOfNodeMetas,
                boolean disableLocks)

Constructor used to create new BTreeMap.

Parameters:

engine - used for persistence

rootRecidRef - reference to root recid

maxNodeSize - maximal BTree Node size. Node will split if number of entries is higher

valsOutsideNodes - Store Values outside of BTree Nodes in separate record?

counterRecid - recid under which `Atomic.Long` is stored, or `0` for no counter

keySerializer - Serializer used for keys. May be null for default value.

valueSerializer - Serializer used for values. May be null for default value

comparator - Comparator to sort keys in this BTree, may be null.

numberOfNodeMetas - number of meta records associated with each BTree node

disableLocks - makes class thread-unsafe but bit faster

Method Detail

preinitCatalog

protected static SortedMap<String,Object> preinitCatalog(DB db)

hack used for DB Catalog

createRootRef

protected static long createRootRef(Engine engine,
                                    BTreeKeySerializer keySer,
                                    Serializer valueSer,
                                    Comparator comparator,
                                    int numberOfNodeMetas)

creates empty root node and returns recid of its reference

findChildren

protected final int findChildren(Object key,
                                 Object[] keys)

Find the first children node with a key equal or greater than the given key. If all items are smaller it returns `keys.length`

get

public V get(Object key)

Specified by:

get in interface Map<K,V>

Overrides:

get in class AbstractMap<K,V>

get

protected Object get(Object key,
                     boolean expandValue)

valExpand

protected V valExpand(Object ret)

nextDir

protected long nextDir(BTreeMap.DirNode d,
                       Object key)

put

public V put(K key,
             V value)

Specified by:

put in interface Map<K,V>

Overrides:

put in class AbstractMap<K,V>

put2

protected V put2(K key,
                 V value2,
                 boolean putOnlyIfAbsent)

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>

makeEntry

protected Map.Entry<K,V> makeEntry(Object key,
                                   Object value)

isEmpty

public boolean isEmpty()

Specified by:

isEmpty in interface Map<K,V>

Overrides:

isEmpty in class AbstractMap<K,V>

size

public int size()

Specified by:

size in interface Map<K,V>

Overrides:

size in class AbstractMap<K,V>

sizeLong

public long sizeLong()

Specified by:

sizeLong in interface Bind.MapWithModificationListener<K,V>

Returns:

size of map, but in 64bit long which does not overflow at 2e9 items.

putIfAbsent

public V putIfAbsent(K key,
                     V value)

Specified by:

putIfAbsent in interface ConcurrentMap<K,V>

remove

public boolean remove(Object key,
                      Object value)

Specified by:

remove in interface ConcurrentMap<K,V>

replace

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

Specified by:

replace in interface ConcurrentMap<K,V>

replace

public V replace(K key,
                 V value)

Specified by:

replace in interface ConcurrentMap<K,V>

comparator

public Comparator<? super K> comparator()

Specified by:

comparator in interface SortedMap<K,V>

firstEntry

public Map.Entry<K,V> firstEntry()

Specified by:

firstEntry in interface NavigableMap<K,V>

pollFirstEntry

public Map.Entry<K,V> pollFirstEntry()

Specified by:

pollFirstEntry in interface NavigableMap<K,V>

pollLastEntry

public Map.Entry<K,V> pollLastEntry()

Specified by:

pollLastEntry in interface NavigableMap<K,V>

findSmaller

protected Map.Entry<K,V> findSmaller(K key,
                                     boolean inclusive)

lastEntry

public Map.Entry<K,V> lastEntry()

Specified by:

lastEntry in interface NavigableMap<K,V>

lowerEntry

public Map.Entry<K,V> lowerEntry(K key)

Specified by:

lowerEntry in interface NavigableMap<K,V>

lowerKey

public K lowerKey(K key)

Specified by:

lowerKey in interface NavigableMap<K,V>

floorEntry

public Map.Entry<K,V> floorEntry(K key)

Specified by:

floorEntry in interface NavigableMap<K,V>

floorKey

public K floorKey(K key)

Specified by:

floorKey in interface NavigableMap<K,V>

ceilingEntry

public Map.Entry<K,V> ceilingEntry(K key)

Specified by:

ceilingEntry in interface NavigableMap<K,V>

findLarger

protected Map.Entry<K,V> findLarger(K key,
                                    boolean inclusive)

findLargerNode

protected Fun.Tuple2<Integer,BTreeMap.LeafNode> findLargerNode(K key,
                                                               boolean inclusive)

ceilingKey

public K ceilingKey(K key)

Specified by:

ceilingKey in interface NavigableMap<K,V>

higherEntry

public Map.Entry<K,V> higherEntry(K key)

Specified by:

higherEntry in interface NavigableMap<K,V>

higherKey

public K higherKey(K key)

Specified by:

higherKey in interface NavigableMap<K,V>

containsKey

public boolean containsKey(Object key)

Specified by:

containsKey in interface Map<K,V>

Overrides:

containsKey in class AbstractMap<K,V>

containsValue

public boolean containsValue(Object value)

Specified by:

containsValue in interface Map<K,V>

Overrides:

containsValue in class AbstractMap<K,V>

firstKey

public K firstKey()

Specified by:

firstKey in interface SortedMap<K,V>

lastKey

public K lastKey()

Specified by:

lastKey in interface SortedMap<K,V>

subMap

public ConcurrentNavigableMap<K,V> subMap(K fromKey,
                                          boolean fromInclusive,
                                          K toKey,
                                          boolean toInclusive)

Specified by:

subMap in interface ConcurrentNavigableMap<K,V>

Specified by:

subMap in interface NavigableMap<K,V>

headMap

public ConcurrentNavigableMap<K,V> headMap(K toKey,
                                           boolean inclusive)

Specified by:

headMap in interface ConcurrentNavigableMap<K,V>

Specified by:

headMap in interface NavigableMap<K,V>

tailMap

public ConcurrentNavigableMap<K,V> tailMap(K fromKey,
                                           boolean inclusive)

Specified by:

tailMap in interface ConcurrentNavigableMap<K,V>

Specified by:

tailMap in interface NavigableMap<K,V>

subMap

public ConcurrentNavigableMap<K,V> subMap(K fromKey,
                                          K toKey)

Specified by:

subMap in interface ConcurrentNavigableMap<K,V>

Specified by:

subMap in interface NavigableMap<K,V>

Specified by:

subMap in interface SortedMap<K,V>

headMap

public ConcurrentNavigableMap<K,V> headMap(K toKey)

Specified by:

headMap in interface ConcurrentNavigableMap<K,V>

Specified by:

headMap in interface NavigableMap<K,V>

Specified by:

headMap in interface SortedMap<K,V>

tailMap

public ConcurrentNavigableMap<K,V> tailMap(K fromKey)

Specified by:

tailMap in interface ConcurrentNavigableMap<K,V>

Specified by:

tailMap in interface NavigableMap<K,V>

Specified by:

tailMap in interface SortedMap<K,V>

keySet

public NavigableSet<K> keySet()

Specified by:

keySet in interface ConcurrentNavigableMap<K,V>

Specified by:

keySet in interface Map<K,V>

Specified by:

keySet in interface SortedMap<K,V>

Overrides:

keySet in class AbstractMap<K,V>

navigableKeySet

public NavigableSet<K> navigableKeySet()

Specified by:

navigableKeySet in interface ConcurrentNavigableMap<K,V>

Specified by:

navigableKeySet in interface NavigableMap<K,V>

values

public Collection<V> values()

Specified by:

values in interface Map<K,V>

Specified by:

values in interface SortedMap<K,V>

Overrides:

values in class AbstractMap<K,V>

entrySet

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

Specified by:

entrySet in interface Map<K,V>

Specified by:

entrySet in interface SortedMap<K,V>

Specified by:

entrySet in class AbstractMap<K,V>

descendingMap

public ConcurrentNavigableMap<K,V> descendingMap()

Specified by:

descendingMap in interface ConcurrentNavigableMap<K,V>

Specified by:

descendingMap in interface NavigableMap<K,V>

descendingKeySet

public NavigableSet<K> descendingKeySet()

Specified by:

descendingKeySet in interface ConcurrentNavigableMap<K,V>

Specified by:

descendingKeySet in interface NavigableMap<K,V>

snapshot

public NavigableMap<K,V> snapshot()

Make readonly snapshot view of current Map. Snapshot is immutable and not affected by modifications made by other threads. Useful if you need consistent view on Map. Maintaining snapshot have some overhead, underlying Engine is closed after Map view is GCed. Please make sure to release reference to this Map view, so snapshot view can be garbage collected.

Returns:

snapshot

modificationListenerAdd

public void modificationListenerAdd(Bind.MapListener<K,V> listener)

Description copied from interface: Bind.MapWithModificationListener

Add new modification listener notified when Map has been updated

Specified by:

modificationListenerAdd in interface Bind.MapWithModificationListener<K,V>

Parameters:

listener - callback interface notified when map changes

modificationListenerRemove

public void modificationListenerRemove(Bind.MapListener<K,V> listener)

Description copied from interface: Bind.MapWithModificationListener

Remove registered notification listener

Specified by:

modificationListenerRemove in interface Bind.MapWithModificationListener<K,V>

Parameters:

listener - callback interface notified when map changes

notify

protected void notify(K key,
                      V oldValue,
                      V newValue)

close

public void close()

Closes underlying storage and releases all resources. Used mostly with temporary collections where engine is not accessible.

getEngine

public Engine getEngine()

printTreeStructure

public void printTreeStructure()

arrayLongPut

protected static long[] arrayLongPut(long[] array,
                                     int pos,
                                     long value)

arrayPut

protected static Object[] arrayPut(Object[] array,
                                   int pos,
                                   Object value)

expand array size by 1, and put value at given position. No items from original array are lost

assertNoLocks

protected static void assertNoLocks(LongConcurrentHashMap<Thread> locks)

unlock

protected static void unlock(LongConcurrentHashMap<Thread> locks,
                             long recid)

unlockAll

protected static void unlockAll(LongConcurrentHashMap<Thread> locks)

lock

protected static void lock(LongConcurrentHashMap<Thread> locks,
                           long recid)