ariba.util.core
Class MapUtil

java.lang.Object
  ariba.util.core.MapUtil

public final class MapUtil
extends Object

Map Utilities. These are helper functions for dealing with maps.

Nested Class Summary

static interface

MapUtil.Transformer<V,W>

Field Summary

static Class

ImmutableMapClass

Method Summary

static <K,V> Map<K,V>	cloneMap(Map<K,V> m) Helper method to clone a map
static Map	convertListToMap(List keys) Create a Map of Maps from a List.
static Map	copyMap(Map source) Copy a Map.
static Map	diff(Map change, Map baseline)
static <T> T[]	elementsArray(Map<?,? extends T> ht) Returns an Object array containing the Map's elements.
static <T> List<T>	elementsList(Map<?,? extends T> ht) Returns a List containing the Map's elements.
static Iterator	enumerationToIterator(Enumeration e) A simple wrapper to convert an Enumeration to an Iterator.
static void	fromSerializedString(Map m, String serialized) Populates the hashtable with serialized data from the string.
static Object	getPath(Map map, String path) Fetch the object (if any) in the designated Map, at the coordinates specified by the path, using dot notation.
static Map	immutableMap(Map m) Returns a version of the map that is not modifiable If m is null, null will be returned.
static int	indexOfMapInList(List l1, Map h1) Search a list for a map.
static boolean	isImmutable(Map m) Test a map to see if it is immutable.
static Enumeration	iteratorToEnumeration(Iterator i) A simple wrapper to convert an Iterator to an Enumeration.
static <T> T[]	keysArray(Map<? extends T,?> ht) Returns an Object array containing the Map's keys.
static <T> List<T>	keysList(Map<? extends T,?> ht) Returns a List containing the Map's keys.
static Map	makeImmutable(Map aMap) Make a map immutable at all levels.
static <K,V> Map<K,V>	map() Constructs an empty Map.
static <K,V> Map<K,V>	map(int initialCapacity) Constructs a Map capable of holding a specified number of elements.
static <K,V> Map<K,V>	map(Map<? extends K,? extends V> source) Creates new Map with the same contents as the given Map.
static boolean	mapEquals(Map h1, Map h2) Determine if the two maps are equal.
static <K,V,C extends Collection<V>> void	merge(Map<K,C> map, K key, Collection<? extends V> values, Factory<C> factory) Merges key and the collection of values into map, by finding the collection of values already in map and adding values to it.
static <K,V> void	merge(Map<K,List<V>> map, K key, Collection<? extends V> values) Convenience generic method that merges key and value into the supplied map.
static <K,V> void	merge(Map<K,List<V>> map, K key, V value) Convenience generic method that merges key and value into the supplied map.
static Map	mergeMapIntoMap(Map dest, Map source) Merges two Maps together.
static Map	mergeMapIntoMap(Map dest, Map source, boolean appendMergeListProperties)
static Map	mergeMapIntoMapWithObjects(Map dest, Map source) Merges two Maps together.
static Map	mergeMapIntoMapWithObjects(Map dest, Map source, boolean overwriteMismatchedClasses)
static boolean	nullOrEmptyMap(Map<?,?> map) Determine if a Map is null or empty.
static Map	overlayMapOntoMap(Map dest, Map source) Overlays source onto dest.
static Map	overwriteMap(Map overriding, Map overridden) Overwrites the contents of a given Map with the contents of another Map.
static void	overwriteMapInPlace(Map overriding, Map overridden) A version of overwriteMap that sideeffects the overriden Map directly, instead of making a copy to return.
static boolean	performDeletesOnMap(Object deletes, Map table) Applies a single deletion or list of deletions to a map.
static int	removeElement(Map ht, Object element) Finds and removes all occurrences of element from the Map.
static <K,V> SortedMap<K,V>	sortedMap() Creates an empty SortedMap
static <K,V> SortedMap<K,V>	sortedMap(Comparator<K> comparator) Creates an empty SortedMap
static <K,V> SortedMap<K,V>	sortedMap(SortedMap<? extends K,? extends V> source) Creates a new SortedMap with the same content as the given SortedMap
static String	toSerializedString(Map m) Returns a string serialization of the Hashtable using the Serializer.
static String[]	toStringArray(Map m) Converts a string into a string array for persistence purposes.
static <K,X,Y> Map<K,Y>	transformValues(Map<K,X> m, MapUtil.Transformer<X,Y> t)

Methods inherited from class java.lang.Object

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

Field Detail

ImmutableMapClass

public static final Class ImmutableMapClass

Method Detail

map

public static <K,V> Map<K,V> map()

Constructs an empty Map. The Map will grow on demand as more elements are added.

Returns:

new empty Map

cloneMap

public static <K,V> Map<K,V> cloneMap(Map<K,V> m)

Helper method to clone a map

Parameters:

m - the map to clone

Returns:

a new map of the same type

map

public static <K,V> Map<K,V> map(int initialCapacity)

Constructs a Map capable of holding a specified number of elements.

To construct a type-safe Map:

• Map<K,V> typesafe = MapUtil.map()

For a raw Map:

• Map raw = MapUtil.map()

