com.alibaba.fastjson2

Class JSONPath

java.lang.Object

com.alibaba.fastjson2.JSONPath

Direct Known Subclasses:

JSONPath.PreviousPath, JSONPath.RootPath, JSONPathCompilerReflect.SingleNamePathTyped, JSONPathMulti, JSONPathSingle, JSONPathTwoSegment, JSONPathTyped, JSONPathTypedMulti

public abstract class JSONPath
extends java.lang.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:

JSONPath specification

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
(package private) static class	JSONPath.Context Represents the execution context for JSONPath operations
static class	JSONPath.Feature Features that can be applied to JSONPath operations
(package private) static class	JSONPath.PreviousPath Represents a previous path reference
(package private) static class	JSONPath.RootPath Represents the root path ($)
(package private) static class	JSONPath.Sequence Represents a sequence of values

Field Summary

Fields

Modifier and Type	Field and Description
(package private) long	features Feature flags for this JSONPath
(package private) static JSONReader.Context	PARSE_CONTEXT
(package private) java.lang.String	path The JSONPath expression string
(package private) JSONReader.Context	readerContext Context for JSON reading operations
(package private) JSONWriter.Context	writerContext Context for JSON writing operations

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	JSONPath(java.lang.String path, JSONPath.Feature... features) Constructs a JSONPath with the specified path and features
protected	JSONPath(java.lang.String path, long features) Constructs a JSONPath with the specified path and feature flags

Method Summary

