T
- The type of the terminating elements.public interface PathMap<T> extends Dictionary<String,T>, org.refcodes.mixin.DelimiterAccessor, org.refcodes.mixin.TypeAccessor<T>, org.refcodes.mixin.Dumpable
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:
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):
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)
.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. |
Dictionary.MutableDictionary<K,V>
Keys.MutableKeys<K,V>, Keys.MutableValues<K,V>
org.refcodes.mixin.DelimiterAccessor.DelimiterBuilder<B extends org.refcodes.mixin.DelimiterAccessor.DelimiterBuilder<B>>, org.refcodes.mixin.DelimiterAccessor.DelimiterMutator, org.refcodes.mixin.DelimiterAccessor.DelimiterProperty
Modifier and Type | Method and Description |
---|---|
PathMap<T> |
childrenOf(String aParentPath)
Gets the children elements of the provided parent's path, excluding the
parent's path.
|
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 String |
fromExternalKey(String aKey,
char... aDelimiters)
Converts an external key which uses a different notation from
DelimiterAccessor.getDelimiter() for the path delimiter and converts those to the
default delimiter. |
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)
|
PathMap<T> |
retrieveFrom(String aFromPath)
|
PathMap<T> |
retrieveTo(String aToPath)
|
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 String |
toExternalKey(String aKey,
char aDelimiter)
COnverts the given key to an external key by converting the default
delimiter
DelimiterAccessor.getDelimiter() to the provided delimiter. |
default Map<String,?> |
toMap()
Applies the
toMap(String) method for the root path "/". |
default Map<String,?> |
toMap(String aFromPath)
|
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.
|
default String |
toPath(String... aPathElements)
Creates a normalized path from the provided path elements by
concatenating the elements with the path delimiter
DelimiterAccessor.getDelimiter() in between and taking care to avoid duplicate
path delimiters. |
default String |
toRootPath()
Returns the path pointing to the root of this
PathMap . |
containsKey, containsValue, get, keySet, use, values
isEmpty, size
default boolean isArray()
isArray(String)
method for the root path "/".isArray(String)
applied to the root path.isArray(String)
default boolean isArray(String aPath)
getArray(String)
if the elements below the
given path can be seen as an array.aPath
- the a pathdefault T[] getArray()
getArray(String)
method for the root path "/".getArray(String)
applied to the root path.getArray(String)
default T[] getArray(String aPath)
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):
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.aPath
- the a pathdefault Set<String> keySet(String aPath)
Keys.keySet()
with the difference, that only the paths are
contained belonging to the given path, excluding the given path.aPath
- The path from which to start retrieving the paths.PathMap
.default Set<String> paths()
Keys.keySet()
with according semantics in the method name.default Set<String> paths(String aPath)
keySet(String)
with according semantics in the method
name.aPath
- The path from which to start seeking.default boolean isEntry(String aPath)
entries(String)
.aPath
- The path for which to determine whether it points to a
entry.default Set<String> entries()
PathMap
and we call records()
, then the resulting
Set
will contain the values "dog" and "cat".PathMap
.default Set<String> entries(String aPath)
PathMap
:
directories(String)
with "/animals", then the
resulting Set
will just contain "dogs"; calling "/" will retrieve
"animals" and "machines".aPath
- The path from which to start retrieving the directories.PathMap
.default boolean isDirectory(String aPath)
directories(String)
.aPath
- The path for which to determine whether it points to a
directory.default Set<String> directories()
directories(String)
method for the root path "/".directories(String)
applied to the root path.directories(String)
default Set<String> directories(String aPath)
PathMap
:
directories(String)
with "/animals", then the
resulting Set
will just contain "dogs"; calling "/" will retrieve
"animals" and "machines".aPath
- The path from which to start retrieving the directories.PathMap
.default boolean isRecord(String aPath)
records(String)
.aPath
- The path for which to determine whether it points to a
record.default Set<String> records()
records(String)
method for the root path "/".records(String)
applied to the root path.records(String)
default Set<String> records(String aPath)
PathMap
:
records(String)
with "/animals", then the resulting
Set
will just contain "loki"; calling "/animals/dogs" will
retrieve "dilbert" and "otto".aPath
- The path from which to start retrieving the records.PathMap
.PathMap<T> retrieveFrom(String aFromPath)
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.PathMap<T> retrieveTo(String aToPath)
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.PathMap<T> childrenOf(String aParentPath)
aParentPath
- The path from where to retrieve the children.default PathMap<T> retrieve(String aFromPath, String aToPath)
PathMap
from the elements of this PathMap
found below the "from-path". The sub-paths will be relocated to the
provided "to-path".aFromPath
- The path from where to start extracting the paths.aToPath
- The path where to relocate the extracted paths to.PathMap
with the elements below the provided path
"from-path" relocated to the given "to-path".default Map<String,?> toMap() throws IllegalStateException
toMap(String)
method for the root path "/".toMap(String)
applied to the root path.IllegalStateException
- the illegal state exceptiondefault Map<String,?> toMap(String aFromPath) throws IllegalStateException
Map
structure from the PathMap
's entries
below the provided path. Each element 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.aFromPath
- The path from which to start retrieving the sub-paths
which will be the root directories in the returned Map
PathMap
starting from
the given path.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 the element would represent a leaf and a node at the
same time.default Object toDataStructure()
toDataStructure(String)
method for the root path
"/".toDataStructure(String)
applied to the root path.toDataStructure(String)
Object toDataStructure(String aPath)
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.default String toNormalizedPath(String aPath)
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
aPath
- The path to be normalized.String
or just the delimiter itself) it starts with
a delimiter and does not end with a delimiter.default String fromExternalKey(String aKey, char... aDelimiters)
DelimiterAccessor.getDelimiter()
for the path delimiter and converts those to the
default delimiter.aKey
- The key which's delimiters are to be converted to the default
DelimiterAccessor.getDelimiter()
delimiter.aDelimiters
- The "external" delimiters in question.DelimiterAccessor.getDelimiter()
instead of the provided delimiters.default String toExternalKey(String aKey, char aDelimiter)
DelimiterAccessor.getDelimiter()
to the provided delimiter. In case we
have a provided delimiter different from the commonly used path
delimiters "/" or "\", then a prefixed delimiter is removed.aKey
- The key which is to be converted to its external
representation.aDelimiter
- The delimiter to be used for the external
representation instead if the default delimiter
DelimiterAccessor.getDelimiter()
.default String toRootPath()
PathMap
. By default
the Root-Path consists just of the one delimiter DelimiterAccessor.getDelimiter()
character.PathMap
.default String toPath(String... aPathElements)
DelimiterAccessor.getDelimiter()
in between and taking care to avoid duplicate
path delimiters.default boolean isRootPath(String aPath)
aPath
- The path to be tested.default String toNormalizedPath(String aParentPath, String aChildPath)
aParentPath
- The path relative to which the child path is
interpreted.aChildPath
- The path relative to the parent's path.toNormalizedPath(String)
.default boolean hasParentPath(String aPath)
aPath
- The path for which to test if it has the parent path.default String toParentPath(String aPath)
aPath
- The path for which to get the parent's path.IllegalArgumentException
- thrown in case there is no such parent
path for the given path; test beforehand using
hasParentPath(String)
.Copyright © 2018. All rights reserved.