org.dhmp.util
Class BasicHierarchicalMap

java.lang.Object
  org.dhmp.util.BasicHierarchicalMap

All Implemented Interfaces:

java.lang.Cloneable, HierarchicalMap, HierarchicalMap2, java.io.Serializable

public class BasicHierarchicalMap

extends java.lang.Object

implements HierarchicalMap2

Reference implementation of HierarchicalMap. Internally, it uses a LinkedHashMultiMap data structure, which is similar to java.util.LinkedHashMap but also accepts multiple occurrence of the same key. This class keeps an internal hash table with default initial size (16) and initial threshold (80%). When the quantity of entries in the hash table achieves the threshold (size * threshold) then rehash process occurs doubling the size of hash table.

This implementation is not thread safe.

Author:

hideyuki

See Also:

Serialized Form

Nested Class Summary

class

BasicHierarchicalMap.BasicHierarchicalMapCollection

Nested classes inherited from class org.dhmp.util.HierarchicalMap

HierarchicalMap.EntrySet

Field Summary

static int	ACCESS_ORDER The last element accessed using get or put method will be placed as the last element returned during iteration.
LinkedHashMultiMap	children
static int	INSERTION_ORDER Iteration will return the elements in first-in first-out order (FIFO).
static int	maximumDepth Maximum iteration that can occur during toString() method call.
static int	REVERSE_ACCESS_ORDER The last element accessed using get or put method will be placed as the first element returned during iteration.

Fields inherited from interface org.dhmp.util.HierarchicalMap

DEFAULT_PATH_SEPARATOR

Constructor Summary

BasicHierarchicalMap()
Default constructor.

BasicHierarchicalMap(int intialSize)
Constructs an empty BasicHierarchicalMap with specified initial size and default threshold (80%).

BasicHierarchicalMap(int intialSize, float loadFactor)
Constructs an empty BasicHierarchicalMap with specified initial size and loadFactor.

BasicHierarchicalMap(int intialSize, float loadFactor, int accessFormat)
Construct an empty BasicHierarchicalMap with a specific initial size, load factor, and ordering mode.

Method Summary

HierarchicalMap	add(java.lang.Object key) Associates a new HierarchicalMap with the specified key in this map.
HierarchicalMap	add(java.lang.Object[] key) Associates a new HierarchicalMap with the specified key in this map.
java.lang.Object	add(java.lang.Object[] key, java.lang.Object value) Associates the specified value with the specified key in this map.
java.lang.Object	add(java.lang.Object key, java.lang.Object value) Associates the specified value with the specified key in this map.
HierarchicalMap	addAll(HierarchicalMap hmap) Adds all the entries contained in the specified hierarchicalmap into this map.
java.lang.Object	addAll(java.lang.Object[] key, java.util.Collection values) Associates all the values contained in the specified collection with the specified key in this map.
java.util.Collection	addAll(java.lang.Object[] key, HierarchicalMap hmap) Associates all the values contained in the specified hierarchicalmap with the specified key in this map.
java.lang.Object	addAll(java.lang.Object key, java.util.Collection values) Associates all the values contained in the specified collection with the specified key in this map.
java.util.Collection	addAll(java.lang.Object key, HierarchicalMap hmap) Adds all the entries with specified key contained in the specified hierarchicalmap into this map under key.
java.lang.Object	clone() Returns a cloned HierarchicalMap.
java.util.Set	entrySet() Returns a set view of the mappings contained in this map.
boolean	equals(java.lang.Object o)
java.lang.Object	get() Returns the value of oldest mapping added to this map.
java.lang.Object	get(java.lang.Object key) Returns the value in this map associated to the specified key.
java.lang.Object	get(java.lang.Object[] key) Returns the value in this map associated to the specified key.
java.util.Collection	getAll(java.lang.Object key) Returns a collection view of all the values to which this map maps the specified key.
java.util.Collection	getAll(java.lang.Object[] key) Returns collection containing all the value in this map associated to the specified key.
java.lang.String	getPathSeparator() Returns the current characters considered as path separators.
java.util.Set	keySet() Returns a set view of the keys contained in this map.
HierarchicalMap	newInstance() Creates a new instance of empty HierarchicalMap.
java.lang.Object	put(java.lang.Object[] key, java.lang.Object value) Associates the specified value with the specified key in this map.
java.lang.Object	put(java.lang.Object key, java.lang.Object value) Associates the specified value with the specified key in this map.
java.lang.Object	remove(java.lang.Object key) Removes the mapping for this key from this map if it is present.
java.lang.Object	remove(java.lang.Object[] key) Removes the mapping for this key from this map if it is present.
java.util.Collection	removeAll(java.lang.Object key) Removes the mapping for this key from this map if it is present.
java.util.Collection	removeAll(java.lang.Object[] key) Removes the mapping for this key from this map if it is present.
java.lang.String	setPathSeparator(java.lang.String pathSeparator) Defines the characters to be considered as path separator inside key.
void	share(HierarchicalMap map) Share the same content of HierarchicalMap passed as parameter.
int	size() Returns the number of key-value mappings in this map.
java.lang.String	toString() This is same as toXMLString(maximumDepth).
java.lang.StringBuffer	toXMLString(int depth) Converts the content of this map into XML like String.
java.util.Collection	values() Returns a collection view of the values contained in this map.