Modifier and Type	Method and Description
void	arrayAdd(java.lang.Object root, java.lang.Object... values) Adds values to an array at the specified root object
static JSONPath	compile(java.lang.String path) Deprecated. use of(String) instead
static JSONPath	compile(java.lang.String strPath, java.lang.Class objectClass) Compiles a JSONPath expression for a specific object class
abstract boolean	contains(java.lang.Object object) Checks if the path exists in the object
static boolean	contains(java.lang.Object rootObject, java.lang.String path) Checks if the specified path exists in the object
protected JSONReader.Context	createContext() Creates a new reading context
boolean	endsWithFilter() Checks if this path ends with a filter
abstract java.lang.Object	eval(java.lang.Object object) Evaluates the path on the object
static java.lang.Object	eval(java.lang.Object rootObject, java.lang.String path) Evaluates the JSONPath expression on an object
static java.lang.Object	eval(java.lang.String str, java.lang.String path) Evaluates the JSONPath expression on a JSON string
java.lang.Object	extract(byte[] jsonBytes) Extracts a value from a JSON byte array
java.lang.Object	extract(byte[] jsonBytes, int off, int len, java.nio.charset.Charset charset) Extracts a value from a JSON byte array with specified offset, length and charset
abstract java.lang.Object	extract(JSONReader jsonReader) Extracts a value using the provided JSONReader
void	extract(JSONReader jsonReader, ValueConsumer consumer) Extracts a value using the provided JSONReader and passes it to the consumer
java.lang.Object	extract(java.lang.String jsonStr) Extracts a value from a JSON string
static java.lang.Object	extract(java.lang.String json, java.lang.String path) Extracts a value from JSON string using the specified path
static java.lang.Object	extract(java.lang.String json, java.lang.String path, JSONPath.Feature... features) Extracts a value from JSON string using the specified path and features
java.lang.Integer	extractInt32(JSONReader jsonReader) Extracts an Integer value using the provided JSONReader
int	extractInt32Value(JSONReader jsonReader) Extracts an int value using the provided JSONReader
java.lang.Long	extractInt64(JSONReader jsonReader) Extracts a Long value using the provided JSONReader
long	extractInt64Value(JSONReader jsonReader) Extracts a long value using the provided JSONReader
abstract java.lang.String	extractScalar(JSONReader jsonReader) Extracts a scalar value using the provided JSONReader
void	extractScalar(JSONReader jsonReader, ValueConsumer consumer) Extracts a scalar value using the provided JSONReader and passes it to the consumer
abstract JSONPath	getParent() Gets the parent JSONPath of this path
JSONReader.Context	getReaderContext() Gets the reading context, creating it if necessary
JSONWriter.Context	getWriterContext() Gets the writing context, creating it if necessary
boolean	isPrevious() Checks if this path represents a previous reference
abstract boolean	isRef() Checks if this path is a reference
(package private) static JSONPathSingle	of(JSONPathSegment segment) Creates a single segment JSONPath from a segment
static JSONPath	of(java.lang.String path) Creates a JSONPath from a path string
static JSONPath	of(java.lang.String[] paths, java.lang.reflect.Type[] types) Creates a multi-path JSONPath
static JSONPath	of(java.lang.String[] paths, java.lang.reflect.Type[] types, JSONReader.Feature... features) Creates a multi-path JSONPath
static JSONPath	of(java.lang.String[] paths, java.lang.reflect.Type[] types, java.lang.String[] formats, long[] pathFeatures, java.time.ZoneId zoneId, JSONReader.Feature... features) Creates a multi-path JSONPath
static JSONPath	of(java.lang.String path, JSONPath.Feature... features) Creates a JSONPath from a path string with specified features
static JSONPath	of(java.lang.String path, java.lang.reflect.Type type) Creates a typed JSONPath from a path string and type
static JSONPath	of(java.lang.String path, java.lang.reflect.Type type, JSONPath.Feature... features) Creates a typed JSONPath from a path string, type and features
(package private) static JSONPathFilter.Operator	parseOperator(JSONReader jsonReader) Parses an operator from the JSONReader
(package private) void	paths(java.util.Map<java.lang.Object,java.lang.String> values, java.util.Map paths, java.lang.String parent, java.lang.Object javaObject) Recursively collects paths and values from the object
static java.util.Map<java.lang.String,java.lang.Object>	paths(java.lang.Object javaObject) Gets all paths in the object
abstract boolean	remove(java.lang.Object object) Removes a value from the object
static void	remove(java.lang.Object rootObject, java.lang.String path) Removes a value from an object using the specified path
static java.lang.String	remove(java.lang.String json, java.lang.String path) Removes a value from a JSON string using the specified path and returns the modified JSON
abstract void	set(java.lang.Object object, java.lang.Object value) Sets a value in the object
abstract void	set(java.lang.Object object, java.lang.Object value, JSONReader.Feature... readerFeatures) Sets a value in the object with specified reader features
static java.lang.Object	set(java.lang.Object rootObject, java.lang.String path, java.lang.Object value) Sets a value in an object using the specified path
static java.lang.String	set(java.lang.String json, java.lang.String path, java.lang.Object value) Sets a value in a JSON string using the specified path and returns the modified JSON
abstract void	setCallback(java.lang.Object object, java.util.function.BiFunction callback) Sets a callback function for the object
void	setCallback(java.lang.Object object, java.util.function.Function callback) Sets a callback function for the object
static java.lang.Object	setCallback(java.lang.Object rootObject, java.lang.String path, java.util.function.BiFunction callback) Sets a callback function for the specified path in an object
static java.lang.Object	setCallback(java.lang.Object rootObject, java.lang.String path, java.util.function.Function callback) Sets a callback function for the specified path in an object
abstract void	setInt(java.lang.Object object, int value) Sets an integer value in the object
abstract void	setLong(java.lang.Object object, long value) Sets a long value in the object
JSONPath	setReaderContext(JSONReader.Context context) Sets the reading context
JSONPath	setWriterContext(JSONWriter.Context writerContext) Sets the writing context
java.lang.String	toString() Returns the string representation of this JSONPath

Methods inherited from class java.lang.Object

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

Field Detail

PARSE_CONTEXT

static final JSONReader.Context PARSE_CONTEXT

readerContext

JSONReader.Context readerContext

