com.taco.data
Class MapUtilities

java.lang.Object
  extended by com.taco.data.MapUtilities

public class MapUtilities
extends java.lang.Object

A utility class for maps. This class provide facilities for wrapping and unwrapping null as a value in a map, and creating a map from an array of key/value pairs.


Field Summary
static java.lang.String NULL_MAP_VALUE
          A map value intended to represent a null value in a map.
static java.lang.Object REMOVE_MAP_VALUE
          A value in an array passed to addMappings() that indicates the corresponding key should be removed.
 
Constructor Summary
protected MapUtilities()
          This class should not be instantiated, so the sole constructor is protected.
 
Method Summary
static boolean addAllToMappedCollection(java.util.Map map, java.lang.Object key, java.util.Collection values)
          If key is already mapped to a collection, add the elements of values to the collection.
static boolean addAllToMappedCollection(java.util.Map map, java.lang.Object key, java.util.Collection values, ICollectionFactory factory)
          If key is already mapped to a collection, add the elements of values to the collection.
static java.util.Map addMappings(java.util.Map map, java.lang.Object[] array)
          Return addMappings(map, array, false) (Don't wrap null values).
static java.util.Map addMappings(java.util.Map map, java.lang.Object[] array, boolean wrap)
          Add the even elements of array as keys and the odd elements of array as values to the argument map.
static boolean addToMappedCollection(java.util.Map map, java.lang.Object key, java.lang.Object value)
          If key is already mapped to a collection, add value to the collection.
static boolean addToMappedCollection(java.util.Map map, java.lang.Object key, java.lang.Object value, ICollectionFactory factory)
          If key is already mapped to a collection, add value to the collection.
static java.util.Map arrayToHashMap(java.lang.Object[] array)
          Return arrayToMap(array, false, IMapFactory.HASH_MAP_FACTORY) (Don't wrap null values).
static java.util.Map arrayToHashMap(java.lang.Object[] array, boolean wrap)
           
static java.util.Map arrayToLinkedHashMap(java.lang.Object[] array)
          Return arrayToMap(array, false, IMapFactory.LINKED_HASH_MAP_FACTORY) (Don't wrap null values).
static java.util.Map arrayToMap(java.lang.Object[] array, boolean wrap, IMapFactory mapFactory)
          Create a new map that contains the even elements of array as keys, and the odd elements as values.
static java.util.Map createSubMap(java.util.Map map, java.lang.Object[] keysToKeep)
          Create a copy of the argument map that only has the keys in keysToKeep.
static java.util.Map createSubMap(java.util.Map map, java.lang.Object[] keysToKeep, IMapFactory mapFactory)
          Create a copy of the argument map that only has the keys in keysToKeep.
static boolean getBooleanValue(java.util.Map map, java.lang.Object key)
          If map is non-null and key is mapped to a true Boolean in map, return true.
static boolean getBooleanValue(java.util.Map map, java.lang.Object key, boolean def)
          If map is non-null and key is mapped to an object in map, return true iff object is a true Boolean.
static int getIntValue(java.util.Map map, java.lang.Object key)
          If map is non-null and key is mapped to an instance of Number in map, return the integer value of the Number.
static int getIntValue(java.util.Map map, java.lang.Object key, int def)
          If map is non-null and key is mapped to an instance of Number in map, return the integer value of the Number.
static java.lang.Object getObjectValue(java.util.Map map, java.lang.Object key)
          If map is non-null and key is mapped to an non-null object in map, return the unwrapped object.
static java.lang.Object getObjectValue(java.util.Map map, java.lang.Object key, java.lang.Object def)
          If map is non-null and key is mapped to an non-null object in map, return the unwrapped object.
static java.lang.Object unwrap(java.lang.Object value)
          Unwrap the non-null value from the map.
static java.lang.Object wrap(java.lang.Object value)
          Wrap the value for putting into a map.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

NULL_MAP_VALUE

public static final java.lang.String NULL_MAP_VALUE
A map value intended to represent a null value in a map. Because it is non-null, we can distinguish it from the null value we get when a key is not mapped.

See Also:
Constant Field Values

REMOVE_MAP_VALUE

public static final java.lang.Object REMOVE_MAP_VALUE
A value in an array passed to addMappings() that indicates the corresponding key should be removed.

Constructor Detail

MapUtilities

protected MapUtilities()
This class should not be instantiated, so the sole constructor is protected.

Method Detail

arrayToHashMap

public static final java.util.Map arrayToHashMap(java.lang.Object[] array)
Return arrayToMap(array, false, IMapFactory.HASH_MAP_FACTORY) (Don't wrap null values).


arrayToHashMap

public static final java.util.Map arrayToHashMap(java.lang.Object[] array,
                                                 boolean wrap)

arrayToLinkedHashMap

public static final java.util.Map arrayToLinkedHashMap(java.lang.Object[] array)
Return arrayToMap(array, false, IMapFactory.LINKED_HASH_MAP_FACTORY) (Don't wrap null values).


arrayToMap

public static final java.util.Map arrayToMap(java.lang.Object[] array,
                                             boolean wrap,
                                             IMapFactory mapFactory)
Create a new map that contains the even elements of array as keys, and the odd elements as values. If wrap is true, wrap null value elements before putting them in the map.

Parameters:
array - An array of keys and values. Each key in array[i] is mapped to the value in array[i + 1]. If a value is REMOVE_MAP_VALUE, the corresponding key will be removed from the map.
wrap - If true, null values are wrapped before putting them in the map.
mapFactory - The factory to use to create the returned map.
Returns:
A map created by mapFactory that has the key / value mappings in array.
Throws:
java.lang.NullPointerException - if either array or mapFactory is null

addMappings

public static final java.util.Map addMappings(java.util.Map map,
                                              java.lang.Object[] array)
Return addMappings(map, array, false) (Don't wrap null values).


addMappings

public static final java.util.Map addMappings(java.util.Map map,
                                              java.lang.Object[] array,
                                              boolean wrap)
Add the even elements of array as keys and the odd elements of array as values to the argument map. If wrap is true, wrap null value elements before putting them in the map.

Parameters:
array - An array of keys and values to add to the map. Each key in array[i] is mapped to the value in array[i + 1]. If a value is REMOVE_MAP_VALUE, the corresponding key will be removed from the map.
wrap - If true, null values are wrapped before putting them in the map.
Returns:
The argument map, which has the key / value mappings in array.
Throws:
java.lang.NullPointerException - if either map or array is null

getBooleanValue

public static final boolean getBooleanValue(java.util.Map map,
                                            java.lang.Object key)
If map is non-null and key is mapped to a true Boolean in map, return true. Otherwise, return false.


getBooleanValue

public static final boolean getBooleanValue(java.util.Map map,
                                            java.lang.Object key,
                                            boolean def)
If map is non-null and key is mapped to an object in map, return true iff object is a true Boolean. Otherwise, return def.


getIntValue

public static final int getIntValue(java.util.Map map,
                                    java.lang.Object key)
If map is non-null and key is mapped to an instance of Number in map, return the integer value of the Number. Otherwise, return 0.


getIntValue

public static final int getIntValue(java.util.Map map,
                                    java.lang.Object key,
                                    int def)
If map is non-null and key is mapped to an instance of Number in map, return the integer value of the Number. Otherwise, return def.


getObjectValue

public static final java.lang.Object getObjectValue(java.util.Map map,
                                                    java.lang.Object key)
If map is non-null and key is mapped to an non-null object in map, return the unwrapped object. Otherwise, return null.


getObjectValue

public static final java.lang.Object getObjectValue(java.util.Map map,
                                                    java.lang.Object key,
                                                    java.lang.Object def)
If map is non-null and key is mapped to an non-null object in map, return the unwrapped object. Otherwise, return def.


wrap

public static final java.lang.Object wrap(java.lang.Object value)
Wrap the value for putting into a map. If value is null, return NULL_WRAP_VALUE. Otherwise, return value.


unwrap

public static final java.lang.Object unwrap(java.lang.Object value)
Unwrap the non-null value from the map. The return value of Map.get() should be checked for null. If it is null, the key is not mapped to a value. Otherwise, the value should be unwrapped with this method. If the value is NULL_MAP_VALUE, return null. If the value is null, throw an IllegalArgumentException to catch tricky bugs. Otherwise, return value.


addToMappedCollection

public static final boolean addToMappedCollection(java.util.Map map,
                                                  java.lang.Object key,
                                                  java.lang.Object value,
                                                  ICollectionFactory factory)
If key is already mapped to a collection, add value to the collection. Otherwise, map key to a new collection (created by the factory) containing value.


addToMappedCollection

public static final boolean addToMappedCollection(java.util.Map map,
                                                  java.lang.Object key,
                                                  java.lang.Object value)
If key is already mapped to a collection, add value to the collection. Otherwise, map key to a new linked list containing value.


addAllToMappedCollection

public static final boolean addAllToMappedCollection(java.util.Map map,
                                                     java.lang.Object key,
                                                     java.util.Collection values,
                                                     ICollectionFactory factory)
If key is already mapped to a collection, add the elements of values to the collection. Otherwise, map key to a new collection (created by the factory) containing the elements of values.


addAllToMappedCollection

public static final boolean addAllToMappedCollection(java.util.Map map,
                                                     java.lang.Object key,
                                                     java.util.Collection values)
If key is already mapped to a collection, add the elements of values to the collection. Otherwise, map key to a new linked list containing the elements of values.


createSubMap

public static final java.util.Map createSubMap(java.util.Map map,
                                               java.lang.Object[] keysToKeep)
Create a copy of the argument map that only has the keys in keysToKeep. The returned map will be a hash map.


createSubMap

public static final java.util.Map createSubMap(java.util.Map map,
                                               java.lang.Object[] keysToKeep,
                                               IMapFactory mapFactory)
Create a copy of the argument map that only has the keys in keysToKeep. The returned map will be created by the argument map factory.