org.apache.commons.collections
Class MapUtils

java.lang.Object
  |
  +--org.apache.commons.collections.MapUtils

public class MapUtils

extends java.lang.Object

A helper class for using Map instances.

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

It also provides the following decorators:

• fixedSizeMap(Map)
• fixedSizeSortedMap(SortedMap)
• lazyMap(Map,Factory)
• lazySortedMap(SortedMap,Factory)
• predicatedMap(Map,Predicate,Predicate)
• predicatedSortedMap(SortedMap,Predicate,Predicate)

Since:

1.0

Author:

James Strachan, Nissim Karpenstein, Kasper Nielsen, Paul Jack, Stephen Colebourne

Constructor Summary

MapUtils()
Please don't instantiate a MapUtils.

Method Summary

static void	debugPrint(java.io.PrintStream out, java.lang.Object key, java.util.Map map) Prints the given map with nice line breaks.
static java.util.Map	fixedSizeMap(java.util.Map map) Returns a fixed-sized map backed by the given map.
static java.util.SortedMap	fixedSizeSortedMap(java.util.SortedMap map) Returns a fixed-sized sorted map backed by the given sorted map.
static java.lang.Boolean	getBoolean(java.util.Map map, java.lang.Object key) Looks up the given key in the given map, converting the result into a Boolean.
static java.lang.Boolean	getBoolean(java.util.Map map, java.lang.Object key, java.lang.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 java.lang.Byte	getByte(java.util.Map map, java.lang.Object key) Looks up the given key in the given map, converting the result into a Byte.
static java.lang.Byte	getByte(java.util.Map map, java.lang.Object key, java.lang.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 java.lang.Double	getDouble(java.util.Map map, java.lang.Object key) Looks up the given key in the given map, converting the result into a Double.
static java.lang.Double	getDouble(java.util.Map map, java.lang.Object key, java.lang.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 java.lang.Float	getFloat(java.util.Map map, java.lang.Object key) Looks up the given key in the given map, converting the result into a Float.
static java.lang.Float	getFloat(java.util.Map map, java.lang.Object key, java.lang.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 java.lang.Integer	getInteger(java.util.Map map, java.lang.Object key) Looks up the given key in the given map, converting the result into an Integer.
static java.lang.Integer	getInteger(java.util.Map map, java.lang.Object key, java.lang.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 java.lang.Long	getLong(java.util.Map map, java.lang.Object key) Looks up the given key in the given map, converting the result into a Long.
static java.lang.Long	getLong(java.util.Map map, java.lang.Object key, java.lang.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 java.util.Map	getMap(java.util.Map map, java.lang.Object key) Looks up the given key in the given map, returning another map.
static java.util.Map	getMap(java.util.Map map, java.lang.Object key, java.util.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 java.lang.Number	getNumber(java.util.Map map, java.lang.Object key) Looks up the given key in the given map, converting the result into a Number.
static java.lang.Number	getNumber(java.util.Map map, java.lang.Object key, java.lang.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 java.lang.Object	getObject(java.util.Map map, java.lang.Object key) Synonym for Map.get(Object).
static java.lang.Object	getObject(java.util.Map map, java.lang.Object key, java.lang.Object defaultValue) Looks up the given key in the given map, converting null into the given default value.
static java.lang.Short	getShort(java.util.Map map, java.lang.Object key) Looks up the given key in the given map, converting the result into a Short.
static java.lang.Short	getShort(java.util.Map map, java.lang.Object key, java.lang.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 java.lang.String	getString(java.util.Map map, java.lang.Object key) Looks up the given key in the given map, converting the result into a string.
static java.lang.String	getString(java.util.Map map, java.lang.Object key, java.lang.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 java.util.Map	lazyMap(java.util.Map map, Factory factory) Returns a "lazy" map whose values will be created on demand.
static java.util.SortedMap	lazySortedMap(java.util.SortedMap map, Factory factory) Returns a "lazy" sorted map whose values will be created on demand.
static java.util.Map	predicatedMap(java.util.Map map, Predicate keyPred, Predicate valuePred) Returns a predicated map backed by the given map.
static java.util.SortedMap	predicatedSortedMap(java.util.SortedMap map, Predicate keyPred, Predicate valuePred) Returns a predicated sorted map backed by the given map.
static void	safeAddToMap(java.util.Map map, java.lang.Object key, java.lang.Object value) Nice method for adding data to a map in such a way as to not get NPE's.
static java.util.Properties	toProperties(java.util.Map map) Gets a new Properties object initialised with the values from a Map.
static void	verbosePrint(java.io.PrintStream out, java.lang.Object key, java.util.Map map) Prints the given map with nice line breaks.

Methods inherited from class java.lang.Object

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

Constructor Detail

MapUtils

public MapUtils()

Please don't instantiate a MapUtils.

Method Detail

getObject

public static java.lang.Object getObject(java.util.Map map,
                                         java.lang.Object key)

Synonym for Map.get(Object).

Parameters:

map - the map whose value to look up

key - the key whose value to look up in that map

Returns:

null if the map is null; or the result of map.get(key)

getString

public static java.lang.String getString(java.util.Map map,
                                         java.lang.Object key)

Looks up the given key in the given map, converting the result into a string.

Parameters:

map - the map whose value to look up

key - the key whose value to look up in that map

Returns:

null if the map is null; null if the value mapped by that key is null; or the toString() result of the value for that key

getBoolean

public static java.lang.Boolean getBoolean(java.util.Map map,
                                           java.lang.Object key)

Looks up the given key in the given map, converting the result into a Boolean. If the map is null, this method returns null. If the value mapped by the given key is a Boolean, then it is returned as-is. Otherwise, if the value is a string, then if that string ignoring case equals "true", then a true Boolean is returned. Any other string value will result in a false Boolean being returned. OR, if the value is a Number, and that Number is 0, then a false Boolean is returned. Any other Number value results in a true Boolean being returned.

Any value that is not a Boolean, String or Number results in null being returned.

Parameters:

map - the map whose value to look up

key - the key whose value to look up in that map

Returns:

a Boolean or null

getNumber

public static java.lang.Number getNumber(java.util.Map map,
                                         java.lang.Object key)

Looks up the given key in the given map, converting the result into a Number. If the map is null, this method returns null. Otherwise, if the key maps to a Number, then that number is returned as-is. Otherwise, if the key maps to a String, that string is parsed into a number using the system default NumberFormat.

If the value is not a Number or a String, or if the value is a String that cannot be parsed into a Number, then null is returned.

Parameters:

map - the map whose value to look up

key - the key whose value to look up in that map

Returns:

a Number or null

getByte

public static java.lang.Byte getByte(java.util.Map map,
                                     java.lang.Object key)

Looks up the given key in the given map, converting the result into a Byte. First, getNumber(Map,Object) is invoked. If the result is null, then null is returned. Otherwise, the byte value of the resulting Number is returned.

Parameters:

map - the map whose value to look up

key - the key whose value to look up in that map

Returns:

a Byte or null

getShort

public static java.lang.Short getShort(java.util.Map map,
                                       java.lang.Object key)

Looks up the given key in the given map, converting the result into a Short. First, getNumber(Map,Object) is invoked. If the result is null, then null is returned. Otherwise, the short value of the resulting Number is returned.

Parameters:

map - the map whose value to look up

key - the key whose value to look up in that map

Returns:

a Short or null

getInteger

public static java.lang.Integer getInteger(java.util.Map map,
                                           java.lang.Object key)

Looks up the given key in the given map, converting the result into an Integer. First, getNumber(Map,Object) is invoked. If the result is null, then null is returned. Otherwise, the integer value of the resulting Number is returned.

Parameters:

map - the map whose value to look up

key - the key whose value to look up in that map

Returns:

an Integer or null

getLong

public static java.lang.Long getLong(java.util.Map map,
                                     java.lang.Object key)

Looks up the given key in the given map, converting the result into a Long. First, getNumber(Map,Object) is invoked. If the result is null, then null is returned. Otherwise, the long value of the resulting Number is returned.

Parameters:

map - the map whose value to look up

key - the key whose value to look up in that map

Returns:

a Long or null

getFloat

public static java.lang.Float getFloat(java.util.Map map,
                                       java.lang.Object key)

Looks up the given key in the given map, converting the result into a Float. First, getNumber(Map,Object) is invoked. If the result is null, then null is returned. Otherwise, the float value of the resulting Number is returned.

Parameters:

map - the map whose value to look up

key - the key whose value to look up in that map

Returns:

a Float or null

getDouble

public static java.lang.Double getDouble(java.util.Map map,
                                         java.lang.Object key)

Looks up the given key in the given map, converting the result into a Double. First, getNumber(Map,Object) is invoked. If the result is null, then null is returned. Otherwise, the double value of the resulting Number is returned.

Parameters:

map - the map whose value to look up

key - the key whose value to look up in that map

Returns:

a Double or null

getMap

public static java.util.Map getMap(java.util.Map map,
                                   java.lang.Object key)

Looks up the given key in the given map, returning another map. If the given map is null or if the given key doesn't map to another map, then this method returns null. Otherwise the mapped map is returned.

Parameters:

map - the map whose value to look up

key - the key whose value to look up in that map

Returns:

a Map or null

getObject

public static java.lang.Object getObject(java.util.Map map,
                                         java.lang.Object key,
                                         java.lang.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

getString

public static java.lang.String getString(java.util.Map map,
                                         java.lang.Object key,
                                         java.lang.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

getBoolean

public static java.lang.Boolean getBoolean(java.util.Map map,
                                           java.lang.Object key,
                                           java.lang.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

getNumber

public static java.lang.Number getNumber(java.util.Map map,
                                         java.lang.Object key,
                                         java.lang.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

getByte

public static java.lang.Byte getByte(java.util.Map map,
                                     java.lang.Object key,
                                     java.lang.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

getShort

public static java.lang.Short getShort(java.util.Map map,
                                       java.lang.Object key,
                                       java.lang.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

getInteger

public static java.lang.Integer getInteger(java.util.Map map,
                                           java.lang.Object key,
                                           java.lang.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

getLong

public static java.lang.Long getLong(java.util.Map map,
                                     java.lang.Object key,
                                     java.lang.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

getFloat

public static java.lang.Float getFloat(java.util.Map map,
                                       java.lang.Object key,
                                       java.lang.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

getDouble

public static java.lang.Double getDouble(java.util.Map map,
                                         java.lang.Object key,
                                         java.lang.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

getMap

public static java.util.Map getMap(java.util.Map map,
                                   java.lang.Object key,
                                   java.util.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

toProperties

public static java.util.Properties toProperties(java.util.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

Returns:

the properties object

verbosePrint

public static void verbosePrint(java.io.PrintStream out,
                                java.lang.Object key,
                                java.util.Map map)

Prints the given map with nice line breaks.

Parameters:

out - the stream to print to

key - the key that maps to the map in some other map

map - the map to print

debugPrint

public static void debugPrint(java.io.PrintStream out,
                              java.lang.Object key,
                              java.util.Map map)

Prints the given map with nice line breaks.

Parameters:

out - the stream to print to

key - the key that maps to the map in some other map

map - the map to print

safeAddToMap

public static final void safeAddToMap(java.util.Map map,
                                      java.lang.Object key,
                                      java.lang.Object value)
                               throws java.lang.NullPointerException

Nice method for adding data to a map in such a way as to not get NPE's. The point being that if the value is null, map.put() will throw an exception. That blows in the case of this class cause you may want to essentially treat put("Not Null", null ) == put("Not Null", "") We will still throw a NPE if the key is null cause that should never happen.

java.lang.NullPointerException

predicatedMap

public static java.util.Map predicatedMap(java.util.Map map,
                                          Predicate keyPred,
                                          Predicate valuePred)

Returns a predicated map backed by the given map. Only keys and values that pass the given predicates can be added to the map. It is important not to use the original map after invoking this method, as it is a backdoor for adding unvalidated objects.

Parameters:

map - the map to predicate, must not be null

keyPred - the predicate for keys, must not be null

valuePred - the predicate for values, must not be null

Returns:

a predicated map backed by the given map

Throws:

java.lang.IllegalArgumentException - if the Map or Predicates are null

fixedSizeMap

public static java.util.Map fixedSizeMap(java.util.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 Map.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:

java.lang.IllegalArgumentException - if the Map is null

lazyMap

public static java.util.Map lazyMap(java.util.Map map,
                                    Factory factory)

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

When the key passed to the returned map's Map.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 lazy = MapUtils.lazyMap(new HashMap(), 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:

java.lang.IllegalArgumentException - if the Map or Factory is null

predicatedSortedMap

public static java.util.SortedMap predicatedSortedMap(java.util.SortedMap map,
                                                      Predicate keyPred,
                                                      Predicate valuePred)

Returns a predicated sorted map backed by the given map. Only keys and values that pass the given predicates can be added to the map. It is important not to use the original map after invoking this method, as it is a backdoor for adding unvalidated objects.

Parameters:

map - the map to predicate, must not be null

keyPred - the predicate for keys, must not be null

valuePred - the predicate for values, must not be null

Returns:

a predicated map backed by the given map

Throws:

java.lang.IllegalArgumentException - if the SortedMap or Predicates are null

fixedSizeSortedMap

public static java.util.SortedMap fixedSizeSortedMap(java.util.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 Map.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:

java.lang.IllegalArgumentException - if the SortedMap is null

lazySortedMap

public static java.util.SortedMap lazySortedMap(java.util.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 Map.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:

java.lang.IllegalArgumentException - if the SortedMap or Factory is null