Package org.json
Class JSONPointer
java.lang.Object
org.json.JSONPointer
A JSON Pointer is a simple query language defined for JSON documents by
RFC 6901.
In a nutshell, JSONPointer allows the user to navigate into a JSON document
using strings, and retrieve targeted objects, like a simple form of XPATH.
Path segments are separated by the '/' char, which signifies the root of
the document when it appears as the first char of the string. Array
elements are navigated using ordinals, counting from 0. JSONPointer strings
may be extended to any arbitrary number of segments. If the navigation
is successful, the matched item is returned. A matched item may be a
JSONObject, a JSONArray, or a JSON value. If the JSONPointer string building
fails, an appropriate exception is thrown. If the navigation fails to find
a match, a JSONPointerException is thrown.
- Version:
- 2016-05-14
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic class
This class allows the user to build a JSONPointer in steps, using exactly one segment in each step. -
Field Summary
Fields -
Constructor Summary
ConstructorsConstructorDescriptionJSONPointer
(String pointer) Pre-parses and initializes a newJSONPointer
instance.JSONPointer
(List<String> refTokens) Constructs a new JSONPointer instance with the provided list of reference tokens. -
Method Summary
Modifier and TypeMethodDescriptionstatic JSONPointer.Builder
builder()
Static factory method forJSONPointer.Builder
.private static String
Escapes path segment values to an unambiguous form.Evaluates this JSON Pointer on the givendocument
.private static Object
readByIndexToken
(Object current, String indexToken) Matches a JSONArray element by ordinal positiontoString()
Returns a string representing the JSONPointer path value using string representationReturns a string representing the JSONPointer path value using URI fragment identifier representationprivate static String
-
Field Details
-
ENCODING
- See Also:
-
refTokens
-
-
Constructor Details
-
JSONPointer
Pre-parses and initializes a newJSONPointer
instance. If you want to evaluate the same JSON Pointer on different JSON documents then it is recommended to keep theJSONPointer
instances due to performance considerations.- Parameters:
pointer
- the JSON String or URI Fragment representation of the JSON pointer.- Throws:
IllegalArgumentException
- ifpointer
is not a valid JSON pointer
-
JSONPointer
Constructs a new JSONPointer instance with the provided list of reference tokens.- Parameters:
refTokens
- A list of strings representing the reference tokens for the JSON Pointer. Each token identifies a step in the path to the targeted value.
-
-
Method Details
-
builder
Static factory method forJSONPointer.Builder
. Example usage:JSONPointer pointer = JSONPointer.builder() .append("obj") .append("other~key").append("another/key") .append("\"") .append(0) .build();
- Returns:
- a builder instance which can be used to construct a
JSONPointer
instance by chainedJSONPointer.Builder.append(String)
calls.
-
unescape
- See Also:
-
queryFrom
Evaluates this JSON Pointer on the givendocument
. Thedocument
is usually aJSONObject
or aJSONArray
instance, but the empty JSON Pointer (""
) can be evaluated on any JSON values and in such case the returned value will bedocument
itself.- Parameters:
document
- the JSON document which should be the subject of querying.- Returns:
- the result of the evaluation
- Throws:
JSONPointerException
- if an error occurs during evaluation
-
readByIndexToken
private static Object readByIndexToken(Object current, String indexToken) throws JSONPointerException Matches a JSONArray element by ordinal position- Parameters:
current
- the JSONArray to be evaluatedindexToken
- the array index in string form- Returns:
- the matched object. If no matching item is found a
- Throws:
JSONPointerException
- is thrown if the index is out of bounds
-
toString
Returns a string representing the JSONPointer path value using string representation -
escape
Escapes path segment values to an unambiguous form. The escape char to be inserted is '~'. The chars to be escaped are ~, which maps to ~0, and /, which maps to ~1.- Parameters:
token
- the JSONPointer segment value to be escaped- Returns:
- the escaped value for the token
- See Also:
-
toURIFragment
Returns a string representing the JSONPointer path value using URI fragment identifier representation- Returns:
- a uri fragment string
-