com.jayway.jsonpath

Class JsonPath

java.lang.Object

com.jayway.jsonpath.JsonPath

public class JsonPath
extends java.lang.Object

JsonPath is to JSON what XPATH is to XML, a simple way to extract parts of a given document. JsonPath is available in many programming languages such as Javascript, Python and PHP.

JsonPath allows you to compile a json path string to use it many times or to compile and apply in one single on demand operation.

Given the Json document:

 String json =
 "{
 "store":
 {
 "book":
 [
 {
 "category": "reference",
 "author": "Nigel Rees",
 "title": "Sayings of the Century",
 "price": 8.95
 },
 {
 "category": "fiction",
 "author": "Evelyn Waugh",
 "title": "Sword of Honour",
 "price": 12.99
 }
 ],
 "bicycle":
 {
 "color": "red",
 "price": 19.95
 }
 }
 }";
 

A JsonPath can be compiled and used as shown:

JsonPath path = JsonPath.compile("$.store.book[1]");
List<Object> books = path.read(json);

Or:

List<Object> authors = JsonPath.read(json, "$.store.book[*].author")

If the json path returns a single value (is definite):

String author = JsonPath.read(json, "$.store.book[1].author")

Method Summary

Modifier and Type	Method and Description
<T> T	add(java.lang.Object jsonObject, java.lang.Object value, Configuration configuration) Adds a new value to the Array this path points to in the provided jsonObject
static JsonPath	compile(java.lang.String jsonPath, Predicate... filters) Compiles a JsonPath
<T> T	delete(java.lang.Object jsonObject, Configuration configuration) Deletes the object this path points to in the provided jsonObject
java.lang.String	getPath() Returns the string representation of this JsonPath
boolean	isDefinite() Checks if a path points to a single item or if it potentially returns multiple items a path is considered not definite if it contains a scan fragment ".." or an array position fragment that is not based on a single index definite path examples are: $store.book $store.book[1].title not definite path examples are: $..book $.store.book[*] $.store.book[1,2] $.store.book[?(@.category = 'fiction')]
static boolean	isPathDefinite(java.lang.String path)
<T> T	map(java.lang.Object jsonObject, MapFunction mapFunction, Configuration configuration) Replaces the value on the given path with the result of the MapFunction.
static DocumentContext	parse(java.io.File json) Parses the given JSON input using the default Configuration and returns a DocumentContext for path evaluation
static DocumentContext	parse(java.io.File json, Configuration configuration) Parses the given JSON input using the provided Configuration and returns a DocumentContext for path evaluation
static DocumentContext	parse(java.io.InputStream json) Parses the given JSON input using the default Configuration and returns a DocumentContext for path evaluation
static DocumentContext	parse(java.io.InputStream json, Configuration configuration) Parses the given JSON input using the provided Configuration and returns a DocumentContext for path evaluation
static DocumentContext	parse(java.lang.Object json) Parses the given JSON input using the default Configuration and returns a DocumentContext for path evaluation
static DocumentContext	parse(java.lang.Object json, Configuration configuration) Parses the given JSON input using the provided Configuration and returns a DocumentContext for path evaluation
static DocumentContext	parse(java.lang.String json) Parses the given JSON input using the default Configuration and returns a DocumentContext for path evaluation
static DocumentContext	parse(java.lang.String json, Configuration configuration) Parses the given JSON input using the provided Configuration and returns a DocumentContext for path evaluation
static DocumentContext	parse(java.net.URL json) Deprecated.
static DocumentContext	parse(java.net.URL json, Configuration configuration) Deprecated.
<T> T	put(java.lang.Object jsonObject, java.lang.String key, java.lang.Object value, Configuration configuration) Adds or updates the Object this path points to in the provided jsonObject with a key with a value
<T> T	read(java.io.File jsonFile) Applies this JsonPath to the provided json file
<T> T	read(java.io.File jsonFile, Configuration configuration) Applies this JsonPath to the provided json file
static <T> T	read(java.io.File jsonFile, java.lang.String jsonPath, Predicate... filters) Creates a new JsonPath and applies it to the provided Json object
<T> T	read(java.io.InputStream jsonInputStream) Applies this JsonPath to the provided json input stream
<T> T	read(java.io.InputStream jsonInputStream, Configuration configuration) Applies this JsonPath to the provided json input stream
<T> T	read(java.io.InputStream jsonInputStream, java.lang.String charset, Configuration configuration) Applies this JsonPath to the provided json input stream
static <T> T	read(java.io.InputStream jsonInputStream, java.lang.String jsonPath, Predicate... filters) Creates a new JsonPath and applies it to the provided Json object
<T> T	read(java.lang.Object jsonObject) Applies this JsonPath to the provided json document.
<T> T	read(java.lang.Object jsonObject, Configuration configuration) Applies this JsonPath to the provided json document.
static <T> T	read(java.lang.Object json, java.lang.String jsonPath, Predicate... filters) Creates a new JsonPath and applies it to the provided Json object
<T> T	read(java.lang.String json) Applies this JsonPath to the provided json string
<T> T	read(java.lang.String json, Configuration configuration) Applies this JsonPath to the provided json string
static <T> T	read(java.lang.String json, java.lang.String jsonPath, Predicate... filters) Creates a new JsonPath and applies it to the provided Json string
<T> T	read(java.net.URL jsonURL) Applies this JsonPath to the provided json URL
static <T> T	read(java.net.URL jsonURL, java.lang.String jsonPath, Predicate... filters) Deprecated.
<T> T	renameKey(java.lang.Object jsonObject, java.lang.String oldKeyName, java.lang.String newKeyName, Configuration configuration)
<T> T	set(java.lang.Object jsonObject, java.lang.Object newVal, Configuration configuration) Set the value this path points to in the provided jsonObject
static ParseContext	using(Configuration configuration) Creates a ParseContext that can be used to parse JSON input.
static ParseContext	using(JsonProvider provider) Deprecated.