Methods inherited from class java.lang.Object

finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

INSERTION_ORDER

public static final int INSERTION_ORDER

Iteration will return the elements in first-in first-out order (FIFO). The method get() will return the first/oldest inserted element. Insertion order does not change the map structure.

See Also:

Constant Field Values

ACCESS_ORDER

public static final int ACCESS_ORDER

The last element accessed using get or put method will be placed as the last element returned during iteration. Useful for implement Least Recently Use (LRU) algorithm. The method get() will return the first/oldest inserted element.

See Also:

Constant Field Values

REVERSE_ACCESS_ORDER

public static final int REVERSE_ACCESS_ORDER

The last element accessed using get or put method will be placed as the first element returned during iteration. The method get() will return the last/newest inserted element.

See Also:

Constant Field Values

maximumDepth

public static int maximumDepth

Maximum iteration that can occur during toString() method call. It prevents infinite loop while converting the content into String when HierarchicalMap contains a recursive reference. This is set to 10 by default. Use toXMLString(int depth) instead to override the default depth.

children

public LinkedHashMultiMap children

Constructor Detail

BasicHierarchicalMap

public BasicHierarchicalMap()

Default constructor.

BasicHierarchicalMap

public BasicHierarchicalMap(int intialSize)

Constructs an empty BasicHierarchicalMap with specified initial size and default threshold (80%).

Parameters:

intialSize - initial size

BasicHierarchicalMap

public BasicHierarchicalMap(int intialSize,
                            float loadFactor)

Constructs an empty BasicHierarchicalMap with specified initial size and loadFactor.

Parameters:

intialSize - initial size. Default is 11

loadFactor - the load factor (> 0, not NaN) that triggers rehashing. Default is 0.75

BasicHierarchicalMap

public BasicHierarchicalMap(int intialSize,
                            float loadFactor,
                            int accessFormat)

Construct an empty BasicHierarchicalMap with a specific initial size, load factor, and ordering mode.

Parameters:

intialSize - initial size. Default is 11

loadFactor - the load factor (> 0, not NaN) that triggers rehashing. Default is 0.75

accessFormat - ACCESS_ORDER, INSERTION_ORDER or REVERSE_ACCESS_ORDER

Throws:

java.lang.IllegalArgumentException - if (initialCapacity < 0) || ! (loadFactor > 0.0)

Method Detail

get

public java.lang.Object get(java.lang.Object key)

Description copied from interface: HierarchicalMap

Returns the value in this map associated to the specified key. Returns null if the map contains no mapping for this key. A return value of null does not necessarily indicate that the map contains no mapping for the key; it's also possible that the map explicitly maps the key to null, however it is not possible to represent a composed key containing null key. The key can be composed by subsequent keys separated by slash "/". When there is a multiple occurrence of the same key, it will return the first object associated to that key. This method will try to get the key checking only the first occurrence of each node. So a structure like below will get the null as returning value for get("Order/Address/Province"):

 Order
    Address
        State = "California"
        Country = "USA"
    Address
        Province = "Hiroshima"
        Country = "Japan"
 

The result is the same as: get("Order").get("Address").get("Province")
(Note: actually the code above needs casting to work)

Specified by:

get in interface HierarchicalMap

Parameters:

key - key whose associated value is to be returned.

Returns:

the value to which this map maps the specified key, or null if the map contains no mapping for this key.

get

public java.lang.Object get(java.lang.Object[] key)

