Package org.multiverse.api.collections

## Interface TxnMap<K,​V>

- All Superinterfaces:
    `Map<K,​V>`
  All Known Implementing Classes:
    `AbstractTxnMap`, `NaiveTxnHashMap`

      public interface TxnMap<K,​V>
      extends Map<K,​V>

- - ### Nested Class Summary

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

      `Map.Entry<K extends Object,​V extends Object>`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `clear​(Txn txn)` | Removes all of the mappings from this map (optional operation).
    `boolean` | `containsKey​(Txn txn, Object key)` | Returns `true` if this map contains a mapping for the specified key.
    `boolean` | `containsValue​(Txn txn, Object value)` | Returns `true` if this map maps one or more keys to the specified value.
    `TxnSet<Map.Entry<K,​V>>` | `entrySet()` | Returns a `TxnSet` view of the mappings contained in this map.
    `TxnSet<Map.Entry<K,​V>>` | `entrySet​(Txn txn)` | Returns a `TxnSet` view of the mappings contained in this map.
    `V` | `get​(Txn txn, Object key)` | Returns the value to which the specified key is mapped, or `null` if this map contains no mapping for the key.
    `Stm` | `getStm()` | Returns the `Stm` that manages this `TxnMap`.
    `boolean` | `isEmpty​(Txn txn)` | Returns `true` if this map contains no key-value mappings.
    `TxnSet<K>` | `keySet()` | Returns a `TxnSet` view of the keys contained in this map.
    `TxnSet<K>` | `keySet​(Txn txn)` | Returns a `TxnSet` view of the keys contained in this map.
    `V` | `put​(Txn txn, K key, V value)` | Associates the specified value with the specified key in this map (optional operation).
    `void` | `putAll​(Txn txn, Map<? extends K,​? extends V> m)` | Copies all of the mappings from the specified map to this map (optional operation).
    `V` | `remove​(Txn txn, Object key)` | Removes the mapping for a key from this map if it is present (optional operation).
    `int` | `size​(Txn txn)` | Returns the number of key-value mappings in this map.
    `String` | `toString​(Txn txn)` |
    `TxnCollection<V>` | `values()` | Returns a `TxnCollection` view of the values contained in this map.
    `TxnCollection<V>` | `values​(Txn txn)` | Returns a `TxnCollection` view of the values contained in this map.

    - ### Methods inherited from interface java.util.Map

      `clear, compute, computeIfAbsent, computeIfPresent, containsKey, containsValue, equals, forEach, get, getOrDefault, hashCode, isEmpty, merge, put, putAll, putIfAbsent, remove, remove, replace, replace, replaceAll, size`

