net.corda.node.utilities

## Class AbstractJDBCHashMap<K,V,T extends JDBCHashedTable>

- net.corda.node.utilities.AbstractJDBCHashMap<K,V,T>

- Direct Known Subclasses:
    JDBCHashMap

      public class AbstractJDBCHashMap<K,V,T extends JDBCHashedTable>

  A base class for a JDBC table backed hash map that iterates in insertion order by using an ever increasing sequence number on entries. Iterators supports remove() but entries are not really mutable and do not support setValue() method from MutableMap.MutableEntry.

  You should only use keys that have overridden Object.hashCode and that have a good hash code distribution. Beware changing the hashCode() implementation once objects have been persisted. A process to re-hash the entries persisted would be necessary if you do this.

  Subclasses must provide their own mapping to and from keys/values and the database table columns, but there are inherited columns that all tables must provide to support iteration order and hashing.

  The map operates in one of two modes.

  1. loadOnInit=true where the entire table is loaded into memory in the constructor and all entries remain in memory, with only writes needing to perform database access.

  2. loadOnInit=false where all entries with the same key hash code are loaded from the database on demand when accessed via any method other than via keys/values/entries properties, and thus the whole map is not loaded into memory. The number of entries retained in memory is controlled indirectly by an LRU algorithm (courtesy of LinkedHashMap) and a maximum number of hash "buckets", where one bucket represents all entries with the same hash code. There is a default value for maximum buckets.

  All operations require a databaseTransaction to be started.

  The keys/values/entries collections are really designed just for iterating and other uses might turn out to be costly in terms of performance. Beware when loadOnInit=true, the iterator first sorts the entries which could be costly too.

  This class is not thread safe.

  TODO: consider caching size once calculated for the first time. TODO: buckets just use a list and so are vulnerable to poor hash code implementations with collisions. TODO: if iterators are used extensively when loadOnInit=true, consider maintaining a collection of keys in iteration order to avoid sorting each time. TODO: revisit whether we need the loadOnInit==true functionality and remove if not.

  See Also:
    Object.hashCode, LinkedHashMap

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `AbstractJDBCHashMap.Companion`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static AbstractJDBCHashMap.Companion` | `Companion`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `AbstractJDBCHashMap(T table, boolean loadOnInit, int maxBuckets)` A base class for a JDBC table backed hash map that iterates in insertion order by using an ever increasing sequence number on entries. Iterators supports remove() but entries are not really mutable and do not support setValue() method from MutableMap.MutableEntry.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addKeyToInsert(org.jetbrains.exposed.sql.statements.InsertStatement insert, java.util.Map.Entry<? extends K,? extends V> entry, java.util.List<kotlin.jvm.functions.Function0> finalizables)` Implementation should marshall the key to the insert statement.
    `void` | `addValueToInsert(org.jetbrains.exposed.sql.statements.InsertStatement insert, java.util.Map.Entry<? extends K,? extends V> entry, java.util.List<kotlin.jvm.functions.Function0> finalizables)` Implementation should marshall the value to the insert statement.
    `void` | `clear()`
    `boolean` | `containsKey(java.lang.Object key)`
    `boolean` | `containsValue(java.lang.Object value)`
    `java.util.Set` | `entrySet()`
    `V` | `get(java.lang.Object key)`
    `java.util.Set<java.util.Map.Entry>` | `getEntries()`
    `java.util.Set<K>` | `getKeys()`
    `boolean` | `getLoadOnInit()`
    `int` | `getMaxBuckets()`
    `int` | `getSize()`
    `T` | `getTable()`
    `java.util.Collection<V>` | `getValues()`
    `boolean` | `isEmpty()`
    `K` | `keyFromRow(org.jetbrains.exposed.sql.ResultRow row)` Implementation should return the key object marshalled from the database table row.
    `java.util.Set` | `keySet()`
    `V` | `put(K key, V value)`
    `V` | `remove(java.lang.Object key)`
    `int` | `size()`
    `V` | `valueFromRow(org.jetbrains.exposed.sql.ResultRow row)` Implementation should return the value object marshalled from the database table row.
    `java.util.Collection` | `values()`