Methods inherited from class java.lang.Object

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

Method Detail

getPath

public java.lang.String getPath()

Returns the string representation of this JsonPath

Returns:

path as String

isPathDefinite

public static boolean isPathDefinite(java.lang.String path)

See Also:

isDefinite()

isDefinite

public boolean isDefinite()

Checks if a path points to a single item or if it potentially returns multiple items

a path is considered not definite if it contains a scan fragment ".." or an array position fragment that is not based on a single index

definite path examples are:

$store.book $store.book[1].title

not definite path examples are:

$..book $.store.book[*] $.store.book[1,2] $.store.book[?(@.category = 'fiction')]

Returns:

true if path is definite (points to single item)

read

public <T> T read(java.lang.Object jsonObject)

Applies this JsonPath to the provided json document. Note that the document must be identified as either a List or Map by the JsonProvider

Type Parameters:

T - expected return type

Parameters:

jsonObject - a container Object

Returns:

object(s) matched by the given path

read

public <T> T read(java.lang.Object jsonObject,
                  Configuration configuration)

Applies this JsonPath to the provided json document. Note that the document must be identified as either a List or Map by the JsonProvider

Type Parameters:

T - expected return type

Parameters:

jsonObject - a container Object

configuration - configuration to use

Returns:

object(s) matched by the given path

set

public <T> T set(java.lang.Object jsonObject,
                 java.lang.Object newVal,
                 Configuration configuration)

Set the value this path points to in the provided jsonObject

Type Parameters:

T - expected return type

Parameters:

jsonObject - a json object

configuration - configuration to use

Returns:

the updated jsonObject or the path list to updated objects if option AS_PATH_LIST is set.

map

public <T> T map(java.lang.Object jsonObject,
                 MapFunction mapFunction,
                 Configuration configuration)

Replaces the value on the given path with the result of the MapFunction.

Parameters:

jsonObject - a json object

mapFunction - Converter object to be invoked

configuration - configuration to use

Returns:

the updated jsonObject or the path list to updated objects if option AS_PATH_LIST is set.

delete

public <T> T delete(java.lang.Object jsonObject,
                    Configuration configuration)

Deletes the object this path points to in the provided jsonObject

Type Parameters:

T - expected return type

Parameters:

jsonObject - a json object

configuration - configuration to use

Returns:

the updated jsonObject or the path list to deleted objects if option AS_PATH_LIST is set.

add

public <T> T add(java.lang.Object jsonObject,
                 java.lang.Object value,
                 Configuration configuration)

Adds a new value to the Array this path points to in the provided jsonObject

