Class JSONPointer

java.lang.Object
org.json.JSONPointer
public class JSONPointer extends 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

  • Field Details

  • Constructor Details

    • JSONPointer

      public JSONPointer(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:
      IllegalArgumentException - if pointer is not a valid JSON pointer

    • JSONPointer

      public JSONPointer(List<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 Details

    • 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.

    • unescape

      private static String unescape(String token)
      See Also:

    • queryFrom

      public Object queryFrom(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

    • readByIndexToken

      private static Object readByIndexToken(Object current, String indexToken) throws JSONPointerException
      Matches a JSONArray element by ordinal position
      Parameters:
      current - the JSONArray to be evaluated
      indexToken - 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 String toString()
      Returns a string representing the JSONPointer path value using string representation
      Overrides:
      toString in class Object

    • escape

      private static String escape(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:

    • toURIFragment

      public String toURIFragment()
      Returns a string representing the JSONPointer path value using URI fragment identifier representation
      Returns:
      a uri fragment string