de.caff.generics

## Class WeakValueHashMap<K,V>

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

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

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

  A hashmap with strong keys and weakly referenced values. According to the Java specification the references to the weak values are removed on each garbage collection. See also `SoftValueHashMap` for a hash map with soft 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:
    `SoftValueHashMap`

- - ### Nested Class Summary

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

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

  - ### Constructor Summary

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

    - #### WeakValueHashMap

          public WeakValueHashMap()

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

    - #### WeakValueHashMap

          public WeakValueHashMap(int initialCapacity)

      Constructs an empty `WeakValueHashMap` 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.

    - #### WeakValueHashMap

          public WeakValueHashMap(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.

    - #### WeakValueHashMap

          public WeakValueHashMap(@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.

    - #### WeakValueHashMap

          public WeakValueHashMap(boolean autoClean)

      Constructs an empty `WeakValueHashMap` 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

    - #### WeakValueHashMap

          public WeakValueHashMap(boolean autoClean,
                                  int initialCapacity)

      Constructs an empty `WeakValueHashMap` 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.

    - #### WeakValueHashMap

          public WeakValueHashMap(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.

    - #### WeakValueHashMap

          public WeakValueHashMap(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.