de.ipcon.tools

Class MapTools

java.lang.Object

de.ipcon.tools.MapTools

public final class MapTools
extends java.lang.Object

Utility class providing static methods for working with Maps.

Constructor Summary

Constructors

Constructor and Description
MapTools()

Method Summary

Modifier and Type	Method and Description
static <K,V,C extends java.util.Collection<V>> void	addToValueCollection(java.util.Map<K,C> map, K key, V value, java.util.function.Supplier<C> colletionCreator) Adds the given value into the collection stored in the map for the given key.
static <K,V> void	addToValueList(java.util.Map<K,java.util.List<V>> map, K key, V value)
static <K,V> void	addToValueSet(java.util.Map<K,java.util.Set<V>> map, K key, V value)
static <K,V> java.util.Map<K,V>	asImmutable(java.util.Map<K,V> map) Returns an unmodifiable version of the passed Map, or the empty Map for a passed null or empty map.
static <K,V> java.util.List<java.util.Map<K,V>>	collateMap(java.util.Map<K,V> map, int size) Breaks a given map into a list of smaller maps, each containing at most the specified number of entries.
static <K,V> java.util.Map<K,V>	createCopy(java.util.Map<K,V> map) Creates a shallow copy of the given Map.
static <K,V> java.util.Map<K,V>	elvis(java.util.Map<K,V>[] maps, boolean fallBackToEmptyMap) "elvis operator" for Maps
static <K,V> java.util.Map<K,V>	elvis(java.util.Map<K,V>[] maps, java.util.function.Supplier<? extends java.util.Map<K,V>> emptyMapCreator) "elvis operator" for Maps
static <K,V> java.util.Map<K,V>	fillMap(java.util.Map<K,V> map, K[] keyArray, V[] valueArray) Fills a passed map using two arrays.
static <K,V> java.util.Map<K,V>	fillMap(java.util.Map<K,V> map, java.lang.Object[] array) Fills a passed map using an array representing keys and values in various possible styles.
static <K,V> java.util.Map<K,V>	fillMap(java.lang.Object[] array, java.util.Map<K,V> map) Fills a passed map using an array representing keys and values in various possible styles.
static <R> R	find(java.lang.Class<R> needle, java.util.Map<?,?> haystack) Returns the first value in the passed Map that is of the passed Class.
static <K,V> java.util.Map<K,V>	findAll(java.lang.Class<?> needle, java.util.Map<K,V> haystack) Returns a map with entries of the passed Map, where the value is of the passed Class.
static <K,V> V	firstValue(java.util.Map<K,V> map) Returns the first Map.Entry's (as determined by the default iterator) value or null if the map is empty.
static <K,V> java.util.Map.Entry<K,V>	getOnlyEntry(java.util.Map<K,V> map) Returns the single key contained in Map.
static <K,V> K	getOnlyKey(java.util.Map<K,V> map) Returns the single key contained in Map.
static <K,V> V	getOnlyValue(java.util.Map<K,V> map) Returns the single value contained in Map.
static boolean	isEmpty(java.util.Map<?,?> map)
static boolean	isEmpty(java.util.Map<?,?> map, boolean lazyEvaluationIfPossible) Returns true if the passed Map is null or empty, using the lazy variant if it is a LazyMapI, so that no unlazy will be triggered by this method.
static boolean	isOneOfClass(java.lang.Class<?> needle, java.util.Map<?,?> haystack) Returns true if one of the values in the passed Map is of the passed Class.
static <K extends java.lang.Comparable<? super K>,V> java.util.Map<K,V>	mergeMaps(java.util.Collection<java.util.Map<K,V>> ms, boolean unmodifiable) Null-safe method to merge all Maps in the given collection into a new Map.
static <K extends java.lang.Comparable<? super K>,V> java.util.Map<K,V>	mergeMaps(java.util.Map<K,V>[] ms)
static <K extends java.lang.Comparable<? super K>,V> java.util.Map<K,V>	mergeMaps(java.util.Map<K,V>[] ms, boolean unmodifiable) Null-safe method to merge all Maps in the passed array into a new Map.
static <K extends java.lang.Comparable<? super K>,V> java.util.Map<K,V>	mergeMaps(java.util.Map<K,V> m1, java.util.Map<K,V> m2)
static <K extends java.lang.Comparable<? super K>,V> java.util.Map<K,V>	mergeMaps(java.util.Map<K,V> m1, java.util.Map<K,V> m2, boolean unmodifiable)
static <K extends java.lang.Comparable<? super K>,V> java.util.Map<K,V>	mergeMaps(java.util.Map<K,V> m1, java.util.Map<K,V> m2, java.util.Map<K,V> m3)
static <K extends java.lang.Comparable<? super K>,V> java.util.Map<K,V>	mergeMaps(java.util.Map<K,V> m1, java.util.Map<K,V> m2, java.util.Map<K,V> m3, boolean unmodifiable)
static int	size(java.util.Map<?,?> map)
static int	size(java.util.Map<?,?> map, boolean lazyEvaluationIfPossible) Returns the size of the passed Map, using the lazy variant if it is a LazyMapI, or zero if null is passed.
static <K,V,R> java.util.HashMap<R,V>	transformMap(java.util.function.Function<V,R> propertyFunc, java.util.Map<K,V> inputMap) Returns a map for the passed map, but with its keys transformed via the passed property.
static <K,V> java.util.HashMap<?,V>	transformMap(java.lang.String property, java.util.Map<K,V> inputMap) Deprecated. since the "property" String parameter is very error-prone, prefer to use transformMap(Function, Map) instead

