Package org.apache.sis.util.collection

Class WeakValueHashMap<K,V>

java.lang.Object
java.util.AbstractMap<K,V>
org.apache.sis.util.collection.WeakValueHashMap<K,V>
Type Parameters:
K - the class of key elements.
V - the class of value elements.
All Implemented Interfaces:
Map<K,V>
public class WeakValueHashMap<K,V> extends AbstractMap<K,V>
A hashtable-based map implementation that uses weak references, leaving memory when an entry is not used anymore. An entry in a WeakValueHashMap will automatically be removed when its value is no longer in ordinary use. This class is similar to the standard WeakHashMap class, except that weak references apply to values rather than keys.

Note that this class is not a cache, because the entries are discarded as soon as the garbage collector determines that they are no longer in use. If caching service are wanted, or if concurrency are wanted, consider using Cache instead.

This class is convenient for avoiding the creation of duplicated elements, as in the example below:

In the above example, the calculation of a new value needs to be fast because it is performed inside a synchronized statement blocking all other access to the map. This is okay if that particular WeakValueHashMap instance is not expected to be used in a highly concurrent environment.

WeakValueHashMap works with array keys as one would expect. For example, arrays of int[] are compared using the Arrays.equals(int[], int[]) method.

Thread safety

The same WeakValueHashMap instance can be safely used by many threads without synchronization on the part of the caller. But if a sequence of two or more method calls need to appear atomic from other threads perspective, then the caller can synchronize on this.
Since:
0.3
Version:
1.2
See Also:

  • Field Details

    • IDENTITY

      private static final byte IDENTITY
      Comparison mode for key objects. The standard mode is EQUALS, which means that keys are compared using their Object.equals(Object) method. But WeakValueHashMap will automatically select DEEP_EQUALS if there is a chance that some keys are arrays. In the latter case, comparisons will be done by the more costly Objects.deepEquals(Object, Object) method instead.

      The IDENTITY mode is rarely used, and is selected only if the user explicitly asks for this mode at construction time. This mode is provided because reference-equality semantic is sometimes required, and hard to simulate if not supported natively by the hash map. See IdentityHashMap javadoc for some examples of cases where reference-equality semantic is useful.

      See Also:

    • EQUALS

      private static final byte EQUALS
      Comparison mode for key objects. The standard mode is EQUALS, which means that keys are compared using their Object.equals(Object) method. But WeakValueHashMap will automatically select DEEP_EQUALS if there is a chance that some keys are arrays. In the latter case, comparisons will be done by the more costly Objects.deepEquals(Object, Object) method instead.

      The IDENTITY mode is rarely used, and is selected only if the user explicitly asks for this mode at construction time. This mode is provided because reference-equality semantic is sometimes required, and hard to simulate if not supported natively by the hash map. See IdentityHashMap javadoc for some examples of cases where reference-equality semantic is useful.

      See Also:

    • DEEP_EQUALS

      private static final byte DEEP_EQUALS
      Comparison mode for key objects. The standard mode is EQUALS, which means that keys are compared using their Object.equals(Object) method. But WeakValueHashMap will automatically select DEEP_EQUALS if there is a chance that some keys are arrays. In the latter case, comparisons will be done by the more costly Objects.deepEquals(Object, Object) method instead.

      The IDENTITY mode is rarely used, and is selected only if the user explicitly asks for this mode at construction time. This mode is provided because reference-equality semantic is sometimes required, and hard to simulate if not supported natively by the hash map. See IdentityHashMap javadoc for some examples of cases where reference-equality semantic is useful.

      See Also:

    • table

      private WeakValueHashMap<K,V>.Entry[] table
      Table of weak references.

    • count

      private int count
      Number of non-null elements in table. This is used for determining when WeakEntry.rehash(WeakEntry[], int, String) needs to be invoked.

    • keyType

      private final Class<K> keyType
      The type of the keys in this map.

    • comparisonMode

      private final byte comparisonMode
      Whether keys shall be compared by reference-equality (IDENTITY), by shallow object-equality (EQUALS) or by deep object-equality (DEEP_EQUALS). The DEEP_EQUALS mode is selected only if the keys in this map may be arrays. If the keys cannot be arrays, then we select the EQUALS mode for avoiding calls to the costly Objects.deepEquals(Object, Object) method.
      See Also:

    • entrySet

      private transient Set<Map.Entry<K,V>> entrySet
      The set of entries, created only when first needed.

    • lastTimeNormalCapacity

      private transient long lastTimeNormalCapacity
      The last time when table was not in need for rehash. When the garbage collector collected a lot of elements, we will wait a few seconds before rehashing table in case lot of news entries are going to be added. Without this field, we noticed many "reduce", "expand", "reduce", "expand", etc. cycles.

  • Constructor Details

    • WeakValueHashMap

      public WeakValueHashMap(Class<K> keyType)
      Creates a new WeakValueHashMap.
      Parameters:
      keyType - the type of keys in the map.

    • WeakValueHashMap

      public WeakValueHashMap(Class<K> keyType, boolean identity)
      Creates a new WeakValueHashMap, optionally using reference-equality in place of object-equality. If identity is true, then two keys k1 and k2 are considered equal if and only if (k1 == k2) instead of if k1.equals(k2).

      Reference-equality semantic is rarely used. See the IdentityHashMap class javadoc for a discussion about drawbacks and use cases when reference-equality semantic is useful.

      Parameters:
      keyType - the type of keys in the map.
      identity - true if the map shall use reference-equality in place of object-equality when comparing keys, or false for the standard behavior.
      Since:
      0.4

  • Method Details

    • removeEntry

      private void removeEntry(WeakValueHashMap<K,V>.Entry toRemove)
      Invoked by WeakValueHashMap<K,V>.Entry when an element has been collected by the garbage collector. This method removes the weak reference from the table.
      Parameters:
      toRemove - the entry to remove from this map.

    • isValid

      @Debug final boolean isValid()
      Checks if this WeakValueHashMap is valid. This method counts the number of elements and compares it to count. This method is invoked in assertions only.
      Returns:
      whether count matches the expected value.

    • size

      public int size()
      Returns the number of key-value mappings in this map.
      Specified by:
      size in interface Map<K,V>
      Overrides:
      size in class AbstractMap<K,V>
      Returns:
      the number of entries in this map.

    • keyHashCode

      final int keyHashCode(Object key)
      Returns the hash code value for the given key.
      Parameters:
      key - the key (cannot be null).

    • keyEquals

      final boolean keyEquals(Object k1, Object k2)
      Returns true if the two given keys are equal.
      Parameters:
      k1 - the first key (cannot be null).

    • containsKey

      public boolean containsKey(Object key)
      Returns true if this map contains a mapping for the specified key. Null keys are considered never present.
      Specified by:
      containsKey in interface Map<K,V>
      Overrides:
      containsKey in class AbstractMap<K,V>
      Parameters:
      key - key whose presence in this map is to be tested.
      Returns:
      true if this map contains a mapping for the specified key.

    • containsValue

      public boolean containsValue(Object value)
      Returns true if this map maps one or more keys to this value. Null values are considered never present.
      Specified by:
      containsValue in interface Map<K,V>
      Overrides:
      containsValue in class AbstractMap<K,V>
      Parameters:
      value - value whose presence in this map is to be tested.
      Returns:
      true if this map maps one or more keys to this value.

    • get

      public V get(Object key)
      Returns the value to which this map maps the specified key. Returns null if the map contains no mapping for this key. Null keys are considered never present.
      Specified by:
      get in interface Map<K,V>
      Overrides:
      get in class AbstractMap<K,V>
      Parameters:
      key - key whose associated value is to be returned.
      Returns:
      the value to which this map maps the specified key.

    • intern

      private V intern(Object key, V value, Object condition)
      Implementation of put(Object, Object), putIfAbsent(Object, Object), remove(Object), replace(Object, Object) and replace(Object, Object, Object) operations.
      Parameters:
      key - key with which the specified value is to be associated.
      value - value to be associated with the specified key, or null for removing the entry.
      condition - previous value that entry must have for doing the action, or null if no restriction.
      Returns:
      the previous value associated with specified key, or null if there was no mapping for the key.

    • put

      public V put(K key, V value)
      Associates the specified value with the specified key in this map. The value is associated using a WeakReference.
      Specified by:
      put in interface Map<K,V>
      Overrides:
      put in class AbstractMap<K,V>
      Parameters:
      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 specified key, or null if there was no mapping for the key.
      Throws:
      NullArgumentException - if the key or the value is null.

    • putIfAbsent

      public V putIfAbsent(K key, V value)
      Associates the specified value with the specified key in this map if no value were previously associated. If another value is already associated to the given key, then the map is left unchanged and the current value is returned. Otherwise the specified value is associated to the key using a WeakReference and null is returned.
      Parameters:
      key - key with which the specified value is to be associated.
      value - value to be associated with the specified key.
      Returns:
      the current value associated with specified key, or null if there was no mapping for the key.
      Throws:
      NullArgumentException - if the key or the value is null.
      Since:
      0.7

    • replace

      public V replace(K key, V value)
      Replaces the entry for the specified key only if it is currently mapped to some value.
      Parameters:
      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 specified key, or null if there was no mapping for the key.
      Throws:
      NullArgumentException - if the value is null.
      Since:
      1.2

    • replace

      public boolean replace(K key, V oldValue, V newValue)
      Replaces the entry for the specified key only if currently mapped to the specified value.
      Parameters:
      key - key with which the specified value is to be associated.
      oldValue - value expected to be associated with the specified key.
      newValue - value to be associated with the specified key.
      Returns:
      true if the value was replaced.
      Throws:
      NullArgumentException - if the new value is null.
      Since:
      1.2

    • remove

      public V remove(Object key)
      Removes the mapping for this key from this map if present.
      Specified by:
      remove in interface Map<K,V>
      Overrides:
      remove in class AbstractMap<K,V>
      Parameters:
      key - key whose mapping is to be removed from the map.
      Returns:
      previous value associated with specified key, or null if there was no entry for the key.

    • remove

      public boolean remove(Object key, Object value)
      Removes the entry for the specified key only if it is currently mapped to the specified value.
      Parameters:
      key - key whose mapping is to be removed from the map.
      value - value expected to be associated with the specified key.
      Returns:
      true if the value was removed.
      Since:
      1.2

    • replaceOrRemove

      private boolean replaceOrRemove(Object key, Object oldValue, V newValue)
      Implementation of replace(Object, Object, Object) and remove(Object, Object). The replace action has a non-null newValue and the remove action has a null new value.

    • clear

      public void clear()
      Removes all of the elements from this map.
      Specified by:
      clear in interface Map<K,V>
      Overrides:
      clear in class AbstractMap<K,V>

    • entrySet

      public Set<Map.Entry<K,V>> entrySet()
      Returns a set view of the mappings contained in this map. Each element in this set is a Map.Entry.
      Specified by:
      entrySet in interface Map<K,V>
      Specified by:
      entrySet in class AbstractMap<K,V>
      Returns:
      a set view of the mappings contained in this map.