org.refcodes.structure

Interface PathMap<T>

Type Parameters:

T - The type of the terminating elements.

All Superinterfaces:

Containable, org.refcodes.mixin.DelimiterAccessor, Dictionary<String,T>, org.refcodes.mixin.Dumpable, Keys<String,T>, org.refcodes.mixin.TypeAccessor<T>

All Known Subinterfaces:

CanonicalMap, CanonicalMap.CanonicalMapBuilder, CanonicalMap.MutableCanonicalMap, PathMap.MutablePathMap<T>, PathMap.PathMapBuilder<T>, ProfileProperties, ProfileProperties.MutableProfileProperties, ProfileProperties.ProfilePropertiesBuilder, Properties, Properties.MutableProperties, Properties.PropertiesBuilder

All Known Implementing Classes:

CanonicalMapBuilderImpl, CanonicalMapImpl, PathMapBuilderImpl, PathMapImpl, ProfilePropertiesBuilderImpl, ProfilePropertiesImpl, PropertiesBuilderImpl, PropertiesImpl

public interface PathMap<T>
extends Dictionary<String,T>, org.refcodes.mixin.DelimiterAccessor, org.refcodes.mixin.TypeAccessor<T>, org.refcodes.mixin.Dumpable

A PathMap is a flat map by which each element is addressed by a path; represented by the PathMap's keys. Each path's elements is separated from each other by the DelimiterAccessor.getDelimiter() character, which, by default, is set to '/'. For the sake of simplicity, we assume a path delimiter of '/' being used when describing the functioning of the PathMap. The PathMap distinguishes between records and directories. A record is reckoned to be the last path element in a path pointing to a value. In contrast a directory is reckoned to be be a path element pointing to a succeeding child path element (sub-directory). Given the example below, "dilbert", "otto", "loki" and "gred" are reckoned to be records whereas "animals", "dogs", "machines" and "robots" are recokned to be records:

• "/animals/dogs/dilbert"
• "/animals/dogs/otto"
• "/animals/loki"
• "/machines/robots/greg"

To address an element in a PathMap, an absolute path is to be provided, e.g. the provided path must start with the path delimiter. A valid path would look something alike "/animals/dogs/otto". A path is also defined to be an absolute path if it does not(!) begin with a delimiter, e.g. both paths "/machines/robots/greg" and "machines/robots/greg" point to the same "greg" record. Elements in a PathMap are reckoned to be an array when they belong to the same hierarchy level and when their keys represent integer numbers. Given the below example, the elements below "/animals/dogs" can be represented as an array with five elements (the path is denoted at the left hand side of the assignment ":=" and the value at the right and side accordingly):

• "/animals/dogs/0" := "ace"
• "/animals/dogs/1" := "bandit"
• "/animals/dogs/2" := "radar"
• "/animals/dogs/3" := "echo"
• "/animals/dogs/4" := "snoopy"

The resulting array when calling getArray(String) for the path "/animals/dogs" would contain {"ace", "bandit", "radar", "echo", "snoopy"}. Calling isArray("/animals/dogs") would return true whereas calling isArray("/animals") would return false. Before processing, an implementation of the PathMap should call toNormalizedPath(String) for each path provided, which will remove any trailing path separators and add any missing prefixed delimiter. As all the keys in the PathMap represent paths, we can apply some path specific logic to a PathMap. This is reflected by methods such as PathMap.MutablePathMap.insertFrom(Object, String) and PathMap.MutablePathMap.insertTo(String, Object) or retrieveFrom(String) and retrieveTo(String).

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	PathMap.MutablePathMap<T> Extends the PathMap with mutator functionality.
static interface	PathMap.PathMapBuilder<T> Extends the PathMap with mutator functionality.

Nested classes/interfaces inherited from interface org.refcodes.structure.Dictionary

Dictionary.MutableDictionary<K,V>

Nested classes/interfaces inherited from interface org.refcodes.structure.Keys

Keys.MutableKeys<K,V>, Keys.MutableValues<K,V>

Nested classes/interfaces inherited from interface org.refcodes.mixin.DelimiterAccessor

