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 advanced Map manipulation, transformation, and performance-optimized operations for lazy-loading collections.

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> collectionCreator) Generic method to add a value to a collection stored within a map.
static <K,V> void	addToValueList(java.util.Map<K,java.util.List<V>> map, K key, V value) Adds a value to a List stored as a Map value.
static <K,V> void	addToValueSet(java.util.Map<K,java.util.Set<V>> map, K key, V value) Adds a value to a Set stored as a Map value.
static <K,V> java.util.Map<K,V>	asImmutable(java.util.Map<K,V> map) Returns an unmodifiable version of the passed Map.
static <K,V> java.util.List<java.util.Map<K,V>>	collateMap(java.util.Map<K,V> map, int size) Breaks a map into a list of smaller LinkedHashMap instances.
static <K,V> java.util.Map<K,V>	createCopy(java.util.Map<K,V> map) Creates a shallow copy of the given Map using optimized cloning where possible.
static <K,V> java.util.Map<K,V>	elvis(java.util.Map<K,V>[] maps, boolean fallBackToEmptyMap) Returns the first non-null and non-empty map from an array.
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) Returns the first non-null and non-empty map from an array, or a default from a supplier.
static <K,V> java.util.Map<K,V>	fillMap(java.util.Map<K,V> map, K[] keyArray, V[] valueArray) Fills a map using two separate arrays for keys and values.
static <K,V> java.util.Map<K,V>	fillMap(java.util.Map<K,V> map, java.lang.Object[] array) Fills a map using an array representing keys and values in various styles.
static <K,V> java.util.Map<K,V>	fillMap(java.lang.Object[] array, java.util.Map<K,V> map) Overload of fillMap(Map, Object[]) with swapped parameters for API flexibility.
static <R> R	find(java.lang.Class<R> needle, java.util.Map<?,?> haystack) Finds the first value in the map that is an instance of the specified class.
static <K,V> java.util.Map<K,V>	findAll(java.lang.Class<?> needle, java.util.Map<K,V> haystack) Returns a new map containing all entries where the value matches the specified class.
static <K,V> V	firstValue(java.util.Map<K,V> map) Returns the first value encountered in the map's iterator, or null.
static <K,V> java.util.Map.Entry<K,V>	getOnlyEntry(java.util.Map<K,V> map) Returns the single entry in a map containing exactly one element.
static <K,V> K	getOnlyKey(java.util.Map<K,V> map) Returns the single key in a map containing exactly one element.
static <K,V> V	getOnlyValue(java.util.Map<K,V> map) Returns the single value in a map containing exactly one element.
static <K,V> V	getOnlyValueNT(java.util.Map<K,V> map) Non-throwing variant of getOnlyValue(Map).
static boolean	isEmpty(java.util.Map<?,?> map) Standard check if a Map is null or empty.
static boolean	isEmpty(java.util.Map<?,?> map, boolean lazyEvaluationIfPossible) Determines if a Map is null or empty, with an option to avoid triggering a full database load for lazy-loading collections.
static boolean	isOneOfClass(java.lang.Class<?> needle, java.util.Map<?,?> haystack) Checks if any value in the map is an instance of the specified 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 a collection of Maps into a new TreeMap.
static <K extends java.lang.Comparable<? super K>,V> java.util.Map<K,V>	mergeMaps(java.util.Map<K,V>[] ms) Merges an array of maps into a new TreeMap.
static <K extends java.lang.Comparable<? super K>,V> java.util.Map<K,V>	mergeMaps(java.util.Map<K,V>[] ms, boolean unmodifiable) Merges an array of maps into a new TreeMap, with optional immutability.
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) Merges two maps into a new TreeMap.
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) Merges two maps into a new TreeMap, with optional immutability.
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) Merges multiple maps into a new TreeMap.
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) Merges three maps into a new TreeMap, with optional immutability.
static int	size(java.util.Map<?,?> map) Returns the number of entries in the map.
static int	size(java.util.Map<?,?> map, boolean lazyEvaluationIfPossible) Returns the size of the map, with an option to avoid triggering a full database load for lazy-loading collections.
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 new HashMap where the keys are derived from the values of the input map using the provided property function.
static <K,V> java.util.HashMap<?,V>	transformMap(java.lang.String property, java.util.Map<K,V> inputMap) Deprecated. Use transformMap(Function, Map) for type safety.

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 using optimized cloning where possible.

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 LazyMapI.cloneInternalMap() to copy the underlying data structure.

For other Map implementations, a new LinkedHashMap is created to preserve insertion order. Note that for synchronized wrappers around sorted maps, a "slow" copy is performed as they do not support direct cloning.

Type Parameters:

K - The type of the keys.

V - The type of the values.

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 new HashMap where the keys are derived from the values of the input map using the provided property function.

Type Parameters:

K - Original key type.

V - Value type.

R - New key type.

Parameters:

propertyFunc - The function used to generate a new key from each value.

inputMap - The map to transform.

Returns:

A HashMap containing the transformed entries. Entries with null keys are skipped.

Throws:

java.lang.IllegalArgumentException - if propertyFunc or inputMap is null.