Description copied from interface: HierarchicalMap2

Returns the value in this map associated to the specified key. Returns null if the map contains no mapping for this key. This method is similar to get(Object key) except that the key is an Object array.

Specified by:

get in interface HierarchicalMap2

Parameters:

key - key array whose associated value is to be returned.

Returns:

the value to which this map maps the specified key array, or null if the map contains no mapping for this key.

See Also:

HierarchicalMap.get(Object key)

get

public java.lang.Object get()

Description copied from interface: HierarchicalMap

Returns the value of oldest mapping added to this map. Returns null if the map contains no mapping at all.

Specified by:

get in interface HierarchicalMap

Returns:

the value of oldest mapping.

getAll

public java.util.Collection getAll(java.lang.Object key)

Description copied from interface: HierarchicalMap

Returns a collection view of all the values to which this map maps the specified key. Returns empty collection if the map contains no mapping for this key.

Specified by:

getAll in interface HierarchicalMap

Parameters:

key - key which associated value is to be returned.

Returns:

a collection of values associated to the specified key, or an empty collection if the map contains no mapping for this key.

getAll

public java.util.Collection getAll(java.lang.Object[] key)

Description copied from interface: HierarchicalMap2

Returns collection containing all the value in this map associated to the specified key. Returns null if the map contains no mapping for this key. This method is similar to getAll(Object key) except that the key is an Object array.

Specified by:

getAll in interface HierarchicalMap2

Parameters:

key - key array whose associated value is to be returned.

Returns:

a collection of values associated to the specified key array, or an empty collection if the map contains no mapping for this key.

See Also:

HierarchicalMap.getAll(Object key)

put

public java.lang.Object put(java.lang.Object key,
                            java.lang.Object value)

Description copied from interface: HierarchicalMap

Associates the specified value with the specified key in this map. If the map previously contained a mapping for this key, the old value is replaced by the specified value. When there is a multiple occurrence of the same key, it will replace the first object associated to that key.

Specified by:

put in interface HierarchicalMap

Parameters:

key - key which the specified value is to be associated.

value - value to be associated with the specified key.

Returns:

previous value associated with specified key, or null if there was no mapping for key. A null return can also indicate that the map previously associated null with the specified key, if the implementation supports null values.

put

public java.lang.Object put(java.lang.Object[] key,
                            java.lang.Object value)

Description copied from interface: HierarchicalMap2

Associates the specified value with the specified key in this map. If the map previously contained a mapping for this key, the old value is replaced by the specified value. This method is similar to put(Object key, Object value) except that the key is an Object array.

Specified by:

put in interface HierarchicalMap2

Parameters:

key - key array which the specified value is to be associated.

value - value to be associated with the specified key.

Returns:

previous value associated with specified key, or null if there was no mapping for key. A null return can also indicate that the map previously associated null with the specified key, if the implementation supports null values.

See Also:

HierarchicalMap.put(Object key, Object value)

add

public java.lang.Object add(java.lang.Object key,
                            java.lang.Object value)

Description copied from interface: HierarchicalMap

Associates the specified value with the specified key in this map. If the map previously contained a mapping for this key, a new association will be appended to the map under the same key.

Specified by:

add in interface HierarchicalMap

Parameters:

key - key which the specified value is to be associated.

value - value to be associated with the specified key.

Returns:

current value which has been added

add

public java.lang.Object add(java.lang.Object[] key,
                            java.lang.Object value)

Description copied from interface: HierarchicalMap2

Associates the specified value with the specified key in this map. This method is similar to add(Object key, Object value) except that the key is an Object array.

Specified by:

add in interface HierarchicalMap2

Parameters:

key - key array which the specified value is to be associated.

value - value to be associated with the specified key.

Returns:

current value which has been added

See Also:

HierarchicalMap.add(Object key, Object value)

add

public HierarchicalMap add(java.lang.Object key)

Description copied from interface: HierarchicalMap

Associates a new HierarchicalMap with the specified key in this map. If the map previously contained a mapping for this key, a new association will be appended to the map under the same key.

Specified by:

add in interface HierarchicalMap

Parameters:

key - key which a new HierarchicalMap is to be associated.

Returns:

new HierarchicalMap which has been added

add

public HierarchicalMap add(java.lang.Object[] key)

Description copied from interface: HierarchicalMap2

