⇒ Index (Frames) |  ⇒ Index (No Frames) |  ⇒ Package |  ⇒ Package Tree |  ⇒ Full Tree 
org.apache.commons.collections

Class MapUtils

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


public class MapUtils
extends java.lang.Object

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:

fixedSizeMap(Map)
  • fixedSizeSortedMap(SortedMap)
  • lazyMap(Map,Factory)
  • lazyMap(Map,Transformer)
  • lazySortedMap(SortedMap,Factory)
  • lazySortedMap(SortedMap,Transformer)
  • predicatedMap(Map,Predicate,Predicate)
  • predicatedSortedMap(SortedMap,Predicate,Predicate)
  • transformedMap(Map, Transformer, Transformer)
  • transformedSortedMap(SortedMap, Transformer, Transformer)
  • typedMap(Map, Class, Class)
  • typedSortedMap(SortedMap, Class, Class)
  • Since:
    Commons Collections 1.0
    Authors:
    Paul Jack
    Stephen Colebourne
    Matthew Hawthorne
    Arun Mammen Thomas
    Janek Bogucki
    Max Rydahl Andersen

    Field Summary

    static Map

    EMPTY_MAP

    An empty unmodifiable map.

    static SortedMap

    EMPTY_SORTED_MAP

    An empty unmodifiable sorted map.

    Constructor Summary

    MapUtils()

    MapUtils should not normally be instantiated.

    Method Summary

    static void

    debugPrint(final PrintStream out, final Object label, final 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(final Map map, final Object key)

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

    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

    getBooleanValue(final Map map, final Object key)

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

    static boolean

    getBooleanValue(final Map map, final 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 Byte

    getByte(final Map map, final 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(final Map map, final Object key)

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

    static byte

    getByteValue(final Map map, final 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(final Map map, final 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(final Map map, final Object key)

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

    static double

    getDoubleValue(final Map map, final 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(final Map map, final 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(final Map map, final Object key)

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

    static float

    getFloatValue(final Map map, final 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 Integer

    getInteger(final Map map, final 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 int

    getIntValue(final Map map, final Object key)

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

    static int

    getIntValue(final Map map, final 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 Long

    getLong(final Map map, final Object key)

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

    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

    getLongValue(final Map map, final Object key)

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

    static long

    getLongValue(final Map map, final 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(final Map map, final Object key)

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

    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 Number

    getNumber(final Map map, final Object key)

    Gets a Number 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 Object

    getObject(final Map map, final 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(final Map map, final 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(final Map map, final Object key)

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

    static short

    getShortValue(final Map map, final 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 String

    getString(final Map map, final Object key)

    Gets a String 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 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 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 void

    logInfo(final Exception ex)

    Logs the given exception to System.out.

    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 map backed by the given map.

    static SortedMap

    predicatedSortedMap(SortedMap map, Predicate keyPred, Predicate valuePred)

    Returns a predicated sorted map backed by the given map.

    static void

    safeAddToMap(Map map, Object key, Object value)

    Nice method for adding data to a map in such a way as to not get NPE's.

    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(final ResourceBundle resourceBundle)

    Creates a new HashMap using data copied from a ResourceBundle.

    static Properties

    toProperties(final 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(final PrintStream out, final Object label, final Map map)

    Prints the given map with nice line breaks.

    Field Details

    EMPTY_MAP

    public static final Map EMPTY_MAP

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


    EMPTY_SORTED_MAP

    public static final SortedMap EMPTY_SORTED_MAP

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

    Constructor Details

    MapUtils

    public MapUtils()

    MapUtils should not normally be instantiated.

    Method Details

    debugPrint

    public static void debugPrint(final PrintStream out, final Object label, final 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.
    map - The map to print, may be null.
    Throws:
    - if the stream is null

    fixedSizeMap

    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 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:
    - if the Map is null

    fixedSizeSortedMap

    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 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:
    - if the SortedMap is null

    getBoolean

    public static Boolean getBoolean(final Map map, final 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

    getBoolean

    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

    getBooleanValue

    public static boolean getBooleanValue(final Map map, final 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

    getBooleanValue

    public static boolean getBooleanValue(final Map map, final 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

    getByte

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

    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

    getByte

    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

    getByteValue

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

    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

    getByteValue

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

    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

    getDouble

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

    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

    getDouble

    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

    getDoubleValue

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

    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

    getDoubleValue

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

    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

    getFloat

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

    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

    getFloat

    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

    getFloatValue

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

    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

    getFloatValue

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

    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

    getInteger

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

    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

    getInteger

    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

    getIntValue

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

    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

    getIntValue

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

    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

    getLong

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

    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

    getLong

    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

    getLongValue

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

    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

    getLongValue

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

    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

    getMap

    public static Map getMap(final Map map, final 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

    getMap

    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

    getNumber

    public static Number getNumber(final Map map, final 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 NumberFormat.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

    getNumber

    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

    getObject

    public static Object getObject(final Map map, final 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

    getObject

    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

    getShort

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

    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

    getShort

    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

    getShortValue

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

    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

    getShortValue

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

    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

    getString

    public static String getString(final Map map, final 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

    getString

    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

    invertMap

    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:
    - if the map is null
    See Also:
    DoubleOrderedMap

    lazyMap

    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 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 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:
    - if the Map or Factory is null

    lazyMap

    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 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. 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:
    - if the Map or Transformer is null

    lazySortedMap

    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 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:
    - if the SortedMap or Factory is null

    lazySortedMap

    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 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. 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:
    - if the Map or Transformer is null

    logInfo

    protected static void logInfo(final 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

    orderedMap

    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:
    - if the Map is null

    predicatedMap

    public static Map predicatedMap(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, null means no check
    valuePred - the predicate for values, null means no check
    Returns:
    a predicated map backed by the given map
    Throws:
    - if the Map is null

    predicatedSortedMap

    public static SortedMap predicatedSortedMap(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, null means no check
    valuePred - the predicate for values, null means no check
    Returns:
    a predicated map backed by the given map
    Throws:
    - if the SortedMap is null

    safeAddToMap

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

    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.

    Parameters:
    map - the map to add to, may not be null
    key - the key
    value - the value
    Throws:
    - if the map is null

    synchronizedMap

    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:
    - if the map is null

    synchronizedSortedMap

    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:
    - if the map is null

    toMap

    public static Map toMap(final 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:
    - if the bundle is null

    toProperties

    public static Properties toProperties(final 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

    transformedMap

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

    Returns a transformed map backed by the given map.

    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.

    Parameters:
    map - the map to transform, must not be null
    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:
    - if the Map is null

    transformedSortedMap

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

    Returns a transformed sorted map backed by the given map.

    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.

    Parameters:
    map - the map to transform, must not be null
    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:
    - if the SortedMap is null

    typedMap

    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:
    - if the Map or Class is null

    typedSortedMap

    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

    unmodifiableMap

    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:
    - if the map is null

    unmodifiableSortedMap

    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:
    - if the map is null

    verbosePrint

    public static void verbosePrint(final PrintStream out, final Object label, final 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.
    map - The map to print, may be null.
    Throws:
    - if the stream is null