Module fr.dufrenoy.util
Package fr.dufrenoy.util

Class SynchronizedMultiMap<K,​V>

  • Type Parameters:
    K - the type of keys at this level
    V - the type of values at this level (may be another MultiMap)
    All Implemented Interfaces:
    MultiMap<K,​V>, Serializable
    public class SynchronizedMultiMap<K,​V>
extends Object
implements MultiMap<K,​V>, Serializable
    A thread-safe implementation of MultiMap, backed by an UnsynchronizedMultiMap and protected by a ReentrantReadWriteLock.

    Multiple threads may read concurrently. Write operations are exclusive: a write blocks until all ongoing reads have completed, and blocks any new reads until the write is done.

    The iterators returned by the views of this map (keySet(), values(), entrySet()) are fail-safe: they operate on a snapshot of the map taken at the time of the call, under a read lock. Subsequent modifications to the map are not reflected in the snapshot.

    Atomicity note: each operation is atomic at the current level only. In a recursive multi-level structure, operations on sub-maps are independent — there is no cross-level locking. Callers requiring atomicity across multiple levels must provide their own synchronization.

    Memory note: snapshot-based iterators copy the entire entry set at the time of the call. Avoid iterating over very large maps in memory-constrained environments.

    Null keys and null values are forbidden. All methods that accept keys or values throw NullPointerException if a null argument is passed.

    See Also:
    MultiMap, UnsynchronizedMultiMap, Serialized Form

    • Constructor Summary

      Constructors 
      Constructor Description
      SynchronizedMultiMap()
      Creates a new empty SynchronizedMultiMap with default initial capacity.
      SynchronizedMultiMap​(int initialCapacity)
      Creates a new empty SynchronizedMultiMap with the specified initial capacity.
      SynchronizedMultiMap​(MultiMap<? extends K,​? extends V> source)
      Creates a new SynchronizedMultiMap containing the same mappings as the specified MultiMap.
      SynchronizedMultiMap​(Map<? extends K,​? extends V> source)
      Creates a new SynchronizedMultiMap containing the same mappings as the specified map.

    • Constructor Detail

      • SynchronizedMultiMap

        public SynchronizedMultiMap()
        Creates a new empty SynchronizedMultiMap with default initial capacity.

      • SynchronizedMultiMap

        public SynchronizedMultiMap​(int initialCapacity)
        Creates a new empty SynchronizedMultiMap with the specified initial capacity.
        Parameters:
        initialCapacity - the initial capacity
        Throws:
        IllegalArgumentException - if initialCapacity is negative

      • SynchronizedMultiMap

        public SynchronizedMultiMap​(Map<? extends K,​? extends V> source)
        Creates a new SynchronizedMultiMap containing the same mappings as the specified map. Null keys and null values in the source map cause a NullPointerException.
        Parameters:
        source - the map whose mappings are to be copied
        Throws:
        NullPointerException - if source is null, or if it contains null keys or null values

      • SynchronizedMultiMap

        public SynchronizedMultiMap​(MultiMap<? extends K,​? extends V> source)
        Creates a new SynchronizedMultiMap containing the same mappings as the specified MultiMap.
        Parameters:
        source - the multi-map whose mappings are to be copied
        Throws:
        NullPointerException - if source is null

    • Method Detail

      • get

        public V get​(K key)
        Description copied from interface: MultiMap
        Returns the value associated with the specified key, or null if no mapping exists. This method is designed for chained lookups across multiple levels.
        Specified by:
        get in interface MultiMap<K,​V>
        Parameters:
        key - the key whose associated value is to be returned
        Returns:
        the value associated with key, or null

      • getOpt

        public Optional<V> getOpt​(K key)
        Description copied from interface: MultiMap
        Returns the value associated with the specified key wrapped in an Optional, or an empty Optional if no mapping exists.
        Specified by:
        getOpt in interface MultiMap<K,​V>
        Parameters:
        key - the key whose associated value is to be returned
        Returns:
        an Optional containing the value, or empty

      • getOrCreate

        public V getOrCreate​(K key,
                     Supplier<V> factory)
        Description copied from interface: MultiMap
        Returns the value associated with the specified key. If no mapping exists, creates one using the given factory, inserts it, and returns the new value. This method is designed for chained writes across multiple levels.
        Specified by:
        getOrCreate in interface MultiMap<K,​V>
        Parameters:
        key - the key whose associated value is to be returned or created
        factory - the supplier used to create a new value if absent
        Returns:
        the existing or newly created value

      • containsKey

        public boolean containsKey​(K key)
        Description copied from interface: MultiMap
        Returns true if this map contains a mapping for the specified key.
        Specified by:
        containsKey in interface MultiMap<K,​V>
        Parameters:
        key - the key whose presence is to be tested
        Returns:
        true if this map contains a mapping for key

      • put

        public V put​(K key,
             V value)
        Description copied from interface: MultiMap
        Associates the specified value with the specified key. If a mapping already exists for this key, the old value is replaced.
        Specified by:
        put in interface MultiMap<K,​V>
        Parameters:
        key - the key with which the value is to be associated
        value - the value to associate
        Returns:
        the previous value associated with key, or null if there was no mapping

      • remove

        public V remove​(K key)
        Description copied from interface: MultiMap
        Removes the mapping for the specified key, if present.
        Specified by:
        remove in interface MultiMap<K,​V>
        Parameters:
        key - the key whose mapping is to be removed
        Returns:
        the previous value associated with key, or null if there was no mapping

      • clear

        public void clear()
        Description copied from interface: MultiMap
        Removes all mappings from this map.
        Specified by:
        clear in interface MultiMap<K,​V>

      • size

        public int size()
        Description copied from interface: MultiMap
        Returns the number of key-value mappings at this level.
        Specified by:
        size in interface MultiMap<K,​V>
        Returns:
        the number of mappings

      • isEmpty

        public boolean isEmpty()
        Description copied from interface: MultiMap
        Returns true if this map contains no mappings.
        Specified by:
        isEmpty in interface MultiMap<K,​V>
        Returns:
        true if empty

      • keySet

        public Set<K> keySet()
        Description copied from interface: MultiMap
        Returns a Set view of the keys contained in this map.
        Specified by:
        keySet in interface MultiMap<K,​V>
        Returns:
        a set view of the keys

      • values

        public Collection<V> values()
        Description copied from interface: MultiMap
        Returns a Collection view of the values contained in this map.
        Specified by:
        values in interface MultiMap<K,​V>
        Returns:
        a collection view of the values

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object