Package org.json
Class JSONPointer
- java.lang.Object
-
- org.json.JSONPointer
-
public class JSONPointer extends java.lang.Object
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 Classes Modifier and Type Class Description static class
JSONPointer.Builder
This class allows the user to build a JSONPointer in steps, using exactly one segment in each step.
-
Constructor Summary
Constructors Constructor Description JSONPointer(java.lang.String pointer)
Pre-parses and initializes a newJSONPointer
instance.JSONPointer(java.util.List<java.lang.String> refTokens)
Constructs a new JSONPointer instance with the provided list of reference tokens.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description static JSONPointer.Builder
builder()
Static factory method forJSONPointer.Builder
.private static java.lang.String
escape(java.lang.String token)
Escapes path segment values to an unambiguous form.java.lang.Object
queryFrom(java.lang.Object document)
Evaluates this JSON Pointer on the givendocument
.private static java.lang.Object
readByIndexToken(java.lang.Object current, java.lang.String indexToken)
Matches a JSONArray element by ordinal positionjava.lang.String
toString()
Returns a string representing the JSONPointer path value using string representationjava.lang.String
toURIFragment()
Returns a string representing the JSONPointer path value using URI fragment identifier representationprivate static java.lang.String
unescape(java.lang.String token)
-
-
-
Field Detail
-
ENCODING
private static final java.lang.String ENCODING
- See Also:
- Constant Field Values
-
refTokens
private final java.util.List<java.lang.String> refTokens
-
-
Constructor Detail
-
JSONPointer
public JSONPointer(java.lang.String pointer)
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:
java.lang.IllegalArgumentException
- ifpointer
is not a valid JSON pointer
-
JSONPointer
public JSONPointer(java.util.List<java.lang.String> refTokens)
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 Detail
-
builder
public static JSONPointer.Builder 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
private static java.lang.String unescape(java.lang.String token)
- See Also:
- rfc6901 section 3
-
queryFrom
public java.lang.Object queryFrom(java.lang.Object document) throws JSONPointerException
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 java.lang.Object readByIndexToken(java.lang.Object current, java.lang.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
public java.lang.String toString()
Returns a string representing the JSONPointer path value using string representation- Overrides:
toString
in classjava.lang.Object
-
escape
private static java.lang.String escape(java.lang.String token)
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:
- rfc6901 section 3
-
toURIFragment
public java.lang.String toURIFragment()
Returns a string representing the JSONPointer path value using URI fragment identifier representation- Returns:
- a uri fragment string
-
-