- - ### Method Detail

    - #### getStm

          Stm getStm()

      Returns the `Stm` that manages this `TxnMap`.
      Returns:
        the Stm that manages this map.

    - #### size

          int size​(Txn txn)

      Returns the number of key-value mappings in this map. If the map contains more than `Integer.MAX_VALUE` elements, returns `Integer.MAX_VALUE`.
      Parameters:
        `txn` -
      Returns:
        the number of key-value mappings in this map

    - #### isEmpty

          boolean isEmpty​(Txn txn)

      Returns `true` if this map contains no key-value mappings.
      Parameters:
        `txn` -
      Returns:
        `true` if this map contains no key-value mappings

    - #### clear

          void clear​(Txn txn)

      Removes all of the mappings from this map (optional operation). The map will be empty after this call returns.
      Parameters:
        `txn` -
      Throws:
        `UnsupportedOperationException` - if the `clear` operation is not supported by this map

    - #### get

          V get​(Txn txn,
                Object key)

      Returns the value to which the specified key is mapped, or `null` if this map contains no mapping for the key.

      More formally, if this map contains a mapping from a key `k` to a value `v` such that `(key==null ? k==null : key.equals(k))`, then this method returns `v`; otherwise it returns `null`. (There can be at most one such mapping.)

      If this map permits null values, then a return value of `null` does not necessarily indicate that the map contains no mapping for the key; it's also possible that the map explicitly maps the key to `null`. The `containsKey` operation may be used to distinguish these two cases.

      Parameters:
        `txn` -
        `key` - the key whose associated value is to be returned
      Returns:
        the value to which the specified key is mapped, or `null` if this map contains no mapping for the key
      Throws:
        `ClassCastException` - if the key is of an inappropriate type for this map (optional)
        `NullPointerException` - if the specified key is null and this map does not permit null keys (optional)

    - #### containsKey

          boolean containsKey​(Txn txn,
                              Object key)

      Returns `true` if this map contains a mapping for the specified key. More formally, returns `true` if and only if this map contains a mapping for a key `k` such that `(key==null ? k==null : key.equals(k))`. (There can be at most one such mapping.)
      Parameters:
        `txn` -
        `key` - key whose presence in this map is to be tested
      Returns:
        `true` if this map contains a mapping for the specified key
      Throws:
        `ClassCastException` - if the key is of an inappropriate type for this map (optional)
        `NullPointerException` - if the specified key is null and this map does not permit null keys (optional)

    - #### containsValue

          boolean containsValue​(Txn txn,
                                Object value)

      Returns `true` if this map maps one or more keys to the specified value. More formally, returns `true` if and only if this map contains at least one mapping to a value `v` such that `(value==null ? v==null : value.equals(v))`. This operation will probably require time linear in the map size for most implementations of the `Map` interface.
      Parameters:
        `txn` -
        `value` - value whose presence in this map is to be tested
      Returns:
        `true` if this map maps one or more keys to the specified value
      Throws:
        `ClassCastException` - if the value is of an inappropriate type for this map (optional)
        `NullPointerException` - if the specified value is null and this map does not permit null values (optional)

    - #### put

          V put​(Txn txn,
                K key,
                V value)

      Associates the specified value with the specified key in this map (optional operation). If the map previously contained a mapping for the key, the old value is replaced by the specified value. (A map `m` is said to contain a mapping for a key `k` if and only if `m.containsKey(k)` would return `true`.)
      Parameters:
        `txn` -
        `key` - key with which the specified value is to be associated
        `value` - value to be associated with the specified key
      Returns:
        the previous value associated with `key`, or `null` if there was no mapping for `key`. (A `null` return can also indicate that the map previously associated `null` with `key`, if the implementation supports `null` values.)
      Throws:
        `UnsupportedOperationException` - if the `put` operation is not supported by this map
        `ClassCastException` - if the class of the specified key or value prevents it from being stored in this map
        `NullPointerException` - if the specified key or value is null and this map does not permit null keys or values
        `IllegalArgumentException` - if some property of the specified key or value prevents it from being stored in this map

    - #### putAll

          void putAll​(Txn txn,
                      Map<? extends K,​? extends V> m)

      Copies all of the mappings from the specified map to this map (optional operation). The effect of this call is equivalent to that of calling `put(k, v)` on this map once for each mapping from key `k` to value `v` in the specified map. The behavior of this operation is undefined if the specified map is modified while the operation is in progress.
      Parameters:
        `txn` -
        `m` - mappings to be stored in this map
      Throws:
        `UnsupportedOperationException` - if the `putAll` operation is not supported by this map
        `ClassCastException` - if the class of a key or value in the specified map prevents it from being stored in this map
        `NullPointerException` - if the specified map is null, or if this map does not permit null keys or values, and the specified map contains null keys or values
        `IllegalArgumentException` - if some property of a key or value in the specified map prevents it from being stored in this map

    - #### remove

          V remove​(Txn txn,
                   Object key)

      Removes the mapping for a key from this map if it is present (optional operation). More formally, if this map contains a mapping from key `k` to value `v` such that `(key==null ? k==null : key.equals(k))`, that mapping is removed. (The map can contain at most one such mapping.)

      Returns the value to which this map previously associated the key, or `null` if the map contained no mapping for the key.

      If this map permits null values, then a return value of `null` does not necessarily indicate that the map contained no mapping for the key; it's also possible that the map explicitly mapped the key to `null`.

      The map will not contain a mapping for the specified key once the call returns.

      Parameters:
        `txn` -
        `key` - key whose mapping is to be removed from the map
      Returns:
        the previous value associated with `key`, or `null` if there was no mapping for `key`.
      Throws:
        `UnsupportedOperationException` - if the `remove` operation is not supported by this map
        `ClassCastException` - if the key is of an inappropriate type for this map (optional)
        `NullPointerException` - if the specified key is null and this map does not permit null keys (optional)

    - #### values

          TxnCollection<V> values()

      Returns a `TxnCollection` view of the values contained in this map. The collection is backed by the map, so changes to the map are reflected in the collection, and vice-versa. If the map is modified while an iteration over the collection is in progress (except through the iterator's own `remove` operation), the results of the iteration are undefined. The collection supports element removal, which removes the corresponding mapping from the map, via the `Iterator.remove`, `Collection.remove`, `removeAll`, `retainAll` and `clear` operations. It does not support the `add` or `addAll` operations.
      Specified by:
        `values` in interface `Map<K,​V>`
      Returns:
        a collection view of the values contained in this map

    - #### values

          TxnCollection<V> values​(Txn txn)

      Returns a `TxnCollection` view of the values contained in this map. The collection is backed by the map, so changes to the map are reflected in the collection, and vice-versa. If the map is modified while an iteration over the collection is in progress (except through the iterator's own `remove` operation), the results of the iteration are undefined. The collection supports element removal, which removes the corresponding mapping from the map, via the `Iterator.remove`, `Collection.remove`, `removeAll`, `retainAll` and `clear` operations. It does not support the `add` or `addAll` operations.
      Parameters:
        `txn` -
      Returns:
        a collection view of the values contained in this map

    - #### keySet

          TxnSet<K> keySet()

      Returns a `TxnSet` view of the keys contained in this map. The set is backed by the map, so changes to the map are reflected in the set, and vice-versa. If the map is modified while an iteration over the set is in progress (except through the iterator's own `remove` operation), the results of the iteration are undefined. The set supports element removal, which removes the corresponding mapping from the map, via the `Iterator.remove`, `Set.remove`, `removeAll`, `retainAll`, and `clear` operations. It does not support the `add` or `addAll` operations.
      Specified by:
        `keySet` in interface `Map<K,​V>`
      Returns:
        a set view of the keys contained in this map

    - #### keySet

          TxnSet<K> keySet​(Txn txn)

      Returns a `TxnSet` view of the keys contained in this map. The set is backed by the map, so changes to the map are reflected in the set, and vice-versa. If the map is modified while an iteration over the set is in progress (except through the iterator's own `remove` operation), the results of the iteration are undefined. The set supports element removal, which removes the corresponding mapping from the map, via the `Iterator.remove`, `Set.remove`, `removeAll`, `retainAll`, and `clear` operations. It does not support the `add` or `addAll` operations.
      Parameters:
        `txn` -
      Returns:
        a set view of the keys contained in this map

    - #### entrySet

          TxnSet<Map.Entry<K,​V>> entrySet()

      Returns a `TxnSet` view of the mappings contained in this map. The set is backed by the map, so changes to the map are reflected in the set, and vice-versa. If the map is modified while an iteration over the set is in progress (except through the iterator's own `remove` operation, or through the `setValue` operation on a map entry returned by the iterator) the results of the iteration are undefined. The set supports element removal, which removes the corresponding mapping from the map, via the `Iterator.remove`, `Set.remove`, `removeAll`, `retainAll` and `clear` operations. It does not support the `add` or `addAll` operations.
      Specified by:
        `entrySet` in interface `Map<K,​V>`
      Returns:
        a set view of the mappings contained in this map

    - #### entrySet

          TxnSet<Map.Entry<K,​V>> entrySet​(Txn txn)

      Returns a `TxnSet` view of the mappings contained in this map. The set is backed by the map, so changes to the map are reflected in the set, and vice-versa. If the map is modified while an iteration over the set is in progress (except through the iterator's own `remove` operation, or through the `setValue` operation on a map entry returned by the iterator) the results of the iteration are undefined. The set supports element removal, which removes the corresponding mapping from the map, via the `Iterator.remove`, `Set.remove`, `removeAll`, `retainAll` and `clear` operations. It does not support the `add` or `addAll` operations.
      Parameters:
        `txn` -
      Returns:
        a set view of the mappings contained in this map

    - #### toString

          String toString​(Txn txn)