public class

MapUtils

extends Object
java.lang.Object
   ↳ org.apache.commons.collections.MapUtils

Summary

Fields
public static final Map EMPTY_MAP An empty unmodifiable map.
public static final SortedMap EMPTY_SORTED_MAP An empty unmodifiable sorted map.
Public Constructors
MapUtils()
MapUtils should not normally be instantiated.
Public Methods
static void debugPrint(PrintStream out, Object label, Map map)
Prints the given map with nice line breaks.
static Map fixedSizeMap(Map map)
Returns a fixed-sized map backed by the given map.
static SortedMap fixedSizeSortedMap(SortedMap map)
Returns a fixed-sized sorted map backed by the given sorted map.
static Boolean getBoolean(Map map, Object key, Boolean defaultValue)
Looks up the given key in the given map, converting the result into a boolean, using the default value if the the conversion fails.
static Boolean getBoolean(Map map, Object key)
Gets a Boolean from a Map in a null-safe manner.
static boolean getBooleanValue(Map map, Object key, boolean defaultValue)
Gets a boolean from a Map in a null-safe manner, using the default value if the the conversion fails.
static boolean getBooleanValue(Map map, Object key)
Gets a boolean from a Map in a null-safe manner.
static Byte getByte(Map map, Object key)
Gets a Byte from a Map in a null-safe manner.
static Byte getByte(Map map, Object key, Byte defaultValue)
Looks up the given key in the given map, converting the result into a byte, using the default value if the the conversion fails.
static byte getByteValue(Map map, Object key)
Gets a byte from a Map in a null-safe manner.
static byte getByteValue(Map map, Object key, byte defaultValue)
Gets a byte from a Map in a null-safe manner, using the default value if the the conversion fails.
static Double getDouble(Map map, Object key)
Gets a Double from a Map in a null-safe manner.
static Double getDouble(Map map, Object key, Double defaultValue)
Looks up the given key in the given map, converting the result into a double, using the default value if the the conversion fails.
static double getDoubleValue(Map map, Object key)
Gets a double from a Map in a null-safe manner.
static double getDoubleValue(Map map, Object key, double defaultValue)
Gets a double from a Map in a null-safe manner, using the default value if the the conversion fails.
static Float getFloat(Map map, Object key)
Gets a Float from a Map in a null-safe manner.
static Float getFloat(Map map, Object key, Float defaultValue)
Looks up the given key in the given map, converting the result into a float, using the default value if the the conversion fails.
static float getFloatValue(Map map, Object key, float defaultValue)
Gets a float from a Map in a null-safe manner, using the default value if the the conversion fails.
static float getFloatValue(Map map, Object key)
Gets a float from a Map in a null-safe manner.
static int getIntValue(Map map, Object key)
Gets an int from a Map in a null-safe manner.
static int getIntValue(Map map, Object key, int defaultValue)
Gets an int from a Map in a null-safe manner, using the default value if the the conversion fails.
static Integer getInteger(Map map, Object key)
Gets a Integer from a Map in a null-safe manner.
static Integer getInteger(Map map, Object key, Integer defaultValue)
Looks up the given key in the given map, converting the result into an integer, using the default value if the the conversion fails.
static Long getLong(Map map, Object key, Long defaultValue)
Looks up the given key in the given map, converting the result into a long, using the default value if the the conversion fails.
static Long getLong(Map map, Object key)
Gets a Long from a Map in a null-safe manner.
static long getLongValue(Map map, Object key)
Gets a long from a Map in a null-safe manner.
static long getLongValue(Map map, Object key, long defaultValue)
Gets a long from a Map in a null-safe manner, using the default value if the the conversion fails.
static Map getMap(Map map, Object key, Map defaultValue)
Looks up the given key in the given map, converting the result into a map, using the default value if the the conversion fails.
static Map getMap(Map map, Object key)
Gets a Map from a Map in a null-safe manner.
static Number getNumber(Map map, Object key, Number defaultValue)
Looks up the given key in the given map, converting the result into a number, using the default value if the the conversion fails.
static Number getNumber(Map map, Object key)
Gets a Number from a Map in a null-safe manner.
static Object getObject(Map map, Object key)
Gets from a Map in a null-safe manner.
static Object getObject(Map map, Object key, Object defaultValue)
Looks up the given key in the given map, converting null into the given default value.
static Short getShort(Map map, Object key)
Gets a Short from a Map in a null-safe manner.
static Short getShort(Map map, Object key, Short defaultValue)
Looks up the given key in the given map, converting the result into a short, using the default value if the the conversion fails.
static short getShortValue(Map map, Object key, short defaultValue)
Gets a short from a Map in a null-safe manner, using the default value if the the conversion fails.
static short getShortValue(Map map, Object key)
Gets a short from a Map in a null-safe manner.
static String getString(Map map, Object key, String defaultValue)
Looks up the given key in the given map, converting the result into a string, using the default value if the the conversion fails.
static String getString(Map map, Object key)
Gets a String from a Map in a null-safe manner.
static Map invertMap(Map map)
Inverts the supplied map returning a new HashMap such that the keys of the input are swapped with the values.
static boolean isEmpty(Map map)
Null-safe check if the specified map is empty.
static boolean isNotEmpty(Map map)
Null-safe check if the specified map is not empty.
static Map lazyMap(Map map, Factory factory)
Returns a "lazy" map whose values will be created on demand.
static Map lazyMap(Map map, Transformer transformerFactory)
Returns a "lazy" map whose values will be created on demand.
static SortedMap lazySortedMap(SortedMap map, Factory factory)
Returns a "lazy" sorted map whose values will be created on demand.
static SortedMap lazySortedMap(SortedMap map, Transformer transformerFactory)
Returns a "lazy" sorted map whose values will be created on demand.
static Map multiValueMap(Map map)
Creates a mult-value map backed by the given map which returns collections of type ArrayList.
static Map multiValueMap(Map map, Class collectionClass)
Creates a multi-value map backed by the given map which returns collections of the specified type.
static Map multiValueMap(Map map, Factory collectionFactory)
Creates a multi-value map backed by the given map which returns collections created by the specified collection factory.
static Map orderedMap(Map map)
Returns a map that maintains the order of keys that are added backed by the given map.
static Map predicatedMap(Map map, Predicate keyPred, Predicate valuePred)
Returns a predicated (validating) map backed by the given map.
static SortedMap predicatedSortedMap(SortedMap map, Predicate keyPred, Predicate valuePred)
Returns a predicated (validating) sorted map backed by the given map.
static Map putAll(Map map, Object[] array)
Puts all the keys and values from the specified array into the map.
static void safeAddToMap(Map map, Object key, Object value)
Protects against adding null values to a map.
static Map synchronizedMap(Map map)
Returns a synchronized map backed by the given map.
static Map synchronizedSortedMap(SortedMap map)
Returns a synchronized sorted map backed by the given sorted map.
static Map toMap(ResourceBundle resourceBundle)
Creates a new HashMap using data copied from a ResourceBundle.
static Properties toProperties(Map map)
Gets a new Properties object initialised with the values from a Map.
static Map transformedMap(Map map, Transformer keyTransformer, Transformer valueTransformer)
Returns a transformed map backed by the given map.
static SortedMap transformedSortedMap(SortedMap map, Transformer keyTransformer, Transformer valueTransformer)
Returns a transformed sorted map backed by the given map.
static Map typedMap(Map map, Class keyType, Class valueType)
Returns a typed map backed by the given map.
static SortedMap typedSortedMap(SortedMap map, Class keyType, Class valueType)
Returns a typed sorted map backed by the given map.
static Map unmodifiableMap(Map map)
Returns an unmodifiable map backed by the given map.
static Map unmodifiableSortedMap(SortedMap map)
Returns an unmodifiable sorted map backed by the given sorted map.
static void verbosePrint(PrintStream out, Object label, Map map)
Prints the given map with nice line breaks.
Protected Methods
static void logInfo(Exception ex)
Logs the given exception to System.out.
[Expand]
Inherited Methods
From class java.lang.Object