Type Parameters:

T - expected return type

Parameters:

jsonObject - a json object

value - the value to add

configuration - configuration to use

Returns:

the updated jsonObject or the path list to updated object if option AS_PATH_LIST is set.

put

public <T> T put(java.lang.Object jsonObject,
                 java.lang.String key,
                 java.lang.Object value,
                 Configuration configuration)

Adds or updates the Object this path points to in the provided jsonObject with a key with a value

Type Parameters:

T - expected return type

Parameters:

jsonObject - a json object

key - the key to add or update

value - the new value

configuration - configuration to use

Returns:

the updated jsonObject or the path list to updated objects if option AS_PATH_LIST is set.

renameKey

public <T> T renameKey(java.lang.Object jsonObject,
                       java.lang.String oldKeyName,
                       java.lang.String newKeyName,
                       Configuration configuration)

read

public <T> T read(java.lang.String json)

Applies this JsonPath to the provided json string

Type Parameters:

T - expected return type

Parameters:

json - a json string

Returns:

list of objects matched by the given path

read

public <T> T read(java.lang.String json,
                  Configuration configuration)

Applies this JsonPath to the provided json string

Type Parameters:

T - expected return type

Parameters:

json - a json string

configuration - configuration to use

Returns:

list of objects matched by the given path

read

public <T> T read(java.net.URL jsonURL)
           throws java.io.IOException

Applies this JsonPath to the provided json URL

Type Parameters:

T - expected return type

Parameters:

jsonURL - url to read from

Returns:

list of objects matched by the given path

Throws:

java.io.IOException

read

public <T> T read(java.io.File jsonFile)
           throws java.io.IOException

Applies this JsonPath to the provided json file

Type Parameters:

T - expected return type

Parameters:

jsonFile - file to read from

Returns:

list of objects matched by the given path

Throws:

java.io.IOException

read

public <T> T read(java.io.File jsonFile,
                  Configuration configuration)
           throws java.io.IOException

Applies this JsonPath to the provided json file

Type Parameters:

T - expected return type

Parameters:

jsonFile - file to read from

configuration - configuration to use

Returns:

list of objects matched by the given path

Throws:

java.io.IOException

read

public <T> T read(java.io.InputStream jsonInputStream)
           throws java.io.IOException

Applies this JsonPath to the provided json input stream

Type Parameters:

T - expected return type

Parameters:

jsonInputStream - input stream to read from

Returns:

list of objects matched by the given path

Throws:

java.io.IOException

read

public <T> T read(java.io.InputStream jsonInputStream,
                  Configuration configuration)
           throws java.io.IOException

Applies this JsonPath to the provided json input stream

Type Parameters:

T - expected return type

Parameters:

jsonInputStream - input stream to read from

configuration - configuration to use

Returns:

list of objects matched by the given path

Throws:

java.io.IOException

read

public <T> T read(java.io.InputStream jsonInputStream,
                  java.lang.String charset,
                  Configuration configuration)
           throws java.io.IOException

Applies this JsonPath to the provided json input stream

Type Parameters:

T - expected return type

Parameters:

jsonInputStream - input stream to read from

configuration - configuration to use

Returns:

list of objects matched by the given path

Throws:

java.io.IOException

compile

public static JsonPath compile(java.lang.String jsonPath,
                               Predicate... filters)

Compiles a JsonPath

Parameters:

jsonPath - to compile

filters - filters to be applied to the filter place holders [?] in the path

Returns:

compiled JsonPath

read

public static <T> T read(java.lang.Object json,
                         java.lang.String jsonPath,
                         Predicate... filters)

Creates a new JsonPath and applies it to the provided Json object

Type Parameters:

T - expected return type

Parameters:

json - a json object

jsonPath - the json path

filters - filters to be applied to the filter place holders [?] in the path

Returns:

list of objects matched by the given path

read

public static <T> T read(java.lang.String json,
                         java.lang.String jsonPath,
                         Predicate... filters)

Creates a new JsonPath and applies it to the provided Json string

Type Parameters:

T - expected return type

Parameters:

json - a json string

jsonPath - the json path

filters - filters to be applied to the filter place holders [?] in the path

Returns:

list of objects matched by the given path

read

