Class PathWalker

java.lang.Object
org.klojang.path.PathWalker
public final class PathWalker extends Object

A PathWalker lets you read from, and write to objects using Path objects. The value you read or write can be deeply nested inside the object. The Path object specifies where inside the object the value is located. A PathWalker can read almost any type of object it encounters as it walks down the path towards the last path segment: JavaBeans, records, maps, collections, arrays and scalar values. It can also write to most of them. The PathWalker class has various use cases:

  • When processing large batches of sparsely populated objects
  • When processing large batches of variously typed objects
  • When it does not really matter whether a deeply nested value is null or just not present at all
  • To keep your code concise and clean when reading a deeply nested value.

By default, a PathWalker will not throw an exception if it cannot read or write a value — that is, if it cannot walk a path all the way down to the last path segment. That would defy the purposes listed above. Instead, it just returns Result.notAvailable() when reading values and false when writing values. However, the PathWalker contains a constructor that enables you to enable and disable exception suppression. Without exception suppression a PathWalker will throw a DeadEndException when failing to read/write a value, which may be useful when debugging.

Author:
Ayco Holleman

  • 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 DeadEndException will be thrown detailing the error.

    • PathWalker

      public PathWalker(List<Path> paths, boolean suppressExceptions, PathSegmentDeserializer segmentDeserializer)
      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 DeadEndException will be thrown detailing the error.
      segmentDeserializer - A function that converts path segments to map keys. You need to provide this when reading from, or writing to Map objects with a non-String key type.

  • Method Details

    • get

      public static <T> T get(Object host, String path)
      Returns the value at the specified path. If the value could not be read a NoSuchElementException exception is thrown (see Result.get()). This method is useful if you already know for sure that the specified path can be traced through the specified host object.
      Type Parameters:
      T - the type of the value
      Parameters:
      host - the object from which to read the value
      path - the path specifying where to find the value
      Returns:
      the value at the specified path

    • read

      public static <T> Result<T> read(Object host, String path)
      Returns a Result object containing the value at the specified path or Result.notAvailable() if the value could not be retrieved.
      Type Parameters:
      T - the type of the value
      Parameters:
      host - the object from which to read the value
      path - the path specifying where to find the value
      Returns:
      a Result object containing the value at the specified path or Result.notAvailable() if the value could not be retrieved

    • readValues

      public List<Result<Object>> readValues(Object host) throws DeadEndException
      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:
      DeadEndException - If suppressExceptions is false and the PathWalker fails to retrieve the values of one or more paths.

    • read

      public <T> Result<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:
      DeadEndException - If suppressExceptions is false and the PathWalker fails to retrieve the value of the first path.

    • writeValues

      public boolean[] 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:
      a boolean array indicating which paths could successfully be set, and which could not.

    • writeValues

      public boolean[] writeValues(Object host, List<Object> 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