Class 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")
    • Field Summary

      Fields 
      Modifier and Type Field Description
      private Path path  
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      private JsonPath​(java.lang.String jsonPath, Predicate[] filters)  
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method 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
      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)
      Parses the given JSON input using the default Configuration and returns a DocumentContext for path evaluation
      static DocumentContext parse​(java.net.URL json, Configuration configuration)
      Parses the given JSON input using the provided Configuration and returns a DocumentContext for path evaluation
      <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)
      Creates a new JsonPath and applies it to the provided Json object
      <T> T renameKey​(java.lang.Object jsonObject, java.lang.String oldKeyName, java.lang.String newKeyName, Configuration configuration)  
      private <T> T resultByConfiguration​(java.lang.Object jsonObject, Configuration configuration, EvaluationContext evaluationContext)  
      <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 a given 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
    • Field Detail

      • path

        private final Path path
    • Constructor Detail

      • JsonPath

        private JsonPath​(java.lang.String jsonPath,
                         Predicate[] filters)
    • 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
        value - 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

        public static <T> T read​(java.net.URL jsonURL,
                                 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:
        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 a given JSON input.
        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

        public static DocumentContext parse​(java.net.URL json)
                                     throws java.io.IOException
        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.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

        public static DocumentContext parse​(java.net.URL 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
      • resultByConfiguration

        private <T> T resultByConfiguration​(java.lang.Object jsonObject,
                                            Configuration configuration,
                                            EvaluationContext evaluationContext)