Package com.alibaba.fastjson2

Class JSONPath

java.lang.Object
com.alibaba.fastjson2.JSONPath
Direct Known Subclasses:
JSONPathCompilerReflect.SingleNamePathTyped, JSONPathCompilerReflect.TwoNameSegmentTypedPath, JSONPathTypedMultiNamesPrefixIndex1, JSONPathTypedMultiNamesPrefixName1, JSONPathTypedMultiNamesPrefixName2
public abstract class JSONPath extends Object
Represents a JSONPath expression for querying and manipulating JSON data.

JSONPath is a query language for JSON, similar to XPath for XML. It allows you to select and extract data from a JSON document.

Example usage: 


 // Parse JSON string and extract value using JSONPath
 String json = "{\"name\":\"John\", \"age\":30, \"city\":\"New York\"}";
 Object result = JSONPath.extract(json, "$.name");
 // result = "John"

 // Evaluate JSONPath on an object
 Map<String, Object> map = new HashMap<>();
 map.put("name", "John");
 map.put("age", 30);
 Object result = JSONPath.eval(map, "$.name");
 // result = "John"

 // Set value using JSONPath
 JSONPath.set(map, "$.name", "Jane");
 // map.get("name") = "Jane"

 // Remove value using JSONPath
 JSONPath.remove(map, "$.age");
 // map.size() = 1 (age field removed)

 // Check if path exists
 boolean exists = JSONPath.contains(map, "$.name");
 // exists = true

Supported JSONPath expressions:

  • $ - Root object/element
  • @ - Current object/element
  • . or [] - Child operator
  • .. - Recursive descent
  • * - Wildcard
  • [] - Array index or filter
  • [start:end:step] - Array slice
  • ?() - Filter expression
