HierarchicalMap (.:. HierarchicalMap

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.dhmp.util
Interface HierarchicalMap

All Superinterfaces:: java.lang.Cloneable, java.io.Serializable

All Known Subinterfaces:: HierarchicalMap2

All Known Implementing Classes:: BasicHierarchicalMap

public interface HierarchicalMap
extends java.lang.Cloneable, java.io.Serializable

A collection type data structure with support for hierarchically organized data representation. This interface provides easy access to an object mapped in a nested map like files in directories.

Each HierarchicalMap can map either another HierarchicalMap (node) or any other Objects (leaf). These elements also can be accessed through composite key separated by slash (/), like path can reach files or directories relatively to the current directory. The toString() method is called for the object passed as key before decomposing it.

Though there are significant differences from a file system:

There is no root HierarchicalMap so the key is always relative to the current map.
HierarchicalMap itself does not have a name. There is only a key referring to the object therefore the HierarchicalMap is essentially a map.
Although this is very similar to a map, it allows duplicated keys.

The implementation must be Cloneable and Serializable.

Author:: dhmp Open Source Group

Nested Class Summary
`static interface`	`HierarchicalMap.EntrySet` Interface for entryset where a key can be specified for iterator.

Field Summary
`static java.lang.String`	`DEFAULT_PATH_SEPARATOR` Default path separator which is a forward slash "/"

Method Summary
`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.
`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)` 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.
`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.util.Collection`	`getAll(java.lang.Object key)` Returns a collection view of all the values to which this map maps 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`	`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.lang.String`	`setPathSeparator(java.lang.String pathSeparator)` Defines the characters to be considered as path separator inside key.
`int`	`size()` Returns the number of key-value mappings in this map.
`java.util.Collection`	`values()` Returns a collection view of the values contained in this map.

Field Detail

DEFAULT_PATH_SEPARATOR

public static final java.lang.String DEFAULT_PATH_SEPARATOR

Default path separator which is a forward slash "/"

See Also:: Constant Field Values

Method Detail

get

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

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)

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

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

Returns:: the value of oldest mapping.

getAll

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

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.

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.

put

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

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.

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.

add

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

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.

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 HierarchicalMap add(java.lang.Object key)

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.

Parameters:: key - key which a new HierarchicalMap is to be associated.
Returns:: new HierarchicalMap which has been added

addAll

public 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. If the map previously contained a mapping for this key, a new association will be appended to the map under same key.

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 HierarchicalMap addAll(HierarchicalMap hmap)

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

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)

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

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

remove

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

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.)

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.

removeAll

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

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.

Parameters:: key - key which mapping is to be removed from the map.
Returns:: a collection of values removed.

values

public java.util.Collection values()

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.

Returns:: a collection view of the values contained in this map.

keySet

public java.util.Set keySet()

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.

Returns:: a set view of the keys contained in this map.

entrySet

public java.util.Set entrySet()

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.

Returns:: a set view of the mappings contained in this map.

size

public int size()

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.

Returns:: the number of key-value mappings in this map.

clone

public java.lang.Object clone()

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

Returns:: a cloned HierarchicalMap.

newInstance

public HierarchicalMap newInstance()

Creates a new instance of empty HierarchicalMap.

Returns:: a new HierarchicalMap

setPathSeparator

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

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!

Parameters:: pathSeparator - new path separators.
Returns:: the previous path separators.

getPathSeparator

public java.lang.String getPathSeparator()

Returns the current characters considered as path separators.

Returns:: current path separators.

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.dhmp.util Interface HierarchicalMap

DEFAULT_PATH_SEPARATOR

get

get

getAll

put

add

add

addAll

addAll

addAll

remove

removeAll

values

keySet

entrySet

size

clone

newInstance

setPathSeparator

getPathSeparator

org.dhmp.util
Interface HierarchicalMap