Java Doc for MapUtils.java in  » Library » Apache-common-Collections » org » apache » commons » collections » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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

It also provides the following decorators:

• MapUtils.fixedSizeMap(Map)
• MapUtils.fixedSizeSortedMap(SortedMap)
• MapUtils.lazyMap(Map,Factory)
• MapUtils.lazyMap(Map,Transformer)
• MapUtils.lazySortedMap(SortedMap,Factory)
• MapUtils.lazySortedMap(SortedMap,Transformer)
• MapUtils.predicatedMap(Map,Predicate,Predicate)
• MapUtils.predicatedSortedMap(SortedMap,Predicate,Predicate)
• MapUtils.transformedMap(Map,Transformer,Transformer)
• MapUtils.transformedSortedMap(SortedMap,Transformer,Transformer)
• MapUtils.typedMap(Map,Class,Class)
• MapUtils.typedSortedMap(SortedMap,Class,Class)
• MapUtils.multiValueMap(Map)
• MapUtils.multiValueMap(Map,Class)
• MapUtils.multiValueMap(Map,Factory)

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.

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");
 

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.

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");
 

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.

This method is an alternative to the java.util.Map.putAll(java.util.Map) method and constructors.

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

Each object is passed through the transformers as it is added to the Map.

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

Each object is passed through the transformers as it is added to the Map.

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.

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
Parameters:
  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.
Parameters:
  map - The map to print, may be null.If null, the text 'null' is output.
throws:
  NullPointerException - if the stream is null

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
Parameters:
  key - the key to look up the value in the Map as a Boolean, null if null map input

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
Parameters:
  key - the key to look up the value in the Map as a Boolean, false if null map input

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
Parameters:
  key - the key to look up
Parameters:
  defaultValue - return if the value is null or if theconversion fails the value in the Map as a Boolean, defaultValue if null map input

The Byte is obtained from the results of MapUtils.getNumber(Map,Object) .
Parameters:
  map - the map to use
Parameters:
  key - the key to look up the value in the Map as a Byte, null if null map input

The byte is obtained from the results of MapUtils.getNumber(Map,Object) .
Parameters:
  map - the map to use
Parameters:
  key - the key to look up the value in the Map as a byte, 0 if null map input

The byte is obtained from the results of MapUtils.getNumber(Map,Object) .
Parameters:
  map - the map to use
Parameters:
  key - the key to look up
Parameters:
  defaultValue - return if the value is null or if theconversion fails the value in the Map as a byte, defaultValue if null map input

The Double is obtained from the results of MapUtils.getNumber(Map,Object) .
Parameters:
  map - the map to use
Parameters:
  key - the key to look up the value in the Map as a Double, null if null map input

The double is obtained from the results of MapUtils.getNumber(Map,Object) .
Parameters:
  map - the map to use
Parameters:
  key - the key to look up the value in the Map as a double, 0.0 if null map input

The double is obtained from the results of MapUtils.getNumber(Map,Object) .
Parameters:
  map - the map to use
Parameters:
  key - the key to look up
Parameters:
  defaultValue - return if the value is null or if theconversion fails the value in the Map as a double, defaultValue if null map input

The Float is obtained from the results of MapUtils.getNumber(Map,Object) .
Parameters:
  map - the map to use
Parameters:
  key - the key to look up the value in the Map as a Float, null if null map input

The float is obtained from the results of MapUtils.getNumber(Map,Object) .
Parameters:
  map - the map to use
Parameters:
  key - the key to look up the value in the Map as a float, 0.0F if null map input

The float is obtained from the results of MapUtils.getNumber(Map,Object) .
Parameters:
  map - the map to use
Parameters:
  key - the key to look up
Parameters:
  defaultValue - return if the value is null or if theconversion fails the value in the Map as a float, defaultValue if null map input

The int is obtained from the results of MapUtils.getNumber(Map,Object) .
Parameters:
  map - the map to use
Parameters:
  key - the key to look up the value in the Map as an int, 0 if null map input

The int is obtained from the results of MapUtils.getNumber(Map,Object) .
Parameters:
  map - the map to use
Parameters:
  key - the key to look up
Parameters:
  defaultValue - return if the value is null or if theconversion fails the value in the Map as an int, defaultValue if null map input

The Integer is obtained from the results of MapUtils.getNumber(Map,Object) .
Parameters:
  map - the map to use
Parameters:
  key - the key to look up the value in the Map as a Integer, null if null map input

The Long is obtained from the results of MapUtils.getNumber(Map,Object) .
Parameters:
  map - the map to use
Parameters:
  key - the key to look up the value in the Map as a Long, null if null map input

The long is obtained from the results of MapUtils.getNumber(Map,Object) .
Parameters:
  map - the map to use
Parameters:
  key - the key to look up the value in the Map as a long, 0L if null map input

