Package io.github.jspinak.brobot.runner.json.parsing

Class JsonPathUtils

java.lang.Object
io.github.jspinak.brobot.runner.json.parsing.JsonPathUtils
@Component public class JsonPathUtils extends Object
Provides utilities for navigating and extracting data from JSON structures using path notation.

This class simplifies working with complex JSON structures by providing type-safe accessors and path-based navigation. It supports dot notation for accessing nested properties and numeric indices for array elements.

Path notation examples:

  • "field" - Access a top-level field
  • "parent.child" - Access a nested field
  • "array.0" - Access the first element of an array
  • "parent.array.2.field" - Complex nested path with array access

The class provides:

  • Type-safe getters for primitives (string, int, boolean)
  • Optional variants for graceful handling of missing values
  • Collection utilities for working with arrays
  • Path existence checking
See Also:

  • Constructor Summary

    Constructors
    Constructor
    Description
    JsonPathUtils()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    Optional<com.fasterxml.jackson.databind.JsonNode>
    findInArray(com.fasterxml.jackson.databind.JsonNode root, String arrayPath, Function<com.fasterxml.jackson.databind.JsonNode,Boolean> predicate)
    Finds the first element in a JSON array that matches the given predicate.
    void
    forEachInArray(com.fasterxml.jackson.databind.JsonNode root, String arrayPath, Consumer<com.fasterxml.jackson.databind.JsonNode> consumer)
    Iterates over each element in a JSON array, applying the given consumer.
    com.fasterxml.jackson.databind.node.ArrayNode
    getArray(com.fasterxml.jackson.databind.JsonNode root, String path)
    Get an array node from a path
    boolean
    getBoolean(com.fasterxml.jackson.databind.JsonNode root, String path)
    Get a boolean value from a JSON path
    List<String>
    getFieldNames(com.fasterxml.jackson.databind.JsonNode root, String objectPath)
    Retrieves all field names from a JSON object at the specified path.
    int
    getInt(com.fasterxml.jackson.databind.JsonNode root, String path)
    Get an integer value from a JSON path
    com.fasterxml.jackson.databind.JsonNode
    getNode(com.fasterxml.jackson.databind.JsonNode root, String path)
    Navigates to and retrieves a JSON node at the specified path.
    com.fasterxml.jackson.databind.node.ObjectNode
    getObject(com.fasterxml.jackson.databind.JsonNode root, String path)
    Get an object node from a path
    Optional<com.fasterxml.jackson.databind.node.ArrayNode>
    getOptionalArray(com.fasterxml.jackson.databind.JsonNode root, String path)
    Get an optional array node from a path
    Optional<Boolean>
    getOptionalBoolean(com.fasterxml.jackson.databind.JsonNode root, String path)
    Get an optional boolean value from a JSON path
    Optional<Integer>
    getOptionalInt(com.fasterxml.jackson.databind.JsonNode root, String path)
    Get an optional integer value from a JSON path
    Optional<com.fasterxml.jackson.databind.node.ObjectNode>
    getOptionalObject(com.fasterxml.jackson.databind.JsonNode root, String path)
    Get an optional object node from a path
    Optional<String>
    getOptionalString(com.fasterxml.jackson.databind.JsonNode root, String path)
    Retrieves an optional string value from a JSON path.
    String
    getString(com.fasterxml.jackson.databind.JsonNode root, String path)
    Retrieves a string value from a JSON path.
    boolean
    hasPath(com.fasterxml.jackson.databind.JsonNode root, String path)
    Checks if a path exists in the JSON structure.
    <T> List<T>
    mapArray(com.fasterxml.jackson.databind.JsonNode root, String arrayPath, Function<com.fasterxml.jackson.databind.JsonNode,T> mapper)
    Transforms each element in a JSON array into a list of typed objects.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • JsonPathUtils

      public JsonPathUtils()

  • Method Details

    • getString

      public String getString(com.fasterxml.jackson.databind.JsonNode root, String path) throws ConfigurationException
      Retrieves a string value from a JSON path.

      The path must point to a text node. If the node exists but is not textual (e.g., number, boolean, object, array), a ConfigurationException is thrown.

      Parameters:
      root - The root JSON node to start navigation from
      path - The dot-notation path to the value (e.g., "config.name")
      Returns:
      The string value at the specified path
      Throws:
      ConfigurationException - if the path doesn't exist or the value is not a string

    • getOptionalString

      public Optional<String> getOptionalString(com.fasterxml.jackson.databind.JsonNode root, String path)
      Retrieves an optional string value from a JSON path.

      This method provides a null-safe way to access string values. If the path doesn't exist or the value is not a string, an empty Optional is returned instead of throwing an exception.

      Parameters:
      root - The root JSON node to start navigation from
      path - The dot-notation path to the value
      Returns:
      An Optional containing the string value, or empty if not found/not a string

    • getInt

      public int getInt(com.fasterxml.jackson.databind.JsonNode root, String path) throws ConfigurationException
      Get an integer value from a JSON path
      Parameters:
      root - The root JSON node
      path - The path to the value (dot notation)
      Returns:
      The integer value
      Throws:
      ConfigurationException - if the path doesn't exist or the value is not an integer

    • getOptionalInt

      public Optional<Integer> getOptionalInt(com.fasterxml.jackson.databind.JsonNode root, String path)
      Get an optional integer value from a JSON path
      Parameters:
      root - The root JSON node
      path - The path to the value (dot notation)
      Returns:
      An optional integer value

    • getBoolean

      public boolean getBoolean(com.fasterxml.jackson.databind.JsonNode root, String path) throws ConfigurationException
      Get a boolean value from a JSON path
      Parameters:
      root - The root JSON node
      path - The path to the value (dot notation)
      Returns:
      The boolean value
      Throws:
      ConfigurationException - if the path doesn't exist or the value is not a boolean

    • getOptionalBoolean

      public Optional<Boolean> getOptionalBoolean(com.fasterxml.jackson.databind.JsonNode root, String path)
      Get an optional boolean value from a JSON path
      Parameters:
      root - The root JSON node
      path - The path to the value (dot notation)
      Returns:
      An optional boolean value

    • getNode

      public com.fasterxml.jackson.databind.JsonNode getNode(com.fasterxml.jackson.databind.JsonNode root, String path) throws ConfigurationException
      Navigates to and retrieves a JSON node at the specified path.

      This is the core navigation method that supports:

      • Dot notation for object field access
      • Numeric indices for array element access
      • Mixed paths combining objects and arrays

      Examples:

      • "field" - Returns root.field
      • "parent.child" - Returns root.parent.child
      • "items.0.name" - Returns root.items[0].name
      Parameters:
      root - The root JSON node to start navigation from
      path - The dot-notation path to navigate (empty/null returns root)
      Returns:
      The JsonNode at the specified path
      Throws:
      ConfigurationException - if any part of the path doesn't exist or is invalid

    • getArray

      public com.fasterxml.jackson.databind.node.ArrayNode getArray(com.fasterxml.jackson.databind.JsonNode root, String path) throws ConfigurationException
      Get an array node from a path
      Parameters:
      root - The root JSON node
      path - The path to the array (dot notation)
      Returns:
      The array node
      Throws:
      ConfigurationException - if the path doesn't exist or the node is not an array

    • getOptionalArray

      public Optional<com.fasterxml.jackson.databind.node.ArrayNode> getOptionalArray(com.fasterxml.jackson.databind.JsonNode root, String path)
      Get an optional array node from a path
      Parameters:
      root - The root JSON node
      path - The path to the array (dot notation)
      Returns:
      An optional array node

    • getObject

      public com.fasterxml.jackson.databind.node.ObjectNode getObject(com.fasterxml.jackson.databind.JsonNode root, String path) throws ConfigurationException
      Get an object node from a path
      Parameters:
      root - The root JSON node
      path - The path to the object (dot notation)
      Returns:
      The object node
      Throws:
      ConfigurationException - if the path doesn't exist or the node is not an object

    • getOptionalObject

      public Optional<com.fasterxml.jackson.databind.node.ObjectNode> getOptionalObject(com.fasterxml.jackson.databind.JsonNode root, String path)
      Get an optional object node from a path
      Parameters:
      root - The root JSON node
      path - The path to the object (dot notation)
      Returns:
      An optional object node

    • hasPath

      public boolean hasPath(com.fasterxml.jackson.databind.JsonNode root, String path)
      Checks if a path exists in the JSON structure.

      This method provides a safe way to check path existence without throwing exceptions. It's useful for conditional logic based on JSON structure.

      Parameters:
      root - The root JSON node to check
      path - The dot-notation path to verify
      Returns:
      true if the complete path exists and is navigable, false otherwise

    • forEachInArray

      public void forEachInArray(com.fasterxml.jackson.databind.JsonNode root, String arrayPath, Consumer<com.fasterxml.jackson.databind.JsonNode> consumer) throws ConfigurationException
      Iterates over each element in a JSON array, applying the given consumer.

      This method provides a functional approach to array processing, allowing side effects for each element without collecting results.

      Parameters:
      root - The root JSON node containing the array
      arrayPath - The dot-notation path to the array
      consumer - The operation to perform on each array element
      Throws:
      ConfigurationException - if the path doesn't exist or doesn't point to an array

    • mapArray

      public <T> List<T> mapArray(com.fasterxml.jackson.databind.JsonNode root, String arrayPath, Function<com.fasterxml.jackson.databind.JsonNode,T> mapper) throws ConfigurationException
      Transforms each element in a JSON array into a list of typed objects.

      This method provides a functional transformation from JSON array elements to a strongly-typed Java list. The mapper function defines how each JsonNode element is converted to the target type.

      Type Parameters:
      T - The target type for list elements
      Parameters:
      root - The root JSON node containing the array
      arrayPath - The dot-notation path to the array
      mapper - The transformation function for each element
      Returns:
      A list containing the transformed elements
      Throws:
      ConfigurationException - if the path doesn't exist or doesn't point to an array

    • findInArray

      public Optional<com.fasterxml.jackson.databind.JsonNode> findInArray(com.fasterxml.jackson.databind.JsonNode root, String arrayPath, Function<com.fasterxml.jackson.databind.JsonNode,Boolean> predicate) throws ConfigurationException
      Finds the first element in a JSON array that matches the given predicate.

      This method provides a functional search mechanism for JSON arrays, returning the first element that satisfies the predicate condition. The search stops as soon as a match is found (short-circuit evaluation).

      Parameters:
      root - The root JSON node containing the array
      arrayPath - The dot-notation path to the array
      predicate - The condition to test each element against
      Returns:
      An Optional containing the first matching element, or empty if no matches
      Throws:
      ConfigurationException - if the path doesn't exist or doesn't point to an array

    • getFieldNames

      public List<String> getFieldNames(com.fasterxml.jackson.databind.JsonNode root, String objectPath) throws ConfigurationException
      Retrieves all field names from a JSON object at the specified path.

      This method is useful for dynamic JSON processing where field names are not known at compile time. It returns the names in iteration order, which may not be the same as the order in the original JSON text.

      Parameters:
      root - The root JSON node to navigate from
      objectPath - The dot-notation path to the object (empty for root)
      Returns:
      A list of field names present in the object
      Throws:
      ConfigurationException - if the path doesn't exist or doesn't point to an object