There will be no compile warnings either way.

Parameters:

initialCapacity - the number of elements this Map is capable of holding before needing to grow.

Returns:

new empty Map with given initial capacity

map

public static <K,V> Map<K,V> map(Map<? extends K,? extends V> source)

Creates new Map with the same contents as the given Map. To construct a type-safe Map:

• Map<K,V> typesafe = MapUtil.map()

For a raw Map:

• Map raw = MapUtil.map()

There will be no compile warnings either way.

Parameters:

source - source Map

Returns:

new Map with same contents as source

sortedMap

public static <K,V> SortedMap<K,V> sortedMap()

Creates an empty SortedMap

Returns:

new empty SortedMap implementation

See Also:

SortedMap

sortedMap

public static <K,V> SortedMap<K,V> sortedMap(Comparator<K> comparator)

Creates an empty SortedMap

Parameters:

comparator - the comparator that will be used to sort this map

Returns:

new empty SortedMap implementation

See Also:

SortedMap

sortedMap

public static <K,V> SortedMap<K,V> sortedMap(SortedMap<? extends K,? extends V> source)

Creates a new SortedMap with the same content as the given SortedMap

Parameters:

source - the sorted map whose mappings are to be placed in this map

Returns:

new map containing the same mappings as the given SortedMap

See Also:

SortedMap

keysList

public static <T> List<T> keysList(Map<? extends T,?> ht)

Returns a List containing the Map's keys. If the Map contains no keys, return an empty List object.

Parameters:

ht - the table to return keys from

Returns:

the List object mentioned above.

elementsList

public static <T> List<T> elementsList(Map<?,? extends T> ht)

Returns a List containing the Map's elements. If the map containes no elements, an empty List object is returned.

Parameters:

ht - the Map whose elements are to be returned in the returned list.

Returns:

the List object mentioned above.

keysArray

public static <T> T[] keysArray(Map<? extends T,?> ht)

Returns an Object array containing the Map's keys. If the Map contains no keys, an empty array is returned.

Parameters:

ht - the table to return keys from

Returns:

the Object array above mentioned.

elementsArray

public static <T> T[] elementsArray(Map<?,? extends T> ht)

Returns an Object array containing the Map's elements.

Parameters:

ht - the table to return elements from

Returns:

the Object array mentioned above. If there the map contains no elements, an empty array is returned.

removeElement

public static int removeElement(Map ht,
                                Object element)

Finds and removes all occurrences of element from the Map. Note that this method is slow -- O(n) -- because it must scan the table searching for the element.

Parameters:

ht - the Map to modify

element - the element to search for. Map compares elements using equals().

Returns:

the number of elements removed.

nullOrEmptyMap

public static boolean nullOrEmptyMap(Map<?,?> map)

Determine if a Map is null or empty.

Parameters:

map - a map object to check

Returns:

true if map is null or empty, false otherwise

convertListToMap

public static Map convertListToMap(List keys)

Create a Map of Maps from a List. Creates a new map where each key is an element from the List v. Each element of the new map is itself an empty map.

Parameters:

keys - a List of items to become keys in created Map

Returns:

a new Map containing each element of keys.

mergeMapIntoMap

public static Map mergeMapIntoMap(Map dest,
                                  Map source)

Merges two Maps together. The source map has precedence.

The allowed keys and values in source and dest are (essentially) Strings, Lists and Maps. After the merge dest can best be described as "a union of the entries in itself and in source." That is any entries in source but not in dest will be copied into dest. For entries that are in both source and dest:

• if both entries are Strings, source overwrites dest
• if both entries are Lists they are unioned
• if both entries are Maps they are merged (hence this method is recursive)

If the entries in source and dest are not the same type, things start to get complicated and are intuitive about half the time. For instance if dest contains a List and source a String, the String in source gets added. (However, the opposite situation is not-at-all intuitive.)

Important note: the only map modified in this method is dest. No sub-maps of dest (or indeed any maps of source) are modified.

Parameters:

source - the map to merge into dest

dest - the map into which source is to be merged

Returns:

the destination map

mergeMapIntoMap

public static Map mergeMapIntoMap(Map dest,
                                  Map source,
                                  boolean appendMergeListProperties)

mergeMapIntoMapWithObjects

public static Map mergeMapIntoMapWithObjects(Map dest,
                                             Map source)

Merges two Maps together. The source map has precedence.

See mergeMapIntoMap. The only addition is that this method attempts to handle non-[String,List,Map] objects by overriding objects of one class with objects of the same class. For non-String objects, no complex operation (such as adding scalar objects to vectors) are attempted.

Parameters:

source - the map to merge into dest

dest - the map into which source is to be merged

Returns:

the destination map

mergeMapIntoMapWithObjects

public static Map mergeMapIntoMapWithObjects(Map dest,
                                             Map source,
                                             boolean overwriteMismatchedClasses)

overlayMapOntoMap

public static Map overlayMapOntoMap(Map dest,
                                    Map source)

Overlays source onto dest.

This method has similar behavior to mergeMapIntoMap(java.util.Map, java.util.Map) with the exception that no merges happen--source is simply written on top of dest. That is, every entry in source but not in dest is copied into dest. For every entry that is in both source and dest the source value overwrites the dest value.

