MapUtils (Commons Collections 4.0 API)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.apache.commons.collections
Class MapUtils

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

public class MapUtils
extends Object
extends 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:

Since:: Commons Collections 1.0
Version:: $Revision: 1.2 $ $Date: 2005/05/23 14:42:13 $
Author:: James Strachan, Nissim Karpenstein, Kasper Nielsen, Paul Jack, Stephen Colebourne, Matthew Hawthorne, Arun Mammen Thomas, Janek Bogucki, Max Rydahl Andersen, Matt Hall, John Watkinson, Ashwin S

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(PrintStream out, Object label, Map map)
Prints the given map with nice line breaks.

static



<K,V> Map<K,V>

fixedSizeMap(Map<K,V> map)
Returns a fixed-sized map backed by the given map.

static



<K,V> SortedMap<K,V>

fixedSizeSortedMap(SortedMap<K,V> map)
Returns a fixed-sized sorted map backed by the given sorted map.

static Boolean getBoolean(Map map, 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(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 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)
Gets a float from a Map in a null-safe manner.

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



<K,A,B> Map<A,B>

getMap(Map<K,Map<A,B>> map,
       K key)

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

static



<K,A,B> Map<A,B>

getMap(Map<K,Map<A,B>> map,
       K key,
       Map<A,B> 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(Map map, 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



<K,V> V

getObject(Map<K,V> map,
          K key,
          V defaultValue)

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

static



<K,V> V

getObject(Map<K,V> map,
          V key)

Gets from a Map in a null-safe manner.

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)
Gets a short from a Map in a null-safe manner.

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



<K,V> String

getString(Map<K,V> map,
          K 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



<K,V> Map<V,K>

invertMap(Map<K,V> map)
Inverts the supplied map returning a new HashMap such that the keys of the input are swapped with the values.

static



<K,V> Map<K,V>

lazyMap(Map<K,V> map,
        Factory<V> factory)

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

static



<K,V> SortedMap<K,V>

lazySortedMap(SortedMap<K,V> map,
              Factory<V> factory)

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

protected static void logInfo(Exception ex)
Logs the given exception to System.out.

static



<K,V> Map<K,V>

orderedMap(Map<K,V> map)
Returns a map that maintains the order of keys that are added backed by the given map.

static



<K,V> Map<K,V>

predicatedMap(Map<K,V> map,
              Predicate<? super K> keyPred,
              Predicate<? super V> valuePred)

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

static



<K,V> SortedMap<K,V>

predicatedSortedMap(SortedMap<K,V> map,
                    Predicate<? super K> keyPred,
                    Predicate<? super V> valuePred)

Returns a predicated (validating) 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



<K,V> Map<K,V>

synchronizedMap(Map<K,V> map)
Returns a synchronized map backed by the given map.

static



<K,V> Map<K,V>

synchronizedSortedMap(SortedMap<K,V> map)
Returns a synchronized sorted map backed by the given sorted map.

static Map<String,Object> 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)
Deprecated. this is no longer needed with Java generics.

static SortedMap typedSortedMap(SortedMap map, Class keyType, Class valueType)
Deprecated. no longer needed with Java generics.

static



<K,V> Map<K,V>

unmodifiableMap(Map<K,V> map)
Returns an unmodifiable map backed by the given map.

static



<K,V> Map<K,V>

unmodifiableSortedMap(SortedMap<K,V> 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.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

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 Detail

MapUtils

public MapUtils()

MapUtils should not normally be instantiated.

Method Detail

getObject

public static <K,V> V getObject(Map<K,V> map,
                                V 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

getString

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

getBoolean

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

getNumber

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

getByte

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

getShort

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

getInteger

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

getLong

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

getFloat

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

getDouble

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

getMap

public static <K,A,B> Map<A,B> getMap(Map<K,Map<A,B>> map,
                                      K 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

getObject

public static <K,V> V getObject(Map<K,V> map,
                                K key,
                                V 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 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

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

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

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

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

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

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

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

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

getMap

public static <K,A,B> Map<A,B> getMap(Map<K,Map<A,B>> map,
                                      K key,
                                      Map<A,B> 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

getBooleanValue

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

getByteValue

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

getShortValue

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

getIntValue

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

getLongValue

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

getFloatValue

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

getDoubleValue

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

getBooleanValue

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.

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

getByteValue

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

getShortValue

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

getIntValue

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

getLongValue

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

getFloatValue

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

getDoubleValue

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

toProperties

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

toMap

public static Map<String,Object> 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

verbosePrint

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

debugPrint

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

logInfo

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

invertMap

public static <K,V> Map<V,K> invertMap(Map<K,V> 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

safeAddToMap

public static void safeAddToMap(Map map,
                                Object key,
                                Object value)
                         throws 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.

Note: this is not a type-safe operation in Java 1.5.

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

synchronizedMap

public static <K,V> Map<K,V> synchronizedMap(Map<K,V> 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 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

unmodifiableMap

public static <K,V> Map<K,V> unmodifiableMap(Map<K,V> 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

predicatedMap

public static <K,V> Map<K,V> predicatedMap(Map<K,V> map,
                                           Predicate<? super K> keyPred,
                                           Predicate<? super V> 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

typedMap

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

Deprecated. this is no longer needed with Java generics.

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

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

fixedSizeMap

public static <K,V> Map<K,V> fixedSizeMap(Map<K,V> 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:: IllegalArgumentException - if the Map is null

lazyMap

public static <K,V> Map<K,V> lazyMap(Map<K,V> map,
                                     Factory<V> 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:: IllegalArgumentException - if the Map or Factory is null

orderedMap

public static <K,V> Map<K,V> orderedMap(Map<K,V> 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

synchronizedSortedMap

public static <K,V> Map<K,V> synchronizedSortedMap(SortedMap<K,V> 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 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

unmodifiableSortedMap

public static <K,V> Map<K,V> unmodifiableSortedMap(SortedMap<K,V> 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

predicatedSortedMap

public static <K,V> SortedMap<K,V> predicatedSortedMap(SortedMap<K,V> map,
                                                       Predicate<? super K> keyPred,
                                                       Predicate<? super V> valuePred)

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

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

typedSortedMap

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

Deprecated. no longer needed with Java generics.

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

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

fixedSizeSortedMap

public static <K,V> SortedMap<K,V> fixedSizeSortedMap(SortedMap<K,V> 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:: IllegalArgumentException - if the SortedMap is null

lazySortedMap

public static <K,V> SortedMap<K,V> lazySortedMap(SortedMap<K,V> map,
                                                 Factory<V> factory)

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

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

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.apache.commons.collections Class MapUtils

EMPTY_MAP

EMPTY_SORTED_MAP

MapUtils

getObject

getString

getBoolean

getNumber

getByte

getShort

getInteger

getLong

getFloat

getDouble

getMap

getObject

getString

getBoolean

getNumber

getByte

getShort

getInteger

getLong

getFloat

getDouble

getMap

getBooleanValue

getByteValue

getShortValue

getIntValue

getLongValue

getFloatValue

getDoubleValue

getBooleanValue

getByteValue

getShortValue

getIntValue

getLongValue

getFloatValue

getDoubleValue

toProperties

toMap

verbosePrint

debugPrint

logInfo

invertMap

safeAddToMap

synchronizedMap

unmodifiableMap

predicatedMap

typedMap

transformedMap

fixedSizeMap

lazyMap

orderedMap

synchronizedSortedMap

unmodifiableSortedMap

predicatedSortedMap

typedSortedMap

transformedSortedMap

fixedSizeSortedMap

lazySortedMap

org.apache.commons.collections
Class MapUtils