Fields

public static final Map EMPTY_MAP

An empty unmodifiable map. This was not provided in JDK1.2.

public static final SortedMap EMPTY_SORTED_MAP

An empty unmodifiable sorted map. This is not provided in the JDK.

Public Constructors

public MapUtils ()

MapUtils should not normally be instantiated.

Public Methods

public static void debugPrint (PrintStream out, Object label, Map map)

Prints the given map with nice line breaks.

This method prints a nicely formatted String describing the Map. Each map entry will be printed with key, value and value classname. When the value is a Map, recursive behaviour occurs.

This method is NOT thread-safe in any special way. You must manually synchronize on either this class or the stream as required.

Parameters
out the stream to print to, must not be null
label 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.
map The map to print, may be null. If null, the text 'null' is output.
Throws
NullPointerException if the stream is null

public static Map fixedSizeMap (Map map)

Returns a fixed-sized map backed by the given map. Elements may not be added or removed from the returned map, but existing elements can be changed (for instance, via the put(Object, Object) method).

Parameters
map the map whose size to fix, must not be null
Returns
  • a fixed-size map backed by that map
Throws
IllegalArgumentException if the Map is null

public static SortedMap fixedSizeSortedMap (SortedMap map)

Returns a fixed-sized sorted map backed by the given sorted map. Elements may not be added or removed from the returned map, but existing elements can be changed (for instance, via the put(Object, Object) method).

