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

Interface MultiMap<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 Known Implementing Classes:
    SynchronizedMultiMap, UnsynchronizedMultiMap
    public interface MultiMap<K,​V>
    A recursive multi-dimensional map. Each MultiMap<K, V> associates keys of type K to values of type V, where V may itself be another MultiMap, enabling multi-level key hierarchies with heterogeneous key types per dimension.

    A partial lookup (stopping before the deepest level) returns a sub-map of reduced dimensionality. A complete lookup returns the terminal value.

    Example with three levels: 

    
 MultiMap<String, MultiMap<String, MultiMap<String, Integer>>> map = ...;

 // Chained write
 map.getOrCreate("France", UnsynchronizedMultiMap::new)
    .getOrCreate("Paris", UnsynchronizedMultiMap::new)
    .put("Q1", 42);

 // Chained read (nullable)
 Integer val = map.get("France").get("Paris").get("Q1");

 // Safe read
 Optional<Integer> safe = map.getOpt("France")
     .flatMap(m -> m.getOpt("Paris"))
     .flatMap(m -> m.getOpt("Q1"));

    This interface does not extend Map because the recursive semantics (partial lookups, getOrCreate) are incompatible with the full Map contract. However, the API intentionally mirrors Map where applicable.

    Null keys and null values are forbidden. Implementations must reject them with NullPointerException.

    Two implementations are provided:

    See Also:
    UnsynchronizedMultiMap, SynchronizedMultiMap

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void clear()
      Removes all mappings from this map.
      boolean containsKey​(K key)
      Returns true if this map contains a mapping for the specified key.
      Set<Map.Entry<K,​V>> entrySet()
      Returns a Set view of the mappings contained in this map.
      V get​(K key)
      Returns the value associated with the specified key, or null if no mapping exists.
      Optional<V> getOpt​(K key)
      Returns the value associated with the specified key wrapped in an Optional, or an empty Optional if no mapping exists.
      V getOrCreate​(K key, Supplier<V> factory)
      Returns the value associated with the specified key.
      boolean isEmpty()
      Returns true if this map contains no mappings.
      Set<K> keySet()
      Returns a Set view of the keys contained in this map.
      V put​(K key, V value)
      Associates the specified value with the specified key.
      V remove​(K key)
      Removes the mapping for the specified key, if present.
      int size()
      Returns the number of key-value mappings at this level.
      Collection<V> values()
      Returns a Collection view of the values contained in this map.

    • Method Detail

      • get

        V get​(K key)
        Returns the value associated with the specified key, or null if no mapping exists. This method is designed for chained lookups across multiple levels.
        Parameters:
        key - the key whose associated value is to be returned
        Returns:
        the value associated with key, or null
        Throws:
        NullPointerException - if key is null

      • getOpt

        Optional<V> getOpt​(K key)
        Returns the value associated with the specified key wrapped in an Optional, or an empty Optional if no mapping exists.
        Parameters:
        key - the key whose associated value is to be returned
        Returns:
        an Optional containing the value, or empty
        Throws:
        NullPointerException - if key is null

      • getOrCreate

        V getOrCreate​(K key,
              Supplier<V> factory)
        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.
        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
        Throws:
        NullPointerException - if key or factory is null, or if the factory returns null

      • containsKey

        boolean containsKey​(K key)
        Returns true if this map contains a mapping for the specified key.
        Parameters:
        key - the key whose presence is to be tested
        Returns:
        true if this map contains a mapping for key
        Throws:
        NullPointerException - if key is null

      • put

        V put​(K key,
      V value)
        Associates the specified value with the specified key. If a mapping already exists for this key, the old value is replaced.
        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
        Throws:
        NullPointerException - if key or value is null

      • remove

        V remove​(K key)
        Removes the mapping for the specified key, if present.
        Parameters:
        key - the key whose mapping is to be removed
        Returns:
        the previous value associated with key, or null if there was no mapping
        Throws:
        NullPointerException - if key is null

      • clear

        void clear()
        Removes all mappings from this map.

      • size

        int size()
        Returns the number of key-value mappings at this level.
        Returns:
        the number of mappings

      • isEmpty

        boolean isEmpty()
        Returns true if this map contains no mappings.
        Returns:
        true if empty

      • keySet

        Set<K> keySet()
        Returns a Set view of the keys contained in this map.
        Returns:
        a set view of the keys

      • values

        Collection<V> values()
        Returns a Collection view of the values contained in this map.
        Returns:
        a collection view of the values

      • entrySet

        Set<Map.Entry<K,​V>> entrySet()
        Returns a Set view of the mappings contained in this map. Each element is a Map.Entry<K, V>.
        Returns:
        a set view of the mappings