Context for JSON reading operations

writerContext

JSONWriter.Context writerContext

Context for JSON writing operations

path

final java.lang.String path

The JSONPath expression string

features

final long features

Feature flags for this JSONPath

Constructor Detail

JSONPath

protected JSONPath(java.lang.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(java.lang.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 Detail

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 java.lang.String toString()

Returns the string representation of this JSONPath

Overrides:

toString in class java.lang.Object

Returns:

the JSONPath expression string

extract

public static java.lang.Object extract(java.lang.String json,
                                       java.lang.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 java.lang.Object extract(java.lang.String json,
                                       java.lang.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 java.lang.Object eval(java.lang.String str,
                                    java.lang.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 java.lang.Object eval(java.lang.Object rootObject,
                                    java.lang.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 java.lang.String set(java.lang.String json,
                                   java.lang.String path,
                                   java.lang.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(java.lang.Object rootObject,
                               java.lang.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 java.lang.Object set(java.lang.Object rootObject,
                                   java.lang.String path,
                                   java.lang.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 java.lang.Object setCallback(java.lang.Object rootObject,
                                           java.lang.String path,
                                           java.util.function.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 java.lang.Object setCallback(java.lang.Object rootObject,
                                           java.lang.String path,
                                           java.util.function.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 java.lang.String remove(java.lang.String json,
                                      java.lang.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(java.lang.Object rootObject,
                          java.lang.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 java.util.Map<java.lang.String,java.lang.Object> paths(java.lang.Object javaObject)

Gets all paths in the object

Parameters:

javaObject - the object to get paths from

Returns:

a map of paths to values

paths

void paths(java.util.Map<java.lang.Object,java.lang.String> values,
           java.util.Map paths,
           java.lang.String parent,
           java.lang.Object javaObject)

Recursively collects paths and values from the object

Parameters:

values - map to store object to path mappings

paths - map to store path to value mappings

parent - the parent path

javaObject - the object to process

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(java.lang.Object root,
                     java.lang.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(java.lang.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 java.lang.Object eval(java.lang.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 java.lang.Object extract(java.lang.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 java.lang.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 java.lang.Object extract(byte[] jsonBytes,
                                int off,
                                int len,
                                java.nio.charset.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 java.lang.Object extract(JSONReader jsonReader)

Extracts a value using the provided JSONReader

Parameters:

jsonReader - the JSONReader to use

Returns:

the extracted value

extractScalar

public abstract java.lang.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(java.lang.Object object,
                         java.lang.Object value)

Sets a value in the object

Parameters:

object - the object to modify

value - the value to set

set

public abstract void set(java.lang.Object object,
                         java.lang.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(java.lang.Object object,
                        java.util.function.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(java.lang.Object object,
                                 java.util.function.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(java.lang.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(java.lang.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(java.lang.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 java.lang.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 java.lang.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(java.lang.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(java.lang.String strPath,
                               java.lang.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

static JSONPathSingle of(JSONPathSegment segment)

Creates a single segment JSONPath from a segment

Parameters:

segment - the segment to create a path from

Returns:

the created JSONPath

of

public static JSONPath of(java.lang.String path)

Creates a JSONPath from a path string

Parameters:

path - the JSONPath expression

Returns:

the created JSONPath

of

public static JSONPath of(java.lang.String path,
                          java.lang.reflect.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(java.lang.String path,
                          java.lang.reflect.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(java.lang.String[] paths,
                          java.lang.reflect.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(java.lang.String[] paths,
                          java.lang.reflect.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(java.lang.String[] paths,
                          java.lang.reflect.Type[] types,
                          java.lang.String[] formats,
                          long[] pathFeatures,
                          java.time.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(java.lang.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

parseOperator

static JSONPathFilter.Operator parseOperator(JSONReader jsonReader)

Parses an operator from the JSONReader

Parameters:

jsonReader - the JSONReader to parse from

Returns:

the parsed operator