Top Description Fields Constructors Methods
org.apache.commons.collections4

public Class MapUtils

extends Object
Class Inheritance
Annotations
@SuppressWarnings:deprecation
Imports
java.io.PrintStream, java.text.NumberFormat, .ParseException, java.util.ArrayDeque, .Collection, .Collections, .Deque, .Enumeration, .HashMap, .Iterator, .Map, .Map.Entry, .Properties, .ResourceBundle, .SortedMap, .TreeMap, org.apache.commons.collections4.map.AbstractMapDecorator, .AbstractSortedMapDecorator, .FixedSizeMap, .FixedSizeSortedMap, .LazyMap, .LazySortedMap, .ListOrderedMap, .MultiValueMap, .PredicatedMap, .PredicatedSortedMap, .TransformedMap, .TransformedSortedMap, .UnmodifiableMap, .UnmodifiableSortedMap
Provides utility methods and decorators for Map and SortedMap instances.

It contains various type safe methods as well as other useful features like deep copying.

It also provides the following decorators:

Since
1.0

Field Summary

Modifier and TypeField and Description
public static final SortedMap<K, V>
EMPTY_SORTED_MAP

An empty unmodifiable sorted map.

private static final String
INDENT_STRING

String used to indent the verbose and debug Map prints.

Constructor Summary

AccessConstructor and Description
private
MapUtils()

MapUtils should not normally be instantiated.

Method Summary

Modifier and TypeMethod and Description
public static void
debugPrint(final PrintStream
the stream to print to, must not be null
out, final Object
The label to be used, may be null. If null, the label is not output. It typically represents the name of the property in a bean or similar.
label, final Map<?, ?>
The map to print, may be null. If null, the text 'null' is output.
map)

Prints the given map with nice line breaks.

public static <
the key type
K,
the value type
V> Map<K, V>

Returns:

an empty map if the argument is null
emptyIfNull(final Map<K, V>
the map, possibly null
map)

Returns an immutable empty map if the argument is null, or the argument itself otherwise.

public static <
the key type
K,
the value type
V> IterableMap<K, V>

Returns:

a fixed-size map backed by that map
fixedSizeMap(final Map<K, V>
the map whose size to fix, must not be null
map)

Returns a fixed-sized map backed by the given map.

public static <
the key type
K,
the value type
V> SortedMap<K, V>

Returns:

a fixed-size map backed by that map
fixedSizeSortedMap(final SortedMap<K, V>
the map whose size to fix, must not be null
map)

Returns a fixed-sized sorted map backed by the given sorted map.

public static <
the key type
K> Boolean

Returns:

the value in the Map as a Boolean, null if null map input
getBoolean(final Map<? super K, ?>
the map to use
map, final K
the key to look up
key)

Gets a Boolean from a Map in a null-safe manner.

public static <
the key type
K> Boolean

Returns:

the value in the map as a boolean, or defaultValue if the original value is null, the map is null or the boolean conversion fails
getBoolean(final Map<? super K, ?>
the map whose value to look up
map, final K
the key of the value to look up in that map
key, final Boolean
what to return if the value is null or if the conversion fails
defaultValue)

Looks up the given key in the given map, converting the result into a boolean, using the default value if the conversion fails.

public static <
the key type
K> boolean

Returns:

the value in the Map as a Boolean, false if null map input
getBooleanValue(final Map<? super K, ?>
the map to use
map, final K
the key to look up
key)

Gets a boolean from a Map in a null-safe manner.

public static <
the key type
K> boolean

Returns:

the value in the Map as a Boolean, defaultValue if null map input
getBooleanValue(final Map<? super K, ?>
the map to use
map, final K
the key to look up
key, final boolean
return if the value is null or if the conversion fails
defaultValue)

Gets a boolean from a Map in a null-safe manner, using the default value if the conversion fails.

public static <
the key type
K> Byte

Returns:

the value in the Map as a Byte, null if null map input
getByte(final Map<? super K, ?>
the map to use
map, final K
the key to look up
key)