Methods inherited from class java.lang.Object

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

Constructor Detail

MapTools

public MapTools()

Method Detail

createCopy

public static <K,V> java.util.Map<K,V> createCopy(java.util.Map<K,V> map)

Creates a shallow copy of the given Map.

This method attempts to use optimized cloning for specific Map implementations like TreeMap and HashMap by calling their respective clone() methods. For LazyMapI instances, it utilizes the LazyMapI.cloneInternalMap() method to obtain a copy of the underlying map.

For other Map implementations, a new LinkedHashMap is created and populated with the entries of the original Map. This ensures that the insertion order of the elements is preserved in the copied Map.

Type Parameters:

K - The type of the keys in the Map.

V - The type of the values in the Map.

Parameters:

map - The Map to create a copy of.

Returns:

A shallow copy of the input Map.

transformMap

public static final <K,V,R> java.util.HashMap<R,V> transformMap(java.util.function.Function<V,R> propertyFunc,
                                                                java.util.Map<K,V> inputMap)

Returns a map for the passed map, but with its keys transformed via the passed property.

Parameters:

propertyFunc - the property function by which to transform each object into a new key for the new. Needs to be passed as a static reference, since we will apply it to all value instances in the map.

inputMap - the map to transform

Returns:

a HashMap with the transformed map entries

Throws:

java.lang.IllegalArgumentException - if a parameter is null

java.lang.RuntimeException - if there was no corresponding get-method found or access or invocation of it failed

transformMap

@Deprecated
public static final <K,V> java.util.HashMap<?,V> transformMap(java.lang.String property,
                                                                          java.util.Map<K,V> inputMap)

Deprecated. since the "property" String parameter is very error-prone, prefer to use transformMap(Function, Map) instead

Returns a map for the passed map, but with its keys transformed via the passed property.

Parameters:

property - the property by which to transform each key-entry of the passed map (by calling the corresponding get-method on the value in the map)

inputMap - the map to transform

Returns:

a HashMap with the transformed map entries

Throws:

java.lang.IllegalArgumentException - if a parameter is null

java.lang.RuntimeException - if there was no corresponding get-method found or access or invocation of it failed

fillMap

public static final <K,V> java.util.Map<K,V> fillMap(java.util.Map<K,V> map,
                                                     java.lang.Object[] array)

Fills a passed map using an array representing keys and values in various possible styles.

Parameters:

array - the keys and values for the to be created map, either in order key, value, key, value, ... or as an array of Map.Entry or KeyValue objects or as an array of object arrays with 2 elements: key and value.

map - the map to be filled

Returns:

a Map with the keys and values from the passed array

Throws:

java.lang.NullPointerException - if map is null

java.lang.IllegalArgumentException - if sub-array or entry matching is used and an entry is invalid

java.lang.ClassCastException - if the array contents are mixed

See Also:

org.apache.commons.MapUtils#fillMap(Map, Object[])

fillMap

public static final <K,V> java.util.Map<K,V> fillMap(java.lang.Object[] array,
                                                     java.util.Map<K,V> map)

Fills a passed map using an array representing keys and values in various possible styles.

Parameters:

map - the map to be filled

array - the keys and values for the to be created map, either in order key, value, key, value, ... or as an array of Map.Entry or KeyValue objects or as an array of object arrays with 2 elements: key and value.

Returns:

a Map with the keys and values from the passed array

Throws:

java.lang.NullPointerException - if map is null

java.lang.IllegalArgumentException - if sub-array or entry matching is used and an entry is invalid

java.lang.ClassCastException - if the array contents are mixed

See Also:

org.apache.commons.MapUtils#fillMap(Map, Object[])

