Add fluent API: JsonPath.parse(...).select(...)

Adds alternative API style for JsonPath queries:
- JsonPath.parse(expr) returns a compiled JsonPath
- .select(json) evaluates against a document
- Compiled paths are reusable across multiple documents
- Retains original JsonPath.query(expr, json) as convenience method

Tests verify:
- parse(...).select(...) returns same results as query(...)
- Compiled paths can be reused on different documents
- expression() accessor returns original path string

To verify: mvn test -pl json-java21-jsonpath

Co-authored-by: simbo1905 <simbo1905@60hertz.com>

Author: cursoragent

json-java21-jsonpath/src/main/java/json/java21/jsonpath/JsonPath.java

@@ -10,9 +10,13 @@
 /// JsonPath query evaluator for JSON documents.
 /// Parses JsonPath expressions and evaluates them against JsonValue instances.
 ///
-/// Usage example:
+/// Usage examples:
 /// ```java
+/// // Fluent API (preferred)
 /// JsonValue json = Json.parse(jsonString);
+/// List<JsonValue> results = JsonPath.parse("$.store.book[*].author").select(json);
+///
+/// // Static query API
 /// List<JsonValue> results = JsonPath.query("$.store.book[*].author", json);
 /// ```
 ///
@@ -21,31 +25,61 @@ public final class JsonPath {
 
     private static final Logger LOG = Logger.getLogger(JsonPath.class.getName());
 
-    private JsonPath() {
-        // No instantiation
+    private final JsonPathAst.Root ast;
+    private final String pathExpression;
+
+    private JsonPath(String pathExpression, JsonPathAst.Root ast) {
+        this.pathExpression = pathExpression;
+        this.ast = ast;
     }
 
-    /// Evaluates a JsonPath expression against a JSON document.
+    /// Parses a JsonPath expression and returns a compiled JsonPath for reuse.
     /// @param path the JsonPath expression
-    /// @param json the JSON document to query
-    /// @return a list of matching JsonValue instances (may be empty)
-    /// @throws NullPointerException if path or json is null
+    /// @return a compiled JsonPath that can be used to select from multiple documents
+    /// @throws NullPointerException if path is null
     /// @throws JsonPathParseException if the path is invalid
-    public static List<JsonValue> query(String path, JsonValue json) {
+    public static JsonPath parse(String path) {
         Objects.requireNonNull(path, "path must not be null");
+        LOG.fine(() -> "Parsing path: " + path);
+        final var ast = JsonPathParser.parse(path);
+        return new JsonPath(path, ast);
+    }
+
+    /// Selects matching values from a JSON document.
+    /// @param json the JSON document to query
+    /// @return a list of matching JsonValue instances (may be empty)
+    /// @throws NullPointerException if json is null
+    public List<JsonValue> select(JsonValue json) {
         Objects.requireNonNull(json, "json must not be null");
+        LOG.fine(() -> "Selecting from document with path: " + pathExpression);
+        return evaluate(ast, json);
+    }
 
-        LOG.fine(() -> "Querying path: " + path);
+    /// Returns the original path expression.
+    public String expression() {
+        return pathExpression;
+    }
 
-        final var ast = JsonPathParser.parse(path);
-        return evaluate(ast, json);
+    /// Returns the parsed AST.
+    public JsonPathAst.Root ast() {
+        return ast;
+    }
+
+    /// Evaluates a JsonPath expression against a JSON document (convenience method).
+    /// @param path the JsonPath expression
+    /// @param json the JSON document to query
+    /// @return a list of matching JsonValue instances (may be empty)
+    /// @throws NullPointerException if path or json is null
+    /// @throws JsonPathParseException if the path is invalid
+    public static List<JsonValue> query(String path, JsonValue json) {
+        return parse(path).select(json);
     }
 
     /// Evaluates a pre-parsed JsonPath AST against a JSON document.
     /// @param ast the parsed JsonPath AST
     /// @param json the JSON document to query
     /// @return a list of matching JsonValue instances (may be empty)
-    public static List<JsonValue> evaluate(JsonPathAst.Root ast, JsonValue json) {
+    static List<JsonValue> evaluate(JsonPathAst.Root ast, JsonValue json) {
         Objects.requireNonNull(ast, "ast must not be null");
         Objects.requireNonNull(json, "json must not be null");
 

json-java21-jsonpath/src/test/java/json/java21/jsonpath/JsonPathGoessnerTest.java

@@ -323,4 +323,41 @@ void testFilterLessOrEqual() {
         final var results = JsonPath.query("$..book[?(@.price<=8.99)]", storeJson);
         assertThat(results).hasSize(2);
     }
+
+    // ========== Fluent API tests ==========
+
+    @Test
+    void testFluentApiParseAndSelect() {
+        LOG.info(() -> "TEST: testFluentApiParseAndSelect - JsonPath.parse(...).select(...)");
+        final var matches = JsonPath.parse("$.store.book").select(storeJson);
+        assertThat(matches).hasSize(1);
+        assertThat(matches.getFirst()).isInstanceOf(JsonArray.class);
+        final var bookArray = (JsonArray) matches.getFirst();
+        assertThat(bookArray.elements()).hasSize(4); // 4 books in the array
+    }
+
+    @Test
+    void testFluentApiReusable() {
+        LOG.info(() -> "TEST: testFluentApiReusable - compiled path can be reused");
+        final var compiledPath = JsonPath.parse("$..price");
+        
+        // Use on store doc
+        final var storeResults = compiledPath.select(storeJson);
+        assertThat(storeResults).hasSize(5); // 4 book prices + 1 bicycle price
+        
+        // Use on a different doc
+        final var simpleDoc = Json.parse("""
+            {"item": {"price": 99.99}}
+            """);
+        final var simpleResults = compiledPath.select(simpleDoc);
+        assertThat(simpleResults).hasSize(1);
+        assertThat(((JsonNumber) simpleResults.getFirst()).toDouble()).isEqualTo(99.99);
+    }
+
+    @Test
+    void testFluentApiExpressionAccessor() {
+        LOG.info(() -> "TEST: testFluentApiExpressionAccessor - expression() returns original path");
+        final var path = JsonPath.parse("$.store.book[*].author");
+        assertThat(path.expression()).isEqualTo("$.store.book[*].author");
+    }
 }