Package org.kiwiproject.collect

Class KiwiMaps

java.lang.Object
org.kiwiproject.collect.KiwiMaps
public final class KiwiMaps extends Object
Utility methods for working with Map instances

  • Method Summary

    Modifier and Type
    Method
    Description
    static @Nullable String
    getAsString(Map<?,?> map, Object key, @Nullable String defaultValue)
    Returns the value associated with the specified key as a String, or the provided default value if the key doesn't exist or the value is null.
    static @Nullable String
    getAsStringOrNull(Map<?,?> map, Object key)
    Returns the value associated with the specified key as a String, or null if the key doesn't exist, or the value is null.
    static <T> @Nullable T
    getConvertedValue(Map<?,?> map, Object key, Function<Object,T> converter)
    Returns the value associated with the specified key, converted using the provided converter function.
    static <T> @Nullable T
    getConvertedValueWithFallback(Map<?,?> map, Object key, Function<Object,T> converter, BiFunction<Object,Exception,T> fallbackConverter)
    Returns the value associated with the specified key, converted using the provided converter function.
    static <K, V> V
    getOrThrow(Map<K,V> map, K key)
    Returns the value to which the specified key is mapped.
    static <K, V, E extends RuntimeException>
    V
    getOrThrow(Map<K,V> map, K key, Supplier<E> exceptionSupplier)
    Returns the value to which the specified key is mapped.
    static <K, V, E extends Exception>
    V
    getOrThrowChecked(Map<K,V> map, K key, Supplier<E> exceptionSupplier)
    Returns the value to which the specified key is mapped.
    static <T> @Nullable Collection<T>
    getTypedCollection(Map<?,?> map, Object key, Class<T> valueType, @Nullable Collection<T> defaultValue)
    Returns the value associated with the specified key as a Collection of the specified type, or the provided default value if the key doesn't exist, or the value is null.
    static <T> Collection<T>
    getTypedCollectionOrEmpty(Map<?,?> map, Object key, Class<T> valueType)
    Returns the value associated with the specified key as a Collection of the specified type, or an empty Collection if the key doesn't exist, or the value is null.
    static <T> @Nullable Collection<T>
    getTypedCollectionOrNull(Map<?,?> map, Object key, Class<T> valueType)
    Returns the value associated with the specified key as a Collection of the specified type, or null if the key doesn't exist, or the value is null.
    static <T> @Nullable List<T>
    getTypedList(Map<?,?> map, Object key, Class<T> valueType, @Nullable List<T> defaultValue)
    Returns the value associated with the specified key as a List of the specified type, or the provided default value if the key doesn't exist, or the value is null.
    static <T> List<T>
    getTypedListOrEmpty(Map<?,?> map, Object key, Class<T> valueType)
    Returns the value associated with the specified key as a List of the specified type, or an empty List if the key doesn't exist, or the value is null.
    static <T> @Nullable List<T>
    getTypedListOrNull(Map<?,?> map, Object key, Class<T> valueType)
    Returns the value associated with the specified key as a List of the specified type, or null if the key doesn't exist, or the value is null.
    static <K, V> @Nullable Map<K,V>
    getTypedMap(Map<?,?> map, Object key, Class<K> keyType, Class<V> valueType, @Nullable Map<K,V> defaultValue)
    Returns the value associated with the specified key as a Map with keys and values of the specified types, or the provided default value if the key doesn't exist, or the value is null.
    static <K, V> Map<K,V>
    getTypedMapOrEmpty(Map<?,?> map, Object key, Class<K> keyType, Class<V> valueType)
    Returns the value associated with the specified key as a Map with keys and values of the specified types, or an empty Map if the key doesn't exist, or the value is null.
    static <K, V> @Nullable Map<K,V>
    getTypedMapOrNull(Map<?,?> map, Object key, Class<K> keyType, Class<V> valueType)
    Returns the value associated with the specified key as a Map with keys and values of the specified types, or null if the key doesn't exist, or the value is null.
    static <T> @Nullable Set<T>
    getTypedSet(Map<?,?> map, Object key, Class<T> valueType, @Nullable Set<T> defaultValue)
    Returns the value associated with the specified key as a Set of the specified type, or the provided default value if the key doesn't exist, or the value is null.
    static <T> Set<T>
    getTypedSetOrEmpty(Map<?,?> map, Object key, Class<T> valueType)
    Returns the value associated with the specified key as a Set of the specified type, or an empty Set if the key doesn't exist, or the value is null.
    static <T> @Nullable Set<T>
    getTypedSetOrNull(Map<?,?> map, Object key, Class<T> valueType)
    Returns the value associated with the specified key as a Set of the specified type, or null if the key doesn't exist, or the value is null.
    static <T> @Nullable T
    getTypedValue(Map<?,?> map, Object key, Class<T> valueType, @Nullable T defaultValue)
    Returns the value associated with the specified key, cast to the specified type, or the provided default value if the key doesn't exist or the value is null.
    static <T> @Nullable T
    getTypedValueOrNull(Map<?,?> map, Object key, Class<T> valueType)
    Returns the value associated with the specified key cast, to the specified type, or null if the key doesn't exist, or the value is null.
    static <K, V> boolean
    isNotNullOrEmpty(Map<K,V> map)
    Checks whether the specified map is neither null nor empty.
    static <K, V> boolean
    isNullOrEmpty(Map<K,V> map)
    Checks whether the specified map is null or empty.
    static <K, V> boolean
    keyExistsWithNonNullValue(Map<K,V> map, K key)
    Checks whether the given map contains a key whose value is not null.
    static <K, V> boolean
    keyExistsWithNullValue(Map<K,V> map, K key)
    Returns true if and only if (1) map is not null or empty, (2) map contains the given key, and (3) the value associated with the given key is null.
    static <K, V> ConcurrentMap<K,V>
    newConcurrentHashMap(Object... items)
    Creates a mutable, ConcurrentHashMap instance containing key/value pairs as parsed in pairs from the items argument.
    static <K, V> Map<K,V>
    newHashMap(Object... items)
    Creates a mutable, HashMap instance containing key/value pairs as parsed in pairs from the items argument.
    static <K, V> Map<K,V>
    newLinkedHashMap(Object... items)
    Creates a mutable, LinkedHashMap instance containing key/value pairs as parsed in pairs from the items argument.
    static <K extends Comparable<? super K>, V>
    SortedMap<K,V>
    newTreeMap(Object... items)
    Creates a mutable, TreeMap instance containing key/value pairs as parsed in pairs from the items argument.
    static <K, V> Map<K,V>
    newUnmodifiableConcurrentHashMap(Object... items)
    Creates an unmodifiable, ConcurrentHashMap instance containing key/value pairs as parsed in pairs from the items argument.
    static <K, V> Map<K,V>
    newUnmodifiableHashMap(Object... items)
    Creates an unmodifiable HashMap instance containing key/value pairs as parsed in pairs from the items argument.
    static <K, V> Map<K,V>
    newUnmodifiableLinkedHashMap(Object... items)
    Creates an unmodifiable, LinkedHashMap instance containing key/value pairs as parsed in pairs from the items argument.
    static <K extends Comparable<? super K>, V>
    SortedMap<K,V>
    newUnmodifiableTreeMap(Object... items)
    Creates an unmodifiable, TreeMap instance containing key/value pairs as parsed in pairs from the items argument.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • isNullOrEmpty

      public static <K, V> boolean isNullOrEmpty(Map<K,V> map)
      Checks whether the specified map is null or empty.
      Type Parameters:
      K - the type of the keys in the map
      V - the type of the values in the map
      Parameters:
      map - the map
      Returns:
      true if map is null or empty; false otherwise

    • isNotNullOrEmpty

      public static <K, V> boolean isNotNullOrEmpty(Map<K,V> map)
      Checks whether the specified map is neither null nor empty.
      Type Parameters:
      K - the type of the keys in the map
      V - the type of the values in the map
      Parameters:
      map - the map
      Returns:
      true if map is neither null nor empty; false otherwise

    • newUnmodifiableHashMap

      public static <K, V> Map<K,V> newUnmodifiableHashMap(Object... items)
      Creates an unmodifiable HashMap instance containing key/value pairs as parsed in pairs from the items argument. The items argument contains keys and values in the form:

      key-1, value-1, key-2, value-2, ... , key-N, value-N

      Note that trying to cast the returned value to a HashMap will result in a ClassCastException because the actual type returned by Collections.unmodifiableMap(Map) is a private class that implements Map. Since it is generally it is best to use the interface type Map this should not present a problem in most use cases.

      Unlike the factory methods in Map, null keys and values are permitted.

      Type Parameters:
      K - the type of the keys in the map
      V - the type of the values in the map
      Parameters:
      items - the items containing keys and values, in pairs
      Returns:
      a new unmodifiable HashMap with data from items
      See Also:
      Implementation Note:
      Wraps result of newHashMap(Object...) with Collections.unmodifiableMap(Map)

    • newHashMap

      public static <K, V> Map<K,V> newHashMap(Object... items)
      Creates a mutable, HashMap instance containing key/value pairs as parsed in pairs from the items argument. The items argument contains keys and values in the form:

      key-1, value-1, key-2, value-2, ... , key-N, value-N

      Type Parameters:
      K - the type of the keys in the map
      V - the type of the values in the map
      Parameters:
      items - the items containing keys and values, in pairs
      Returns:
      a new HashMap with data from items

    • newUnmodifiableLinkedHashMap

      public static <K, V> Map<K,V> newUnmodifiableLinkedHashMap(Object... items)
      Creates an unmodifiable, LinkedHashMap instance containing key/value pairs as parsed in pairs from the items argument. The items argument contains keys and values in the form:

      key-1, value-1, key-2, value-2, ... , key-N, value-N

      Note that trying to cast the returned value to a LinkedHashMap will result in a ClassCastException because the actual type returned by Collections.unmodifiableMap(Map) is a private class that implements Map. Since it is generally it is best to use the interface type Map this should not present a problem in most use cases.

      Unlike the factory methods in Map, null keys and values are permitted.

      Type Parameters:
      K - the type of the keys in the map
      V - the type of the values in the map
      Parameters:
      items - the items containing keys and values, in pairs
      Returns:
      a new unmodifiable LinkedHashMap with data from items
      See Also:
      Implementation Note:
      Wraps result of newLinkedHashMap(Object...) with Collections.unmodifiableMap(Map)

    • newLinkedHashMap

      public static <K, V> Map<K,V> newLinkedHashMap(Object... items)
      Creates a mutable, LinkedHashMap instance containing key/value pairs as parsed in pairs from the items argument. The items argument contains keys and values in the form:

      key-1, value-1, key-2, value-2, ... , key-N, value-N

      Type Parameters:
      K - the type of the keys in the map
      V - the type of the values in the map
      Parameters:
      items - the items containing keys and values, in pairs
      Returns:
      a new LinkedHashMap with data from items

    • newUnmodifiableTreeMap

      public static <K extends Comparable<? super K>, V> SortedMap<K,V> newUnmodifiableTreeMap(Object... items)
      Creates an unmodifiable, TreeMap instance containing key/value pairs as parsed in pairs from the items argument. The items argument contains keys and values in the form:

      key-1, value-1, key-2, value-2, ... , key-N, value-N

      Note that trying to cast the returned value to a TreeMap will result in a ClassCastException because the actual type returned by Collections.unmodifiableMap(Map) is a private class that implements Map. Since it is generally it is best to use the interface type Map this should not present a problem in most use cases.

      Like the factory methods in Map, null keys and values are not permitted.

      Type Parameters:
      K - the type of the keys in the map
      V - the type of the values in the map
      Parameters:
      items - the items containing keys and values, in pairs
      Returns:
      a new unmodifiable TreeMap with data from items
      See Also:
      Implementation Note:
      Wraps result of newTreeMap(Object...) with Collections.unmodifiableMap(Map)

    • newTreeMap

      public static <K extends Comparable<? super K>, V> SortedMap<K,V> newTreeMap(Object... items)
      Creates a mutable, TreeMap instance containing key/value pairs as parsed in pairs from the items argument. The items argument contains keys and values in the form:

      key-1, value-1, key-2, value-2, ... , key-N, value-N

      Type Parameters:
      K - the type of the keys in the map
      V - the type of the values in the map
      Parameters:
      items - the items containing keys and values, in pairs
      Returns:
      a new TreeMap with data from items

    • newUnmodifiableConcurrentHashMap

      public static <K, V> Map<K,V> newUnmodifiableConcurrentHashMap(Object... items)
      Creates an unmodifiable, ConcurrentHashMap instance containing key/value pairs as parsed in pairs from the items argument. The items argument contains keys and values in the form:

      key-1, value-1, key-2, value-2, ... , key-N, value-N

      Note that, unlike newConcurrentHashMap(Object...), this method has a return type of Map. This is because Collections.unmodifiableMap(Map) returns Map and trying to cast the returned instance to a ConcurrentMap results in a ClassCastException. Since it is generally it is best to use the interface type Map this should not present a problem in most use cases.

      Like the factory methods in Map, null keys and values are not permitted.

      Type Parameters:
      K - the type of the keys in the map
      V - the type of the values in the map
      Parameters:
      items - the items containing keys and values, in pairs
      Returns:
      a new unmodifiable ConcurrentHashMap with data from items
      See Also:
      Implementation Note:
      Wraps result of newConcurrentHashMap(Object...) with Collections.unmodifiableMap(Map)

    • newConcurrentHashMap

      public static <K, V> ConcurrentMap<K,V> newConcurrentHashMap(Object... items)
      Creates a mutable, ConcurrentHashMap instance containing key/value pairs as parsed in pairs from the items argument. The items argument contains keys and values in the form:

      key-1, value-1, key-2, value-2, ... , key-N, value-N

      Type Parameters:
      K - the type of the keys in the map
      V - the type of the values in the map
      Parameters:
      items - the items containing keys and values, in pairs
      Returns:
      a new ConcurrentHashMap with data from items

    • keyExistsWithNullValue

      public static <K, V> boolean keyExistsWithNullValue(Map<K,V> map, K key)
      Returns true if and only if (1) map is not null or empty, (2) map contains the given key, and (3) the value associated with the given key is null.
      Type Parameters:
      K - the type of the keys in the map
      V - the type of the values in the map
      Parameters:
      map - the map
      key - the key to check
      Returns:
      true if and only if (1) map is not null or empty, (2) map contains the given key, and (3) the value associated with the given key is null

    • keyExistsWithNonNullValue

      public static <K, V> boolean keyExistsWithNonNullValue(Map<K,V> map, K key)
      Checks whether the given map contains a key whose value is not null.
      Type Parameters:
      K - the type of the keys in the map
      V - the type of the values in the map
      Parameters:
      map - the map
      key - the key to check
      Returns:
      true if and only if (1) map is not null or empty, (2) map contains the given key, and (3) the value associated with the given key is not null

    • getOrThrow

      public static <K, V> V getOrThrow(Map<K,V> map, K key)
      Returns the value to which the specified key is mapped.

      If the map is null or empty, or it does not contain the specified key, or the value associated with the key is null, a NoSuchElementException is thrown.

      Type Parameters:
      K - the type of the keys in the map
      V - the type of the values in the map
      Parameters:
      map - the map
      key - the key whose associated value is to be returned
      Returns:
      the value to which the specified key is mapped
      Throws:
      IllegalArgumentException - if either argument is null
      NoSuchElementException - if the map is null or empty, does not contain the specified key, or the value associated with the key is null

    • getOrThrow

      public static <K, V, E extends RuntimeException> V getOrThrow(Map<K,V> map, K key, Supplier<E> exceptionSupplier)
      Returns the value to which the specified key is mapped.

      If the map is null or empty, or it does not contain the specified key, or the value associated with the key is null, the exception provided by the given Supplier is thrown.

      Type Parameters:
      K - the type of the keys in the map
      V - the type of the values in the map
      E - the type of RuntimeException
      Parameters:
      map - the map
      key - the key whose associated value is to be returned
      exceptionSupplier - supplies a RuntimeException when there is no value to return
      Returns:
      the value to which the specified key is mapped
      Throws:
      IllegalArgumentException - if any of the arguments is null
      E - if the map is null or empty, does not contain the specified key, or the value associated with the key is null

    • getOrThrowChecked

      public static <K, V, E extends Exception> V getOrThrowChecked(Map<K,V> map, K key, Supplier<E> exceptionSupplier) throws E
      Returns the value to which the specified key is mapped.

      If the map is null or empty, or it does not contain the specified key, or the value associated with the key is null, the exception provided by the given Supplier is thrown.

      Type Parameters:
      K - the type of the keys in the map
      V - the type of the values in the map
      E - the type of Exception
      Parameters:
      map - the map
      key - the key whose associated value is to be returned
      exceptionSupplier - supplies an Exception when there is no value to return
      Returns:
      the value to which the specified key is mapped
      Throws:
      IllegalArgumentException - if any of the arguments is null
      E - if the map is null or empty, does not contain the specified key, or the value associated with the key is null

    • getAsStringOrNull

      public static @Nullable String getAsStringOrNull(Map<?,?> map, Object key)
      Returns the value associated with the specified key as a String, or null if the key doesn't exist, or the value is null.

      If the (non-null) value is not a String, it is converted using Object.toString().

      Parameters:
      map - the map
      key - the key whose associated value is to be returned as a String
      Returns:
      the value associated with the key as a String, or null if the key doesn't exist or the value is null

    • getAsString

      public static @Nullable String getAsString(Map<?,?> map, Object key, @Nullable String defaultValue)
      Returns the value associated with the specified key as a String, or the provided default value if the key doesn't exist or the value is null.

      If the (non-null) value is not a String, it is converted using Object.toString().

      Parameters:
      map - the map
      key - the key whose associated value is to be returned as a String
      defaultValue - the default value to return if the key doesn't exist or the value is null
      Returns:
      the value associated with the key as a String, or the default value if the key doesn't exist or the value is null

    • getTypedValueOrNull

      public static <T> @Nullable T getTypedValueOrNull(Map<?,?> map, Object key, Class<T> valueType)
      Returns the value associated with the specified key cast, to the specified type, or null if the key doesn't exist, or the value is null.
      Type Parameters:
      T - the type of the value to be returned
      Parameters:
      map - the map
      key - the key whose associated value is to be returned
      valueType - the class representing the type to cast the value to
      Returns:
      the value associated with the key, cast to the specified type, or null if the key doesn't exist or the value is null
      Throws:
      MapTypeMismatchException - if the value cannot be cast to the specified type

    • getTypedValue

      public static <T> @Nullable T getTypedValue(Map<?,?> map, Object key, Class<T> valueType, @Nullable T defaultValue)
      Returns the value associated with the specified key, cast to the specified type, or the provided default value if the key doesn't exist or the value is null.
      Type Parameters:
      T - the type of the value to be returned
      Parameters:
      map - the map
      key - the key whose associated value is to be returned
      valueType - the class representing the type to cast the value to
      defaultValue - the default value to return if the key doesn't exist or the value is null
      Returns:
      the value associated with the key, cast to the specified type, or the default value if the key doesn't exist or the value is null
      Throws:
      IllegalArgumentException - if the map, key, or valueType is null
      MapTypeMismatchException - if the value cannot be cast to the specified type

    • getTypedCollectionOrNull

      public static <T> @Nullable Collection<T> getTypedCollectionOrNull(Map<?,?> map, Object key, Class<T> valueType)
      Returns the value associated with the specified key as a Collection of the specified type, or null if the key doesn't exist, or the value is null.
      Type Parameters:
      T - the type of elements in the collection
      Parameters:
      map - the map
      key - the key whose associated value is to be returned
      valueType - the class representing the type of elements in the collection
      Returns:
      the value associated with the key as a Collection of the specified type, or null if the key doesn't exist or the value is null
      Throws:
      IllegalArgumentException - if the map, key, or valueType is null
      MapTypeMismatchException - if the value cannot be cast to a Collection
      Implementation Note:
      see implementation note in getTypedCollection(Map, Object, Class, Collection)

    • getTypedCollectionOrEmpty

      public static <T> Collection<T> getTypedCollectionOrEmpty(Map<?,?> map, Object key, Class<T> valueType)
      Returns the value associated with the specified key as a Collection of the specified type, or an empty Collection if the key doesn't exist, or the value is null.
      Type Parameters:
      T - the type of elements in the collection
      Parameters:
      map - the map
      key - the key whose associated value is to be returned
      valueType - the class representing the type of elements in the collection
      Returns:
      the value associated with the key as a Collection of the specified type, or an empty Collection if the key doesn't exist or the value is null
      Throws:
      IllegalArgumentException - if the map, key, or valueType is null
      MapTypeMismatchException - if the value cannot be cast to a Collection
      Implementation Note:
      see implementation note in getTypedCollection(Map, Object, Class, Collection)

    • getTypedCollection

      public static <T> @Nullable Collection<T> getTypedCollection(Map<?,?> map, Object key, Class<T> valueType, @Nullable Collection<T> defaultValue)
      Returns the value associated with the specified key as a Collection of the specified type, or the provided default value if the key doesn't exist, or the value is null.
      Type Parameters:
      T - the type of elements in the collection
      Parameters:
      map - the map
      key - the key whose associated value is to be returned
      valueType - the class representing the type of elements in the collection
      defaultValue - the default value to return if the key doesn't exist or the value is null
      Returns:
      the value associated with the key as a Collection of the specified type, or the default value if the key doesn't exist or the value is null
      Throws:
      IllegalArgumentException - if the map, key, or valueType is null
      MapTypeMismatchException - if the value cannot be cast to a Collection
      Implementation Note:
      Internally this performs an unchecked cast of the value to Collection<T>. If the values in the collection are not actually of type T, a ClassCastException will be thrown when the collection is accessed, which may be downstream from the original call site and therefore be challenging to diagnose the root cause.

    • getTypedListOrNull

      public static <T> @Nullable List<T> getTypedListOrNull(Map<?,?> map, Object key, Class<T> valueType)
      Returns the value associated with the specified key as a List of the specified type, or null if the key doesn't exist, or the value is null.
      Type Parameters:
      T - the type of elements in the list
      Parameters:
      map - the map
      key - the key whose associated value is to be returned
      valueType - the class representing the type of elements in the list
      Returns:
      the value associated with the key as a List of the specified type, or null if the key doesn't exist or the value is null
      Throws:
      IllegalArgumentException - if the map, key, or valueType is null
      MapTypeMismatchException - if the value cannot be cast to a List
      Implementation Note:
      see implementation note in getTypedList(Map, Object, Class, List)

    • getTypedListOrEmpty

      public static <T> List<T> getTypedListOrEmpty(Map<?,?> map, Object key, Class<T> valueType)
      Returns the value associated with the specified key as a List of the specified type, or an empty List if the key doesn't exist, or the value is null.
      Type Parameters:
      T - the type of elements in the list
      Parameters:
      map - the map
      key - the key whose associated value is to be returned
      valueType - the class representing the type of elements in the list
      Returns:
      the value associated with the key as a List of the specified type, or an empty List if the key doesn't exist or the value is null
      Throws:
      IllegalArgumentException - if the map, key, or valueType is null
      MapTypeMismatchException - if the value cannot be cast to a List
      Implementation Note:
      see implementation note in getTypedList(Map, Object, Class, List)

    • getTypedList

      public static <T> @Nullable List<T> getTypedList(Map<?,?> map, Object key, Class<T> valueType, @Nullable List<T> defaultValue)
      Returns the value associated with the specified key as a List of the specified type, or the provided default value if the key doesn't exist, or the value is null.
      Type Parameters:
      T - the type of elements in the list
      Parameters:
      map - the map
      key - the key whose associated value is to be returned
      valueType - the class representing the type of elements in the list
      defaultValue - the default value to return if the key doesn't exist or the value is null
      Returns:
      the value associated with the key as a List of the specified type, or the default value if the key doesn't exist or the value is null
      Throws:
      IllegalArgumentException - if the map, key, or valueType is null
      MapTypeMismatchException - if the value cannot be cast to a List
      Implementation Note:
      Internally this performs an unchecked cast of the value to List<T>. If the values in the list are not actually of type T, a ClassCastException will be thrown when the list is accessed, which may be downstream from the original call site and therefore be challenging to diagnose the root cause.

    • getTypedSetOrNull

      public static <T> @Nullable Set<T> getTypedSetOrNull(Map<?,?> map, Object key, Class<T> valueType)
      Returns the value associated with the specified key as a Set of the specified type, or null if the key doesn't exist, or the value is null.
      Type Parameters:
      T - the type of elements in the set
      Parameters:
      map - the map
      key - the key whose associated value is to be returned
      valueType - the class representing the type of elements in the set
      Returns:
      the value associated with the key as a Set of the specified type, or null if the key doesn't exist or the value is null
      Throws:
      IllegalArgumentException - if the map, key, or valueType is null
      MapTypeMismatchException - if the value cannot be cast to a Set
      Implementation Note:
      see implementation note in getTypedSet(Map, Object, Class, Set)

    • getTypedSetOrEmpty

      public static <T> Set<T> getTypedSetOrEmpty(Map<?,?> map, Object key, Class<T> valueType)
      Returns the value associated with the specified key as a Set of the specified type, or an empty Set if the key doesn't exist, or the value is null.
      Type Parameters:
      T - the type of elements in the set
      Parameters:
      map - the map
      key - the key whose associated value is to be returned
      valueType - the class representing the type of elements in the set
      Returns:
      the value associated with the key as a Set of the specified type, or an empty Set if the key doesn't exist or the value is null
      Throws:
      IllegalArgumentException - if the map, key, or valueType is null
      MapTypeMismatchException - if the value cannot be cast to a Set
      Implementation Note:
      see implementation note in getTypedSet(Map, Object, Class, Set)

    • getTypedSet

      public static <T> @Nullable Set<T> getTypedSet(Map<?,?> map, Object key, Class<T> valueType, @Nullable Set<T> defaultValue)
      Returns the value associated with the specified key as a Set of the specified type, or the provided default value if the key doesn't exist, or the value is null.
      Type Parameters:
      T - the type of elements in the set
      Parameters:
      map - the map
      key - the key whose associated value is to be returned
      valueType - the class representing the type of elements in the set
      defaultValue - the default value to return if the key doesn't exist or the value is null
      Returns:
      the value associated with the key as a Set of the specified type, or the default value if the key doesn't exist or the value is null
      Throws:
      IllegalArgumentException - if the map, key, or valueType is null
      MapTypeMismatchException - if the value cannot be cast to a Set
      Implementation Note:
      Internally this performs an unchecked cast of the value to Set<T>. If the values in the list are not actually of type T, a ClassCastException will be thrown when the set is accessed, which may be downstream from the original call site and therefore be challenging to diagnose the root cause.

    • getTypedMapOrNull

      public static <K, V> @Nullable Map<K,V> getTypedMapOrNull(Map<?,?> map, Object key, Class<K> keyType, Class<V> valueType)
      Returns the value associated with the specified key as a Map with keys and values of the specified types, or null if the key doesn't exist, or the value is null.
      Type Parameters:
      K - the type of keys in the returned map
      V - the type of values in the returned map
      Parameters:
      map - the map
      key - the key whose associated value is to be returned
      keyType - the class representing the type of keys in the returned map
      valueType - the class representing the type of values in the returned map
      Returns:
      the value associated with the key as a Map with the specified key and value types, or null if the key doesn't exist or the value is null
      Throws:
      IllegalArgumentException - if the map, key, keyType, or valueType is null
      MapTypeMismatchException - if the value cannot be cast to a Map
      Implementation Note:
      see implementation note in getTypedMap(Map, Object, Class, Class, Map)

    • getTypedMapOrEmpty

      public static <K, V> Map<K,V> getTypedMapOrEmpty(Map<?,?> map, Object key, Class<K> keyType, Class<V> valueType)
      Returns the value associated with the specified key as a Map with keys and values of the specified types, or an empty Map if the key doesn't exist, or the value is null.
      Type Parameters:
      K - the type of keys in the returned map
      V - the type of values in the returned map
      Parameters:
      map - the map
      key - the key whose associated value is to be returned
      keyType - the class representing the type of keys in the returned map
      valueType - the class representing the type of values in the returned map
      Returns:
      the value associated with the key as a Map with the specified key and value types, or an empty Map if the key doesn't exist or the value is null
      Throws:
      IllegalArgumentException - if the map, key, keyType, or valueType is null
      MapTypeMismatchException - if the value cannot be cast to a Map
      Implementation Note:
      see implementation note in getTypedMap(Map, Object, Class, Class, Map)

    • getTypedMap

      public static <K, V> @Nullable Map<K,V> getTypedMap(Map<?,?> map, Object key, Class<K> keyType, Class<V> valueType, @Nullable Map<K,V> defaultValue)
      Returns the value associated with the specified key as a Map with keys and values of the specified types, or the provided default value if the key doesn't exist, or the value is null.
      Type Parameters:
      K - the type of keys in the returned map
      V - the type of values in the returned map
      Parameters:
      map - the map
      key - the key whose associated value is to be returned
      keyType - the class representing the type of keys in the returned map
      valueType - the class representing the type of values in the returned map
      defaultValue - the default value to return if the key doesn't exist or the value is null
      Returns:
      the value associated with the key as a Map with the specified key and value types, or the default value if the key doesn't exist or the value is null
      Throws:
      IllegalArgumentException - if the map, key, keyType, or valueType is null
      MapTypeMismatchException - if the value cannot be cast to a Map
      Implementation Note:
      Internally this performs an unchecked cast of the value to Map<K, V>. If the keys and values in the map are not actually of type K and V, respectively, a ClassCastException will be thrown when the map is accessed, which may be downstream from the original call site and therefore be challenging to diagnose the root cause.

    • getConvertedValue

      @Beta public static <T> @Nullable T getConvertedValue(Map<?,?> map, Object key, Function<Object,T> converter)
      Returns the value associated with the specified key, converted using the provided converter function.

      This method is marked as Beta and may change in future releases.

      Type Parameters:
      T - the type of the value to be returned
      Parameters:
      map - the map
      key - the key whose associated value is to be returned
      converter - a function that converts the value to the desired type
      Returns:
      the value associated with the key, converted using the provided converter function
      Throws:
      IllegalArgumentException - if the map, key, or converter is null

    • getConvertedValueWithFallback

      @Beta public static <T> @Nullable T getConvertedValueWithFallback(Map<?,?> map, Object key, Function<Object,T> converter, BiFunction<Object,Exception,T> fallbackConverter)
      Returns the value associated with the specified key, converted using the provided converter function. If the conversion fails with an exception, the fallback converter is used to provide an alternative value.

      This method is marked as Beta and may change in future releases.

      Type Parameters:
      T - the type of the value to be returned
      Parameters:
      map - the map
      key - the key whose associated value is to be returned
      converter - a function that converts the value to the desired type
      fallbackConverter - a function that provides a fallback value when the primary converter throws an exception
      Returns:
      the value associated with the key, converted using the provided converter function, or the result of the fallback converter if the primary conversion fails
      Throws:
      IllegalArgumentException - if the map, key, converter, or fallbackConverter is null