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

Class PathWalker

java.lang.Object
org.klojang.path.PathWalker
public final class PathWalker extends Object
A PathWalker lets you read and write deeply nested values using Path objects. It can read almost any type of object it encounters as it walks down the path towards the last path segment: JavaBeans, maps, collections, arrays and scalar values. It can also write to most of them. A PathWalker can be useful when processing large batches of sparsely populated maps or objects and/or it doesn't really matter whether a deeply nested value is null or just not present at all. By default, the PathWalker will return null in either case (although you can change this).
Author:
Ayco Holleman

  • Constructor Summary

    Constructors
    Constructor
    Description
    PathWalker(String... paths)
    Creates a PathWalker for the specified paths.
    PathWalker(List<Path> paths)
    Creates a PathWalker for the specified paths.
    PathWalker(List<Path> paths, boolean suppressExceptions)
    Creates a PathWalker for the specified paths.
    PathWalker(List<Path> paths, boolean suppressExceptions, KeyDeserializer keyDeserializer)
    Creates a PathWalker for the specified paths.
    PathWalker(Path... paths)
    Creates a PathWalker for the specified paths.

  • Method Summary

    Modifier and Type
    Method
    Description
    <T> T
    read(Object host)
    Reads the value of the first path specified through the constructor.
    static <T> T
    read(Object host, String path)
    Returns the value of the specified path within the specified object.
    static <T> T
    read(Object host, Path path)
    Returns the value of the specified path within the specified object.
    Object[]
    readValues(Object host)
    Returns the values of all paths specified through the constructor.
    void
    readValues(Object host, Object[] output)
    Reads the values of all paths specified through the constructor.
    void
    readValues(Object host, Map<Path,Object> output)
    Reads the values of all paths and inserts them into the provided path-to-value map.
    boolean
    write(Object host, Object value)
    Sets the value of the first path specified through the constructor.
    int
    writeValues(Object host, Object... values)
    Sets the values of the paths specified through the constructor.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • PathWalker

      public PathWalker(Path... paths)
      Creates a PathWalker for the specified paths.
      Parameters:
      paths - one or more paths representing possibly deeply-nested properties

    • PathWalker

      public PathWalker(String... paths)
      Creates a PathWalker for the specified paths.
      Parameters:
      paths - the paths to walk through the provided host objects

    • PathWalker

      public PathWalker(List<Path> paths)
      Creates a PathWalker for the specified paths.
      Parameters:
      paths - the paths to walk through the provided host objects

    • PathWalker

      public PathWalker(List<Path> paths, boolean suppressExceptions)
      Creates a PathWalker for the specified paths.
      Parameters:
      paths - the action to take if a path could not be read or written
      suppressExceptions - if true, the read methods will return null for paths that could not be read. The write methods will quietly return without having written the value. If false, a PathWalkerException will be thrown detailing the error.

    • PathWalker

      public PathWalker(List<Path> paths, boolean suppressExceptions, KeyDeserializer keyDeserializer)
      Creates a PathWalker for the specified paths.
      Parameters:
      paths - the paths to walk
      suppressExceptions - if true, the read methods will return null for paths that could not be read. The write methods will quietly return without having written the value. If false, a PathWalkerException will be thrown detailing the error.
      keyDeserializer - A function that converts path segments to map keys. You need to provide this if the host objects are, or contain, Map instances with non-string keys.

  • Method Details

    • read

      public static <T> T read(Object host, String path)
      Returns the value of the specified path within the specified object. This method returns null if the path is invalid or if it is blocked midway by a null value or an out-of-range index.
      Type Parameters:
      T - the type of the value
      Parameters:
      host - the object to read the value from
      path - the path to the value
      Returns:
      the value of the specified path within the specified object

    • read

      public static <T> T read(Object host, Path path)
      Returns the value of the specified path within the specified object. This method returns null if the path is invalid or if it is blocked midway by a null value or an out-of-range index.
      Type Parameters:
      T - the type of the value
      Parameters:
      host - the object to read the value from
      path - the path to the value
      Returns:
      the value of the specified path within the specified object

    • readValues

      public Object[] readValues(Object host) throws PathWalkerException
      Returns the values of all paths specified through the constructor.
      Parameters:
      host - the object to read the values from
      Returns:
      the values of all paths specified through the constructor
      Throws:
      PathWalkerException - If suppressExceptions is false and the PathWalker fails to retrieve the values of one or more paths.

    • readValues

      public void readValues(Object host, Object[] output) throws PathWalkerException
      Reads the values of all paths specified through the constructor.
      Parameters:
      host - the object to read the path values from
      output - an array into which to place the values. The length of the output array must be equal to, or greater than the number of paths specified through the constructor.
      Throws:
      PathWalkerException - If suppressExceptions is false and the PathWalker fails to retrieve the values of one or more paths.

    • readValues

      public void readValues(Object host, Map<Path,Object> output) throws PathWalkerException
      Reads the values of all paths and inserts them into the provided path-to-value map.
      Parameters:
      host - the object from which to read the values
      output - The Map into which to put the values
      Throws:
      PathWalkerException - If suppressExceptions is false and the PathWalker fails to retrieve the values of one or more paths.

    • read

      public <T> T read(Object host)
      Reads the value of the first path specified through the constructor. Convenient if you specified just one path.
      Type Parameters:
      T - The type of the value being returned
      Parameters:
      host - the object from which to read the value
      Returns:
      the value of the first path specified through the constructor
      Throws:
      PathWalkerException - If suppressExceptions is false and the PathWalker fails to retrieve the value of the first path.

    • writeValues

      public int writeValues(Object host, Object... values)
      Sets the values of the paths specified through the constructor. The provided array of values must have the same length as the number of paths.
      Parameters:
      host - the object to which to write the values
      values - The values to write
      Returns:
      the number of successfully written values

    • write

      public boolean write(Object host, Object value)
      Sets the value of the first path specified through the constructor. Convenient if you specified just one path.
      Parameters:
      host - the object to write the value to
      value - The value to write
      Returns:
      true if the value was successfully written