org.dhmp.util
Class BasicHierarchicalMap

java.lang.Object
  extended byorg.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.