Associates a new HierarchicalMap with the specified key in this map. This method is similar to add(Object key) except that the key is an Object array.

Specified by:

add in interface HierarchicalMap2

Parameters:

key - key array which a new HierarchicalMap is to be associated.

Returns:

new HierarchicalMap which has been added

See Also:

HierarchicalMap.add(Object key)

addAll

public java.lang.Object addAll(java.lang.Object key,
                               java.util.Collection values)

Description copied from interface: HierarchicalMap

Associates all the values contained in the specified collection with the specified key in this map. If the map previously contained a mapping for this key, a new association will be appended to the map under same key.

Specified by:

addAll in interface HierarchicalMap

Parameters:

key - key which the specified values is to be associated.

values - a collection containing the values to be associated with the specified key.

Returns:

current collection which has been added

addAll

public java.lang.Object addAll(java.lang.Object[] key,
                               java.util.Collection values)

Description copied from interface: HierarchicalMap2

Associates all the values contained in the specified collection with the specified key in this map. This method is similar to addAll(Object key, Collection values) except that the key is an Object array.

Specified by:

addAll in interface HierarchicalMap2

Parameters:

key - key array which the specified values is to be associated.

values - a collection containing the values to be associated with the specified key.

Returns:

current collection which has been added

See Also:

HierarchicalMap.addAll(Object key, Collection values)

addAll

public HierarchicalMap addAll(HierarchicalMap hmap)

Description copied from interface: HierarchicalMap

Adds all the entries contained in the specified hierarchicalmap into this map.

Specified by:

addAll in interface HierarchicalMap

Parameters:

hmap - a hierarchicalmap containing the entries to be added.

Returns:

original hierarchicalmap which has been added

addAll

public java.util.Collection addAll(java.lang.Object key,
                                   HierarchicalMap hmap)

Description copied from interface: HierarchicalMap

Adds all the entries with specified key contained in the specified hierarchicalmap into this map under key.

Specified by:

addAll in interface HierarchicalMap

Parameters:

key - specifying the source and target.

hmap - a hierarchicalmap containing the entries to be added.

Returns:

collection containing all objects in hmap referenced by key

addAll

public java.util.Collection addAll(java.lang.Object[] key,
                                   HierarchicalMap hmap)

Description copied from interface: HierarchicalMap2

Associates all the values contained in the specified hierarchicalmap with the specified key in this map. This method is similar to addAll(Object key, HierarchicalMap hmap) except that the key is an Object array.

Specified by:

addAll in interface HierarchicalMap2

Parameters:

key - key array which the specified values is to be associated.

hmap - a HierarchicalMap containing the values to be associated with the specified key.

Returns:

collection containing all objects in hmap referenced by key

See Also:

HierarchicalMap.addAll(Object key, HierarchicalMap hmap)

remove

public java.lang.Object remove(java.lang.Object key)

Description copied from interface: HierarchicalMap

Removes the mapping for this key from this map if it is present. When there is a multiple occurrence of the same key, it will remove the first object associated to that key. Returns the value to which the map previously associated the key, or null if the map contained no mapping for this key. (A null return can also indicate that the map previously associated null with the specified key if the implementation supports null values.)

Specified by:

remove in interface HierarchicalMap

Parameters:

key - key which mapping is to be removed from the map.

Returns:

previous value associated with specified key, or null if there was no mapping for key.

remove

public java.lang.Object remove(java.lang.Object[] key)

Description copied from interface: HierarchicalMap2

Removes the mapping for this key from this map if it is present. This method is similar to remove(Object key) except that the key is an Object array.

Specified by:

remove in interface HierarchicalMap2

Parameters:

key - key array which mapping is to be removed from the map.

Returns:

previous value associated with specified key, or null if there was no mapping for key.

See Also:

HierarchicalMap.remove(Object key)

removeAll

public java.util.Collection removeAll(java.lang.Object key)

Description copied from interface: HierarchicalMap

Removes the mapping for this key from this map if it is present. When there is a multiple occurrence of the same key, it will remove all the objects associated to that key. Returns a collection of the values to which the map previously associated the key, or an empty collection if the map contained no mapping for this key.

Specified by:

removeAll in interface HierarchicalMap

Parameters:

key - key which mapping is to be removed from the map.

Returns:

a collection of values removed.

removeAll

public java.util.Collection removeAll(java.lang.Object[] key)

Description copied from interface: HierarchicalMap2

