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

Author:

JSON.org

Nested Class Summary

Nested Classes

Modifier and Type	Class and 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 and Description
JSONPointer(java.util.List<java.lang.String> refTokens)
JSONPointer(java.lang.String pointer) Pre-parses and initializes a new JSONPointer instance.

Method Summary

Modifier and Type	Method and Description
static JSONPointer.Builder	builder() Static factory method for JSONPointer.Builder.
java.lang.Object	queryFrom(java.lang.Object document) Evaluates this JSON Pointer on the given document.
java.lang.String	toString() Returns a string representing the JSONPointer path value using string representation
java.lang.String	toURIFragment() Returns a string representing the JSONPointer path value using URI fragment identifier representation

Methods inherited from class java.lang.Object

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

Constructor Detail

JSONPointer

public JSONPointer(java.lang.String pointer)

Pre-parses and initializes a new JSONPointer instance. If you want to evaluate the same JSON Pointer on different JSON documents then it is recommended to keep the JSONPointer instances due to performance considerations.

Parameters:

pointer - the JSON String or URI Fragment representation of the JSON pointer.

Throws:

java.lang.IllegalArgumentException - if pointer is not a valid JSON pointer

JSONPointer

public JSONPointer(java.util.List<java.lang.String> refTokens)

Method Detail

builder

public static JSONPointer.Builder builder()

Static factory method for JSONPointer.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 chained JSONPointer.Builder.append(String) calls.

queryFrom

public java.lang.Object queryFrom(java.lang.Object document)
                           throws JSONPointerException

Evaluates this JSON Pointer on the given document. The document is usually a JSONObject or a JSONArray instance, but the empty JSON Pointer ("") can be evaluated on any JSON values and in such case the returned value will be document 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

toString

public java.lang.String toString()

Returns a string representing the JSONPointer path value using string representation

Overrides:

toString in class java.lang.Object

toURIFragment

public java.lang.String toURIFragment()

Returns a string representing the JSONPointer path value using URI fragment identifier representation