Package org.apache.sis.util.collection

Class 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 Weak­Value­Hash­Map will automatically be removed when its value is no longer in ordinary use. This class is similar to the standard Weak­Hash­Map 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:

    K key = ...
V value;
synchronized (map) {
    value = map.get(key);
    if (value == null) {
        value = ...; // Create the value here.
        map.put(key, value);
    }
}
    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 Weak­Value­Hash­Map instance is not expected to be used in a highly concurrent environment.

    Weak­Value­Hash­Map 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 Weak­Value­Hash­Map 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
    See Also:
    Weak­Hash­Map, Weak­Hash­Set, Cache

    Defined in the sis-utility module

    • Constructor Detail

      • WeakValueHashMap

        public WeakValueHashMap​(Class<K> keyType)
        Creates a new Weak­Value­Hash­Map.
        Parameters:
        key­Type - the type of keys in the map.

      • WeakValueHashMap

        public WeakValueHashMap​(Class<K> keyType,
                        boolean identity)
        Creates a new Weak­Value­Hash­Map, 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 than if k1​.equals(k2).

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

        Parameters:
        key­Type - 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 Detail

      • 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 Abstract­Map<K,​V>
        Returns:
        the number of entries in this map.

      • 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:
        contains­Key in interface Map<K,​V>
        Overrides:
        contains­Key in class Abstract­Map<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:
        contains­Value in interface Map<K,​V>
        Overrides:
        contains­Value in class Abstract­Map<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 Abstract­Map<K,​V>
        Parameters:
        key - key whose associated value is to be returned.
        Returns:
        the value to which this map maps the specified key.

      • put

        public V put​(K key,
             V value)
      throws NullArgumentException
        Associates the specified value with the specified key in this map. The value is associated using a Weak­Reference.
        Specified by:
        put in interface Map<K,​V>
        Overrides:
        put in class Abstract­Map<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 key.
        Throws:
        Null­Argument­Exception - if the key or the value is null.

      • putIfAbsent

        public V putIfAbsent​(K key,
                     V value)
              throws NullArgumentException
        Associates the specified value with the specified key in this map if no value were previously associated. If an other 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 Weak­Reference 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 key.
        Throws:
        Null­Argument­Exception - if the key or the value is null.
        Since:
        0.7

      • 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 Abstract­Map<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 key.

      • clear

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