org.mapdb

Class Bind

java.lang.Object

org.mapdb.Bind

public final class Bind
extends Object

Binding is simple yet powerful way to keep secondary collection synchronized with primary collection. Primary collection provides notification on updates and secondary collection is modified accordingly. This way MapDB provides secondary indexes, values and keys. It also supports less usual scenarios such as histograms, inverse lookup index (on maps), group counters and so on. There are two things to keep on mind when using binding: * Binding is not persistent, so it needs to be restored every time store is reopened. If you modify primary collection before binding is restored, secondary collection does not get updated and becomes inconsistent. * If secondary collection is empty, binding will recreate its content based on primary collection. If there is even single item on secondary collection, binding assumes it is consistent and leaves it as its. Any thread-safe collection can be used as secondary (not just collections provided by MapDB). This gives great flexibility for modeling and scaling your data. For example primary data can be stored in durable DB with transactions and large secondary indexes may be stored in other faster non-durable DB. Or primary collection may be stored on disk and smaller secondary index (such as category counters) can be stored in memory for faster lookups. Also you may use ordinary java.util.* collections (if they are thread safe) to get additional speed. There are many [code examples](https://github.com/jankotek/MapDB/tree/master/src/test/java/examples) how Collection Binding can be used. NOTE: Binding just installs Modification Listener on primary collection. Binding itself is not persistent and has to be restored after primary collection is loaded. Data contained in secondary collection are persistent.

Author:

Jan Kotek

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	Bind.MapListener<K,V> Listener called when Map is modified.
static interface	Bind.MapWithModificationListener<K,V> Primary Maps must provide notifications when it is modified.

Method Summary

Methods

Modifier and Type	Method and Description
static <K,V,C> void	histogram(Bind.MapWithModificationListener<K,V> primary, ConcurrentMap<C,Long> histogram, Fun.Function2<C,K,V> entryToCategory) Binds Secondary Map so it it creates [histogram](http://en.wikipedia.org/wiki/Histogram) from data in Primary Map.
static <K,V> void	mapInverse(Bind.MapWithModificationListener<K,V> primary, Map<V,K> inverse) Binds Secondary Set so it contains inverse mapping to Primary Map: Primary Value will become Secondary Key.
static <K,V> void	mapInverse(Bind.MapWithModificationListener<K,V> primary, Set<Object[]> inverse) Binds Secondary Set so it contains inverse mapping to Primary Map: Primary Value will become Secondary Key.
static <K,V> void	mapPutAfterDelete(Bind.MapWithModificationListener<K,V> primary, Bind.MapWithModificationListener<K,V> secondary, boolean overwriteSecondary) After key is removed from primary for some reason (map.remove, or expiration in HTreeMap), it gets moved into secondary collection.
static <K,V,K2> void	secondaryKey(Bind.MapWithModificationListener<K,V> map, Map<K2,K> secondary, Fun.Function2<K2,K,V> fun) Binds Secondary Set so it contains Secondary Key (Index).
static <K,V,K2> void	secondaryKey(Bind.MapWithModificationListener<K,V> map, Set<Object[]> secondary, Fun.Function2<K2,K,V> fun) Binds Secondary Set so it contains Secondary Key (Index).
static <K,V,K2> void	secondaryKeys(Bind.MapWithModificationListener<K,V> map, Set<Object[]> secondary, Fun.Function2<K2[],K,V> fun) Binds Secondary Set so it contains Secondary Key (Index).
static <K,V,V2> void	secondaryValue(Bind.MapWithModificationListener<K,V> map, Map<K,V2> secondary, Fun.Function2<V2,K,V> fun) Binds Secondary Map so that it contains Key from Primary Map and custom Value.
static <K,V,V2> void	secondaryValues(Bind.MapWithModificationListener<K,V> map, Set<Object[]> secondary, Fun.Function2<V2[],K,V> fun) Binds Secondary Map so that it contains Key from Primary Map and custom Value.
static <K,V> void	size(Bind.MapWithModificationListener<K,V> map, Atomic.Long sizeCounter) Binds Atomic.Long to Primary Map so the Atomic.Long contains size of Map.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

size

public static <K,V> void size(Bind.MapWithModificationListener<K,V> map,
              Atomic.Long sizeCounter)

Binds Atomic.Long to Primary Map so the Atomic.Long contains size of Map. Atomic.Long is incremented on each insert and decremented on each entry removal. MapDB collections usually do not keep their size, but require complete traversal to count items. If Atomic.Long has zero value, it will be updated with value from map.size() and than bind to map. NOTE: Binding just installs Modification Listener on primary collection. Binding itself is not persistent and has to be restored after primary collection is loaded. Data contained in secondary collection are persistent. NOTE: BTreeMap and HTreeMap already supports this directly as optional parameter named counter. In that case all calls to Map.size() are forwarded to underlying counter. Check parameters at DB.hashMapCreate(String) and DB.treeMapCreate(String)

Type Parameters:

K - type of key in map

V - type of value in map

Parameters:

map - primary map whose size needs to be tracked

sizeCounter - number updated when Map Entry is added or removed.

secondaryValue

public static <K,V,V2> void secondaryValue(Bind.MapWithModificationListener<K,V> map,
                           Map<K,V2> secondary,
                           Fun.Function2<V2,K,V> fun)

Binds Secondary Map so that it contains Key from Primary Map and custom Value. Secondary Value is updated every time Primary Map is modified. If Secondary Map is empty its content will be recreated from Primary Map. This binding is not persistent. You need to restore it every time store is reopened. NOTE: Binding just installs Modification Listener on primary collection. Binding itself is not persistent and has to be restored after primary collection is loaded. Data contained in secondary collection are persistent. Type params:

Type Parameters:

K - - key type in primary and Secondary Map

V - - value type in Primary Map

V2 - - value type in Secondary Map

Parameters:

map - Primary Map

secondary - Secondary Map with custom

fun - function which calculates secondary value from primary key and value

secondaryValues

public static <K,V,V2> void secondaryValues(Bind.MapWithModificationListener<K,V> map,
                            Set<Object[]> secondary,
                            Fun.Function2<V2[],K,V> fun)

Binds Secondary Map so that it contains Key from Primary Map and custom Value. Secondary Value is updated every time Primary Map is modified. If Secondary Map is empty its content will be recreated from Primary Map. This binding is not persistent. You need to restore it every time store is reopened. NOTE: Binding just installs Modification Listener on primary collection. Binding itself is not persistent and has to be restored after primary collection is loaded. Data contained in secondary collection are persistent. Type params:

Type Parameters:

K - - key type in primary and Secondary Map

V - - value type in Primary Map

V2 - - value type in Secondary Map .

Parameters:

map - Primary Map

secondary - Secondary Map with custom

fun - function which calculates secondary values from primary key and value

secondaryKey

public static <K,V,K2> void secondaryKey(Bind.MapWithModificationListener<K,V> map,
                         Set<Object[]> secondary,
                         Fun.Function2<K2,K,V> fun)

Binds Secondary Set so it contains Secondary Key (Index). Usefull if you need to lookup Keys from Primary Map by custom criteria. Other use is for reverse lookup To lookup keys in Secondary Set use Fun.filter(java.util.NavigableSet, Object[]) If Secondary Set is empty its content will be recreated from Primary Map. This binding is not persistent. You need to restore it every time store is reopened. NOTE: Binding just installs Modification Listener on primary collection. Binding itself is not persistent and has to be restored after primary collection is loaded. Data contained in secondary collection are persistent. Type params:

Type Parameters:

K - - Key in Primary Map

V - - Value in Primary Map

K2 - - Secondary

Parameters:

map - primary map

secondary - secondary set

fun - function which calculates Secondary Key from Primary Key and Value

secondaryKey

public static <K,V,K2> void secondaryKey(Bind.MapWithModificationListener<K,V> map,
                         Map<K2,K> secondary,
                         Fun.Function2<K2,K,V> fun)

Binds Secondary Set so it contains Secondary Key (Index). Usefull if you need to lookup Keys from Primary Map by custom criteria. Other use is for reverse lookup If Secondary Set is empty its content will be recreated from Primary Map. This binding is not persistent. You need to restore it every time store is reopened. NOTE: Binding just installs Modification Listener on primary collection. Binding itself is not persistent and has to be restored after primary collection is loaded. Data contained in secondary collection are persistent. Type params:

Type Parameters:

K - - Key in Primary Map

V - - Value in Primary Map

K2 - - Secondary

Parameters:

map - primary map

secondary - secondary set

fun - function which calculates Secondary Key from Primary Key and Value

secondaryKeys

public static <K,V,K2> void secondaryKeys(Bind.MapWithModificationListener<K,V> map,
                          Set<Object[]> secondary,
                          Fun.Function2<K2[],K,V> fun)

Binds Secondary Set so it contains Secondary Key (Index). Useful if you need to lookup Keys from Primary Map by custom criteria. Other use is for reverse lookup To lookup keys in Secondary Set use Fun.filter(java.util.NavigableSet, Object[])} If Secondary Set is empty its content will be recreated from Primary Map. NOTE: Binding just installs Modification Listener on primary collection. Binding itself is not persistent and has to be restored after primary collection is loaded. Data contained in secondary collection are persistent. Type params:

Type Parameters:

K - - Key in Primary Map

V - - Value in Primary Map

K2 - - Secondary

Parameters:

map - primary map

secondary - secondary set

fun - function which calculates Secondary Keys from Primary Key and Value

mapInverse

public static <K,V> void mapInverse(Bind.MapWithModificationListener<K,V> primary,
                    Set<Object[]> inverse)

Binds Secondary Set so it contains inverse mapping to Primary Map: Primary Value will become Secondary Key. This is useful for creating bi-directional Maps. To lookup keys in Secondary Set use Fun.filter(java.util.NavigableSet, Object[]) If Secondary Set is empty its content will be recreated from Primary Map. NOTE: Binding just installs Modification Listener on primary collection. Binding itself is not persistent and has to be restored after primary collection is loaded. Data contained in secondary collection are persistent. Type params:

Type Parameters:

K - - Key in Primary Map and Second Value in Secondary Set

V - - Value in Primary Map and Primary Value in Secondary Set

Parameters:

primary - Primary Map for which inverse mapping will be created

inverse - Secondary Set which will contain inverse mapping

mapInverse

public static <K,V> void mapInverse(Bind.MapWithModificationListener<K,V> primary,
                    Map<V,K> inverse)

Binds Secondary Set so it contains inverse mapping to Primary Map: Primary Value will become Secondary Key. This is useful for creating bi-directional Maps. In this case some data may be lost, if there are duplicated primary values. It is recommended to use multimap: NavigableSet<Fun.Tuple2<V,K>> which handles value duplicities. Use mapInverse(org.mapdb.Bind.MapWithModificationListener, java.util.Map) If Secondary Set is empty its content will be recreated from Primary Map. NOTE: Binding just installs Modification Listener on primary collection. Binding itself is not persistent and has to be restored after primary collection is loaded. Data contained in secondary collection are persistent. Type params:

Type Parameters:

K - - Key in Primary Map and Second Value in Secondary Set

V - - Value in Primary Map and Primary Value in Secondary Set

Parameters:

primary - Primary Map for which inverse mapping will be created

inverse - Secondary Set which will contain inverse mapping

histogram

public static <K,V,C> void histogram(Bind.MapWithModificationListener<K,V> primary,
                     ConcurrentMap<C,Long> histogram,
                     Fun.Function2<C,K,V> entryToCategory)

Binds Secondary Map so it it creates [histogram](http://en.wikipedia.org/wiki/Histogram) from data in Primary Map. Histogram keeps count how many items are in each category. This method takes function which defines in what category each Primary Map entry is in. If Secondary Map is empty its content will be recreated from Primary Map. NOTE: Binding just installs Modification Listener on primary collection. Binding itself is not persistent and has to be restored after primary collection is loaded. Data contained in secondary collection are persistent. Type params:

Type Parameters:

K - - Key type in primary map

V - - Value type in primary map

C - - Category type

Parameters:

primary - Primary Map to create histogram for

histogram - Secondary Map to create histogram for, key is Category, value is number of items in category

entryToCategory - returns Category in which entry from Primary Map belongs to.

mapPutAfterDelete

public static <K,V> void mapPutAfterDelete(Bind.MapWithModificationListener<K,V> primary,
                           Bind.MapWithModificationListener<K,V> secondary,
                           boolean overwriteSecondary)

After key is removed from primary for some reason (map.remove, or expiration in HTreeMap), it gets moved into secondary collection. This does not apply to updated values where key remains unchanged (put(), replace()..)

Type Parameters:

K - key

V - value

Parameters:

primary - map from which data are removed by user

secondary - map which gets automatically updated with data removed from primary

overwriteSecondary - if true any data in secondary will be overwritten. If false only non-existing keys will be inserted (put() versus putIfAbsent();