TypeSafeMultiMap.java

  1. /*
  2.  * *********************************************************************************************************************
  3.  *
  4.  * TheseFoolishThings: Miscellaneous utilities
  5.  * http://tidalwave.it/projects/thesefoolishthings
  6.  *
  7.  * Copyright (C) 2009 - 2023 by Tidalwave s.a.s. (http://tidalwave.it)
  8.  *
  9.  * *********************************************************************************************************************
  10.  *
  11.  * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
  12.  * the License. You may obtain a copy of the License at
  13.  *
  14.  *     http://www.apache.org/licenses/LICENSE-2.0
  15.  *
  16.  * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
  17.  * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the
  18.  * specific language governing permissions and limitations under the License.
  19.  *
  20.  * *********************************************************************************************************************
  21.  *
  22.  * git clone https://bitbucket.org/tidalwave/thesefoolishthings-src
  23.  * git clone https://github.com/tidalwave-it/thesefoolishthings-src
  24.  *
  25.  * *********************************************************************************************************************
  26.  */
  27. package it.tidalwave.util;

  28. import javax.annotation.Nonnegative;
  29. import javax.annotation.Nonnull;
  30. import java.util.Collection;
  31. import java.util.Collections;
  32. import java.util.Map;
  33. import java.util.Set;
  34. import java.util.function.BiConsumer;
  35. import it.tidalwave.util.impl.TypeSafeHashMultiMap;

  36. /***********************************************************************************************************************
  37.  *
  38.  * A map that is type safe, i.e. the pairs (key, value) are type-checked, and can contain multiple values, i.e. it's
  39.  * associated to collections (key, collection of values). It's immutable.
  40.  *
  41.  * @author  Fabrizio Giudici
  42.  *
  43.  **********************************************************************************************************************/
  44. public interface TypeSafeMultiMap extends Iterable<Map.Entry<Key<?>, Collection<?>>>
  45.   {
  46.     /*******************************************************************************************************************
  47.      *
  48.      * Returns a value given its key.
  49.      *
  50.      * @param   <T>   the type
  51.      * @param   key   the key
  52.      * @return        the value as a {@link Collection}
  53.      *
  54.      ******************************************************************************************************************/
  55.     @Nonnull
  56.     public <T> Collection<T> get (@Nonnull Key<T> key);

  57.     /*******************************************************************************************************************
  58.      *
  59.      * Checks whether a pair has been stored.
  60.      *
  61.      * @param   key   the key
  62.      * @return        {@code true} if the pair is present
  63.      *
  64.      ******************************************************************************************************************/
  65.     public boolean containsKey (@Nonnull Key<?> key);

  66.     /*******************************************************************************************************************
  67.      *
  68.      * Returns a set of all the contained keys.
  69.      *
  70.      * @return        the keys as a mutable set
  71.      *
  72.      ******************************************************************************************************************/
  73.     @Nonnull
  74.     public Set<Key<?>> keySet();

  75.     /*******************************************************************************************************************
  76.      *
  77.      * Returns a set of all the contained values.
  78.      *
  79.      * @return        the values as a mutable collection
  80.      * @since         3.2-ALPHA-6
  81.      *
  82.      ******************************************************************************************************************/
  83.     @Nonnull
  84.     public Collection<Collection<?>> values();

  85.     /*******************************************************************************************************************
  86.      *
  87.      * Returns a set of all the contained (key, value) pairs.
  88.      *
  89.      * @return        the pairs as a mutable collection
  90.      * @since         3.2-ALPHA-6
  91.      *
  92.      ******************************************************************************************************************/
  93.      @Nonnull
  94.      public Set<Map.Entry<Key<?>, Collection<?>>> entrySet();

  95.     /*******************************************************************************************************************
  96.      *
  97.      * Returns the size of this map.
  98.      *
  99.      * @return        the size
  100.      *
  101.      ******************************************************************************************************************/
  102.     @Nonnegative
  103.     public int size();

  104.     /*******************************************************************************************************************
  105.      *
  106.      * Performs the given action on all the pairs (key, value) contained in this map.
  107.      *
  108.      * @param action  the action
  109.      * @since         3.2-ALPHA-10
  110.      *
  111.      ******************************************************************************************************************/
  112.     public void forEach (@Nonnull BiConsumer<? super Key<?>, ? super Collection<?>> action);

  113.     /*******************************************************************************************************************
  114.      *
  115.      * Returns the contents as a plain {@link Map}.
  116.      *
  117.      * @return        the contents as a mutable map
  118.      *
  119.      ******************************************************************************************************************/
  120.     @Nonnull
  121.     public Map<Key<?>, Collection<?>> asMap();

  122.     /*******************************************************************************************************************
  123.      *
  124.      * Creates a new instance with an additional pair (key, value).
  125.      *
  126.      * @param   <T>   the type
  127.      * @param   key   the key
  128.      * @param   value the value
  129.      * @return        the new instance
  130.      * @since         3.2-ALPHA-2
  131.      *
  132.      ******************************************************************************************************************/
  133.     @Nonnull
  134.     public <T> TypeSafeMultiMap with (@Nonnull final Key<T> key, @Nonnull final T value);

  135.     /*******************************************************************************************************************
  136.      *
  137.      * Creates an instance cloning the given map.
  138.      *
  139.      * @param   map   the map to clone
  140.      * @return        the new instance
  141.      * @since         3.2-ALPHA-2
  142.      *
  143.      ******************************************************************************************************************/
  144.     @Nonnull
  145.     public static TypeSafeMultiMap ofCloned (@Nonnull final Map<? extends Key<?>, ? extends Collection<?>> map)
  146.       {
  147.         return new TypeSafeHashMultiMap(map);
  148.       }

  149.     /*******************************************************************************************************************
  150.      *
  151.      * Creates a new empty instance.
  152.      *
  153.      * @return        the new instance
  154.      * @since         3.2-ALPHA-2
  155.      *
  156.      ******************************************************************************************************************/
  157.     @Nonnull
  158.     public static TypeSafeMultiMap newInstance()
  159.       {
  160.         return new TypeSafeHashMultiMap(Collections.emptyMap());
  161.       }
  162.   }