org.refcodes.mixin.DelimiterAccessor.DelimiterBuilder<B extends org.refcodes.mixin.DelimiterAccessor.DelimiterBuilder<B>>, org.refcodes.mixin.DelimiterAccessor.DelimiterMutator, org.refcodes.mixin.DelimiterAccessor.DelimiterProperty

Nested classes/interfaces inherited from interface org.refcodes.mixin.TypeAccessor

org.refcodes.mixin.TypeAccessor.TypeMutator<T>, org.refcodes.mixin.TypeAccessor.TypeProperty<T>

Method Summary

Modifier and Type	Method and Description
default Set<String>	directories() Applies the directories(String) method for the root path "/".
default Set<String>	directories(String aPath) Retrieves the directory names below the given path excluding any entries representing records.
default Set<String>	entries() Retrieves the records names excluding from the root path.
default Set<String>	entries(String aPath) Retrieves the entry names below the given path including records as well as directories.
default T[]	getArray() Applies the getArray(String) method for the root path "/".
default T[]	getArray(String aPath) Returns the records below the given path in an array.
default boolean	hasParentPath(String aPath) Tests whether there exists a parent path for the given path.
default boolean	isArray() Applies the isArray(String) method for the root path "/".
default boolean	isArray(String aPath) Determines as of getArray(String) if the elements below the given path can be seen as an array.
default boolean	isDirectory(String aPath) Determines whether the give path points to a directory in terms of directories(String).
default boolean	isEntry(String aPath) Determines whether the give path points to an entry in terms of entries(String).
default boolean	isRecord(String aPath) Determines whether the give path points to a record in terms of records(String).
default boolean	isRootPath(String aPath) Determines whether the given path represents the toor path.
default Set<String>	keySet(String aPath) Same as Keys.keySet() with the difference, that only the paths are contained belonging to the given path, excluding the given path.
default Set<String>	paths() Same as Keys.keySet() with according semantics in the method name.
default Set<String>	paths(String aPath) Same as keySet(String) with according semantics in the method name.
default Set<String>	records() Applies the records(String) method for the root path "/".
default Set<String>	records(String aPath) Retrieves the records names below the given path excluding any entries representing directories.
default PathMap<T>	retrieve(String aFromPath, String aToPath) Extracts a new PathMap from the elements of this PathMap found below the "from-path".
PathMap<T>	retrieveFrom(String aFromPath) Extracts a new PathMap from the elements of this PathMap found below the "from-path".
PathMap<T>	retrieveTo(String aToPath) Extracts a new PathMap from this PathMap's elements with the paths relocated to the provided "to-path".
default Object	toDataStructure() Applies the toDataStructure(String) method for the root path "/".
Object	toDataStructure(String aPath) Similar to the toMap(String) method, though in case all the keys of a nested Map instance (applicable to the root Map as well) represent an array (as of getArray( String)), then an array is generated where the index of each value in the Map is represented by the number representation of the Map's key for that value.
default Map<String,?>	toMap() Applies the toMap(String) method for the root path "/".
default Map<String,?>	toMap(String aFromPath) Creates a nested Map structure from the PathMap's entries below the provided path.
default String	toNormalizedPath(String aPath) Normalizes a path for it to start with the delimiter (as of DelimiterAccessor.getDelimiter()) and for it not to end with a delimiter.
default String	toNormalizedPath(String aParentPath, String aChildPath) Creates a normalized path for the child path being relative to the given parent path.
default String	toParentPath(String aPath) Returns the path representing the parent path for the given path.
static <T> PathMap<T>	toPathMap(Object aObj, char aDelimiter, Class<T> aType) Factory method to create a PathMap instance containing the elements as of PathMap.MutablePathMap.insert(Object).
static <T> PathMap<T>	toPathMap(Object aObj, Class<T> aType) Factory method to create a PathMap instance containing the elements as of PathMap.MutablePathMap.insert(Object) using the default path delimiter "/" for the path declarations.
static <T> PathMap<T>	toPathMap(Object aObj, String aFromPath, char aDelimiter, Class<T> aType) Factory method to create a PathMap instance containing the elements as of PathMap.MutablePathMap.insert(Object).
static <T> PathMap<T>	toPathMap(Object aObj, String aFromPath, Class<T> aType) Factory method to create a PathMap instance containing the elements as of PathMap.MutablePathMap.insert(Object) using the default path delimiter "/" for the path declarations.
static <T> PathMap<T>	toPathMap(String aToPath, Object aObj, char aDelimiter, Class<T> aType) Factory method to create a PathMap instance containing the elements as of PathMap.MutablePathMap.insert(Object).
static <T> PathMap<T>	toPathMap(String aToPath, Object aObj, Class<T> aType) Factory method to create a PathMap instance containing the elements as of PathMap.MutablePathMap.insert(Object) using the default path delimiter "/" for the path declarations.
static <T> PathMap<T>	toPathMap(String aToPath, Object aObj, String aFromPath, char aDelimiter, Class<T> aType) Factory method to create a PathMap instance containing the elements as of PathMap.MutablePathMap.insert(Object).
static <T> PathMap<T>	toPathMap(String aToPath, Object aObj, String aFromPath, Class<T> aType) Factory method to create a PathMap instance containing the elements as of PathMap.MutablePathMap.insert(Object) using the default path delimiter "/" for the path declarations.
default String	toRootPath() Returns the path pointing to the root of this PathMap.

