TypeSafeMap.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 javax.annotation.concurrent.Immutable;
  31. import java.util.Collection;
  32. import java.util.Collections;
  33. import java.util.Map;
  34. import java.util.Optional;
  35. import java.util.Set;
  36. import java.util.function.BiConsumer;
  37. import it.tidalwave.util.impl.TypeSafeHashMap;

  38. /***********************************************************************************************************************
  39.  *
  40.  * A map that is type safe, i.e. the pairs (key, value) are type-checked. It's immutable.
  41.  *
  42.  * @author  Fabrizio Giudici
  43.  *
  44.  **********************************************************************************************************************/
  45. @Immutable
  46. public interface TypeSafeMap extends Iterable<Map.Entry<Key<?>, Object>>
  47.   {
  48.     /*******************************************************************************************************************
  49.      *
  50.      * Returns a value given its key.
  51.      *
  52.      * @param   <T>   the type
  53.      * @param   key   the key
  54.      * @return        the value
  55.      * @throws        NotFoundException if the key is not found
  56.      * @deprecated    Use {@link #getOptional(Key)} instead
  57.      *
  58.      ******************************************************************************************************************/
  59.     @Nonnull @Deprecated
  60.     public <T> T get (@Nonnull Key<T> key)
  61.       throws NotFoundException;

  62.     /*******************************************************************************************************************
  63.      *
  64.      * Returns an optional value given its key.
  65.      *
  66.      * @param   <T>   the type
  67.      * @param   key   the key
  68.      * @return        the value
  69.      *
  70.      * @since 3.2-ALPHA-1
  71.      *
  72.      ******************************************************************************************************************/
  73.     @Nonnull
  74.     public default <T> Optional<T> getOptional (@Nonnull final Key<? extends T> key)
  75.       {
  76.         try
  77.           {
  78.             return Optional.of(get(key));
  79.           }
  80.         catch (NotFoundException e)
  81.           {
  82.             return Optional.empty();
  83.           }
  84.       }

  85.     /*******************************************************************************************************************
  86.      *
  87.      * Checks whether a pair has been stored.
  88.      *
  89.      * @param   key   the key
  90.      * @return        {@code true} if the pair is present
  91.      *
  92.      ******************************************************************************************************************/
  93.     public boolean containsKey (@Nonnull Key<?> key);

  94.     /*******************************************************************************************************************
  95.      *
  96.      * Returns a set of all the contained keys.
  97.      *
  98.      * @return  the keys as a mutable set
  99.      *
  100.      ******************************************************************************************************************/
  101.     @Nonnull
  102.     public Set<Key<?>> keySet();

  103.     /*******************************************************************************************************************
  104.      *
  105.      * Returns a set of all the contained values.
  106.      *
  107.      * @return  the values as a mutable collection
  108.      * @since   3.2-ALPHA-6
  109.      *
  110.      ******************************************************************************************************************/
  111.     @Nonnull
  112.     public Collection<Object> values();

  113.     /*******************************************************************************************************************
  114.      *
  115.      * Returns a set of all the contained (key, value) pairs.
  116.      *
  117.      * @return  the pairs as a mutable collection
  118.      * @since   3.2-ALPHA-6
  119.      *
  120.      ******************************************************************************************************************/
  121.     @Nonnull
  122.     public Set<Map.Entry<Key<?>, Object>> entrySet();

  123.     /*******************************************************************************************************************
  124.      *
  125.      * Returns the size of this map.
  126.      *
  127.      * @return    the size
  128.      *
  129.      ******************************************************************************************************************/
  130.     @Nonnegative
  131.     public int size();

  132.     /*******************************************************************************************************************
  133.      *
  134.      * Returns the contents as a plain {@link Map}.
  135.      *
  136.      * @return        the contents as a mutable map
  137.      *
  138.      ******************************************************************************************************************/
  139.     @Nonnull
  140.     public Map<Key<?>, Object> asMap();

  141.     /*******************************************************************************************************************
  142.      *
  143.      * Performs the given action on all the pairs (key, value) contained in this map.
  144.      *
  145.      * @param action  the action
  146.      * @since         3.2-ALPHA-10
  147.      *
  148.      ******************************************************************************************************************/
  149.     public void forEach (@Nonnull BiConsumer<? super Key<?>, ? super Object> action);

  150.     /*******************************************************************************************************************
  151.      *
  152.      * Create a new instance with an additional pair (key, value=
  153.      *
  154.      * @param   <T>   the type
  155.      * @param   key   the key
  156.      * @param   value the value
  157.      * @return        the new instance
  158.      * @since         3.2-ALPHA-2
  159.      *
  160.      ******************************************************************************************************************/
  161.     @Nonnull
  162.     public <T> TypeSafeMap with (@Nonnull final Key<T> key, @Nonnull final T value);

  163.     /*******************************************************************************************************************
  164.      *
  165.      * Creates a new empty instance.
  166.      *
  167.      * @return        the new instance
  168.      * @since         3.2-ALPHA-2
  169.      *
  170.      ******************************************************************************************************************/
  171.     @Nonnull
  172.     public static TypeSafeMap newInstance()
  173.       {
  174.         return new TypeSafeHashMap(Collections.emptyMap());
  175.       }

  176.     /*******************************************************************************************************************
  177.      *
  178.      * Creates an instance cloning the given map.
  179.      *
  180.      * @param   map   the map to clone
  181.      * @return        the new instance
  182.      * @since         3.2-ALPHA-2
  183.      *
  184.      ******************************************************************************************************************/
  185.     @Nonnull
  186.     public static TypeSafeMap ofCloned (@Nonnull final Map<? extends Key<?>, Object> map)
  187.       {
  188.         return new TypeSafeHashMap(map);
  189.       }
  190.   }