Package org.refcodes.structure

Interface PathMap<T>

  • Type Parameters:
    T - The type of the terminating elements.
    All Superinterfaces:
    Containable, org.refcodes.mixin.DelimiterAccessor, Dictionary<java.lang.String,T>, org.refcodes.mixin.Dumpable, Keys<K,V>, org.refcodes.mixin.TypeAccessor<T>
    All Known Subinterfaces:
    CanonicalMap, CanonicalMap.CanonicalMapBuilder, CanonicalMap.MutableCanonicalMap, PathMap.MutablePathMap<T>, PathMap.PathMapBuilder<T>
    All Known Implementing Classes:
    CanonicalMapBuilderImpl, CanonicalMapImpl, PathMapBuilderImpl, PathMapImpl

    public interface PathMap<T>
extends Dictionary<java.lang.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 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.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 extends java.lang.Object>, org.refcodes.mixin.TypeAccessor.TypeProperty<T extends java.lang.Object>

    • Method Summary

      All Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      default java.util.Set<java.lang.String> children​()
      Retrieves the entry names below the root including records as well as directories.
      default java.util.Set<java.lang.String> children​(java.lang.String aPath)
      Retrieves the entry names below the given path including records as well as directories.
      default java.util.Set<java.lang.String> children​(java.lang.String... aPathElements)
      Retrieves the entry names below the given path including records as well as directories.
      default java.util.Set<java.lang.String> directories​()
      Applies the directories(String) method for the root path "/".
      default java.util.Set<java.lang.String> directories​(java.lang.Object aPath)
      Retrieves the directory names below the given path excluding any entries representing records.
      default java.util.Set<java.lang.String> directories​(java.lang.Object... aPathElements)
      Retrieves the directory names below the given path elements excluding any entries representing records.
      default java.util.Set<java.lang.String> directories​(java.lang.String aPath)
      Retrieves the directory names below the given path excluding any entries representing records.
      default java.util.Set<java.lang.String> directories​(java.lang.String... aPathElements)
      Retrieves the directory names below the given path elements excluding any entries representing records.
      default java.lang.String fromExternalKey​(java.lang.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 get​(java.lang.Object... aPathElements)
      Experimental convenience method: Applies the Keys.get(Object) method for the provided path elements by first converting them to a String (if not being a String already) and then concatenating the elements with the path delimiter DelimiterAccessor.getDelimiter() in between and taking care to avoid duplicate path delimiters.
      default T get​(java.lang.String... aPathElements)
      Experimental convenience method: Applies the Keys.get(Object) method for 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 T[] getArray​()
      Applies the getArray(String) method for the root path "/".
      default T[] getArray​(java.lang.String aPath)
      Returns the records below the given path in an array.
      default java.lang.Boolean getBoolean​(java.lang.Object... aPathElements)
      Returns the Boolean value of the property referred to by the path elements.
      default java.lang.Boolean getBoolean​(java.lang.String... aPathElements)
      Returns the Boolean value of the property referred to by the path elements.
      default java.lang.Byte getByte​(java.lang.Object... aPathElements)
      Returns the Byte value of the property referred to by the path elements.
      default java.lang.Byte getByte​(java.lang.String... aPathElements)
      Returns the Byte value of the property referred to by the path elements.
      default java.lang.Character getCharacter​(java.lang.Object... aPathElements)
      Returns the Character value of the property referred to by the path elements.
      default java.lang.Character getCharacter​(java.lang.String... aPathElements)
      Returns the Character value of the property referred to by the key.
      default java.lang.Double getDouble​(java.lang.Object... aPathElements)
      Returns the Double value of the property referred to by the path elements.
      default java.lang.Double getDouble​(java.lang.String... aPathElements)
      Returns the Double value of the property referred to by the path elements.
      default java.lang.Float getFloat​(java.lang.Object... aPathElements)
      Returns the Float value of the property referred to by the path elements.
      default java.lang.Float getFloat​(java.lang.String... aPathElements)
      Returns the Float value of the property referred to by the path elements.
      default PathMap<T> getIndexed​(int aIndex)
      Returns the accordingly indexed Elements of the root "array" path.
      default PathMap<T> getIndexed​(java.lang.String aPath, int aIndex)
      Returns the accordingly indexed Elements of the root "array" path.
      default int[] getIndexes​()
      Returns the indexes pointing to elements of the root "array" path.
      default int[] getIndexes​(java.lang.String aPath)
      Returns the indexes pointing to elements of the given "array" path.
      default java.lang.Integer getInteger​(java.lang.Object... aPathElements)
      Returns the Integer value of the property referred to by the path elements.
      default java.lang.Integer getInteger​(java.lang.String... aPathElements)
      Returns the Integer value of the property referred to by the path elements.
      default java.lang.Long getLong​(java.lang.Object... aPathElements)
      Returns the Long value of the property referred to by the path elements.
      default java.lang.Long getLong​(java.lang.String... aPathElements)
      Returns the Long value of the property referred to by the path elements.
      default java.lang.String getRootPath​()
      Returns the path pointing to the root of this PathMap.
      default java.lang.Short getShort​(java.lang.Object... aPathElements)
      Returns the Short value of the property referred to by the path elements.
      default java.lang.Short getShort​(java.lang.String... aPathElements)
      Returns the Short value of the property referred to by the path elements.
      default boolean hasChildren​(java.lang.Object... aPathElements)
      Determines whether the give path contains children as of children(String).
      default boolean hasChildren​(java.lang.String aPath)
      Determines whether the give path contains children as of children(String).
      default boolean hasChildren​(java.lang.String... aPathElements)
      Determines whether the give path contains children as of children(String).
      default boolean hasIndexed​(int aIndex)
      Determines whether the index points to an index root "array" path.
      default boolean hasIndexed​(java.lang.String aPath, int aIndex)
      Determines whether the index points to an index root "array" path.
      default boolean hasParentPath​(java.lang.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​(java.lang.Object aPath)
      Determines as of getArray(String) if the elements below the given path can be seen as an array.
      default boolean isArray​(java.lang.Object... aPathElements)
      Determines as of getArray(String) if the elements below the given path elements can be seen as an array.
      default boolean isArray​(java.lang.String aPath)
      Determines as of getArray(String) if the elements below the given path can be seen as an array.
      default boolean isArray​(java.lang.String... aPathElements)
      Determines as of getArray(String) if the elements below the given path elements can be seen as an array.
      default boolean isChild​(java.lang.Object... aPathElements)
      Determines whether the give path points to an entry in terms of children(String).
      default boolean isChild​(java.lang.String aPath)
      Determines whether the give path points to an entry in terms of children(String).
      default boolean isChild​(java.lang.String... aPathElements)
      Determines whether the give path points to an entry in terms of children(String).
      default boolean isDirectory​(java.lang.Object aPath)
      Determines whether the give path points to a directory in terms of directories(String).
      default boolean isDirectory​(java.lang.Object... aPathElements)
      Determines whether the give path points to a directory in terms of directories(String).
      default boolean isDirectory​(java.lang.String aPath)
      Determines whether the give path points to a directory in terms of directories(String).
      default boolean isDirectory​(java.lang.String... aPathElements)
      Determines whether the give path points to a directory in terms of directories(String).
      default boolean isIndexed​()
      Determines whether the root path represents an "array" path with indexes within the given PathMap.
      default boolean isIndexed​(java.lang.String aPath)
      Determines whether the provided path represents an "array" path with indexes within the given PathMap.
      default boolean isPath​(java.lang.String aPath)
      Determines whether the provided path represents a path within the given PathMap.
      default boolean isRecord​(java.lang.Object aPath)
      Determines whether the give path points to a record in terms of records(String).
      default boolean isRecord​(java.lang.Object... aPathElements)
      Determines whether the give path points to a record in terms of records(String).
      default boolean isRecord​(java.lang.String aPath)
      Determines whether the give path points to a record in terms of records(String).
      default boolean isRecord​(java.lang.String... aPathElements)
      Determines whether the give path points to a record in terms of records(String).
      default boolean isRootPath​(java.lang.String aPath)
      Determines whether the given path represents the toor path.
      default java.util.Set<java.lang.String> keySet​(java.lang.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 java.util.Set<java.lang.String> paths​()
      Same as Keys.keySet() with according semantics in the method name.
      default java.util.Set<java.lang.String> paths​(java.lang.Object aPath)
      Same as keySet(String) with according semantics in the method name.
      default java.util.Set<java.lang.String> paths​(java.lang.Object... aPathElements)
      Same as keySet(String) with according semantics in the method name.
      default java.util.Set<java.lang.String> paths​(java.lang.String aPath)
      Same as keySet(String) with according semantics in the method name.
      default java.util.Set<java.lang.String> paths​(java.lang.String... aPathElements)
      Same as keySet(String) with according semantics in the method name.
      default PathMap<T> query​(java.lang.String aPathQuery)
      Queries the keys of the instance using the PathMatcher' matching patterns, similar to the wildcards '*', '?'
      default PathMap<T> query​(java.lang.String aPathQuery, java.lang.String aFromPath, java.lang.String aToPath)
      Queries the keys of the instance using the PathMatcher' matching patterns, similar to the wildcards '*', '?'
      default PathMap<T> queryFrom​(java.lang.String aPathQuery, java.lang.String aFromPath)
      Queries the keys of the instance using the PathMatcher' matching patterns, similar to the wildcards '*', '?'
      default java.util.Set<java.lang.String> queryPaths​(java.lang.String aPathQuery)
      Queries the keys of the instance using the PathMatcher' matching patterns, similar to the wildcards '*', '?'
      default PathMap<T> queryTo​(java.lang.String aPathQuery, java.lang.String aToPath)
      Queries the keys of the instance using the PathMatcher' matching patterns, similar to the wildcards '*', '?'
      default java.util.Set<java.lang.String> records​()
      Applies the records(String) method for the root path "/".
      default java.util.Set<java.lang.String> records​(java.lang.Object aPath)
      Retrieves the records names below the given path excluding any entries representing directories.
      default java.util.Set<java.lang.String> records​(java.lang.Object... aPathElements)
      Retrieves the records names below the given path elements excluding any entries representing directories.
      default java.util.Set<java.lang.String> records​(java.lang.String aPath)
      Retrieves the records names below the given path excluding any entries representing directories.
      default java.util.Set<java.lang.String> records​(java.lang.String... aPathElements)
      Retrieves the records names below the given path elements excluding any entries representing directories.
      default PathMap<T> retrieve​(java.lang.String aFromPath, java.lang.String aToPath)
      Extracts a new PathMap from the elements of this PathMap found below the "from-path".
      default PathMap<T> retrieveFrom​(java.lang.Object aParentPath)
      Gets the children elements of the provided parent's path, excluding the parent's path.
      default PathMap<T> retrieveFrom​(java.lang.Object... aPathElements)
      Gets the children elements of the provided parent's path elements, excluding the parent's path.
      PathMap<T> retrieveFrom​(java.lang.String aFromPath)
      Extracts a new PathMap from the elements of this PathMap found below the "from-path".
      default PathMap<T> retrieveFrom​(java.lang.String... aPathElements)
      Gets the children elements of the provided parent's path elements, excluding the parent's path.
      default PathMap<T> retrieveTo​(java.lang.Object aToPath)
      Extracts a new PathMap from this PathMap's elements with the paths relocated to the provided "to-path".
      default PathMap<T> retrieveTo​(java.lang.Object... aToPathElements)
      Extracts a new PathMap from this PathMap's elements with the paths relocated to the provided "to-path".
      PathMap<T> retrieveTo​(java.lang.String aToPath)
      Extracts a new PathMap from this PathMap's elements with the paths relocated to the provided "to-path".
      default PathMap<T> retrieveTo​(java.lang.String... aToPathElements)
      Extracts a new PathMap from this PathMap's elements with the paths relocated to the provided "to-path".
      default java.lang.Object toDataStructure​()
      Applies the toDataStructure(String) method for the root path "/".
      java.lang.Object toDataStructure​(java.lang.String aFromPath)
      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 java.lang.String toExternalKey​(java.lang.String aKey, char aDelimiter)
      Converts the given key to an external key by converting the default delimiter DelimiterAccessor.getDelimiter() to the provided delimiter.
      default java.util.Map<java.lang.String,?> toMap​()
      Applies the toMap(String) method for the root path "/".
      default java.util.Map<java.lang.String,?> toMap​(java.lang.String aFromPath)
      Creates a nested Map structure from the PathMap's entries below the provided path.
      default java.lang.String toNormalizedPath​(java.lang.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 java.lang.String toNormalizedPath​(java.lang.String aParentPath, java.lang.String aChildPath)
      Creates a normalized path for the child path being relative to the given parent path.
      default java.lang.String toParentPath​(java.lang.String aPath)
      Returns the path representing the parent path for the given path.
      default java.lang.String toPath​(java.lang.Object... aPathElements)
      Creates a normalized path from the provided path elements by first converting them to a String (if not being a String already) and then concatenating the elements with the path delimiter DelimiterAccessor.getDelimiter() in between and taking care to avoid duplicate path delimiters.
      default java.lang.String toPath​(java.lang.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.

      • Methods inherited from interface org.refcodes.mixin.DelimiterAccessor

        getDelimiter

      • Methods inherited from interface org.refcodes.mixin.Dumpable

        toDump, toDump

      • Methods inherited from interface org.refcodes.mixin.TypeAccessor

        getType

    • Method Detail

      • queryPaths

        default java.util.Set<java.lang.String> queryPaths​(java.lang.String aPathQuery)
        Queries the keys of the instance using the PathMatcher' matching patterns, similar to the wildcards '*', '?' and '**' known when querying folders of a filesystem: The PathMatcher applies the following rules from the ANT path pattern to the query provided: A single asterisk ("*") matches zero or more characters within a path name. A double asterisk ("**") matches zero or more characters across directory levels. A question mark ("?") matches exactly one character within a path name. The single asterisk ("*"), the double asterisk ("**") and the question mark ("?") we refer to as wildcards.
        Parameters:
        aPathQuery - The path query including your wildcards.
        Returns:
        The result contains the matching paths.

      • query

        default PathMap<T> query​(java.lang.String aPathQuery)
        Queries the keys of the instance using the PathMatcher' matching patterns, similar to the wildcards '*', '?' and '**' known when querying folders of a filesystem: The PathMatcher applies the following rules from the ANT path pattern to the query provided: A single asterisk ("*") matches zero or more characters within a path name. A double asterisk ("**") matches zero or more characters across directory levels. A question mark ("?") matches exactly one character within a path name. The single asterisk ("*"), the double asterisk ("**") and the question mark ("?") we refer to as wildcards.
        Parameters:
        aPathQuery - The path query including your wildcards.
        Returns:
        The result contains the matching paths with the according values.

      • queryTo

        default PathMap<T> queryTo​(java.lang.String aPathQuery,
                           java.lang.String aToPath)
        Queries the keys of the instance using the PathMatcher' matching patterns, similar to the wildcards '*', '?' and '**' known when querying folders of a filesystem: The PathMatcher applies the following rules from the ANT path pattern to the query provided: A single asterisk ("*") matches zero or more characters within a path name. A double asterisk ("**") matches zero or more characters across directory levels. A question mark ("?") matches exactly one character within a path name. The single asterisk ("*"), the double asterisk ("**") and the question mark ("?") we refer to as wildcards.
        Parameters:
        aPathQuery - The path query including your wildcards.
        aToPath - The path where to relocate the result to.
        Returns:
        The result contains the matching paths (with respect to the to-path) with the according values.

      • queryFrom

        default PathMap<T> queryFrom​(java.lang.String aPathQuery,
                             java.lang.String aFromPath)
        Queries the keys of the instance using the PathMatcher' matching patterns, similar to the wildcards '*', '?' and '**' known when querying folders of a filesystem: The PathMatcher applies the following rules from the ANT path pattern to the query provided: A single asterisk ("*") matches zero or more characters within a path name. A double asterisk ("**") matches zero or more characters across directory levels. A question mark ("?") matches exactly one character within a path name. The single asterisk ("*"), the double asterisk ("**") and the question mark ("?") we refer to as wildcards.
        Parameters:
        aPathQuery - The path query including your wildcards.
        aFromPath - The path from where to start querying and extracting the paths.
        Returns:
        The result contains the matching paths (with respect to the from-path) with the according values.

      • query

        default PathMap<T> query​(java.lang.String aPathQuery,
                         java.lang.String aFromPath,
                         java.lang.String aToPath)
        Queries the keys of the instance using the PathMatcher' matching patterns, similar to the wildcards '*', '?' and '**' known when querying folders of a filesystem: The PathMatcher applies the following rules from the ANT path pattern to the query provided: A single asterisk ("*") matches zero or more characters within a path name. A double asterisk ("**") matches zero or more characters across directory levels. A question mark ("?") matches exactly one character within a path name. The single asterisk ("*"), the double asterisk ("**") and the question mark ("?") we refer to as wildcards.
        Parameters:
        aPathQuery - The path query including your wildcards.
        aFromPath - The path from where to start querying and extracting the paths.
        aToPath - The path where to relocate the result to.
        Returns:
        The result contains the matching paths (with respect to the from-path and the to-path) with the according values.

      • get

        default T get​(java.lang.Object... aPathElements)
        Experimental convenience method: Applies the Keys.get(Object) method for the provided path elements by first converting them to a String (if not being a String already) and then concatenating the elements with the path delimiter DelimiterAccessor.getDelimiter() in between and taking care to avoid duplicate path delimiters.
        Parameters:
        aPathElements - The elements of the path to be concatenated with the path delimiter.
        Returns:
        As of Keys.get(Object) applied path the path elements.
        See Also:
        Keys.get(Object)

      • get

        default T get​(java.lang.String... aPathElements)
        Experimental convenience method: Applies the Keys.get(Object) method for the provided path elements by concatenating the elements with the path delimiter DelimiterAccessor.getDelimiter() in between and taking care to avoid duplicate path delimiters.
        Parameters:
        aPathElements - The elements of the path to be concatenated with the path delimiter.
        Returns:
        As of Keys.get(Object) applied path the path elements.
        See Also:
        Keys.get(Object)

      • getCharacter

        default java.lang.Character getCharacter​(java.lang.Object... aPathElements)
                                  throws java.lang.NumberFormatException
        Returns the Character value of the property referred to by the path elements. As property keys and values are of type String, the String value is converted accordingly.
        Parameters:
        aPathElements - The key for which to retrieve the value.
        Returns:
        The Character representation of the key's String value.
        Throws:
        java.lang.NumberFormatException - thrown in case conversion fails.

      • getInteger

        default java.lang.Integer getInteger​(java.lang.Object... aPathElements)
                              throws java.lang.NumberFormatException
        Returns the Integer value of the property referred to by the path elements. As property keys and values are of type String, the String value is converted accordingly.
        Parameters:
        aPathElements - The key for which to retrieve the value.
        Returns:
        The Integer representation of the key's String value.
        Throws:
        java.lang.NumberFormatException - thrown in case conversion fails.

      • getLong

        default java.lang.Long getLong​(java.lang.Object... aPathElements)
                        throws java.lang.NumberFormatException
        Returns the Long value of the property referred to by the path elements. As property keys and values are of type String, the String value is converted accordingly.
        Parameters:
        aPathElements - The key for which to retrieve the value.
        Returns:
        The Long representation of the key's String value.
        Throws:
        java.lang.NumberFormatException - thrown in case conversion fails.

      • getShort

        default java.lang.Short getShort​(java.lang.Object... aPathElements)
                          throws java.lang.NumberFormatException
        Returns the Short value of the property referred to by the path elements. As property keys and values are of type String, the String value is converted accordingly.
        Parameters:
        aPathElements - The key for which to retrieve the value.
        Returns:
        The Short representation of the key's String value.
        Throws:
        java.lang.NumberFormatException - thrown in case conversion fails.

      • getByte

        default java.lang.Byte getByte​(java.lang.Object... aPathElements)
                        throws java.lang.NumberFormatException
        Returns the Byte value of the property referred to by the path elements. As property keys and values are of type String, the String value is converted accordingly.
        Parameters:
        aPathElements - The key for which to retrieve the value.
        Returns:
        The Byte representation of the key's String value.
        Throws:
        java.lang.NumberFormatException - thrown in case conversion fails.

      • getDouble

        default java.lang.Double getDouble​(java.lang.Object... aPathElements)
                            throws java.lang.NumberFormatException
        Returns the Double value of the property referred to by the path elements. As property keys and values are of type String, the String value is converted accordingly.
        Parameters:
        aPathElements - The key for which to retrieve the value.
        Returns:
        The Double representation of the key's String value.
        Throws:
        java.lang.NumberFormatException - thrown in case conversion fails.

      • getFloat

        default java.lang.Float getFloat​(java.lang.Object... aPathElements)
                          throws java.lang.NumberFormatException
        Returns the Float value of the property referred to by the path elements. As property keys and values are of type String, the String value is converted accordingly.
        Parameters:
        aPathElements - The key for which to retrieve the value.
        Returns:
        The Float representation of the key's String value.
        Throws:
        java.lang.NumberFormatException - thrown in case conversion fails.

      • getBoolean

        default java.lang.Boolean getBoolean​(java.lang.Object... aPathElements)
                              throws java.lang.NumberFormatException
        Returns the Boolean value of the property referred to by the path elements. As property keys and values are of type String, the String value is converted accordingly.
        Parameters:
        aPathElements - The key for which to retrieve the value.
        Returns:
        The Boolean representation of the key's String value of false if there is no such key.
        Throws:
        java.lang.NumberFormatException - thrown in case conversion fails.

      • getCharacter

        default java.lang.Character getCharacter​(java.lang.String... aPathElements)
                                  throws java.lang.NumberFormatException
        Returns the Character value of the property referred to by the key. As property keys and values are of type String, the String value is converted accordingly.
        Parameters:
        aPathElements - The key for which to retrieve the value.
        Returns:
        The Character representation of the key's String value.
        Throws:
        java.lang.NumberFormatException - thrown in case conversion fails.

      • getInteger

        default java.lang.Integer getInteger​(java.lang.String... aPathElements)
                              throws java.lang.NumberFormatException
        Returns the Integer value of the property referred to by the path elements. As property keys and values are of type String, the String value is converted accordingly.
        Parameters:
        aPathElements - The key for which to retrieve the value.
        Returns:
        The Integer representation of the key's String value.
        Throws:
        java.lang.NumberFormatException - thrown in case conversion fails.

      • getLong

        default java.lang.Long getLong​(java.lang.String... aPathElements)
                        throws java.lang.NumberFormatException
        Returns the Long value of the property referred to by the path elements. As property keys and values are of type String, the String value is converted accordingly.
        Parameters:
        aPathElements - The key for which to retrieve the value.
        Returns:
        The Long representation of the key's String value.
        Throws:
        java.lang.NumberFormatException - thrown in case conversion fails.

      • getShort

        default java.lang.Short getShort​(java.lang.String... aPathElements)
                          throws java.lang.NumberFormatException
        Returns the Short value of the property referred to by the path elements. As property keys and values are of type String, the String value is converted accordingly.
        Parameters:
        aPathElements - The key for which to retrieve the value.
        Returns:
        The Short representation of the key's String value.
        Throws:
        java.lang.NumberFormatException - thrown in case conversion fails.

      • getByte

        default java.lang.Byte getByte​(java.lang.String... aPathElements)
                        throws java.lang.NumberFormatException
        Returns the Byte value of the property referred to by the path elements. As property keys and values are of type String, the String value is converted accordingly.
        Parameters:
        aPathElements - The key for which to retrieve the value.
        Returns:
        The Byte representation of the key's String value.
        Throws:
        java.lang.NumberFormatException - thrown in case conversion fails.

      • getDouble

        default java.lang.Double getDouble​(java.lang.String... aPathElements)
                            throws java.lang.NumberFormatException
        Returns the Double value of the property referred to by the path elements. As property keys and values are of type String, the String value is converted accordingly.
        Parameters:
        aPathElements - The key for which to retrieve the value.
        Returns:
        The Double representation of the key's String value.
        Throws:
        java.lang.NumberFormatException - thrown in case conversion fails.

      • getFloat

        default java.lang.Float getFloat​(java.lang.String... aPathElements)
                          throws java.lang.NumberFormatException
        Returns the Float value of the property referred to by the path elements. As property keys and values are of type String, the String value is converted accordingly.
        Parameters:
        aPathElements - The key for which to retrieve the value.
        Returns:
        The Float representation of the key's String value.
        Throws:
        java.lang.NumberFormatException - thrown in case conversion fails.

      • getBoolean

        default java.lang.Boolean getBoolean​(java.lang.String... aPathElements)
                              throws java.lang.NumberFormatException
        Returns the Boolean value of the property referred to by the path elements. As property keys and values are of type String, the String value is converted accordingly.
        Parameters:
        aPathElements - The key for which to retrieve the value.
        Returns:
        The Boolean representation of the key's String value of false if there is no such key.
        Throws:
        java.lang.NumberFormatException - thrown in case conversion fails.

      • isPath

        default boolean isPath​(java.lang.String aPath)
        Determines whether the provided path represents a path within the given PathMap. The path not necessarily points to a leaf in terms of being a record or a directory. Use isChild(String) (isRecord(String) or isDirectory(String)) if we have a leaf.
        Parameters:
        aPath - The path to be tested.
        Returns:
        True in case we have a path being contained in the given PathMap, else false.

      • isIndexed

        default boolean isIndexed​()
        Determines whether the root path represents an "array" path with indexes within the given PathMap. The path not necessarily points to a leaf in terms of being a record or a directory. Use isChild(String) (isRecord(String) or isDirectory(String)) if we have a leaf. Given the following paths: /0/0aaa /0/0bbb /0/0bbb /1/1aaa /1/1bbb /1/1bbb The root path points to an index path with the two indexes "0" and "1".
        Returns:
        True in case we have a path points to an array being contained in the given PathMap, else false.

      • isIndexed

        default boolean isIndexed​(java.lang.String aPath)
        Determines whether the provided path represents an "array" path with indexes within the given PathMap. The path not necessarily points to a leaf in terms of being a record or a directory. Use isChild(String) (isRecord(String) or isDirectory(String)) if we have a leaf. Given the following paths: /root/child/0/0aaa /root/child/0/0bbb /root/child/0/0bbb /root/child/1/1aaa /root/child/1/1bbb /root/child/1/1bbb The path "/root/child" points to an index path with the two indexes "0" and "1".
        Parameters:
        aPath - The path to be tested.
        Returns:
        True in case we have a path points to an array being contained in the given PathMap, else false.

      • getIndexes

        default int[] getIndexes​()
        Returns the indexes pointing to elements of the root "array" path. You may use the method "retrieveFrom( toPath( aIndex) )" to address the sub-maps at the given index. Given the following paths: /0/0aaa /0/0bbb /0/0bbb /1/1aaa /1/1bbb /1/1bbb The root path points to an index path with the two indexes "0" and "1".
        Returns:
        The indexes which can be used

      • getIndexes

        default int[] getIndexes​(java.lang.String aPath)
        Returns the indexes pointing to elements of the given "array" path. You may use the method "retrieveFrom( toPath( aPath, aIndex) )" to address the sub-maps at the given index. Given the following paths: /root/child/0/0aaa /root/child/0/0bbb /root/child/0/0bbb /root/child/1/1aaa /root/child/1/1bbb /root/child/1/1bbb The path "/root/child" points to an index path with the two indexes "0" and "1".
        Parameters:
        aPath - The path for which to get the indexes.
        Returns:
        The indexes which can be used

      • getIndexed

        default PathMap<T> getIndexed​(int aIndex)
        Returns the accordingly indexed Elements of the root "array" path. Given the following paths and index = 1: /0/0aaa /0/0bbb /0/0bbb /1/1aaa /1/1bbb /1/1bbb You will get a result containing all the elements which's keys begin with "/1/".
        Parameters:
        aIndex - The index which to use.
        Returns:
        The indexed elements without the index in the paths.

      • getIndexed

        default PathMap<T> getIndexed​(java.lang.String aPath,
                              int aIndex)
        Returns the accordingly indexed Elements of the root "array" path. Given the following paths and index = 1 with a queried path "/root/child": /root/child/0/0aaa /root/child/0/0bbb /root/child/0/0bbb /root/child/1/1aaa /root/child/1/1bbb /root/child/1/1bbb You will get a result containing all the elements which's keys begin with "/root/child/1/".
        Parameters:
        aIndex - The index which to use.
        aPath - The path from which to get the indexed elements.
        Returns:
        The indexed elements without the index in the paths.

      • hasIndexed

        default boolean hasIndexed​(int aIndex)
        Determines whether the index points to an index root "array" path. Given the following paths: /0/0aaa /0/0bbb /0/0bbb /1/1aaa /1/1bbb /1/1bbb For indexes 0 and 1 you will get true, for all others you will get false.
        Parameters:
        aIndex - The index which to use.
        Returns:
        True if the index points to an index root "array" path.

      • hasIndexed

        default boolean hasIndexed​(java.lang.String aPath,
                           int aIndex)
        Determines whether the index points to an index root "array" path. Given the following paths: /root/child/0/0aaa /root/child/0/0bbb /root/child/0/0bbb /root/child/1/1aaa /root/child/1/1bbb /root/child/1/1bbb For path "/root/child" and indexes 0 and 1 you will get true, for all others you will get false.
        Parameters:
        aIndex - The index which to use.
        aPath - The path for which to test.
        Returns:
        True if the index points to an index root "array" path.

      • isArray

        default boolean isArray​(java.lang.String aPath)
        Determines as of getArray(String) if the elements below the given path can be seen as an array.
        Parameters:
        aPath - the path
        Returns:
        True in case we have an array structure below the path or not.

      • isArray

        default boolean isArray​(java.lang.Object aPath)
        Determines as of getArray(String) if the elements below the given path can be seen as an array.
        Parameters:
        aPath - the path
        Returns:
        True in case we have an array structure below the path or not.

      • isArray

        default boolean isArray​(java.lang.String... aPathElements)
        Determines as of getArray(String) if the elements below the given path elements can be seen as an array.
        Parameters:
        aPathElements - the path elements
        Returns:
        True in case we have an array structure below the path or not.

      • isArray

        default boolean isArray​(java.lang.Object... aPathElements)
        Determines as of getArray(String) if the elements below the given path elements can be seen as an array.
        Parameters:
        aPathElements - the path elements
        Returns:
        True in case we have an array structure below the path or not.

      • getArray

        default T[] getArray​(java.lang.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 path
        Returns:
        An array of the records found below the given path.

      • keySet

        default java.util.Set<java.lang.String> keySet​(java.lang.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 java.util.Set<java.lang.String> paths​()
        Same as Keys.keySet() with according semantics in the method name.
        Returns:
        The paths which are assigned to values.

      • paths

        default java.util.Set<java.lang.String> paths​(java.lang.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.

      • paths

        default java.util.Set<java.lang.String> paths​(java.lang.Object 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.

      • paths

        default java.util.Set<java.lang.String> paths​(java.lang.String... aPathElements)
        Same as keySet(String) with according semantics in the method name.
        Parameters:
        aPathElements - The path elements from which to start seeking.
        Returns:
        The paths (excluding the preceding given path) which are assigned to values.

      • paths

        default java.util.Set<java.lang.String> paths​(java.lang.Object... aPathElements)
        Same as keySet(String) with according semantics in the method name.
        Parameters:
        aPathElements - The path elements from which to start seeking.
        Returns:
        The paths (excluding the preceding given path) which are assigned to values.

      • isChild

        default boolean isChild​(java.lang.String aPath)
        Determines whether the give path points to an entry in terms of children(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.

      • isChild

        default boolean isChild​(java.lang.String... aPathElements)
        Determines whether the give path points to an entry in terms of children(String).
        Parameters:
        aPathElements - The path elements for which to determine whether them point to a entry.
        Returns:
        True in case the given path points to a entry, else false.

      • isChild

        default boolean isChild​(java.lang.Object... aPathElements)
        Determines whether the give path points to an entry in terms of children(String).
        Parameters:
        aPathElements - The path elements for which to determine whether them point to a entry.
        Returns:
        True in case the given path points to a entry, else false.

      • children

        default java.util.Set<java.lang.String> children​()
        Retrieves the entry names below the root 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 "/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.

      • children

        default java.util.Set<java.lang.String> children​(java.lang.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" and "loki"; calling "/" will retrieve "animals" and "machines".
        Parameters:
        aPath - The path from which to start retrieving the children.
        Returns:
        The child names (excluding the preceding given path) of the directories below the given path contained within this PathMap.

      • children

        default java.util.Set<java.lang.String> children​(java.lang.String... aPathElements)
        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 children(String) with "/animals", then the resulting Set will just contain "dogs" and "loki"; calling "/" will retrieve "animals" and "machines".
        Parameters:
        aPathElements - The path elements from which to start retrieving the children.
        Returns:
        The child names (excluding the preceding given path) of the directories below the given path contained within this PathMap.

      • hasChildren

        default boolean hasChildren​(java.lang.String aPath)
        Determines whether the give path contains children as of children(String).
        Parameters:
        aPath - The path for which to determine whether it contains entries.
        Returns:
        True in case the given path contains children.

      • hasChildren

        default boolean hasChildren​(java.lang.String... aPathElements)
        Determines whether the give path contains children as of children(String).
        Parameters:
        aPathElements - The path elements for which to determine whether them point to a entry.
        Returns:
        True in case the given path points to a entry, else false.

      • hasChildren

        default boolean hasChildren​(java.lang.Object... aPathElements)
        Determines whether the give path contains children as of children(String).
        Parameters:
        aPathElements - The path elements for which to determine whether them point to a entry.
        Returns:
        True in case the given path points to a entry, else false.

      • isDirectory

        default boolean isDirectory​(java.lang.Object 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.

      • isDirectory

        default boolean isDirectory​(java.lang.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.

      • isDirectory

        default boolean isDirectory​(java.lang.String... aPathElements)
        Determines whether the give path points to a directory in terms of directories(String).
        Parameters:
        aPathElements - The path elements for which to determine whether them point to a directory.
        Returns:
        True in case the given path points to a directory, else false.

      • isDirectory

        default boolean isDirectory​(java.lang.Object... aPathElements)
        Determines whether the give path points to a directory in terms of directories(String).
        Parameters:
        aPathElements - The path elements for which to determine whether them point to a directory.
        Returns:
        True in case the given path points to a directory, else false.

      • directories

        default java.util.Set<java.lang.String> directories​(java.lang.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.

      • directories

        default java.util.Set<java.lang.String> directories​(java.lang.Object 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.

      • directories

        default java.util.Set<java.lang.String> directories​(java.lang.String... aPathElements)
        Retrieves the directory names below the given path elements 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:
        aPathElements - The path elements 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.

      • directories

        default java.util.Set<java.lang.String> directories​(java.lang.Object... aPathElements)
        Retrieves the directory names below the given path elements 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:
        aPathElements - The path elements 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​(java.lang.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.

      • isRecord

        default boolean isRecord​(java.lang.Object 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.

      • isRecord

        default boolean isRecord​(java.lang.String... aPathElements)
        Determines whether the give path points to a record in terms of records(String).
        Parameters:
        aPathElements - The path elements for which to determine whether them points to a record.
        Returns:
        True in case the given path points to a record, else false.

      • isRecord

        default boolean isRecord​(java.lang.Object... aPathElements)
        Determines whether the give path points to a record in terms of records(String).
        Parameters:
        aPathElements - The path elements for which to determine whether them points to a record.
        Returns:
        True in case the given path points to a record, else false.

      • records

        default java.util.Set<java.lang.String> records​(java.lang.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.

      • records

        default java.util.Set<java.lang.String> records​(java.lang.Object 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.

      • records

        default java.util.Set<java.lang.String> records​(java.lang.String... aPathElements)
        Retrieves the records names below the given path elements 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:
        aPathElements - The path elements 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.

      • records

        default java.util.Set<java.lang.String> records​(java.lang.Object... aPathElements)
        Retrieves the records names below the given path elements 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:
        aPathElements - The path elements 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​(java.lang.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.

      • retrieveFrom

        default PathMap<T> retrieveFrom​(java.lang.Object aParentPath)
        Gets the children elements of the provided parent's path, excluding the parent's path.
        Parameters:
        aParentPath - The path from where to retrieve the children.
        Returns:
        The children of the given parent's path.

      • retrieveFrom

        default PathMap<T> retrieveFrom​(java.lang.String... aPathElements)
        Gets the children elements of the provided parent's path elements, excluding the parent's path.
        Parameters:
        aPathElements - The path elements from where to retrieve the children.
        Returns:
        The children of the given parent's path.

      • retrieveFrom

        default PathMap<T> retrieveFrom​(java.lang.Object... aPathElements)
        Gets the children elements of the provided parent's path elements, excluding the parent's path.
        Parameters:
        aPathElements - The path elements from where to retrieve the children.
        Returns:
        The children of the given parent's path.

      • retrieveTo

        PathMap<T> retrieveTo​(java.lang.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.

      • retrieveTo

        default PathMap<T> retrieveTo​(java.lang.Object 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.

      • retrieveTo

        default PathMap<T> retrieveTo​(java.lang.String... aToPathElements)
        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:
        aToPathElements - The path elements representing 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.

      • retrieveTo

        default PathMap<T> retrieveTo​(java.lang.Object... aToPathElements)
        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:
        aToPathElements - The path elements representing 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​(java.lang.String aFromPath,
                            java.lang.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 java.util.Map<java.lang.String,?> toMap​()
                                         throws java.lang.IllegalStateException
        Applies the toMap(String) method for the root path "/".
        Returns:
        As of toMap(String) applied to the root path.
        Throws:
        java.lang.IllegalStateException - the illegal state exception

      • toMap

        default java.util.Map<java.lang.String,?> toMap​(java.lang.String aFromPath)
                                         throws java.lang.IllegalStateException
        Creates a nested 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.
        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:
        java.lang.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.

      • toDataStructure

        java.lang.Object toDataStructure​(java.lang.String aFromPath)
        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:
        aFromPath - 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 java.lang.String toNormalizedPath​(java.lang.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.

      • fromExternalKey

        default java.lang.String fromExternalKey​(java.lang.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.
        Parameters:
        aKey - The key which's delimiters are to be converted to the default DelimiterAccessor.getDelimiter() delimiter.
        aDelimiters - The "external" delimiters in question.
        Returns:
        The converted key using the default delimiter DelimiterAccessor.getDelimiter() instead of the provided delimiters.

      • toExternalKey

        default java.lang.String toExternalKey​(java.lang.String aKey,
                                       char aDelimiter)
        Converts the given key to an external key by converting the default delimiter 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.
        Parameters:
        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().
        Returns:
        The external representation of the key as of the provided delimiter.

      • getRootPath

        default java.lang.String getRootPath​()
        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.

      • toPath

        default java.lang.String toPath​(java.lang.Object... aPathElements)
        Creates a normalized path from the provided path elements by first converting them to a String (if not being a String already) and then concatenating the elements with the path delimiter DelimiterAccessor.getDelimiter() in between and taking care to avoid duplicate path delimiters.
        Parameters:
        aPathElements - The elements of the path to be concatenated with the path delimiter.
        Returns:
        The concatenated and normalized path.

      • toPath

        default java.lang.String toPath​(java.lang.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.
        Parameters:
        aPathElements - The elements of the path to be concatenated with the path delimiter.
        Returns:
        The concatenated and normalized path.

      • isRootPath

        default boolean isRootPath​(java.lang.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 java.lang.String toNormalizedPath​(java.lang.String aParentPath,
                                          java.lang.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​(java.lang.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 java.lang.String toParentPath​(java.lang.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:
        java.lang.IllegalArgumentException - thrown in case there is no such parent path for the given path; test beforehand using hasParentPath(String).