Module org.klojang.invoke
Package org.klojang.path

Class Path

java.lang.Object
org.klojang.path.Path
All Implemented Interfaces:
Comparable<Path>, Iterable<String>, Emptyable
public final class Path extends Object implements Comparable<Path>, Iterable<String>, Emptyable
Specifies a path to a value within an object. For example: employee.address.street. Path segments are separated by the dot character ('.'). Array indices are specified as separate path segments. For example: employees.3.address.street. Non-numeric segments can be either bean properties or map keys. Therefore the Path class does not impose any constraints on what constitutes a valid path segment. A map key, after all, can be anything - including null and the empty string. Of course, if the path segment denotes a JavaBean property, it should be a valid Java identifier.

Escaping

These are the escaping rules when specifying path strings:

  • If a path segment represents a map key that happens to contain the segment separator ('.'), it must be escaped using the circumflex character ('^'). So a map key with the value "my.awkward.map.key" should be escaped like this: "my^.awkward^.map^.key".
  • The escape character ('^') itself must not be escaped. Thus, if the escape character is followed by anything but a dot or the zero character (see next rule), it is just that character.
  • If a segment needs to denote a map key with value null, use this escape sequence: "^0". So the path "lookups.^0.name" references the name field of an object stored under key null in the lookups map.
  • If a segment needs to denote a map key whose value is the empty string, simply make it a zero-length segment: "lookups..name". This also implies that a path string that ends with a dot in fact ends with an empty (zero-length) segment.

If a path segment represents a map key that happens to contain the segment separator ('.'), it must be escaped using the circumflex character ('^'). So a map key with the unfortunate value of "my.awkward.map.key" should be escaped like this: "my^.awkward^.map^.key". The escape character itself must not be escaped. If a segment needs to denote a map key with value null, use this escape sequence: "^0". So the path "lookups.^0.name" references the name field of an object stored under key null in the lookups map. In case you want a segment to denote a map key whose value is the empty string, simply make it a zero-length segment: "lookups..name".

You can let the escape method do the escaping for you.

Do not escape path segments when passing them individually (as a String array) to the constructor. Only escape them when passing a complete path string.