Parameters
map the map whose size to fix, must not be null
Returns
  • a fixed-size map backed by that map
Throws
IllegalArgumentException if the SortedMap is null

public static Boolean getBoolean (Map map, Object key, Boolean defaultValue)

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

Parameters
map the map whose value to look up
key the key of the value to look up in that map
defaultValue what to return if the value is null or if the conversion fails
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

public static Boolean getBoolean (Map map, Object key)

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

If the value is a Boolean it is returned directly. If the value is a String and it equals 'true' ignoring case then true is returned, otherwise false. If the value is a Number an integer zero value returns false and non-zero returns true. Otherwise, null is returned.

Parameters
map the map to use
key the key to look up
Returns
  • the value in the Map as a Boolean, null if null map input

public static boolean getBooleanValue (Map map, Object key, boolean defaultValue)

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

If the value is a Boolean its value is returned. If the value is a String and it equals 'true' ignoring case then true is returned, otherwise false. If the value is a Number an integer zero value returns false and non-zero returns true. Otherwise, defaultValue is returned.

Parameters
map the map to use
key the key to look up
defaultValue return if the value is null or if the conversion fails
Returns
  • the value in the Map as a Boolean, defaultValue if null map input

public static boolean getBooleanValue (Map map, Object key)

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

If the value is a Boolean its value is returned. If the value is a String and it equals 'true' ignoring case then true is returned, otherwise false. If the value is a Number an integer zero value returns false and non-zero returns true. Otherwise, false is returned.

Parameters
map the map to use
key the key to look up
Returns
  • the value in the Map as a Boolean, false if null map input

public static Byte getByte (Map map, Object key)

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

The Byte is obtained from the results of getNumber(Map, Object).

Parameters
map the map to use
key the key to look up
Returns
  • the value in the Map as a Byte, null if null map input

public static Byte getByte (Map map, Object key, Byte defaultValue)

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

Parameters
map the map whose value to look up
key the key of the value to look up in that map
defaultValue what to return if the value is null or if the conversion fails
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

public static byte getByteValue (Map map, Object key)

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

The byte is obtained from the results of getNumber(Map, Object).

Parameters
map the map to use
key the key to look up
Returns
  • the value in the Map as a byte, 0 if null map input

public static byte getByteValue (Map map, Object key, byte defaultValue)

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

The byte is obtained from the results of getNumber(Map, Object).

Parameters
map the map to use
key the key to look up
defaultValue return if the value is null or if the conversion fails
Returns
  • the value in the Map as a byte, defaultValue if null map input

public static Double getDouble (Map map, Object key)

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

