de.caff.generics

## Class SoftValueHashMap<K,V>

- java.lang.Object
- - de.caff.generics.RefValueHashMap<K,V>
  - - de.caff.generics.SoftValueHashMap<K,V>

- All Implemented Interfaces:
    java.util.Map<K,V>

      public class SoftValueHashMap<K,V>
      extends RefValueHashMap<K,V>

  A hashmap with strong keys and soft referenced values. According to the Java specification the references to the weak values are removed on garbage collection if there is no more memory available. See also `WeakValueHashMap` for a hash map with weak referenced values.

  The behavior of this hashmap is that it is possible that a value is `null` because of garbage collection although `RefValueHashMap.containsKey(Object)` says that the associated key is defined. It is able to handle `null` keys and `null` values.

  The default constructors enable auto cleaning, which will automatically remove all dead values each time a dead value is detected, but there are also constructors accepting a boolean autoClean parameter which allow to switch this feature off.

  Some invariances usually true for maps hold not here:

  - Even when the map is not changed in between, subsequent calls to `RefValueHashMap.containsValue(Object)` may return different results.
  - When auto cleaning is switched on, the same is true for calls to `RefValueHashMap.containsKey(Object)`.
  - When auto cleaning is switched on, the entries in the returned set of `RefValueHashMap.keySet()` may no longer be keys when used.
  With these restriction the best usage of this map is as a cache for values which can easily be reconstructed. The only methods which should be used without any problems are the `RefValueHashMap.put(Object, Object)`, `RefValueHashMap.putAll(java.util.Map)` and `RefValueHashMap.get(Object)` methods, when expecting a `null` return on the latter even if a value was added before.
  Author:
    Rammi
  See Also:
    `WeakValueHashMap`

- - ### Nested Class Summary

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

      `java.util.Map.Entry<K,V>`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SoftValueHashMap()` Constructs an empty `SoftValueHashMap` with the default initial capacity (16) and the default load factor (0.75).
    `SoftValueHashMap(boolean autoClean)` Constructs an empty `SoftValueHashMap` with the default initial capacity (16) and the default load factor (0.75).
    `SoftValueHashMap(boolean autoClean, int initialCapacity)` Constructs an empty `SoftValueHashMap` with the specified initial capacity and the default load factor (0.75).
    `SoftValueHashMap(boolean autoClean, int initialCapacity, float loadFactor)` Constructs an empty `HashMap` with the specified initial capacity and load factor.
    `SoftValueHashMap(boolean autoClean, java.util.Map<? extends K,? extends V> m)` Constructs a new `HashMap` with the same mappings as the specified `Map`.
    `SoftValueHashMap(int initialCapacity)` Constructs an empty `SoftValueHashMap` with the specified initial capacity and the default load factor (0.75).
    `SoftValueHashMap(int initialCapacity, float loadFactor)` Constructs an empty `HashMap` with the specified initial capacity and load factor.
    `SoftValueHashMap(java.util.Map<? extends K,? extends V> m)` Constructs a new `HashMap` with the same mappings as the specified `Map`.

  - ### Method Summary

    - ### Methods inherited from class de.caff.generics.RefValueHashMap

      `clear, containsKey, containsValue, entrySet, get, hasDeadValue, isEmpty, keySet, put, putAll, remove, removeDeadValues, size, values`

    - ### Methods inherited from class java.lang.Object

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

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

      `compute, computeIfAbsent, computeIfPresent, equals, forEach, getOrDefault, hashCode, merge, putIfAbsent, remove, replace, replace, replaceAll`

- - ### Constructor Detail

    - #### SoftValueHashMap

          public SoftValueHashMap()

      Constructs an empty `SoftValueHashMap` with the default initial capacity (16) and the default load factor (0.75).

    - #### SoftValueHashMap

          public SoftValueHashMap(int initialCapacity)

      Constructs an empty `SoftValueHashMap` with the specified initial capacity and the default load factor (0.75).
      Parameters:
        `initialCapacity` - the initial capacity.
      Throws:
        `java.lang.IllegalArgumentException` - if the initial capacity is negative.

    - #### SoftValueHashMap

          public SoftValueHashMap(int initialCapacity,
                                  float loadFactor)

      Constructs an empty `HashMap` with the specified initial capacity and load factor.
      Parameters:
        `initialCapacity` - The initial capacity.
        `loadFactor` - The load factor.
      Throws:
        `java.lang.IllegalArgumentException` - if the initial capacity is negative or the load factor is nonpositive.

    - #### SoftValueHashMap

          public SoftValueHashMap(@NotNull
                                  java.util.Map<? extends K,? extends V> m)

      Constructs a new `HashMap` with the same mappings as the specified `Map`. The `HashMap` is created with default load factor (0.75) and an initial capacity sufficient to hold the mappings in the specified `Map`.
      Parameters:
        `m` - the map whose mappings are to be placed in this map.
      Throws:
        `java.lang.NullPointerException` - if the specified map is null.

    - #### SoftValueHashMap

          public SoftValueHashMap(boolean autoClean)

      Constructs an empty `SoftValueHashMap` with the default initial capacity (16) and the default load factor (0.75).
      Parameters:
        `autoClean` - if `true` call `RefValueHashMap.removeDeadValues()` when finding a dead value

    - #### SoftValueHashMap

          public SoftValueHashMap(boolean autoClean,
                                  int initialCapacity)

      Constructs an empty `SoftValueHashMap` with the specified initial capacity and the default load factor (0.75).
      Parameters:
        `autoClean` - if `true` call `RefValueHashMap.removeDeadValues()` when finding a dead value
        `initialCapacity` - the initial capacity.
      Throws:
        `java.lang.IllegalArgumentException` - if the initial capacity is negative.

    - #### SoftValueHashMap

          public SoftValueHashMap(boolean autoClean,
                                  int initialCapacity,
                                  float loadFactor)

      Constructs an empty `HashMap` with the specified initial capacity and load factor.
      Parameters:
        `autoClean` - if `true` call `RefValueHashMap.removeDeadValues()` when finding a dead value
        `initialCapacity` - The initial capacity.
        `loadFactor` - The load factor.
      Throws:
        `java.lang.IllegalArgumentException` - if the initial capacity is negative or the load factor is nonpositive.

    - #### SoftValueHashMap

          public SoftValueHashMap(boolean autoClean,
                                  @NotNull
                                  java.util.Map<? extends K,? extends V> m)

      Constructs a new `HashMap` with the same mappings as the specified `Map`. The `HashMap` is created with default load factor (0.75) and an initial capacity sufficient to hold the mappings in the specified `Map`.
      Parameters:
        `autoClean` - if `true` call `RefValueHashMap.removeDeadValues()` when finding a dead value
        `m` - the map whose mappings are to be placed in this map.
      Throws:
        `java.lang.NullPointerException` - if the specified map is null.