Gets a Byte from a Map in a null-safe manner.

public static <
the key type
K> Byte

Returns:

the value in the map as a number, or defaultValue if the original value is null, the map is null or the number conversion fails
getByte(final Map<? super K, ?>
the map whose value to look up
map, final K
the key of the value to look up in that map
key, final Byte
what to return if the value is null or if the conversion fails
defaultValue)

Looks up the given key in the given map, converting the result into a byte, using the default value if the conversion fails.

public static <
the key type
K> byte

Returns:

the value in the Map as a byte, 0 if null map input
getByteValue(final Map<? super K, ?>
the map to use
map, final K
the key to look up
key)

Gets a byte from a Map in a null-safe manner.

public static <
the key type
K> byte

Returns:

the value in the Map as a byte, defaultValue if null map input
getByteValue(final Map<? super K, ?>
the map to use
map, final K
the key to look up
key, final byte
return if the value is null or if the conversion fails
defaultValue)

Gets a byte from a Map in a null-safe manner, using the default value if the conversion fails.

public static <
the key type
K> Double

Returns:

the value in the Map as a Double, null if null map input
getDouble(final Map<? super K, ?>
the map to use
map, final K
the key to look up
key)

Gets a Double from a Map in a null-safe manner.

public static <
the key type
K> Double

Returns:

the value in the map as a number, or defaultValue if the original value is null, the map is null or the number conversion fails
getDouble(final Map<? super K, ?>
the map whose value to look up
map, final K
the key of the value to look up in that map
key, final Double
what to return if the value is null or if the conversion fails
defaultValue)

Looks up the given key in the given map, converting the result into a double, using the default value if the conversion fails.

public static <
the key type
K> double

Returns:

the value in the Map as a double, 0.0 if null map input
getDoubleValue(final Map<? super K, ?>
the map to use
map, final K
the key to look up
key)

Gets a double from a Map in a null-safe manner.

public static <
the key type
K> double

Returns:

the value in the Map as a double, defaultValue if null map input
getDoubleValue(final Map<? super K, ?>
the map to use
map, final K
the key to look up
key, final double
return if the value is null or if the conversion fails
defaultValue)

Gets a double from a Map in a null-safe manner, using the default value if the conversion fails.

public static <
the key type
K> Float

Returns:

the value in the Map as a Float, null if null map input
getFloat(final Map<? super K, ?>
the map to use
map, final K
the key to look up
key)

Gets a Float from a Map in a null-safe manner.

public static <
the key type
K> Float

Returns:

the value in the map as a number, or defaultValue if the original value is null, the map is null or the number conversion fails
getFloat(final Map<? super K, ?>
the map whose value to look up
map, final K
the key of the value to look up in that map
key, final Float
what to return if the value is null or if the conversion fails
defaultValue)

Looks up the given key in the given map, converting the result into a float, using the default value if the conversion fails.

public static <
the key type
K> float

Returns:

the value in the Map as a float, 0.0F if null map input
getFloatValue(final Map<? super K, ?>
the map to use
map, final K
the key to look up
key)

Gets a float from a Map in a null-safe manner.

public static <
the key type
K> float

Returns:

the value in the Map as a float, defaultValue if null map input
getFloatValue(final Map<? super K, ?>
the map to use
map, final K
the key to look up
key, final float
return if the value is null or if the conversion fails
defaultValue)

Gets a float from a Map in a null-safe manner, using the default value if the conversion fails.

public static <
the key type
K> Integer

Returns:

the value in the Map as a Integer, null if null map input
getInteger(final Map<? super K, ?>
the map to use
map, final K
the key to look up
key)

Gets a Integer from a Map in a null-safe manner.

public static <
the key type
K> Integer

Returns:

the value in the map as a number, or defaultValue if the original value is null, the map is null or the number conversion fails
getInteger(final Map<? super K, ?>
the map whose value to look up
map, final K
the key of the value to look up in that map
key, final Integer
what to return if the value is null or if the conversion fails
defaultValue)

Looks up the given key in the given map, converting the result into an integer, using the default value if the conversion fails.