Author:
Ayco Holleman

  • Method Summary

    Modifier and Type
    Method
    Description
    Path
    append(String path)
    Returns a new Path representing the concatenation of this Path and the specified Path.
    Path
    append(Path other)
    Returns a new Path consisting of the segments of this Path plus the segments of the specified Path.
    int
    compareTo(Path other)
     
    static Path
    copyOf(Path other)
    Returns a copy of the specified path.
    static Path
    empty()
    Returns an empty Path instance, consisting of zero path segments.
    boolean
    equals(Object obj)
     
    static String
    escape(String segment)
    Escapes the provided path segment.
    static Path
    from(String path)
    Returns a new Path instance for the specified path string.
    Path
    getCanonicalPath()
    Returns a new Path containing only the segments of this Path that are not array indices.
    int
    hashCode()
     
    boolean
    isEmpty()
    Returns true if this is an empty Path, consisting of zero segments.
    Iterator<String>
    iterator()
    Returns an Iterator over the path segments.
    static Path
    of(String segment)
    Returns a Path consisting of a single segment.
    static Path
    of(String... segments)
    Returns a Path consisting of the specified segments.
    static Path
    of(String segment0, String segment1)
    Returns a Path consisting of the specified segments.
    static Path
    of(String segment0, String segment1, String segment2)
    Returns a Path consisting of the specified segments.
    static Path
    of(String segment0, String segment1, String segment2, String segment3)
    Returns a Path consisting of the specified segments.
    static Path
    of(String segment0, String segment1, String segment2, String segment3, String segment4)
    Returns a Path consisting of the specified segments.
    static Path
    ofSegments(String[] segments)
    Returns a Path consisting of the specified segments.
    Path
    parent()
    Return the parent of this Path.
    Path
    replace(int index, String newValue)
    Returns a new Path with the path segment at the specified array index set to the new value.
    Path
    reverse()
    Returns a Path in which the order of the segments is reversed.
    String
    segment(int index)
    Returns the path segment at the specified index.
    Path
    shift()
    Returns a Path with all segments of this Path except the first segment.
    int
    size()
    Returns the number of segments in this Path.
    Stream<String>
    stream()
    Returns a Stream of path segments.
    Path
    subPath(int offset)
    Returns a new Path starting with the segment at the specified array index.
    Path
    subPath(int offset, int length)
    Returns a new Path consisting of length segments starting with segment offset.
    String
    toString()
    Returns this Path as a string, properly escaped.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

    Methods inherited from interface org.klojang.check.aux.Emptyable

    isDeepNotEmpty

    Methods inherited from interface java.lang.Iterable

    forEach, spliterator

  • Method Details

    • from

      public static Path from(String path)
      Returns a new Path instance for the specified path string.
      Parameters:
      path - the path string from which to create a Path
      Returns:
      a new Path instance for the specified path string

    • empty

      public static Path empty()
      Returns an empty Path instance, consisting of zero path segments.
      Returns:
      an empty Path instance, consisting of zero path segments

    • of

      public static Path of(String segment)
      Returns a Path consisting of a single segment. Do not escape the segment.
      Parameters:
      segment - the one and only segment of the Path
      Returns:
      a Path consisting of a single segment

    • of

      public static Path of(String segment0, String segment1)
      Returns a Path consisting of the specified segments. Do not escape the segments.
      Parameters:
      segment0 - the 1st segment
      segment1 - the 2nd segment
      Returns:
      a Path consisting of the specified segments

    • of

      public static Path of(String segment0, String segment1, String segment2)
      Returns a Path consisting of the specified segments. Do not escape the segments.
      Parameters:
      segment0 - the 1st segment
      segment1 - the 2nd segment
      segment2 - the 3rd segment
      Returns:
      a Path consisting of the specified segments

    • of

      public static Path of(String segment0, String segment1, String segment2, String segment3)
      Returns a Path consisting of the specified segments. Do not escape the segments.
      Parameters:
      segment0 - the 1st segment
      segment1 - the 2nd segment
      segment2 - the 3rd segment
      segment3 - the 4th segment
      Returns:
      a Path consisting of the specified segments

    • of

      public static Path of(String segment0, String segment1, String segment2, String segment3, String segment4)
      Returns a Path consisting of the specified segments. Do not escape the segments.
      Parameters:
      segment0 - the 1st segment
      segment1 - the 2nd segment
      segment2 - the 3rd segment
      segment3 - the 4th segment
      segment4 - the 5th segment
      Returns:
      a Path consisting of the specified segments

    • of

      public static Path of(String... segments)
      Returns a Path consisting of the specified segments. Do not escape the segments.
      Parameters:
      segments - the path segments
      Returns:
      a Path consisting of the specified segments

    • ofSegments

      public static Path ofSegments(String[] segments)
      Returns a Path consisting of the specified segments. Do not escape the segments.
      Parameters:
      segments - the path segments
      Returns:
      a Path consisting of the specified segments

    • copyOf

      public static Path copyOf(Path other)
      Returns a copy of the specified path.
      Parameters:
      other - the Path to copy.
      Returns:
      a copy of the specified path

    • escape

      public static String escape(String segment)
      Escapes the provided path segment. Do not escape path segments when passing them individually to one of the static factory methods. Only use this method to construct complete path strings from individual path segments. Generally you don't need this method when specifying path strings, unless one or more segments contain a dot ('.') or the escape character ('^') itself.
      Parameters:
      segment - The path segment to escape
      Returns:
      the escaped version of the segment

    • segment

      public String segment(int index)
      Returns the path segment at the specified index. Specify a negative index to retrieve a segment relative to end of the Path (-1 would return the last path segment).
      Parameters:
      index - The array index of the path segment
      Returns:
      the path segment at the specified index.

    • subPath

      public Path subPath(int offset)
      Returns a new Path starting with the segment at the specified array index. Specify a negative index to count back from the last segment of the Path (-1 returns the last path segment).
      Parameters:
      offset - The index of the first segment of the new Path
      Returns:
      a new Path starting with the segment at the specified array index

    • subPath

      public Path subPath(int offset, int length)
      Returns a new Path consisting of length segments starting with segment offset. The offset argument may be negative to specify a segment relative to the end of the Path. Thus, -1 specifies the last segment of the Path.
      Parameters:
      offset - The index of the first segment to extract
      length - The number of segments to extract
      Returns:
      a new Path consisting of len segments starting with segment from.

    • parent

      public Path parent()
      Return the parent of this Path. If the path is empty, this method returns null. If it consists of a single segment, and empty Path is returned.
      Returns:
      the parent of this Path

    • getCanonicalPath

      public Path getCanonicalPath()
      Returns a new Path containing only the segments of this Path that are not array indices.
      Returns:
      a new Path without any array indices

    • append

      public Path append(String path)
      Returns a new Path representing the concatenation of this Path and the specified Path.
      Parameters:
      path - The path to append to this Path
      Returns:
      a new Path representing the concatenation of this Path and the specified Path

    • append

      public Path append(Path other)
      Returns a new Path consisting of the segments of this Path plus the segments of the specified Path.
      Parameters:
      other - the Path to append to this Path.
      Returns:
      a new Path consisting of the segments of this Path plus the segments of the specified Path

    • replace

      public Path replace(int index, String newValue)
      Returns a new Path with the path segment at the specified array index set to the new value.
      Parameters:
      index - The array index of the segment to replace
      newValue - The new segment
      Returns:
      a new Path with the path segment at the specified array index set to the new value

    • shift

      public Path shift()
      Returns a Path with all segments of this Path except the first segment.
      Returns:
      a Path with all segments of this Path except the first segment

    • reverse

      public Path reverse()
      Returns a Path in which the order of the segments is reversed.
      Returns:
      a Path in which the order of the segments is reversed

    • iterator

      public Iterator<String> iterator()
      Returns an Iterator over the path segments.
      Specified by:
      iterator in interface Iterable<String>
      Returns:
      an Iterator over the path segments

    • stream

      public Stream<String> stream()
      Returns a Stream of path segments.
      Returns:
      a Stream of path segments

    • size

      public int size()
      Returns the number of segments in this Path.
      Returns:
      the number of segments in this Path

    • isEmpty

      public boolean isEmpty()
      Returns true if this is an empty Path, consisting of zero segments.
      Specified by:
      isEmpty in interface Emptyable
      Returns:
      true if this is an empty Path, consisting of zero segments

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • compareTo

      public int compareTo(Path other)
      Specified by:
      compareTo in interface Comparable<Path>

    • toString

      public String toString()
      Returns this Path as a string, properly escaped.
      Overrides:
      toString in class Object
      Returns:
      this Path as a string, properly escaped