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 differently structured 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.

Exception Suppression

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 failing to read a value, and false when failing to write a value. However, the PathWalker class contains constructors that allow you to disable exception suppression. With exception suppression disabled a PathWalker will throw a DeadEndException when failing to read/write a value, which may be useful for debugging.

Path Segment Deserialization

If you want a PathWalker to be able to read from, or write to maps with a non-String key type, you must instruct the PathWalker how to deserialize the path segment representing the key. This is done using a PathSegmentDeserializer. The PathWalker class has a constructor that enables you to specify a PathSegmentDeserializer.

Author:
Ayco Holleman

  • Constructor Details

    • PathWalker

      public PathWalker(Path... paths)
      Creates a PathWalker for the specified paths.
      Parameters:
      paths - the paths to read or write

    • PathWalker

      public PathWalker(String... paths)
      Creates a PathWalker for the specified paths.
      Parameters:
      paths - the paths to read or write

    • PathWalker

      public PathWalker(List<Path> paths)
      Creates a PathWalker for the specified paths.
      Parameters:
      paths - the paths to read or write

    • PathWalker

      public PathWalker(List<Path> paths, boolean suppressExceptions)
      Creates a PathWalker for the specified paths.
      Parameters:
      paths - the paths to read or write
      suppressExceptions - whether to enable exception suppression

    • PathWalker

      public PathWalker(List<Path> paths, boolean suppressExceptions, PathSegmentDeserializer segmentDeserializer)
      Creates a PathWalker for the specified paths.
      Parameters:
      paths - the paths to read or write
      suppressExceptions - whether to enable exception suppression
      segmentDeserializer - a function that deserializes path segments into non-String map keys

  • Method Details

    • 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

    • readAll

      public Map<Path, Result<Object>> readAll(Object host) throws DeadEndException
      Returns the values of the paths specified through the constructor. The returned map maps the paths to their values.
      Parameters:
      host - the object to read the values from
      Returns:
      the values of the paths specified through the constructor
      Throws:
      DeadEndException - if exception suppression is disabled and the PathWalker fails to retrieve the values of one or more paths.

    • readIntoMap

      public Map<String, Result<Object>> readIntoMap(Object host) throws DeadEndException
      Returns the values of the paths specified through the constructor. The returned map maps the path strings to their values.
      Parameters:
      host - the object to read the values from
      Returns:
      the values of the paths specified through the constructor
      Throws:
      DeadEndException - if exception suppression is disabled and the PathWalker fails to retrieve the values of one or more paths.

    • readIntoList

      public List<Result<Object>> readIntoList(Object host) throws DeadEndException
      Returns the values of the paths specified through the constructor. The values are returned in the same order as the paths.
      Parameters:
      host - the object to read the values from
      Returns:
      the values of the paths specified through the constructor
      Throws:
      DeadEndException - if exception suppression is disabled 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 exception suppression is disabled and the PathWalker fails to retrieve the values of one or more paths.

    • 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)
      Sets the values of the paths specified through the constructor. The provided List of values must have the same size 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.

    • 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