public static <
the key type
K> int

Returns:

the value in the Map as an int, 0 if null map input
getIntValue(final Map<? super K, ?>
the map to use
map, final K
the key to look up
key)

Gets an int from a Map in a null-safe manner.

public static <
the key type
K> int

Returns:

the value in the Map as an int, defaultValue if null map input
getIntValue(final Map<? super K, ?>
the map to use
map, final K
the key to look up
key, final int
return if the value is null or if the conversion fails
defaultValue)

Gets an int from a Map in a null-safe manner, using the default value if the conversion fails.

public static <
the key type
K> Long

Returns:

the value in the Map as a Long, null if null map input
getLong(final Map<? super K, ?>
the map to use
map, final K
the key to look up
key)

Gets a Long from a Map in a null-safe manner.

public static <
the key type
K> Long

Returns:

the value in the map as a number, or defaultValue if the original value is null, the map is null or the number conversion fails
getLong(final Map<? super K, ?>
the map whose value to look up
map, final K
the key of the value to look up in that map
key, final Long
what to return if the value is null or if the conversion fails
defaultValue)

Looks up the given key in the given map, converting the result into a long, using the default value if the conversion fails.

public static <
the key type
K> long

Returns:

the value in the Map as a long, 0L if null map input
getLongValue(final Map<? super K, ?>
the map to use
map, final K
the key to look up
key)

Gets a long from a Map in a null-safe manner.

public static <
the key type
K> long

Returns:

the value in the Map as a long, defaultValue if null map input
getLongValue(final Map<? super K, ?>
the map to use
map, final K
the key to look up
key, final long
return if the value is null or if the conversion fails
defaultValue)

Gets a long from a Map in a null-safe manner, using the default value if the conversion fails.

public static <
the key type
K> Map<?, ?>

Returns:

the value in the Map as a Map, null if null map input
getMap(final Map<? super K, ?>
the map to use
map, final K
the key to look up
key)

Gets a Map from a Map in a null-safe manner.

public static <
the key type
K> Map<?, ?>

Returns:

the value in the map as a number, or defaultValue if the original value is null, the map is null or the map conversion fails
getMap(final Map<? super K, ?>
the map whose value to look up
map, final K
the key of the value to look up in that map
key, final Map<?, ?>
what to return if the value is null or if the conversion fails
defaultValue)

Looks up the given key in the given map, converting the result into a map, using the default value if the conversion fails.

public static <
the key type
K> Number

Returns:

the value in the Map as a Number, null if null map input
getNumber(final Map<? super K, ?>
the map to use
map, final K
the key to look up
key)

Gets a Number from a Map in a null-safe manner.

public static <
the key type
K> Number

Returns:

the value in the map as a number, or defaultValue if the original value is null, the map is null or the number conversion fails
getNumber(final Map<? super K, ?>
the map whose value to look up
map, final K
the key of the value to look up in that map
key, final Number
what to return if the value is null or if the conversion fails
defaultValue)

Looks up the given key in the given map, converting the result into a number, using the default value if the conversion fails.

public static <
the key type
K,
the value type
V> V

Returns:

the value in the Map, null if null map input
getObject(final Map<? super K, V>
the map to use
map, final K
the key to look up
key)

Gets from a Map in a null-safe manner.

public static <
the key type
K,
the value type
V> V

Returns:

the value in the map, or defaultValue if the original value is null or the map is null
getObject(final Map<K, V>
the map whose value to look up
map, final K
the key of the value to look up in that map
key, final V
what to return if the value is null
defaultValue)

Looks up the given key in the given map, converting null into the given default value.

public static <
the key type
K> Short

Returns:

the value in the Map as a Short, null if null map input
getShort(final Map<? super K, ?>
the map to use
map, final K
the key to look up
key)

Gets a Short from a Map in a null-safe manner.

public static <
the key type
K> Short

Returns:

the value in the map as a number, or defaultValue if the original value is null, the map is null or the number conversion fails
getShort(final Map<? super K, ?>
the map whose value to look up
map, final K
the key of the value to look up in that map
key, final Short
what to return if the value is null or if the conversion fails
defaultValue)