So, in essence this method is alot simpler than mergeMapIntoMap(java.util.Map, java.util.Map).

Parameters:

source - the map to merge into dest

dest - the map into which source is to be merged

Returns:

dest

overwriteMap

public static Map overwriteMap(Map overriding,
                               Map overridden)

Overwrites the contents of a given Map with the contents of another Map.

Parameters:

overriding - the overriding Map

overridden - the Map to be overridden

Returns:

a new Map that results from the overwriting process.

overwriteMapInPlace

public static void overwriteMapInPlace(Map overriding,
                                       Map overridden)

A version of overwriteMap that sideeffects the overriden Map directly, instead of making a copy to return.

performDeletesOnMap

public static boolean performDeletesOnMap(Object deletes,
                                          Map table)

Applies a single deletion or list of deletions to a map. This is used to implement the deleteProperty AML element. deletes can be either a single string or a list of Objects. Returns false if it had any undeletable deletes.

copyMap

public static Map copyMap(Map source)

Copy a Map. This method will copy the source map and output a destination map. For each list or hastable within the source map they will also be copied,all other types will be shared. So for a map of lists or maps, this will recurse.

Parameters:

source - the source map to copy.

Returns:

the destination map.

mapEquals

public static boolean mapEquals(Map h1,
                                Map h2)

Determine if the two maps are equal. Note: this is different from Map.equals() method because this one is recursive.

Parameters:

h1 - the first Map

h2 - the second Map

Returns:

true if the two maps are equal, false otherwise

merge

public static <K,V> void merge(Map<K,List<V>> map,
                               K key,
                               V value)

Convenience generic method that merges key and value into the supplied map.

The semantics are, add value to the list of values associated with key in map.

Parameters:

map - the map to merge into

key - the key

value - the value

merge

public static <K,V,C extends Collection<V>> void merge(Map<K,C> map,
                                                       K key,
                                                       Collection<? extends V> values,
                                                       Factory<C> factory)

Merges key and the collection of values into map, by finding the collection of values already in map and adding values to it.

Parameters:

map - the map to merge into

key - the key

values - the collection of values

factory - the factory to use to create new collections if needed

merge

public static <K,V> void merge(Map<K,List<V>> map,
                               K key,
                               Collection<? extends V> values)

Convenience generic method that merges key and value into the supplied map.

The semantics are, add value to the list of values associated with key in map.

Parameters:

map - the map to merge into

key - the key

values - the values

toSerializedString

public static String toSerializedString(Map m)

Returns a string serialization of the Hashtable using the Serializer.

Returns:

string serialization of this Hashtable

See Also:

Serializer

fromSerializedString

public static void fromSerializedString(Map m,
                                        String serialized)

Populates the hashtable with serialized data from the string.

Parameters:

serialized - String containing serialized Hashtable data

getPath

public static Object getPath(Map map,
                             String path)

Fetch the object (if any) in the designated Map, at the coordinates specified by the path, using dot notation.

Parameters:

map - The map to search

path - The dotted path to traverse

Returns:

The Object at the location specified by path, if any. If no such object exists, returns null.

toStringArray

public static String[] toStringArray(Map m)

Converts a string into a string array for persistence purposes.

Returns:

string array serialization of this Hashtable

indexOfMapInList

public static int indexOfMapInList(List l1,
                                   Map h1)

Search a list for a map. Will only search this list, and not sub lists.

Parameters:

l1 - the list

h1 - the Map

Returns:

element location if the map is found, -1 otherwise

iteratorToEnumeration

public static Enumeration iteratorToEnumeration(Iterator i)

A simple wrapper to convert an Iterator to an Enumeration.

Parameters:

i - the Iterator to convert to an Enumeration

Returns:

an enumeration wrapped around the iterator

enumerationToIterator

public static Iterator enumerationToIterator(Enumeration e)

A simple wrapper to convert an Enumeration to an Iterator. The returned iterator may not support the remove() operation.

Parameters:

e - the Enumeration to convert to an Iterator

Returns:

an iterator wrapped around the enumeration

isImmutable

public static boolean isImmutable(Map m)

Test a map to see if it is immutable.

Parameters:

m - The Map to be tested

Returns:

True if the Map m is immutable, False otherwise.

immutableMap

public static Map immutableMap(Map m)

Returns a version of the map that is not modifiable If m is null, null will be returned.

makeImmutable

public static Map makeImmutable(Map aMap)

Make a map immutable at all levels. If the incoming map (aMap) contains maps and is fully mutable at all levels, it will be changed so that its contained maps are now immutable while the top level map is still mutable. Callers cannot keep references to aMap and use it as fully mutable map.

Parameters:

aMap - - the Map to be made immutable.

Returns:

An immutable Map wrapping the original map, any subMaps of which have been replaced by immutable Maps wrapping the originals.

transformValues

public static <K,X,Y> Map<K,Y> transformValues(Map<K,X> m,
                                               MapUtil.Transformer<X,Y> t)

diff

public static Map diff(Map change,
                       Map baseline)