The Double is obtained from the results of getNumber(Map, Object).

Parameters
map the map to use
key the key to look up
Returns
  • the value in the Map as a Double, null if null map input

public static Double getDouble (Map map, Object key, Double defaultValue)

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

Parameters
map the map whose value to look up
key the key of the value to look up in that map
defaultValue what to return if the value is null or if the conversion fails
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

public static double getDoubleValue (Map map, Object key)

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

The double is obtained from the results of getNumber(Map, Object).

Parameters
map the map to use
key the key to look up
Returns
  • the value in the Map as a double, 0.0 if null map input

public static double getDoubleValue (Map map, Object key, double defaultValue)

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

The double is obtained from the results of getNumber(Map, Object).

Parameters
map the map to use
key the key to look up
defaultValue return if the value is null or if the conversion fails
Returns
  • the value in the Map as a double, defaultValue if null map input

public static Float getFloat (Map map, Object key)

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

The Float is obtained from the results of getNumber(Map, Object).

Parameters
map the map to use
key the key to look up
Returns
  • the value in the Map as a Float, null if null map input

public static Float getFloat (Map map, Object key, Float defaultValue)

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

Parameters
map the map whose value to look up
key the key of the value to look up in that map
defaultValue what to return if the value is null or if the conversion fails
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

public static float getFloatValue (Map map, Object key, float defaultValue)

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

The float is obtained from the results of getNumber(Map, Object).

Parameters
map the map to use
key the key to look up
defaultValue return if the value is null or if the conversion fails
Returns
  • the value in the Map as a float, defaultValue if null map input

public static float getFloatValue (Map map, Object key)

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

The float is obtained from the results of getNumber(Map, Object).

Parameters
map the map to use
key the key to look up
Returns
  • the value in the Map as a float, 0.0F if null map input

public static int getIntValue (Map map, Object key)

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

The int is obtained from the results of getNumber(Map, Object).

Parameters
map the map to use
key the key to look up
Returns
  • the value in the Map as an int, 0 if null map input

public static int getIntValue (Map map, Object key, int defaultValue)

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

The int is obtained from the results of getNumber(Map, Object).

Parameters
map the map to use
key the key to look up
defaultValue return if the value is null or if the conversion fails
Returns
  • the value in the Map as an int, defaultValue if null map input

public static Integer getInteger (Map map, Object key)

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

The Integer is obtained from the results of getNumber(Map, Object).

Parameters
map the map to use
key the key to look up
Returns
  • the value in the Map as a Integer, null if null map input

public static Integer getInteger (Map map, Object key, Integer defaultValue)

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

Parameters
map the map whose value to look up
key the key of the value to look up in that map
defaultValue what to return if the value is null or if the conversion fails
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

public static Long getLong (Map map, Object key, Long defaultValue)

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

Parameters
map the map whose value to look up
key the key of the value to look up in that map
defaultValue what to return if the value is null or if the conversion fails
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

public static Long getLong (Map map, Object key)

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

The Long is obtained from the results of getNumber(Map, Object).

Parameters
map the map to use
key the key to look up
Returns
  • the value in the Map as a Long, null if null map input

public static long getLongValue (Map map, Object key)

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

The long is obtained from the results of getNumber(Map, Object).

Parameters
map the map to use
key the key to look up
Returns
  • the value in the Map as a long, 0L if null map input

public static long getLongValue (Map map, Object key, long defaultValue)

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

The long is obtained from the results of getNumber(Map, Object).

Parameters
map the map to use
key the key to look up
defaultValue return if the value is null or if the conversion fails
Returns
  • the value in the Map as a long, defaultValue if null map input

public static Map getMap (Map map, Object key, Map defaultValue)

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

Parameters
map the map whose value to look up
key the key of the value to look up in that map
defaultValue what to return if the value is null or if the conversion fails
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

public static Map getMap (Map map, Object key)

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

If the value returned from the specified map is not a Map then null is returned.

Parameters
map the map to use
key the key to look up
Returns
  • the value in the Map as a Map, null if null map input