Looks up the given key in the given map, converting the result into a short, using the default value if the conversion fails.

public static <
the key type
K> short

Returns:

the value in the Map as a short, 0 if null map input
getShortValue(final Map<? super K, ?>
the map to use
map, final K
the key to look up
key)

Gets a short from a Map in a null-safe manner.

public static <
the key type
K> short

Returns:

the value in the Map as a short, defaultValue if null map input
getShortValue(final Map<? super K, ?>
the map to use
map, final K
the key to look up
key, final short
return if the value is null or if the conversion fails
defaultValue)

Gets a short from a Map in a null-safe manner, using the default value if the conversion fails.

public static <
the key type
K> String

Returns:

the value in the Map as a String, null if null map input
getString(final Map<? super K, ?>
the map to use
map, final K
the key to look up
key)

Gets a String from a Map in a null-safe manner.

public static <
the key type
K> String

Returns:

the value in the map as a string, or defaultValue if the original value is null, the map is null or the string conversion fails
getString(final Map<? super K, ?>
the map whose value to look up
map, final K
the key of the value to look up in that map
key, final String
what to return if the value is null or if the conversion fails
defaultValue)

Looks up the given key in the given map, converting the result into a string, using the default value if the conversion fails.

public static <
the key type
K,
the value type
V> Map<V, K>

Returns:

a new HashMap containing the inverted data
invertMap(final Map<K, V>
the map to invert, may not be null
map)

Inverts the supplied map returning a new HashMap such that the keys of the input are swapped with the values.

public static boolean

Returns:

true if empty or null
isEmpty(final Map<?, ?>
the map to check, may be null
map)

Null-safe check if the specified map is empty.

public static boolean

Returns:

true if non-null and non-empty
isNotEmpty(final Map<?, ?>
the map to check, may be null
map)

Null-safe check if the specified map is not empty.

public static <
the key type
K,
the value type
V> IterableMap<K, V>

Returns:

IterableMap<K, V>
iterableMap(final Map<K, V>
to wrap if necessary.
map)

Get the specified Map as an IterableMap.

public static <
the key type
K,
the value type
V> IterableSortedMap<K, V>

Returns:

IterableSortedMap<K, V>
iterableSortedMap(final SortedMap<K, V>
to wrap if necessary
sortedMap)

Get the specified SortedMap as an IterableSortedMap.

public static <
the key type
K,
the value type
V> IterableMap<K, V>

Returns:

a lazy map backed by the given map
lazyMap(final Map<K, V>
the map to make lazy, must not be null
map, final Factory<? extends V>
the factory for creating new objects, must not be null
factory)

Returns a "lazy" map whose values will be created on demand.

public static <
the key type
K,
the value type
V> IterableMap<K, V>

Returns:

a lazy map backed by the given map
lazyMap(final Map<K, V>
the map to make lazy, must not be null
map, final Transformer<? super K, ? extends V>
the factory for creating new objects, must not be null
transformerFactory)

Returns a "lazy" map whose values will be created on demand.

public static <
the key type
K,
the value type
V> SortedMap<K, V>

Returns:

a lazy map backed by the given map
lazySortedMap(final SortedMap<K, V>
the map to make lazy, must not be null
map, final Factory<? extends V>
the factory for creating new objects, must not be null
factory)

Returns a "lazy" sorted map whose values will be created on demand.

public static <
the key type
K,
the value type
V> SortedMap<K, V>

Returns:

a lazy map backed by the given map
lazySortedMap(final SortedMap<K, V>
the map to make lazy, must not be null
map, final Transformer<? super K, ? extends V>
the factory for creating new objects, must not be null
transformerFactory)

Returns a "lazy" sorted map whose values will be created on demand.

public static <
the key type
K,
the value type
V> MultiValueMap<K, V>

Returns:

a multi-value map backed by the given map which returns ArrayLists of values.
multiValueMap(final Map<K, ? super Collection<V>>
the map to decorate
map)