Removes the mapping for this key from this map if it is present. This method is similar to removeAll(Object key) except that the key is an Object array.

Specified by:

removeAll in interface HierarchicalMap2

Parameters:

key - key array which mapping is to be removed from the map.

Returns:

a collection of values removed.

See Also:

HierarchicalMap.removeAll(Object key)

values

public java.util.Collection values()

Description copied from interface: HierarchicalMap

Returns a collection view of the values contained in this map. The collection is backed by the map, so changes to the map are reflected in the collection, and vice-versa. If the map is modified while an iteration over the collection is in progress, the results of the iteration are undefined. The collection supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove. It does not support the add or addAll operations.

Specified by:

values in interface HierarchicalMap

Returns:

a collection view of the values contained in this map.

keySet

public java.util.Set keySet()

Description copied from interface: HierarchicalMap

Returns a set view of the keys contained in this map. The set is backed by the map, so changes to the map are reflected in the set, and vice-versa. If the map is modified while an iteration over the set is in progress, the results of the iteration are undefined. The set supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove. It does not support the add or addAll operations.

Specified by:

keySet in interface HierarchicalMap

Returns:

a set view of the keys contained in this map.

entrySet

public java.util.Set entrySet()

Description copied from interface: HierarchicalMap

Returns a set view of the mappings contained in this map. Each element in the returned set is a Map.Entry. The set is backed by the map, so changes to the map are reflected in the set, and vice-versa. If the map is modified while an iteration over the set is in progress, the results of the iteration are undefined. The set supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove. It does not support the add or addAll operations.

Specified by:

entrySet in interface HierarchicalMap

Returns:

a set view of the mappings contained in this map.

size

public int size()

Description copied from interface: HierarchicalMap

Returns the number of key-value mappings in this map. If the map contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE. This method does not recursively count the elements in HierarchicalMap mapped as a value in current map.

Specified by:

size in interface HierarchicalMap

Returns:

the number of key-value mappings in this map.

toXMLString

public java.lang.StringBuffer toXMLString(int depth)

Converts the content of this map into XML like String. Each element inside Map will be converted to String representation surrounded by <key> and </key>. This method does not check for the occurrence of recursive reference. An error message "<Error>Too many recursion. String truncated...</Error>" will be placed when maximum depth is reached during the String conversion.

Parameters:

depth - maximum number of iteration allowed during String convention.

Returns:

content of this map converted into String.

toString

public java.lang.String toString()

This is same as toXMLString(maximumDepth).

Returns:

content of this map converted into String.

clone

public java.lang.Object clone()

Description copied from interface: HierarchicalMap

Returns a cloned HierarchicalMap. This method only duplicates the nodes, i.e. HierarhcicalMaps. The leaf objects are shared between original and copied HierarchicalMaps.

Specified by:

clone in interface HierarchicalMap

equals

public boolean equals(java.lang.Object o)

share

public void share(HierarchicalMap map)
           throws java.lang.IllegalArgumentException

Share the same content of HierarchicalMap passed as parameter. So both HierarchicalMap will contain the same information and any method that change the structure, like put, add or remove applied on one Map will reflect on to other Map.

Parameters:

map - the map in which the content will be shared.

Throws:

java.lang.IllegalArgumentException - is thrown when passed Map is not a instance of BasicHierarchicalMap.

newInstance

public HierarchicalMap newInstance()

Description copied from interface: HierarchicalMap

Creates a new instance of empty HierarchicalMap.

Specified by:

newInstance in interface HierarchicalMap

Returns:

a new HierarchicalMap

getPathSeparator

public java.lang.String getPathSeparator()

Description copied from interface: HierarchicalMap

Returns the current characters considered as path separators.

Specified by:

getPathSeparator in interface HierarchicalMap

Returns:

current path separators.

setPathSeparator

public java.lang.String setPathSeparator(java.lang.String pathSeparator)

Description copied from interface: HierarchicalMap

Defines the characters to be considered as path separator inside key. All the characters in the String pathSeparator will be considered as delimiters for separating key's tokens. Delimiter characters themselves will not be treated as tokens. We discourage the use of this method unless there is a strong reason for doing that. A data structure containing mixed path separator can be unmanageable!

Specified by:

setPathSeparator in interface HierarchicalMap

Parameters:

pathSeparator - new path separators.

Returns:

the previous path separators.