transformMap

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

Deprecated. Use transformMap(Function, Map) for type safety.

Returns a new HashMap where the keys are derived from values via reflection.

Parameters:

property - The property name (appended to "get") used to fetch the new key.

inputMap - The map to transform.

Returns:

A HashMap with transformed keys.

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 map using an array representing keys and values in various styles. Styles supported: [key, value, key, value], [Map.Entry], or [ [key, value] ].

Parameters:

map - The map to be filled.

array - The source array of keys and values.

Returns:

The filled Map.

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:

MapUtils.putAll(Map, Object[])

fillMap

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

Overload of fillMap(Map, Object[]) with swapped parameters for API flexibility.

fillMap

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

Fills a map using two separate arrays for keys and values.

Parameters:

map - The map to fill.

keyArray - Array of keys.

valueArray - Array of values.

Throws:

java.lang.IllegalArgumentException - if map is null, arrays are null/empty inconsistently, or sizes differ.

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

See Also:

MapUtils.putAll(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)

Merges multiple maps into a new TreeMap.

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)

Merges three maps into a new TreeMap, with optional immutability.

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)

Merges two maps into a new TreeMap.

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)

Merges two maps into a new TreeMap, with optional immutability.

mergeMaps

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

Merges an array of maps into a new TreeMap.

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)

Merges an array of maps into a new TreeMap, with optional immutability.

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 a collection of Maps into a new TreeMap.

Parameters:

ms - A collection of maps to merge.

unmodifiable - If true, the resulting map is wrapped in Collections.unmodifiableSortedMap(java.util.SortedMap<K, ? extends V>).

Returns:

A new TreeMap containing all entries.

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 map into a list of smaller LinkedHashMap instances.

Parameters:

map - The source map.

size - Maximum entries per sub-map.

Returns:

A list of sub-maps preserving insertion order.

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)

Returns the first non-null and non-empty map from an array.

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)

Returns the first non-null and non-empty map from an array, or a default from a supplier.

isOneOfClass

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

Checks if any value in the map is an instance of the specified class.

find

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

Finds the first value in the map that is an instance of the specified class.

findAll

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

Returns a new map containing all entries where the value matches the specified class.

firstValue

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

Returns the first value encountered in the map's iterator, or null.

getOnlyEntry

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

Returns the single entry in a map containing exactly one element.

Throws:

java.util.NoSuchElementException - if map is null, empty, or has multiple elements.

getOnlyKey

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

Returns the single key in a map containing exactly one element.

Throws:

java.util.NoSuchElementException - if map is null, empty, or has multiple elements.

getOnlyValue

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

Returns the single value in a map containing exactly one element.

Throws:

java.util.NoSuchElementException - if map is null, empty, or has multiple elements.

getOnlyValueNT

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

Non-throwing variant of getOnlyValue(Map). Returns null if empty.

Throws:

java.util.NoSuchElementException - only if map is null.

isEmpty

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

Standard check if a Map is null or empty. Defaults to lazy evaluation for LazyMapI to avoid database roundtrips.

Performance Warning: Calling this on a LazyMapI initiates a database count roundtrip. If you are about to access the map's contents, call isEmpty(Map, boolean) with false to avoid two roundtrips.

isEmpty

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

Determines if a Map is null or empty, with an option to avoid triggering a full database load for lazy-loading collections.

Performance Warning: Calling this on a LazyMapI with lazyEvaluationIfPossible = true initiates a database count roundtrip. If you are about to access the map's contents (e.g. in a loop), setting this to false is more efficient, as it avoids executing two separate database roundtrips (one for count, one for data).

Parameters:

map - The map to check; may be null.

lazyEvaluationIfPossible - If true, uses LazyMapI.lazyIsEmpty().

Returns:

true if the map is null or contains no entries.

size

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

Returns the number of entries in the map. Defaults to lazy evaluation for LazyMapI to avoid database roundtrips.

Performance Warning: Calling this on a LazyMapI initiates a database count roundtrip. If you are about to access the map's contents, call size(Map, boolean) with false to avoid two roundtrips.

size

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

Returns the size of the map, with an option to avoid triggering a full database load for lazy-loading collections.

Performance Warning: Calling this on a LazyMapI with lazyEvaluationIfPossible = true initiates a database count roundtrip. If you are about to access the map's contents (e.g. in a loop), setting this to false is more efficient, as it avoids executing two separate database roundtrips (one for count, one for data).

Parameters:

map - The map to check; may be null.

lazyEvaluationIfPossible - If true, uses LazyMapI.lazySize().

Returns:

The number of entries in the map, or 0 if null.

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. Maps are treated as SortedMap if applicable.

addToValueSet

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

Adds a value to a Set stored as a Map value. Creates a new HashSet if needed.

addToValueList

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

Adds a value to a List stored as a Map value. Creates a new ArrayList if needed.

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> collectionCreator)

Generic method to add a value to a collection stored within a map. This method may be useful for splitting a map into different collections.

Parameters:

map - The target map.

key - The map key.

value - The value to add to the inner collection.

collectionCreator - Supplier for the inner collection if it doesn't exist yet.