public static Number getNumber (Map map, Object key, Number defaultValue)

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

Parameters
map the map whose value to look up
key the key of the value to look up in that map
defaultValue what to return if the value is null or if the conversion fails
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

public static Number getNumber (Map map, Object key)

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

If the value is a Number it is returned directly. If the value is a String it is converted using parse(String) on the system default formatter returning null if the conversion fails. Otherwise, null is returned.

Parameters
map the map to use
key the key to look up
Returns
  • the value in the Map as a Number, null if null map input

public static Object getObject (Map map, Object key)

Gets from a Map in a null-safe manner.

Parameters
map the map to use
key the key to look up
Returns
  • the value in the Map, null if null map input

public static Object getObject (Map map, Object key, Object defaultValue)

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

Parameters
map the map whose value to look up
key the key of the value to look up in that map
defaultValue what to return if the value is null
Returns
  • the value in the map, or defaultValue if the original value is null or the map is null

public static Short getShort (Map map, Object key)

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

The Short is obtained from the results of getNumber(Map, Object).

Parameters
map the map to use
key the key to look up
Returns
  • the value in the Map as a Short, null if null map input

public static Short getShort (Map map, Object key, Short defaultValue)

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

Parameters
map the map whose value to look up
key the key of the value to look up in that map
defaultValue what to return if the value is null or if the conversion fails
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

public static short getShortValue (Map map, Object key, short defaultValue)

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

The short is obtained from the results of getNumber(Map, Object).

Parameters
map the map to use
key the key to look up
defaultValue return if the value is null or if the conversion fails
Returns
  • the value in the Map as a short, defaultValue if null map input

public static short getShortValue (Map map, Object key)

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

The short is obtained from the results of getNumber(Map, Object).

Parameters
map the map to use
key the key to look up
Returns
  • the value in the Map as a short, 0 if null map input

public static String getString (Map map, Object key, String defaultValue)

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

Parameters
map the map whose value to look up
key the key of the value to look up in that map
defaultValue what to return if the value is null or if the conversion fails
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

public static String getString (Map map, Object key)

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

The String is obtained via toString.

Parameters
map the map to use
key the key to look up
Returns
  • the value in the Map as a String, null if null map input

public static Map invertMap (Map map)

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

This operation assumes that the inverse mapping is well defined. If the input map had multiple entries with the same value mapped to different keys, the returned map will map one of those keys to the value, but the exact key which will be mapped is undefined.

Parameters
map the map to invert, may not be null
Returns
  • a new HashMap containing the inverted data
Throws
NullPointerException if the map is null

public static boolean isEmpty (Map map)

Null-safe check if the specified map is empty.

Null returns true.

Parameters
map the map to check, may be null
Returns
  • true if empty or null

public static boolean isNotEmpty (Map map)

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

Null returns false.

Parameters
map the map to check, may be null
Returns
  • true if non-null and non-empty

public static Map lazyMap (Map map, Factory factory)

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

When the key passed to the returned map's get(Object) method is not present in the map, then the factory will be used to create a new object and that object will become the value associated with that key.

For instance:

 Factory factory = new Factory() {
     public Object create() {
         return new Date();
     }
 }
 Map lazyMap = MapUtils.lazyMap(new HashMap(), factory);
 Object obj = lazyMap.get("test");
 
After the above code is executed, obj will contain a new Date instance. Furthermore, that Date instance is the value for the "test" key in the map.

Parameters
map the map to make lazy, must not be null
factory the factory for creating new objects, must not be null
Returns
  • a lazy map backed by the given map
Throws
IllegalArgumentException if the Map or Factory is null

public static Map lazyMap (Map map, Transformer transformerFactory)

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

When the key passed to the returned map's get(Object) method is not present in the map, then the factory will be used to create a new object and that object will become the value associated with that key. The factory is a Transformer that will be passed the key which it must transform into the value.

For instance:

 Transformer factory = new Transformer() {
     public Object transform(Object mapKey) {
         return new File(mapKey);
     }
 }
 Map lazyMap = MapUtils.lazyMap(new HashMap(), factory);
 Object obj = lazyMap.get("C:/dev");
 