Methods inherited from interface org.refcodes.structure.Keys

containsKey, containsValue, get, keySet, values

Methods inherited from interface org.refcodes.structure.Containable

isEmpty, size

Methods inherited from interface org.refcodes.mixin.DelimiterAccessor

getDelimiter

Methods inherited from interface org.refcodes.mixin.TypeAccessor

getType

Methods inherited from interface org.refcodes.mixin.Dumpable

toDump, toDump

Method Detail

toPathMap

static <T> PathMap<T> toPathMap(Object aObj,
                                Class<T> aType)

Factory method to create a PathMap instance containing the elements as of PathMap.MutablePathMap.insert(Object) using the default path delimiter "/" for the path declarations.

Type Parameters:

T - the generic type

Parameters:

aObj - The object from which the elements are to be added.

aType - The type of the values being referenced by the paths.

Returns:

The according pre-filled Path-Map.

toPathMap

static <T> PathMap<T> toPathMap(Object aObj,
                                char aDelimiter,
                                Class<T> aType)

Factory method to create a PathMap instance containing the elements as of PathMap.MutablePathMap.insert(Object).

Type Parameters:

T - the generic type

Parameters:

aObj - The object from which the elements are to be added.

aDelimiter - The path delimiter to be used for the path declarations.

aType - The type of the values being referenced by the paths.

Returns:

The according pre-filled Path-Map.

toPathMap

static <T> PathMap<T> toPathMap(String aToPath,
                                Object aObj,
                                Class<T> aType)

Factory method to create a PathMap instance containing the elements as of PathMap.MutablePathMap.insert(Object) using the default path delimiter "/" for the path declarations.

Type Parameters:

T - the generic type

Parameters:

aToPath - The sub-path where to insert the object's introspected values to.

aObj - The object from which the elements are to be added.

aType - The type of the values being referenced by the paths.

Returns:

The according pre-filled Path-Map.

toPathMap

static <T> PathMap<T> toPathMap(Object aObj,
                                String aFromPath,
                                Class<T> aType)

Factory method to create a PathMap instance containing the elements as of PathMap.MutablePathMap.insert(Object) using the default path delimiter "/" for the path declarations.

Type Parameters:

T - the generic type

Parameters:

aObj - The object from which the elements are to be added.

aFromPath - The path from where to start adding elements of the provided object.

aType - The type of the values being referenced by the paths.

Returns:

The according pre-filled Path-Map.

toPathMap

static <T> PathMap<T> toPathMap(String aToPath,
                                Object aObj,
                                String aFromPath,
                                Class<T> aType)

Factory method to create a PathMap instance containing the elements as of PathMap.MutablePathMap.insert(Object) using the default path delimiter "/" for the path declarations.

Type Parameters:

T - the generic type

Parameters:

aToPath - The sub-path where to insert the object's introspected values to.

aObj - The object from which the elements are to be added.

aFromPath - The path from where to start adding elements of the provided object.