- - ### Field Detail

    - #### Companion

          public static AbstractJDBCHashMap.Companion Companion

  - ### Constructor Detail

    - #### AbstractJDBCHashMap

          public AbstractJDBCHashMap(T table,
                                     boolean loadOnInit,
                                     int maxBuckets)

      A base class for a JDBC table backed hash map that iterates in insertion order by using an ever increasing sequence number on entries. Iterators supports remove() but entries are not really mutable and do not support setValue() method from MutableMap.MutableEntry.

      You should only use keys that have overridden Object.hashCode and that have a good hash code distribution. Beware changing the hashCode() implementation once objects have been persisted. A process to re-hash the entries persisted would be necessary if you do this.

      Subclasses must provide their own mapping to and from keys/values and the database table columns, but there are inherited columns that all tables must provide to support iteration order and hashing.

      The map operates in one of two modes.

      1. loadOnInit=true where the entire table is loaded into memory in the constructor and all entries remain in memory, with only writes needing to perform database access.

      2. loadOnInit=false where all entries with the same key hash code are loaded from the database on demand when accessed via any method other than via keys/values/entries properties, and thus the whole map is not loaded into memory. The number of entries retained in memory is controlled indirectly by an LRU algorithm (courtesy of LinkedHashMap) and a maximum number of hash "buckets", where one bucket represents all entries with the same hash code. There is a default value for maximum buckets.

      All operations require a databaseTransaction to be started.

      The keys/values/entries collections are really designed just for iterating and other uses might turn out to be costly in terms of performance. Beware when loadOnInit=true, the iterator first sorts the entries which could be costly too.

      This class is not thread safe.

      TODO: consider caching size once calculated for the first time. TODO: buckets just use a list and so are vulnerable to poor hash code implementations with collisions. TODO: if iterators are used extensively when loadOnInit=true, consider maintaining a collection of keys in iteration order to avoid sorting each time. TODO: revisit whether we need the loadOnInit==true functionality and remove if not.

      See Also:
        Object.hashCode, LinkedHashMap

  - ### Method Detail

    - #### isEmpty

          public boolean isEmpty()

    - #### remove

          public V remove(java.lang.Object key)

    - #### containsKey

          public boolean containsKey(java.lang.Object key)

    - #### getKeys

          public java.util.Set<K> getKeys()

    - #### keySet

          public java.util.Set keySet()

    - #### getValues

          public java.util.Collection<V> getValues()

    - #### values

          public java.util.Collection values()

    - #### getEntries

          public java.util.Set<java.util.Map.Entry> getEntries()

    - #### entrySet

          public java.util.Set entrySet()

    - #### put

          public V put(K key,
                       V value)

    - #### containsValue

          public boolean containsValue(java.lang.Object value)

    - #### getSize

          public int getSize()

    - #### size

          public int size()

    - #### clear

          public void clear()

    - #### get

          public V get(java.lang.Object key)

    - #### keyFromRow

          public K keyFromRow(org.jetbrains.exposed.sql.ResultRow row)

      Implementation should return the key object marshalled from the database table row.

      See example implementations in `class JDBCHashMap`.

      See Also:
        `class JDBCHashMap`

    - #### valueFromRow

          public V valueFromRow(org.jetbrains.exposed.sql.ResultRow row)

      Implementation should return the value object marshalled from the database table row.

      See example implementations in `class JDBCHashMap`.

      See Also:
        `class JDBCHashMap`

    - #### addKeyToInsert

          public void addKeyToInsert(org.jetbrains.exposed.sql.statements.InsertStatement insert,
                                     java.util.Map.Entry<? extends K,? extends V> entry,
                                     java.util.List<kotlin.jvm.functions.Function0> finalizables)

      Implementation should marshall the key to the insert statement.

      If some cleanup is required after the insert statement is executed, such as closing a Blob, then add a closure to the finalizables to do so.

      See example implementations in `class JDBCHashMap`.

      See Also:
        `class JDBCHashMap`

    - #### addValueToInsert

          public void addValueToInsert(org.jetbrains.exposed.sql.statements.InsertStatement insert,
                                       java.util.Map.Entry<? extends K,? extends V> entry,
                                       java.util.List<kotlin.jvm.functions.Function0> finalizables)

      Implementation should marshall the value to the insert statement.

      If some cleanup is required after the insert statement is executed, such as closing a Blob, then add a closure to the finalizables to do so.

      See example implementations in `class JDBCHashMap`.

      See Also:
        `class JDBCHashMap`

    - #### getTable

          public T getTable()

    - #### getLoadOnInit

          public boolean getLoadOnInit()

    - #### getMaxBuckets

          public int getMaxBuckets()