After the above code is executed, obj will contain a new File instance for the C drive dev directory. Furthermore, that File instance is the value for the "C:/dev" key in the map.

If a lazy map is wrapped by a synchronized map, the result is a simple synchronized cache. When an object is not is the cache, the cache itself calls back to the factory Transformer to populate itself, all within the same synchronized block.

Parameters
map the map to make lazy, must not be null
transformerFactory the factory for creating new objects, must not be null
Returns
  • a lazy map backed by the given map
Throws
IllegalArgumentException if the Map or Transformer is null

public static SortedMap lazySortedMap (SortedMap map, Factory factory)

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

When the key passed to the returned map's get(Object) method is not present in the map, then the factory will be used to create a new object and that object will become the value associated with that key.

For instance:

 Factory factory = new Factory() {
     public Object create() {
         return new Date();
     }
 }
 SortedMap lazy = MapUtils.lazySortedMap(new TreeMap(), factory);
 Object obj = lazy.get("test");
 
After the above code is executed, obj will contain a new Date instance. Furthermore, that Date instance is the value for the "test" key.

Parameters
map the map to make lazy, must not be null
factory the factory for creating new objects, must not be null
Returns
  • a lazy map backed by the given map
Throws
IllegalArgumentException if the SortedMap or Factory is null

public static SortedMap lazySortedMap (SortedMap map, Transformer transformerFactory)

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

When the key passed to the returned map's get(Object) method is not present in the map, then the factory will be used to create a new object and that object will become the value associated with that key. The factory is a Transformer that will be passed the key which it must transform into the value.

For instance:

 Transformer factory = new Transformer() {
     public Object transform(Object mapKey) {
         return new File(mapKey);
     }
 }
 SortedMap lazy = MapUtils.lazySortedMap(new TreeMap(), factory);
 Object obj = lazy.get("C:/dev");
 
After the above code is executed, obj will contain a new File instance for the C drive dev directory. Furthermore, that File instance is the value for the "C:/dev" key in the map.

If a lazy map is wrapped by a synchronized map, the result is a simple synchronized cache. When an object is not is the cache, the cache itself calls back to the factory Transformer to populate itself, all within the same synchronized block.

Parameters
map the map to make lazy, must not be null
transformerFactory the factory for creating new objects, must not be null
Returns
  • a lazy map backed by the given map
Throws
IllegalArgumentException if the Map or Transformer is null

public static Map multiValueMap (Map map)

Creates a mult-value map backed by the given map which returns collections of type ArrayList.

Parameters
map the map to decorate
Returns
  • a multi-value map backed by the given map which returns ArrayLists of values.
See Also

public static Map multiValueMap (Map map, Class collectionClass)

Creates a multi-value map backed by the given map which returns collections of the specified type.

Parameters
map the map to decorate
collectionClass the type of collections to return from the map (must contain public no-arg constructor and extend Collection).
Returns
  • a multi-value map backed by the given map which returns collections of the specified type
See Also

public static Map multiValueMap (Map map, Factory collectionFactory)

Creates a multi-value map backed by the given map which returns collections created by the specified collection factory.

Parameters
map the map to decorate
collectionFactory a factor which creates collection objects
Returns
  • a multi-value map backed by the given map which returns collections created by the specified collection factory
See Also

public static Map orderedMap (Map map)

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

If a key is added twice, the order is determined by the first add. The order is observed through the keySet, values and entrySet.

Parameters
map the map to order, must not be null
Returns
  • an ordered map backed by the given map
Throws
IllegalArgumentException if the Map is null

public static Map predicatedMap (Map map, Predicate keyPred, Predicate valuePred)

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

Only objects that pass the tests in the given predicates can be added to the map. Trying to add an invalid object results in an IllegalArgumentException. Keys must pass the key predicate, values must pass the value predicate. It is important not to use the original map after invoking this method, as it is a backdoor for adding invalid objects.