aType - The type of the values being referenced by the paths.

Returns:

The according pre-filled Path-Map.

toPathMap

static <T> PathMap<T> toPathMap(String aToPath,
                                Object aObj,
                                char aDelimiter,
                                Class<T> aType)

Factory method to create a PathMap instance containing the elements as of PathMap.MutablePathMap.insert(Object).

Type Parameters:

T - the generic type

Parameters:

aToPath - The sub-path where to insert the object's introspected values to.

aObj - The object from which the elements are to be added.

aDelimiter - The path delimiter to be used for the path declarations.

aType - The type of the values being referenced by the paths.

Returns:

The according pre-filled Path-Map.

toPathMap

static <T> PathMap<T> toPathMap(Object aObj,
                                String aFromPath,
                                char aDelimiter,
                                Class<T> aType)

Factory method to create a PathMap instance containing the elements as of PathMap.MutablePathMap.insert(Object).

Type Parameters:

T - the generic type

Parameters:

aObj - The object from which the elements are to be added.

aFromPath - The path from where to start adding elements of the provided object.

aDelimiter - The path delimiter to be used for the path declarations.

aType - The type of the values being referenced by the paths.

Returns:

The according pre-filled Path-Map.

toPathMap

static <T> PathMap<T> toPathMap(String aToPath,
                                Object aObj,
                                String aFromPath,
                                char aDelimiter,
                                Class<T> aType)

Factory method to create a PathMap instance containing the elements as of PathMap.MutablePathMap.insert(Object).

Type Parameters:

T - the generic type

Parameters:

aToPath - The sub-path where to insert the object's introspected values to.

aObj - The object from which the elements are to be added.

aFromPath - The path from where to start adding elements of the provided object.

aDelimiter - The path delimiter to be used for the path declarations.

aType - The type of the values being referenced by the paths.

Returns:

The according pre-filled Path-Map.

isArray

default boolean isArray()

Applies the isArray(String) method for the root path "/".

Returns:

As of isArray(String) applied to the root path.

See Also:

isArray(String)

isArray

default boolean isArray(String aPath)

Determines as of getArray(String) if the elements below the given path can be seen as an array.

Parameters:

aPath - the a path

Returns:

True in case we have an array structure below the path or not.

getArray

default T[] getArray()

Applies the getArray(String) method for the root path "/".

Returns:

As of getArray(String) applied to the root path.

See Also:

getArray(String)

getArray

default T[] getArray(String aPath)

Returns the records below the given path in an array. Records in a PathMap are reckoned to be part of an array when they belong to the same hierarchy level and when their keys represent integer numbers. Given the below example, the elements below "/animals/dogs" can be represented as an array with five elements (the path is denoted at the left hand side of the assignment ":=" operator and the value at the right and side accordingly):

• "/animals/dogs/0" := "ace"
• "/animals/dogs/1" := "bandit"
• "/animals/dogs/2" := "radar"
• "/animals/dogs/3" := "echo"
• "/animals/dogs/4" := "snoopy"

The resulting array when calling getArray(String) for the path "/animals/dogs" would contain {"ace", "bandit", "radar", "echo", "snoopy"}. Calling isArray("/animals/dogs") would return true whereas calling isArray("/animals") would return false.

Parameters:

aPath - the a path

Returns:

An array of the records found below the given path.

keySet

default Set<String> keySet(String aPath)

Same as Keys.keySet() with the difference, that only the paths are contained belonging to the given path, excluding the given path.

Parameters:

aPath - The path from which to start retrieving the paths.

Returns:

The relative paths starting at the given path (excluding the preceding given path) contained in this PathMap.

paths

default Set<String> paths()

Same as Keys.keySet() with according semantics in the method name.

Returns:

The paths which are assigned to values.

paths

default Set<String> paths(String aPath)

Same as keySet(String) with according semantics in the method name.

Parameters:

aPath - The path from which to start seeking.

Returns:

The paths (excluding the preceding given path) which are assigned to values.

isEntry

default boolean isEntry(String aPath)

Determines whether the give path points to an entry in terms of entries(String).

Parameters:

aPath - The path for which to determine whether it points to a entry.

Returns:

True in case the given path points to a entry, else false.

entries

default Set<String> entries()

Retrieves the records names excluding from the root path. Record names point to values and do not represent a sup-path. Also any paths pointing to a value (not being a sub-path) are excluded. Given we have values for paths "/dog/cat" and "/cat/mouse" in the PathMap and we call records(), then the resulting Set will contain the values "dog" and "cat".

Returns:

The relative directory names starting at the root path contained in this PathMap.

entries

default Set<String> entries(String aPath)

Retrieves the entry names below the given path including records as well as directories. A record is reckoned to be the last path element in a path pointing to a value. In contrast a directory is reckoned to be be a path element pointing to a succeeding child path element (sub-directory). Given we have values for paths in our PathMap:

• "/animals/dogs/dilbert"
• "/animals/dogs/otto"
• "/animals/loki"
• "/machines/robots/greg"

When we call directories(String) with "/animals", then the resulting Set will just contain "dogs"; calling "/" will retrieve "animals" and "machines".

Parameters:

aPath - The path from which to start retrieving the directories.

Returns:

The directory names (excluding the preceding given path) of the directories below the given path contained within this PathMap.

isDirectory

default boolean isDirectory(String aPath)

Determines whether the give path points to a directory in terms of directories(String).

Parameters:

aPath - The path for which to determine whether it points to a directory.

Returns:

True in case the given path points to a directory, else false.

directories

default Set<String> directories()

Applies the directories(String) method for the root path "/".

Returns:

As of directories(String) applied to the root path.

See Also:

directories(String)

directories

default Set<String> directories(String aPath)

Retrieves the directory names below the given path excluding any entries representing records. A record is reckoned to be the last path element in a path pointing to a value. In contrast a directory is reckoned to be be a path element pointing to a succeeding child path element (sub-directory). Given we have values for paths in our PathMap:

• "/animals/dogs/dilbert"
• "/animals/dogs/otto"
• "/animals/loki"
• "/machines/robots/greg"

When we call directories(String) with "/animals", then the resulting Set will just contain "dogs"; calling "/" will retrieve "animals" and "machines".

Parameters:

aPath - The path from which to start retrieving the directories.

Returns:

The directory names (excluding the preceding given path) of the directories below the given path contained within this PathMap.

isRecord

default boolean isRecord(String aPath)

Determines whether the give path points to a record in terms of records(String).

Parameters:

aPath - The path for which to determine whether it points to a record.

Returns:

True in case the given path points to a record, else false.

records

default Set<String> records()

Applies the records(String) method for the root path "/".

Returns:

As of records(String) applied to the root path.

See Also:

records(String)

records

default Set<String> records(String aPath)

Retrieves the records names below the given path excluding any entries representing directories. A record is reckoned to be the last path element in a path pointing to a value. In contrast a directory is reckoned to be be a path element pointing to a succeeding child path element (sub-directory). Given we have values for paths in our PathMap:

• "/animals/dogs/dilbert"
• "/animals/dogs/otto"
• "/animals/loki"
• "/machines/robots/greg"

When we call records(String) with "/animals", then the resulting Set will just contain "loki"; calling "/animals/dogs" will retrieve "dilbert" and "otto".

Parameters:

aPath - The path from which to start retrieving the records.

Returns:

The record names (excluding the preceding given path) of the records below the given path contained within this PathMap.

retrieveFrom

PathMap<T> retrieveFrom(String aFromPath)

Extracts a new PathMap from the elements of this PathMap found below the "from-path". The sub-paths will be the root paths for the new PathMap. Given we have a value for path "/dog/cat" in the PathMap and we call retrieveFrom(String) with "/dog", then the resulting PathMap will contain the path "/cat" for that value.

Parameters:

aFromPath - The path from where to start extracting the paths.

Returns:

The PathMap with the elements below the provided path which are root elements in the new PathMap.

retrieveTo

PathMap<T> retrieveTo(String aToPath)

Extracts a new PathMap from this PathMap's elements with the paths relocated to the provided "to-path". Given we have a value for path "/dog/cat" in the PathMap and we call retrieveTo(String) with "/animals", then the resulting PathMap will contain the path "/animals/dog/cat" for that value.