The long is obtained from the results of MapUtils.getNumber(Map,Object) .
Parameters:
  map - the map to use
Parameters:
  key - the key to look up
Parameters:
  defaultValue - return if the value is null or if theconversion fails the value in the Map as a long, defaultValue if null map input

If the value returned from the specified map is not a Map then null is returned.
Parameters:
  map - the map to use
Parameters:
  key - the key to look up the value in the Map as a Map, null if null map input

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
Parameters:
  key - the key to look up the value in the Map as a Number, null if null map input

The Short is obtained from the results of MapUtils.getNumber(Map,Object) .
Parameters:
  map - the map to use
Parameters:
  key - the key to look up the value in the Map as a Short, null if null map input

The short is obtained from the results of MapUtils.getNumber(Map,Object) .
Parameters:
  map - the map to use
Parameters:
  key - the key to look up the value in the Map as a short, 0 if null map input

The short is obtained from the results of MapUtils.getNumber(Map,Object) .
Parameters:
  map - the map to use
Parameters:
  key - the key to look up
Parameters:
  defaultValue - return if the value is null or if theconversion fails the value in the Map as a short, defaultValue if null map input

The String is obtained via toString.
Parameters:
  map - the map to use
Parameters:
  key - the key to look up the value in the Map as a String, null if null map input

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 a new HashMap containing the inverted data
throws:
  NullPointerException - if the map is null

Null returns true.
Parameters:
  map - the map to check, may be null true if empty or null
since:
   Commons Collections 3.2

Null returns false.
Parameters:
  map - the map to check, may be null true if non-null and non-empty
since:
   Commons Collections 3.2

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");
 

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");
 

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
Parameters:
  transformerFactory - the factory for creating new objects, must not be null a lazy map backed by the given map
throws:
  IllegalArgumentException - if the Map or Transformer is null

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");
 

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");
 

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
Parameters:
  transformerFactory - the factory for creating new objects, must not be null a lazy map backed by the given map
throws:
  IllegalArgumentException - if the Map or Transformer is null

This method exists as Jakarta Collections does not depend on logging.
Parameters:
  ex - the exception to log

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 an ordered map backed by the given map
throws:
  IllegalArgumentException - if the Map is null

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
Parameters:
  keyPred - the predicate for keys, null means no check
Parameters:
  valuePred - the predicate for values, null means no check a predicated map backed by the given map
throws:
  IllegalArgumentException - if the Map is null

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
Parameters:
  keyPred - the predicate for keys, null means no check
Parameters:
  valuePred - the predicate for values, null means no check a predicated map backed by the given map
throws:
  IllegalArgumentException - if the SortedMap is null

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

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

For example, to create a color map:

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

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

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

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

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

Keys are not validated.
Parameters:
  map - the map to add to, may not be null
Parameters:
  key - the key
Parameters:
  value - the value, null converted to ""
throws:
  NullPointerException - if the map is null

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());
 }
 }
 

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 returns a new map (decorating the specified map) that will transform any new entries added to it. Existing entries in the specified map will not be transformed. If you want that behaviour, see TransformedMap.decorateTransform .

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

If there are any elements already in the map being decorated, they are NOT transformed.
Parameters:
  map - the map to transform, must not be null, typically empty
Parameters:
  keyTransformer - the transformer for the map keys, null means no transformation
Parameters:
  valueTransformer - the transformer for the map values, null means no transformation a transformed map backed by the given map
throws:
  IllegalArgumentException - if the Map is null

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

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

If there are any elements already in the map being decorated, they are NOT transformed.
Parameters:
  map - the map to transform, must not be null, typically empty
Parameters:
  keyTransformer - the transformer for the map keys, null means no transformation
Parameters:
  valueTransformer - the transformer for the map values, null means no transformation a transformed map backed by the given map
throws:
  IllegalArgumentException - if the SortedMap is null

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
Parameters:
  keyType - the type of keys which may be added to the map, must not be null
Parameters:
  valueType - the type of values which may be added to the map, must not be null a typed map backed by the specified map
throws:
  IllegalArgumentException - if the Map or Class is null

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
Parameters:
  keyType - the type of keys which may be added to the map, must not be null
Parameters:
  valueType - the type of values which may be added to the map, must not be null a typed map backed by the specified map

This method uses the implementation in the decorators subpackage.
Parameters:
  map - the map to make unmodifiable, must not be null an unmodifiable map backed by the given map
throws:
  IllegalArgumentException - if the map is null

This method uses the implementation in the decorators subpackage.
Parameters:
  map - the sorted map to make unmodifiable, must not be null an unmodifiable map backed by the given map
throws:
  IllegalArgumentException - if the map is null

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
Parameters:
  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.
Parameters:
  map - The map to print, may be null.If null, the text 'null' is output.
throws:
  NullPointerException - if the stream is null