Parameters
map the map to predicate, must not be null
keyPred the predicate for keys, null means no check
valuePred the predicate for values, null means no check
Returns
  • a predicated map backed by the given map
Throws
IllegalArgumentException if the Map is null

public static SortedMap predicatedSortedMap (SortedMap map, Predicate keyPred, Predicate valuePred)

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

Only objects that pass the tests in the given predicates can be added to the map. Trying to add an invalid object results in an IllegalArgumentException. Keys must pass the key predicate, values must pass the value predicate. It is important not to use the original map after invoking this method, as it is a backdoor for adding invalid objects.

Parameters
map the map to predicate, must not be null
keyPred the predicate for keys, null means no check
valuePred the predicate for values, null means no check
Returns
  • a predicated map backed by the given map
Throws
IllegalArgumentException if the SortedMap is null

public static Map putAll (Map map, Object[] array)

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

This method is an alternative to the putAll(java.util.Map) method and constructors. It allows you to build a map from an object array of various possible styles.

If the first entry in the object array implements java.util.Map.Entry or KeyValue then the key and value are added from that object. If the first entry in the object array is an object array itself, then it is assumed that index 0 in the sub-array is the key and index 1 is the value. Otherwise, the array is treated as keys and values in alternate indices.

For example, to create a color map:

 Map colorMap = MapUtils.putAll(new HashMap(), new String[][] {
     {"RED", "#FF0000"},
     {"GREEN", "#00FF00"},
     {"BLUE", "#0000FF"}
 });
 
or:
 Map colorMap = MapUtils.putAll(new HashMap(), new String[] {
     "RED", "#FF0000",
     "GREEN", "#00FF00",
     "BLUE", "#0000FF"
 });
 
or:
 Map colorMap = MapUtils.putAll(new HashMap(), new Map.Entry[] {
     new DefaultMapEntry("RED", "#FF0000"),
     new DefaultMapEntry("GREEN", "#00FF00"),
     new DefaultMapEntry("BLUE", "#0000FF")
 });
 

Parameters
map the map to populate, must not be null
array an array to populate from, null ignored
Returns
  • the input map
Throws
NullPointerException if map is null
IllegalArgumentException if sub-array or entry matching used and an entry is invalid
ClassCastException if the array contents is mixed

public static void safeAddToMap (Map map, Object key, Object value)

Protects against adding null values to a map.

This method checks the value being added to the map, and if it is null it is replaced by an empty string.

This could be useful if the map does not accept null values, or for receiving data from a source that may provide null or empty string which should be held in the same way in the map.

Keys are not validated.

Parameters
map the map to add to, may not be null
key the key
value the value, null converted to ""
Throws
NullPointerException if the map is null

public static Map synchronizedMap (Map map)

Returns a synchronized map backed by the given map.

You must manually synchronize on the returned buffer's iterator to avoid non-deterministic behavior:

 Map m = MapUtils.synchronizedMap(myMap);
 Set s = m.keySet();  // outside synchronized block
 synchronized (m) {  // synchronized on MAP!
     Iterator i = s.iterator();
     while (i.hasNext()) {
         process (i.next());
     }
 }
 
This method uses the implementation in java.util.Collections Collections.

Parameters
map the map to synchronize, must not be null
Returns
  • a synchronized map backed by the given map
Throws
IllegalArgumentException if the map is null

public static Map synchronizedSortedMap (SortedMap map)

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

You must manually synchronize on the returned buffer's iterator to avoid non-deterministic behavior:

 Map m = MapUtils.synchronizedSortedMap(myMap);
 Set s = m.keySet();  // outside synchronized block
 synchronized (m) {  // synchronized on MAP!
     Iterator i = s.iterator();
     while (i.hasNext()) {
         process (i.next());
     }
 }
 
This method uses the implementation in java.util.Collections Collections.

Parameters
map the map to synchronize, must not be null
Returns
  • a synchronized map backed by the given map
Throws
IllegalArgumentException if the map is null

public static Map toMap (ResourceBundle resourceBundle)

Creates a new HashMap using data copied from a ResourceBundle.