Deprecated since 4.1, use MultiValuedMap instead
Creates a mult-value map backed by the given map which returns collections of type ArrayList.
public static <
the key type
K,
the value type
V,
the collection class type
C extends Collection<V>> MultiValueMap<K, V>

Returns:

a multi-value map backed by the given map which returns collections of the specified type
multiValueMap(final Map<K, C>
the map to decorate
map, final Class<C>
the type of collections to return from the map (must contain public no-arg constructor and extend Collection)
collectionClass)

Deprecated since 4.1, use MultiValuedMap instead
Creates a multi-value map backed by the given map which returns collections of the specified type.
public static <
the key type
K,
the value type
V,
the collection class type
C extends Collection<V>> MultiValueMap<K, V>

Returns:

a multi-value map backed by the given map which returns collections created by the specified collection factory
multiValueMap(final Map<K, C>
the map to decorate
map, final Factory<C>
a factor which creates collection objects
collectionFactory)

Deprecated since 4.1, use MultiValuedMap instead
Creates a multi-value map backed by the given map which returns collections created by the specified collection factory.
public static <
the key type
K,
the value type
V> OrderedMap<K, V>

Returns:

an ordered map backed by the given map
orderedMap(final Map<K, V>
the map to order, must not be null
map)

Returns a map that maintains the order of keys that are added backed by the given map.

public static <
the key type
K,
the value type
V> void
populateMap(final Map<K, V>
the Map to populate.
map, final Iterable<? extends V>
the Iterable containing the input values for the map.
elements, final Transformer<V, K>
the Transformer used to transform the element into a key value
keyTransformer)

Populates a Map using the supplied Transformer to transform the elements into keys, using the unaltered element as the value in the Map.

public static <
the key type
K,
the value type
V,
the type of object contained in the Iterable
E> void
populateMap(final Map<K, V>
the Map to populate.
map, final Iterable<? extends E>
the Iterable containing the input values for the map.
elements, final Transformer<E, K>
the Transformer used to transform the element into a key value
keyTransformer, final Transformer<E, V>
the Transformer used to transform the element into a value
valueTransformer)

Populates a Map using the supplied Transformers to transform the elements into keys and values.

public static <
the key type
K,
the value type
V> void
populateMap(final MultiMap<K, V>
the MultiMap to populate.
map, final Iterable<? extends V>
the Iterable to use as input values for the map.
elements, final Transformer<V, K>
the Transformer used to transform the element into a key value
keyTransformer)

Deprecated as a consequence of MultiMap being deprecated.
Populates a MultiMap using the supplied Transformer to transform the elements into keys, using the unaltered element as the value in the MultiMap.
public static <
the key type
K,
the value type
V,
the type of object contained in the Iterable
E> void
populateMap(final MultiMap<K, V>
the MultiMap to populate.
map, final Iterable<? extends E>
the Iterable containing the input values for the map.
elements, final Transformer<E, K>
the Transformer used to transform the element into a key value
keyTransformer, final Transformer<E, V>
the Transformer used to transform the element into a value
valueTransformer)

Deprecated as a consequence of MultiMap being deprecated.
Populates a MultiMap using the supplied Transformers to transform the elements into keys and values.
public static <
the key type
K,
the value type
V> IterableMap<K, V>

Returns:

a predicated map backed by the given map
predicatedMap(final Map<K, V>
the map to predicate, must not be null
map, final Predicate<? super K>
the predicate for keys, null means no check
keyPred, final Predicate<? super V>
the predicate for values, null means no check
valuePred)

Returns a predicated (validating) map backed by the given map.

public static <
the key type
K,
the value type
V> SortedMap<K, V>

Returns:

a predicated map backed by the given map
predicatedSortedMap(final SortedMap<K, V>
the map to predicate, must not be null
map, final Predicate<? super K>
the predicate for keys, null means no check
keyPred, final Predicate<? super V>
the predicate for values, null means no check
valuePred)

Returns a predicated (validating) sorted map backed by the given map.

