Class Path

java.lang.Object
org.klojang.util.Path
All Implemented Interfaces:
Comparable<Path>, Iterable<String>, org.klojang.check.extra.Emptyable
public final class Path extends Object implements Comparable<Path>, Iterable<String>, org.klojang.check.extra.Emptyable
Specifies a path to a value within an object. For example: employee.address.city. A path string consists of path segments separated by the dot character ('.'). Array indices are specified as separate path segments. For example: employees.3.address.city — the city component of the address of the fourth employee in a list or array of Employee instances. Non-numeric segments can be bean properties, record components, or map keys. Notably because of the last possibility, 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. Path segments representing bean properties or record components must of course be valid Java identifier strings.

Escaping

These are the escaping rules when specifying path strings:

  • If a map key happens to contain the segment separator ('.'), it must be escaped using the circumflex character ('^'). So key "my.awkward.map.key" should be escaped to "my^.awkward^.map^.key".
  • For a map key with value null, use this escape sequence: "^0". So "lookups.^0" represents the null key in the lookups map.
  • If a segment needs to represent a map key whose value is the empty string, simply make it a zero-length segment: "lookups..name". This implies that a path string that ends with a dot in fact ends with an empty (zero-length) segment.
  • The escape character ('^') itself may optionally be escaped. Thus, key "super^awkward" can be represented either as "super^awkward" or as "super^^awkward". If the escape character is not followed by a dot or another escape character, it is just that character. You must escape the escape character, though, if the entire path segment happens to be the escape sequence for null ("^0"). Thus, in the odd case you have a key with value "^0", escape it to "^^0".

You can let the escape method do the escaping for you. Important: do not escape path segments when passing them individually, as a String array. Only escape them when passing a complete path string.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    NULL_SEGMENT
    escape sequence to use for null keys: ^0

  • 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
    empty()
    Returns an empty Path instance, consisting of zero path segments.
    boolean
    equals(Object obj)
     
    static String
    escape(String segment)
    Escapes the specified path segment.
    String
    firstSegment()
    Returns the first segment of the path.
    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
    isDeepNotEmpty()
    Returns true if this is a non-empty Path, consisting only of non-null, non-empty of path segments.
    boolean
    isEmpty()
    Returns true if this is an empty Path, consisting of zero segments.
    Iterator<String>
    iterator()
    Returns an Iterator over the path segments.
    String
    lastSegment()
    Returns the last segment of the path.
    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.
    static Path
    ofSegments(List<String> segments)
    Returns a Path consisting of the specified segments.
    Path
    parent()
    Returns a Path with all segments of this Path except the last segment.
    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 java.lang.Iterable

    forEach, spliterator

  • Field Details

  • 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

    • ofSegments

      public static Path ofSegments(String[] segments)
      Returns a Path consisting of the specified segments. Do not escape the segments. The array may contain null values as well as empty strings.
      Parameters:
      segments - the path segments
      Returns:
      a Path consisting of the specified segments

    • ofSegments

      public static Path ofSegments(List<String> segments)
      Returns a Path consisting of the specified segments. Do not escape the segments. The array may contain null values as well as empty strings.
      Parameters:
      segments - the path segments
      Returns:
      a Path consisting of the specified segments

    • 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

    • escape

      public static String escape(String segment)
      Escapes the specified path segment. Do not escape path segments when passing them individually to one of the static factory methods. Only use this method to assemble complete path strings from individual path segments. Generally you don't need this method when specifying path strings, unless one or more path segments contain a dot ('.') or the escape character ('^') itself. The argument may be null, in which case the escape sequence for null ("^0") is returned.
      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.

    • firstSegment

      public String firstSegment()
      Returns the first segment of the path.
      Returns:
      the first segment of the path

    • lastSegment

      public String lastSegment()
      Returns the last segment of the path.
      Returns:
      the last segment of the path

    • shift

      public Path shift()
      Returns a Path with all segments of this Path except the first segment. If the path is empty, this method returns null. If it consists of a single segment, this method returns EMPTY_PATH.
      Returns:
      a Path with all segments of this Path except the first segment

    • parent

      public Path parent()
      Returns a Path with all segments of this Path except the last segment. If the path is empty, this method returns null. If it consists of a single segment, this method returns EMPTY_PATH.
      Returns:
      the parent of this Path

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

    • 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

    • 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 org.klojang.check.extra.Emptyable
      Returns:
      true if this is an empty Path, consisting of zero segments

    • isDeepNotEmpty

      public boolean isDeepNotEmpty()
      Returns true if this is a non-empty Path, consisting only of non-null, non-empty of path segments.
      Specified by:
      isDeepNotEmpty in interface org.klojang.check.extra.Emptyable
      Returns:
      true if this is a non-empty Path, consisting only of non-null, non-empty of path 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