Parameters
resourceBundle the resource bundle to convert, may not be null
Returns
  • the hashmap containing the data
Throws
NullPointerException if the bundle is null

public static Properties toProperties (Map map)

Gets a new Properties object initialised with the values from a Map. A null input will return an empty properties object.

Parameters
map the map to convert to a Properties object, may not be null
Returns
  • the properties object

public static Map transformedMap (Map map, Transformer keyTransformer, Transformer valueTransformer)

Returns a transformed map backed by the given map.

This method returns a new map (decorating the specified map) that will transform any new entries added to it. Existing entries in the specified map will not be transformed. If you want that behaviour, see decorateTransform(Map, Transformer, Transformer).

Each object is passed through the transformers as it is added to the Map. It is important not to use the original map after invoking this method, as it is a backdoor for adding untransformed objects.

If there are any elements already in the map being decorated, they are NOT transformed.

Parameters
map the map to transform, must not be null, typically empty
keyTransformer the transformer for the map keys, null means no transformation
valueTransformer the transformer for the map values, null means no transformation
Returns
  • a transformed map backed by the given map
Throws
IllegalArgumentException if the Map is null

public static SortedMap transformedSortedMap (SortedMap map, Transformer keyTransformer, Transformer valueTransformer)

Returns a transformed sorted map backed by the given map.

This method returns a new sorted map (decorating the specified map) that will transform any new entries added to it. Existing entries in the specified map will not be transformed. If you want that behaviour, see decorateTransform(Map, Transformer, Transformer).

Each object is passed through the transformers as it is added to the Map. It is important not to use the original map after invoking this method, as it is a backdoor for adding untransformed objects.

If there are any elements already in the map being decorated, they are NOT transformed.

Parameters
map the map to transform, must not be null, typically empty
keyTransformer the transformer for the map keys, null means no transformation
valueTransformer the transformer for the map values, null means no transformation
Returns
  • a transformed map backed by the given map
Throws
IllegalArgumentException if the SortedMap is null

public static Map typedMap (Map map, Class keyType, Class valueType)

Returns a typed map backed by the given map.

Only keys and values of the specified types can be added to the map.

Parameters
map the map to limit to a specific type, must not be null
keyType the type of keys which may be added to the map, must not be null
valueType the type of values which may be added to the map, must not be null
Returns
  • a typed map backed by the specified map
Throws
IllegalArgumentException if the Map or Class is null

public static SortedMap typedSortedMap (SortedMap map, Class keyType, Class valueType)

Returns a typed sorted map backed by the given map.

Only keys and values of the specified types can be added to the map.

Parameters
map the map to limit to a specific type, must not be null
keyType the type of keys which may be added to the map, must not be null
valueType the type of values which may be added to the map, must not be null
Returns
  • a typed map backed by the specified map

public static Map unmodifiableMap (Map map)

Returns an unmodifiable map backed by the given map.

This method uses the implementation in the decorators subpackage.

Parameters
map the map to make unmodifiable, must not be null
Returns
  • an unmodifiable map backed by the given map
Throws
IllegalArgumentException if the map is null

public static Map unmodifiableSortedMap (SortedMap map)

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

This method uses the implementation in the decorators subpackage.

Parameters
map the sorted map to make unmodifiable, must not be null
Returns
  • an unmodifiable map backed by the given map
Throws
IllegalArgumentException if the map is null

public static void verbosePrint (PrintStream out, Object label, Map map)

Prints the given map with nice line breaks.

This method prints a nicely formatted String describing the Map. Each map entry will be printed with key and value. When the value is a Map, recursive behaviour occurs.

This method is NOT thread-safe in any special way. You must manually synchronize on either this class or the stream as required.

Parameters
out the stream to print to, must not be null
label 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.
map The map to print, may be null. If null, the text 'null' is output.
Throws
NullPointerException if the stream is null

Protected Methods

protected static void logInfo (Exception ex)

Logs the given exception to System.out.

This method exists as Jakarta Collections does not depend on logging.

Parameters
ex the exception to log