@Deprecated
public static <T> T read(java.net.URL jsonURL,
                                     java.lang.String jsonPath,
                                     Predicate... filters)
                              throws java.io.IOException

Deprecated.

Creates a new JsonPath and applies it to the provided Json object

Type Parameters:

T - expected return type

Parameters:

jsonURL - url pointing to json doc

jsonPath - the json path

filters - filters to be applied to the filter place holders [?] in the path

Returns:

list of objects matched by the given path

Throws:

java.io.IOException

read

public static <T> T read(java.io.File jsonFile,
                         java.lang.String jsonPath,
                         Predicate... filters)
                  throws java.io.IOException

Creates a new JsonPath and applies it to the provided Json object

Type Parameters:

T - expected return type

Parameters:

jsonFile - json file

jsonPath - the json path

filters - filters to be applied to the filter place holders [?] in the path

Returns:

list of objects matched by the given path

Throws:

java.io.IOException

read

public static <T> T read(java.io.InputStream jsonInputStream,
                         java.lang.String jsonPath,
                         Predicate... filters)
                  throws java.io.IOException

Creates a new JsonPath and applies it to the provided Json object

Type Parameters:

T - expected return type

Parameters:

jsonInputStream - json input stream

jsonPath - the json path

filters - filters to be applied to the filter place holders [?] in the path

Returns:

list of objects matched by the given path

Throws:

java.io.IOException

using

public static ParseContext using(Configuration configuration)

Creates a ParseContext that can be used to parse JSON input. The parse context is as thread safe as the underlying JsonProvider. Note that not all JsonProvider are thread safe.

Parameters:

configuration - configuration to use when parsing JSON

Returns:

a parsing context based on given configuration

using

@Deprecated
public static ParseContext using(JsonProvider provider)

Deprecated.

Creates a ParseContext that will parse a given JSON input.

Parameters:

provider - jsonProvider to use when parsing JSON

Returns:

a parsing context based on given jsonProvider

parse

public static DocumentContext parse(java.lang.Object json)

Parses the given JSON input using the default Configuration and returns a DocumentContext for path evaluation

Parameters:

json - input

Returns:

a read context

parse

public static DocumentContext parse(java.lang.String json)

Parses the given JSON input using the default Configuration and returns a DocumentContext for path evaluation

Parameters:

json - string

Returns:

a read context

parse

public static DocumentContext parse(java.io.InputStream json)

Parses the given JSON input using the default Configuration and returns a DocumentContext for path evaluation

Parameters:

json - stream

Returns:

a read context

parse

public static DocumentContext parse(java.io.File json)
                             throws java.io.IOException

Parses the given JSON input using the default Configuration and returns a DocumentContext for path evaluation

Parameters:

json - file

Returns:

a read context

Throws:

java.io.IOException

parse

@Deprecated
public static DocumentContext parse(java.net.URL json)
                                         throws java.io.IOException

Deprecated.

Parses the given JSON input using the default Configuration and returns a DocumentContext for path evaluation

Parameters:

json - url

Returns:

a read context

Throws:

java.io.IOException

parse

public static DocumentContext parse(java.lang.Object json,
                                    Configuration configuration)

Parses the given JSON input using the provided Configuration and returns a DocumentContext for path evaluation

Parameters:

json - input

Returns:

a read context

parse

public static DocumentContext parse(java.lang.String json,
                                    Configuration configuration)

Parses the given JSON input using the provided Configuration and returns a DocumentContext for path evaluation

Parameters:

json - input

Returns:

a read context

parse

public static DocumentContext parse(java.io.InputStream json,
                                    Configuration configuration)

Parses the given JSON input using the provided Configuration and returns a DocumentContext for path evaluation

Parameters:

json - input

Returns:

a read context

parse

public static DocumentContext parse(java.io.File json,
                                    Configuration configuration)
                             throws java.io.IOException

Parses the given JSON input using the provided Configuration and returns a DocumentContext for path evaluation

Parameters:

json - input

Returns:

a read context

Throws:

java.io.IOException

parse

@Deprecated
public static DocumentContext parse(java.net.URL json,
                                                Configuration configuration)
                                         throws java.io.IOException

Deprecated.

Parses the given JSON input using the provided Configuration and returns a DocumentContext for path evaluation

Parameters:

json - input

Returns:

a read context

Throws:

java.io.IOException