api changes

Author: simbo1905

json-java21-jsonpath/AGENTS.md

@@ -63,5 +63,15 @@ import jdk.sandbox.java.util.json.*;
 import json.java21.jsonpath.JsonPath;
 
 JsonValue json = Json.parse(jsonString);
-List<JsonValue> results = JsonPath.query("$.store.book[*].author", json);
+
+// Preferred: parse once (cache) and reuse
+JsonPath path = JsonPath.parse("$.store.book[*].author");
+List<JsonValue> results = path.query(json);
+
+// If you want a static call site, pass the compiled JsonPath
+List<JsonValue> sameResults = JsonPath.query(path, json);
 ```
+
+Notes:
+- Parsing a JsonPath expression is relatively expensive compared to evaluation; cache compiled `JsonPath` instances in hot code paths.
+- `JsonPath.query(String, JsonValue)` is intended for one-off usage only.

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

@@ -14,13 +14,14 @@
 /// ```java
 /// // Fluent API (preferred)
 /// JsonValue json = Json.parse(jsonString);
-/// List<JsonValue> results = JsonPath.parse("$.store.book[*].author").select(json);
+/// List<JsonValue> results = JsonPath.parse("$.store.book[*].author").query(json);
 ///
-/// // Static query API
-/// List<JsonValue> results = JsonPath.query("$.store.book[*].author", json);
+/// // Compiled + static call site (also reusable)
+/// JsonPath path = JsonPath.parse("$.store.book[*].author");
+/// List<JsonValue> results = JsonPath.query(path, json);
 /// ```
 ///
-/// Based on the JSONPath specification from https://goessner.net/articles/JsonPath/
+/// Based on the JSONPath specification from [...](https://goessner.net/articles/JsonPath/)
 public final class JsonPath {
 
     private static final Logger LOG = Logger.getLogger(JsonPath.class.getName());
@@ -49,9 +50,23 @@ public static JsonPath parse(String path) {
     /// @param json the JSON document to query
     /// @return a list of matching JsonValue instances (may be empty)
     /// @throws NullPointerException if json is null
+    /// @deprecated Use `query(JsonValue)` (aligns with Goessner JSONPath terminology).
+    @Deprecated(forRemoval = false)
     public List<JsonValue> select(JsonValue json) {
+        return query(json);
+    }
+
+    /// Queries matching values from a JSON document.
+    ///
+    /// This is the preferred instance API: compile once via `parse(String)`, then call `query(JsonValue)`
+    /// for each already-parsed 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> query(JsonValue json) {
         Objects.requireNonNull(json, "json must not be null");
-        LOG.fine(() -> "Selecting from document with path: " + pathExpression);
+        LOG.fine(() -> "Querying document with path: " + pathExpression);
         return evaluate(ast, json);
     }
 
@@ -65,14 +80,14 @@ public JsonPathAst.Root ast() {
         return ast;
     }
 
-    /// Evaluates a JsonPath expression against a JSON document (convenience method).
-    /// @param path the JsonPath expression
+    /// Evaluates a compiled JsonPath against a JSON document.
+    /// @param path a compiled JsonPath (typically cached)
     /// @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);
+    public static List<JsonValue> query(JsonPath path, JsonValue json) {
+        Objects.requireNonNull(path, "path must not be null");
+        return path.query(json);
     }
 
     /// Evaluates a pre-parsed JsonPath AST against a JSON document.

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

@@ -44,10 +44,10 @@ record PropertyAccess(String name) implements Segment {
         }
     }
 
-    /// Access array element by index: [n] where n can be negative for reverse indexing
+    /// Access array element by index: \[n\] where n can be negative for reverse indexing
     record ArrayIndex(int index) implements Segment {}
 
-    /// Slice array: [start:end:step]
+    /// Slice array: \[start:end:step\]
     /// All fields are optional (null means not specified)
     record ArraySlice(Integer start, Integer end, Integer step) implements Segment {}
 

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

@@ -21,7 +21,7 @@
 /// - \[?(@.prop)\] : filter expression for existence
 /// - \[?(@.prop op value)\] : filter expression with comparison
 /// - \[(@.length-1)\] : script expression
-public final class JsonPathParser {
+final class JsonPathParser {
 
     private static final Logger LOG = Logger.getLogger(JsonPathParser.class.getName());