fillMap

public static final <K,V> java.util.Map<K,V> fillMap(java.util.Map<K,V> map,
                                                     K[] keyArray,
                                                     V[] valueArray)

Fills a passed map using two arrays. First array contains the keys, second the values.

Parameters:

map - the map to be filled

keyArray - the keys for the to be created map

valueArray - the values for the to be created map

Returns:

a Map with the keys and values from the passed arrays

Throws:

java.lang.IllegalArgumentException - if map is null or if sub-array or entry matching is used and an entry is invalid or if the passed arrays do not have the same size

java.lang.ClassCastException - if the array contents are mixed

See Also:

org.apache.commons.MapUtils#fillMap(Map, Object[])

mergeMaps

public static final <K extends java.lang.Comparable<? super K>,V> java.util.Map<K,V> mergeMaps(java.util.Map<K,V> m1,
                                                                                               java.util.Map<K,V> m2,
                                                                                               java.util.Map<K,V> m3)

mergeMaps

public static final <K extends java.lang.Comparable<? super K>,V> java.util.Map<K,V> mergeMaps(java.util.Map<K,V> m1,
                                                                                               java.util.Map<K,V> m2,
                                                                                               java.util.Map<K,V> m3,
                                                                                               boolean unmodifiable)

mergeMaps

public static final <K extends java.lang.Comparable<? super K>,V> java.util.Map<K,V> mergeMaps(java.util.Map<K,V> m1,
                                                                                               java.util.Map<K,V> m2)

mergeMaps

public static final <K extends java.lang.Comparable<? super K>,V> java.util.Map<K,V> mergeMaps(java.util.Map<K,V> m1,
                                                                                               java.util.Map<K,V> m2,
                                                                                               boolean unmodifiable)

mergeMaps

public static final <K extends java.lang.Comparable<? super K>,V> java.util.Map<K,V> mergeMaps(java.util.Map<K,V>[] ms)

mergeMaps

public static final <K extends java.lang.Comparable<? super K>,V> java.util.Map<K,V> mergeMaps(java.util.Map<K,V>[] ms,
                                                                                               boolean unmodifiable)

Null-safe method to merge all Maps in the passed array into a new Map. Will return the empty Map if all Maps are null (or empty), or a new map containing the mappings of all passed Maps, unmodifiable if requested.

Parameters:

ms - an array of Maps to merge

unmodifiable - if the returned Map shall be unmodifiable

Returns:

the empty Map if all Maps are null (or empty), or a new map containing the mappings of all passed Maps, unmodifiable if requested

mergeMaps

public static final <K extends java.lang.Comparable<? super K>,V> java.util.Map<K,V> mergeMaps(java.util.Collection<java.util.Map<K,V>> ms,
                                                                                               boolean unmodifiable)

Null-safe method to merge all Maps in the given collection into a new Map. Will return the empty Map if all Maps are null (or empty), or a new map containing the mappings of all passed Maps, unmodifiable if requested.

Parameters:

ms - a collection of Maps to merge

unmodifiable - if the returned Map shall be unmodifiable

Returns:

the empty Map if all Maps are null (or empty), or a new map containing the mappings of all passed Maps, unmodifiable if requested

collateMap

public static final <K,V> java.util.List<java.util.Map<K,V>> collateMap(java.util.Map<K,V> map,
                                                                        int size)

Breaks a given map into a list of smaller maps, each containing at most the specified number of entries. The returned smaller maps are instances of LinkedHashMap to maintain the insertion order of the elements, which is often a desirable property when collating entries from a map. This way, the smaller maps preserve the order of elements as they appeared in the original map.

Type Parameters:

K - the type of keys in the map

V - the type of values in the map

Parameters:

map - the map to be collated

size - the maximum number of entries in each resulting submap

Returns:

a list of maps of type LinkedHashMap, each containing at most the specified number of entries from the original map, maintaining the order of elements as they appeared in the original map.

Throws:

java.lang.IllegalArgumentException - if the specified size is less than or equal to 0

elvis

public static final <K,V> java.util.Map<K,V> elvis(java.util.Map<K,V>[] maps,
                                                   boolean fallBackToEmptyMap)

"elvis operator" for Maps

Returns:

the first of the Maps which is not null and not empty. If all maps are null or empty, null is returned or if fallBackToEmptyMap is passed as true an empty unmodifiable map is returned.

elvis

public static final <K,V> java.util.Map<K,V> elvis(java.util.Map<K,V>[] maps,
                                                   java.util.function.Supplier<? extends java.util.Map<K,V>> emptyMapCreator)

"elvis operator" for Maps