Parameters:

aToPath - The path where to relocate the paths of this PathMap to.

Returns:

The PathMap with the elements from the provided PathMap with accordingly relocated paths.

retrieve

default PathMap<T> retrieve(String aFromPath,
                            String aToPath)

Extracts a new PathMap from the elements of this PathMap found below the "from-path". The sub-paths will be relocated to the provided "to-path".

Parameters:

aFromPath - The path from where to start extracting the paths.

aToPath - The path where to relocate the extracted paths to.

Returns:

The PathMap with the elements below the provided path "from-path" relocated to the given "to-path".

toMap

default Map<String,?> toMap()
                     throws IllegalStateException

Applies the toMap(String) method for the root path "/".

Returns:

As of toMap(String) applied to the root path.

Throws:

IllegalStateException - the illegal state exception

See Also:

toMap(String)

toMap

default Map<String,?> toMap(String aFromPath)
                     throws IllegalStateException

Creates a nested Map structure from the PathMap's entries below the provided path. Each elelemt of the paths (below the provided path), except of the last (pointing to the path's value) is represented by a Map contained in the preceeding's path element.

Parameters:

aFromPath - The path from which to start retrieving the sub-paths which will be the root directories in the returned Map

Returns:

The nested Map representing this PathMap starting from the given path.

Throws:

IllegalStateException - in case the PathMap contains a path which points to a value and which is also part of other paths. Such a state cannot be represented by a nested Map structure as

toDataStructure

default Object toDataStructure()

Applies the toDataStructure(String) method for the root path "/".

Returns:

As of toDataStructure(String) applied to the root path.

See Also:

toDataStructure(String)

toDataStructure

Object toDataStructure(String aPath)

Similar to the toMap(String) method, though in case all the keys of a nested Map instance (applicable to the root Map as well) represent an array (as of getArray( String)), then an array is generated where the index of each value in the Map is represented by the number representation of the Map's key for that value. The result is a data structure consisting of Map instances and arrays.

Parameters:

aPath - The path below which the PathMap to be converted into a data structure.

Returns:

A data structure being a mixture of Map instances and arrays representing the data below the given path.

toNormalizedPath

default String toNormalizedPath(String aPath)

Normalizes a path for it to start with the delimiter (as of DelimiterAccessor.getDelimiter()) and for it not to end with a delimiter. This implementation will return in empty String in case the path is an empty String or the path just consists of a delimiter: Any missing prefixed (starting) delimiter is added and any suffixed delimiters are removed, ending up with an empty String

Parameters:

aPath - The path to be normalized.

Returns:

The normalized path; afterwards (in case the path was not an empty String or just the delimiter itself) it starts with a delimiter and does not end with a delimiter.

toRootPath

default String toRootPath()

Returns the path pointing to the root of this PathMap. By default the Root-Path consists just of the one delimiter DelimiterAccessor.getDelimiter() character.

Returns:

The path pointing to the root of this PathMap.

isRootPath

default boolean isRootPath(String aPath)

Determines whether the given path represents the toor path.

Parameters:

aPath - The path to be tested.

Returns:

True in case we have a root path, else false.

toNormalizedPath

default String toNormalizedPath(String aParentPath,
                                String aChildPath)

Creates a normalized path for the child path being relative to the given parent path.

Parameters:

aParentPath - The path relative to which the child path is interpreted.

aChildPath - The path relative to the parent's path.

Returns:

The accordingly normalized path as of toNormalizedPath(String).

hasParentPath

default boolean hasParentPath(String aPath)

Tests whether there exists a parent path for the given path. Given we have a path "/animals/dogs/otto", then its parent path is "/animals/dogs".

Parameters:

aPath - The path for which to test if it has the parent path.

Returns:

True in case the path has a parent, else false.

toParentPath

default String toParentPath(String aPath)

Returns the path representing the parent path for the given path. Given we have a path "/animals/dogs/otto", then its parent path is "/animals/dogs".

Parameters:

aPath - The path for which to get the parent's path.

Returns:

The parent path.

Throws:

IllegalArgumentException - thrown in case there is no such parent path for the given path; test beforehand using hasParentPath(String).