private static void
printIndent(final PrintStream
the stream to indent
out, final int indent)

Writes indentation to the given stream.

public static <
the key type
K,
the value type
V> Map<K, V>

Returns:

the input map
putAll(final Map<K, V>
the map to populate, must not be null
map, final Object[]
an array to populate from, null ignored
array)

Puts all the keys and values from the specified array into the map.

public static <
the key type
K> void
safeAddToMap(final Map<? super K, Object>
the map to add to, may not be null
map, final K
the key
key, final Object
the value, null converted to ""
value)

Protects against adding null values to a map.

public static int

Returns:

the given map size or 0 if the map is null
size(final Map<?, ?>
a Map or null
map)

Gets the given map size or 0 if the map is null

public static <
the key type
K,
the value type
V> Map<K, V>

Returns:

a synchronized map backed by the given map
synchronizedMap(final Map<K, V>
the map to synchronize, must not be null
map)

Returns a synchronized map backed by the given map.

public static <
the key type
K,
the value type
V> SortedMap<K, V>

Returns:

a synchronized map backed by the given map
synchronizedSortedMap(final SortedMap<K, V>
the map to synchronize, must not be null
map)

Returns a synchronized sorted map backed by the given sorted map.

public static Map<String, Object>

Returns:

the hashmap containing the data
toMap(final ResourceBundle
the resource bundle to convert, may not be null
resourceBundle)

Creates a new HashMap using data copied from a ResourceBundle.

public static <
the key type
K,
the value type
V> Properties

Returns:

the properties object
toProperties(final Map<K, V>
the map to convert to a Properties object
map)

Gets a new Properties object initialised with the values from a Map.

public static <
the key type
K,
the value type
V> IterableMap<K, V>

Returns:

a transformed map backed by the given map
transformedMap(final Map<K, V>
the map to transform, must not be null, typically empty
map, final Transformer<? super K, ? extends K>
the transformer for the map keys, null means no transformation
keyTransformer, final Transformer<? super V, ? extends V>
the transformer for the map values, null means no transformation
valueTransformer)

Returns a transformed map backed by the given map.

public static <
the key type
K,
the value type
V> SortedMap<K, V>

Returns:

a transformed map backed by the given map
transformedSortedMap(final SortedMap<K, V>
the map to transform, must not be null, typically empty
map, final Transformer<? super K, ? extends K>
the transformer for the map keys, null means no transformation
keyTransformer, final Transformer<? super V, ? extends V>
the transformer for the map values, null means no transformation
valueTransformer)

Returns a transformed sorted map backed by the given map.

public static <
the key type
K,
the value type
V> Map<K, V>

Returns:

an unmodifiable map backed by the given map
unmodifiableMap(final Map<? extends K, ? extends V>
the map to make unmodifiable, must not be null
map)

Returns an unmodifiable map backed by the given map.

public static <
the key type
K,
the value type
V> SortedMap<K, V>

Returns:

an unmodifiable map backed by the given map
unmodifiableSortedMap(final SortedMap<K, ? extends V>
the sorted map to make unmodifiable, must not be null
map)

Returns an unmodifiable sorted map backed by the given sorted map.

public static void
verbosePrint(final PrintStream
the stream to print to, must not be null
out, final Object
The label to be used, may be null. If null, the label is not output. It typically represents the name of the property in a bean or similar.
label, final Map<?, ?>
The map to print, may be null. If null, the text 'null' is output.
map)

Prints the given map with nice line breaks.

private static void
verbosePrintInternal(final PrintStream
the stream to print to
out, final Object
the label to be used, may be null. If null, the label is not output. It typically represents the name of the property in a bean or similar.
label, final Map<?, ?>
the map to print, may be null. If null, the text 'null' is output
map, final Deque<Map<?, ?>>
a stack consisting of any maps in which the previous argument is contained. This is checked to avoid infinite recursion when printing the output
lineage, final boolean
flag indicating whether type names should be output.
debug)

Implementation providing functionality for debugPrint and for verbosePrint.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait