Interface PathMap<T>

Type Parameters:
T - The type of the value elements.
All Superinterfaces:
org.refcodes.mixin.AnnotatorAccessor, Containable, org.refcodes.mixin.DelimiterAccessor, org.refcodes.mixin.Dumpable, org.refcodes.mixin.EmptyAccessor, Keys<String,T>, Table<String,T>, org.refcodes.mixin.TypeAccessor<T>
All Known Subinterfaces:
CanonicalMap, CanonicalMap.CanonicalMapBuilder, CanonicalMap.MutableCanonicalMap, ClassStructMap, ClassStructMap.ClassStructMapBuilder, ClassStructMap.MutableClassStructMap, InterOperableMap<T>, InterOperableMap.InterOperableMapBuilder<T>, InterOperableMap.MutableInterOperableMap<T>, PathMap.MutablePathMap<T>, PathMap.PathMapBuilder<T>, SimpleTypeMap, SimpleTypeMap.MutableSimpleTypeMap, SimpleTypeMap.SimpleTypeMapBuilder
All Known Implementing Classes:
CanonicalMapBuilderImpl, CanonicalMapImpl, ClassStructMapBuilderImpl, ClassStructMapImpl, PathMapBuilderImpl, PathMapImpl, SimpleTypeMapBuilderImpl, SimpleTypeMapImpl

public interface PathMap<T> extends Table<String,T>, org.refcodes.mixin.TypeAccessor<T>, org.refcodes.mixin.Dumpable, org.refcodes.mixin.DelimiterAccessor, org.refcodes.mixin.AnnotatorAccessor
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 leaves and directories. A leave 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 leaves whereas "animals", "dogs", "machines" and "robots" are recokned to be directories: *

  • "/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 like "/animals/dogs/otto".

A path is also handled as 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" leave.

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. In such a case additional array related functionality is at your hands. E.g. isIndexDir(String), getDirAt(String, int) or getArray(String).

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