Since:
2.0.0
See Also:

  • Constructor Details

    • JSONPath

      protected JSONPath(String path, JSONPath.Feature... features)
      Constructs a JSONPath with the specified path and features
      Parameters:
      path - the JSONPath expression
      features - the features to apply

    • JSONPath

      protected JSONPath(String path, long features)
      Constructs a JSONPath with the specified path and feature flags
      Parameters:
      path - the JSONPath expression
      features - the feature flags to apply

  • Method Details

    • getParent

      public abstract JSONPath getParent()
      Gets the parent JSONPath of this path
      Returns:
      the parent JSONPath, or null if this is the root path

    • endsWithFilter

      public boolean endsWithFilter()
      Checks if this path ends with a filter
      Returns:
      true if this path ends with a filter, false otherwise

    • isPrevious

      public boolean isPrevious()
      Checks if this path represents a previous reference
      Returns:
      true if this path is a previous reference, false otherwise

    • toString

      public final String toString()
      Returns the string representation of this JSONPath
      Overrides:
      toString in class Object
      Returns:
      the JSONPath expression string

    • extract

      public static Object extract(String json, String path)
      Extracts a value from JSON string using the specified path
      Parameters:
      json - the JSON string to extract from
      path - the JSONPath expression
      Returns:
      the extracted value, or null if not found

    • extract

      public static Object extract(String json, String path, JSONPath.Feature... features)
      Extracts a value from JSON string using the specified path and features
      Parameters:
      json - the JSON string to extract from
      path - the JSONPath expression
      features - the features to apply during extraction
      Returns:
      the extracted value, or null if not found

    • eval

      public static Object eval(String str, String path)
      Evaluates the JSONPath expression on a JSON string
      Parameters:
      str - the JSON string to evaluate
      path - the JSONPath expression
      Returns:
      the evaluated result, or null if not found

    • eval

      public static Object eval(Object rootObject, String path)
      Evaluates the JSONPath expression on an object
      Parameters:
      rootObject - the root object to evaluate
      path - the JSONPath expression
      Returns:
      the evaluated result, or null if not found

    • set

      public static String set(String json, String path, Object value)
      Sets a value in a JSON string using the specified path and returns the modified JSON
      Parameters:
      json - the JSON string to modify
      path - the JSONPath expression
      value - the value to set
      Returns:
      the modified JSON string

    • contains

      public static boolean contains(Object rootObject, String path)
      Checks if the specified path exists in the object
      Parameters:
      rootObject - the root object to check
      path - the JSONPath expression
      Returns:
      true if the path exists, false otherwise

    • set

      public static Object set(Object rootObject, String path, Object value)
      Sets a value in an object using the specified path
      Parameters:
      rootObject - the root object to modify
      path - the JSONPath expression
      value - the value to set
      Returns:
      the modified root object

    • setCallback

      public static Object setCallback(Object rootObject, String path, Function callback)
      Sets a callback function for the specified path in an object
      Parameters:
      rootObject - the root object to modify
      path - the JSONPath expression
      callback - the callback function to set
      Returns:
      the modified root object

    • setCallback

      public static Object setCallback(Object rootObject, String path, BiFunction callback)
      Sets a callback function for the specified path in an object
      Parameters:
      rootObject - the root object to modify
      path - the JSONPath expression
      callback - the callback function to set
      Returns:
      the modified root object

    • remove

      public static String remove(String json, String path)
      Removes a value from a JSON string using the specified path and returns the modified JSON
      Parameters:
      json - the JSON string to modify
      path - the JSONPath expression
      Returns:
      the modified JSON string

    • remove

      public static void remove(Object rootObject, String path)
      Removes a value from an object using the specified path
      Parameters:
      rootObject - the root object to modify
      path - the JSONPath expression

    • paths

      public static Map<String,Object> paths(Object javaObject)
      Gets all paths in the object
      Parameters:
      javaObject - the object to get paths from
      Returns:
      a map of paths to values

    • isRef

      public abstract boolean isRef()
      Checks if this path is a reference
      Returns:
      true if this path is a reference, false otherwise

    • arrayAdd

      public void arrayAdd(Object root, Object... values)
      Adds values to an array at the specified root object
      Parameters:
      root - the root object
      values - the values to add

    • contains

      public abstract boolean contains(Object object)
      Checks if the path exists in the object
      Parameters:
      object - the object to check
      Returns:
      true if the path exists, false otherwise

    • eval

      public abstract Object eval(Object object)
      Evaluates the path on the object
      Parameters:
      object - the object to evaluate
      Returns:
      the evaluation result

    • createContext

      protected JSONReader.Context createContext()
      Creates a new reading context
      Returns:
      a new JSONReader.Context

    • extract

      public Object extract(String jsonStr)
      Extracts a value from a JSON string
      Parameters:
      jsonStr - the JSON string to extract from
      Returns:
      the extracted value, or null if input is null

    • extract

      public Object extract(byte[] jsonBytes)
      Extracts a value from a JSON byte array
      Parameters:
      jsonBytes - the JSON bytes to extract from
      Returns:
      the extracted value, or null if input is null

    • extract

      public Object extract(byte[] jsonBytes, int off, int len, Charset charset)
      Extracts a value from a JSON byte array with specified offset, length and charset
      Parameters:
      jsonBytes - the JSON bytes to extract from
      off - the offset in the byte array
      len - the number of bytes to read
      charset - the charset to use
      Returns:
      the extracted value, or null if input is null

    • extract

      public abstract Object extract(JSONReader jsonReader)
      Extracts a value using the provided JSONReader
      Parameters:
      jsonReader - the JSONReader to use
      Returns:
      the extracted value

    • extractScalar

      public abstract String extractScalar(JSONReader jsonReader)
      Extracts a scalar value using the provided JSONReader
      Parameters:
      jsonReader - the JSONReader to use
      Returns:
      the extracted scalar value

    • getReaderContext

      public JSONReader.Context getReaderContext()
      Gets the reading context, creating it if necessary
      Returns:
      the JSONReader.Context

    • setReaderContext

      public JSONPath setReaderContext(JSONReader.Context context)
      Sets the reading context
      Parameters:
      context - the context to set
      Returns:
      this JSONPath instance

    • getWriterContext

      public JSONWriter.Context getWriterContext()
      Gets the writing context, creating it if necessary
      Returns:
      the JSONWriter.Context

    • setWriterContext

      public JSONPath setWriterContext(JSONWriter.Context writerContext)
      Sets the writing context
      Parameters:
      writerContext - the context to set
      Returns:
      this JSONPath instance

    • set

      public abstract void set(Object object, Object value)
      Sets a value in the object
      Parameters:
      object - the object to modify
      value - the value to set

    • set

      public abstract void set(Object object, Object value, JSONReader.Feature... readerFeatures)
      Sets a value in the object with specified reader features
      Parameters:
      object - the object to modify
      value - the value to set
      readerFeatures - the reader features to apply

    • setCallback

      public void setCallback(Object object, Function callback)
      Sets a callback function for the object
      Parameters:
      object - the object to modify
      callback - the callback function to set

    • setCallback

      public abstract void setCallback(Object object, BiFunction callback)
      Sets a callback function for the object
      Parameters:
      object - the object to modify
      callback - the callback function to set

    • setInt

      public abstract void setInt(Object object, int value)
      Sets an integer value in the object
      Parameters:
      object - the object to modify
      value - the integer value to set

    • setLong

      public abstract void setLong(Object object, long value)
      Sets a long value in the object
      Parameters:
      object - the object to modify
      value - the long value to set

    • remove

      public abstract boolean remove(Object object)
      Removes a value from the object
      Parameters:
      object - the object to modify
      Returns:
      true if removal was successful, false otherwise

    • extract

      public void extract(JSONReader jsonReader, ValueConsumer consumer)
      Extracts a value using the provided JSONReader and passes it to the consumer
      Parameters:
      jsonReader - the JSONReader to use
      consumer - the consumer to accept the extracted value

    • extractScalar

      public void extractScalar(JSONReader jsonReader, ValueConsumer consumer)
      Extracts a scalar value using the provided JSONReader and passes it to the consumer
      Parameters:
      jsonReader - the JSONReader to use
      consumer - the consumer to accept the extracted scalar value

    • extractInt64

      public Long extractInt64(JSONReader jsonReader)
      Extracts a Long value using the provided JSONReader
      Parameters:
      jsonReader - the JSONReader to use
      Returns:
      the extracted Long value, or null if the value was null

    • extractInt64Value

      public long extractInt64Value(JSONReader jsonReader)
      Extracts a long value using the provided JSONReader
      Parameters:
      jsonReader - the JSONReader to use
      Returns:
      the extracted long value, or 0 if the value was null

    • extractInt32

      public Integer extractInt32(JSONReader jsonReader)
      Extracts an Integer value using the provided JSONReader
      Parameters:
      jsonReader - the JSONReader to use
      Returns:
      the extracted Integer value, or null if the value was null

    • extractInt32Value

      public int extractInt32Value(JSONReader jsonReader)
      Extracts an int value using the provided JSONReader
      Parameters:
      jsonReader - the JSONReader to use
      Returns:
      the extracted int value, or 0 if the value was null

    • compile

      @Deprecated public static JSONPath compile(String path)
      Deprecated.
      use of(String) instead
      Compiles a JSONPath expression (deprecated, use of(String) instead)
      Parameters:
      path - the JSONPath expression to compile
      Returns:
      the compiled JSONPath

    • compile

      public static JSONPath compile(String strPath, Class objectClass)
      Compiles a JSONPath expression for a specific object class
      Parameters:
      strPath - the JSONPath expression to compile
      objectClass - the class of the object to use with this path
      Returns:
      the compiled JSONPath

    • of

      public static JSONPath of(String path)
      Creates a JSONPath from a path string
      Parameters:
      path - the JSONPath expression
      Returns:
      the created JSONPath

    • of

      public static JSONPath of(String path, Type type)
      Creates a typed JSONPath from a path string and type
      Parameters:
      path - the JSONPath expression
      type - the type of the result
      Returns:
      the created JSONPath

    • of

      public static JSONPath of(String path, Type type, JSONPath.Feature... features)
      Creates a typed JSONPath from a path string, type and features
      Parameters:
      path - the JSONPath expression
      type - the type of the result
      features - the features to apply
      Returns:
      the created JSONPath

    • of

      public static JSONPath of(String[] paths, Type[] types)
      Creates a multi-path JSONPath
      Parameters:
      paths - the JSONPath expressions
      types - the types of the results
      Returns:
      the created JSONPath
      Since:
      2.0.20

    • of

      public static JSONPath of(String[] paths, Type[] types, JSONReader.Feature... features)
      Creates a multi-path JSONPath
      Parameters:
      paths - the JSONPath expressions
      types - the types of the results
      features - the reader features to apply
      Returns:
      the created JSONPath
      Since:
      2.0.20

    • of

      public static JSONPath of(String[] paths, Type[] types, String[] formats, long[] pathFeatures, ZoneId zoneId, JSONReader.Feature... features)
      Creates a multi-path JSONPath
      Parameters:
      paths - the JSONPath expressions
      types - the types of the results
      formats - the formats to apply
      pathFeatures - the path features
      zoneId - the zone ID
      features - the reader features to apply
      Returns:
      the created JSONPath
      Since:
      2.0.20

    • of

      public static JSONPath of(String path, JSONPath.Feature... features)
      Creates a JSONPath from a path string with specified features
      Parameters:
      path - the JSONPath expression
      features - the features to apply
      Returns:
      the created JSONPath