Returns:

the first of the Maps which is not null and not empty. If all maps are null or empty, null is returned or if a fallBackSupplier is passed, the resulting Map of a get-call on that supplier.

isOneOfClass

public static final boolean isOneOfClass(java.lang.Class<?> needle,
                                         java.util.Map<?,?> haystack)

Returns true if one of the values in the passed Map is of the passed Class.

Parameters:

needle - the Class to look for

haystack - the Map to check the values of

Returns:

true if the passed Class is assignable from one of the values in the passed Map.

find

public static final <R> R find(java.lang.Class<R> needle,
                               java.util.Map<?,?> haystack)

Returns the first value in the passed Map that is of the passed Class.

Parameters:

needle - the Class to look for

haystack - the Map to check the values of

Returns:

the first value in the passed Map that the passed Class is assignable from.

findAll

public static final <K,V> java.util.Map<K,V> findAll(java.lang.Class<?> needle,
                                                     java.util.Map<K,V> haystack)

Returns a map with entries of the passed Map, where the value is of the passed Class.

Parameters:

needle - the Class to look for

haystack - the Map to check the values of

Returns:

map with entries of the passed Map that the passed Class is assignable from.

firstValue

public static final <K,V> V firstValue(java.util.Map<K,V> map)

Returns the first Map.Entry's (as determined by the default iterator) value or null if the map is empty.

Parameters:

map - the Map to get the first value from

Returns:

the first value from the Map or null if it is null or empty

getOnlyEntry

public static final <K,V> java.util.Map.Entry<K,V> getOnlyEntry(java.util.Map<K,V> map)

Returns the single key contained in Map.

Parameters:

map - the Map to inspect

Returns:

the single key contained in Map

Throws:

java.util.NoSuchElementException - if the Map is null or empty

getOnlyKey

public static final <K,V> K getOnlyKey(java.util.Map<K,V> map)

Returns the single key contained in Map.

Parameters:

map - the Map to inspect

Returns:

the single key contained in Map

Throws:

java.util.NoSuchElementException - if the Map is null or empty

getOnlyValue

public static final <K,V> V getOnlyValue(java.util.Map<K,V> map)

Returns the single value contained in Map.

Parameters:

map - the Map to inspect

Returns:

the single value contained in Map

Throws:

java.util.NoSuchElementException - if the Map is null or empty

isEmpty

public static final boolean isEmpty(java.util.Map<?,?> map)

isEmpty

public static final boolean isEmpty(java.util.Map<?,?> map,
                                    boolean lazyEvaluationIfPossible)

Returns true if the passed Map is null or empty, using the lazy variant if it is a LazyMapI, so that no unlazy will be triggered by this method. Mind that calling this method with a LazyMapI only makes sense, if you do _not_ need the values and thus will unlazy the LazyMapI shortly after in the not empty case, as you'd cause two roundtrips instead of one then (one for count, another one to fetch the actual objects), adding overhead and time instead of reducing it.

size

public static final int size(java.util.Map<?,?> map)

size

public static final int size(java.util.Map<?,?> map,
                             boolean lazyEvaluationIfPossible)

Returns the size of the passed Map, using the lazy variant if it is a LazyMapI, or zero if null is passed. Mind that calling this method with a LazyMapI only makes sense, if you do _not_ need the values and thus will unlazy the LazyMapI shortly after in the not empty case, as you'd cause two roundtrips instead of one then (one for count, another one to fetch the actual objects), adding overhead and time instead of reducing it.

asImmutable

public static final <K,V> java.util.Map<K,V> asImmutable(java.util.Map<K,V> map)

Returns an unmodifiable version of the passed Map, or the empty Map for a passed null or empty map.

addToValueSet

public static final <K,V> void addToValueSet(java.util.Map<K,java.util.Set<V>> map,
                                             K key,
                                             V value)

addToValueList

public static final <K,V> void addToValueList(java.util.Map<K,java.util.List<V>> map,
                                              K key,
                                              V value)

addToValueCollection

public static final <K,V,C extends java.util.Collection<V>> void addToValueCollection(java.util.Map<K,C> map,
                                                                                      K key,
                                                                                      V value,
                                                                                      java.util.function.Supplier<C> colletionCreator)

Adds the given value into the collection stored in the map for the given key. If no collection is set for the key thus far, a new collection will be created with the supplier given. This method may be useful for splitting a map onto different collections.

Type Parameters:

K - map key type

V - type of the values stored within each set of map values

Parameters:

map - the map to manipulate

key - the key for which the value should be added

value - the value that should be added

colletionCreator - constructor ref with which new collections should be created