Class Json

java.lang.Object
uk.ac.starlink.ttools.func.Json

public class Json extends Object
Functions for working with JSON strings.

Usage of this class to manipulate hierarchical JSON objects is a bit different from the way that most of the other functions in the expression language are used. The main function provided by this class is jsonObject, which can be applied to a string value containing a JSON object (legal JSON object strings are enclosed in curly brackets), and returns a JSONObject instance. This JSONObject cannot be used on its own in the rest of the application, but various methods can be applied to it to extract information from its structure. These methods are applied by writing jsonObject.method(arg,arg,...) rather than function(jsonObject,arg,arg,...).

Methods you can apply to a JSONObject include:

  • getString(key)
  • getInt(key)
  • getDouble(key)
  • getBoolean(key)
  • getJSONObject(key)
  • getJSONArray(key)

where key is a string giving the name with which the member of the JSON object is associated. The first four of the above methods give you string, numeric, or boolean values that you can use in the application for plotting etc. getJSONObject returns another JSONObject that you can interrogate with further methods. getJSONArray gives you a JSONArray.

You can apply a different set of methods to a JSONArray, including:

  • getString(index)
  • getInt(index)
  • getDouble(index)
  • getBoolean(index)
  • getJSONObject(index)
  • getJSONArray(index)

where index is an integer giving the (zero-based) index of the element in the array that you want.

Using these methods you can drill down into the hierarchical structure of a JSON string to retrieve the string, numeric or boolean values that you need. If you are not familiar with this syntax, an example is the best way to illustrate it. Consider the following JSON string, which may be the value in a column named txt:

    {
       "sequence": 23,
       "temperature": {
          "value": 278.5,
          "units": "Kelvin"
       },
       "operational": true,
       "readings": [12, null, 23.2, 441, 0]
    }
 
To obtain the sequence value, you can write:
    jsonObject(txt).getInt("sequence")
 
to obtain the numeric temperature value, you can write:
    jsonObject(txt).getJSONObject("temperature").getDouble("value")
 
and to obtain the first element of the readings array, you can write:
    jsonObject(txt).getJSONArray("readings").getDouble(0)
 

Other methods are available on JSONObject and JSONArray; you can currently find documentation on them at https://stleary.github.io/JSON-java/. Note in particular that each of the JSONObject.get*(key) and JSONArray.get*(index) methods is accompanied by a corresponding opt* method; where the key/index may not exist, this will probably give effectively the same behaviour (generating a blank result) but may be considerably faster.

This class also contains some other utility functions for working with JSONObjects and JSONArrays; see the function documentation below for details.

Note: This class is somewhat experimental, and the functions and methods may change in future. An attempt will be made to retain the functions and methods described in this section, but those described in the external JSON-java javadocs may be subject to change.

Since:
21 Nov 2023
Author:
Mark Taylor
  • Method Summary

    Modifier and Type
    Method
    Description
    static org.json.JSONArray
    Converts the supplied string to a JSONArray which can be interrogated further.
    static org.json.JSONArray
    Converts the supplied string to a JSONArray which can be interrogated further.
    static String[]
    jsonGetKeys(org.json.JSONObject jsonObject)
    Returns an array giving keys for each key-value pair in a JSON object.
    static org.json.JSONObject
    Converts the supplied string to a JSONObject which can be interrogated further.
    static org.json.JSONObject
    Converts the supplied string to a JSON object which can be interrogated further.
    static double[]
    jsonToDoubles(org.json.JSONArray jsonArray)
    Converts a JSONArray to an array of floating point values.
    static String[]
    jsonToStrings(org.json.JSONArray jsonArray)
    Converts a JSONArray to an array of string values.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Method Details

    • jsonObject

      public static org.json.JSONObject jsonObject(String txt)
      Converts the supplied string to a JSONObject which can be interrogated further. If the input string doesn't have the syntax of a JSON object, an empty JSONObject will be returned.

      The JSON parsing is currently somewhat lenient, for instance allowing a comma before a closing curly bracket.

      Parameters:
      txt - string assumed to contain a JSON object
      Returns:
      JSON object value on which further methods can be called
    • jsonArray

      public static org.json.JSONArray jsonArray(String txt)
      Converts the supplied string to a JSONArray which can be interrogated further. If the input string doesn't have the syntax of a JSON array, a zero-length JSONArray will be returned.

      The JSON parsing is currently somewhat lenient, for instance allowing a comma before a closing square bracket.

      Parameters:
      txt - string assumed to contain a JSON array
      Returns:
      JSON array value on which further methods can be called
    • jsonObjectOpt

      public static org.json.JSONObject jsonObjectOpt(String txt)
      Converts the supplied string to a JSON object which can be interrogated further. If the input doesn't have the syntax of a JSON object, null will be returned.

      For most purposes this will behave the same as the jsonObject function, but it may be slower if there are many invalid or empty JSON strings.

      Parameters:
      txt - JSON object text
      Returns:
      JSON object value on which further methods can be called, or null
    • jsonArrayOpt

      public static org.json.JSONArray jsonArrayOpt(String txt)
      Converts the supplied string to a JSONArray which can be interrogated further. If the input string doesn't have the syntax of a JSON array, null will be returned.
      Parameters:
      txt - JSON object text
      Returns:
      JSON array value on which further methods can be called, or null
    • jsonToDoubles

      public static double[] jsonToDoubles(org.json.JSONArray jsonArray)
      Converts a JSONArray to an array of floating point values. The result will be the same length as the supplied JSONArray, and any element in the JSONArray which cannot be interpreted as a floating point value is represented by a NaN.
      Parameters:
      jsonArray - JSON Array
      Returns:
      floating point array the same length as the input array
      Examples:
      jsonToDoubles(jsonArray("[true, \"two\", 3.0, 4, null"])) = [NaN, NaN, 3.0, 4.0, NaN]
    • jsonToStrings

      public static String[] jsonToStrings(org.json.JSONArray jsonArray)
      Converts a JSONArray to an array of string values.
      Parameters:
      jsonArray - JSON Array
      Returns:
      string array the same length as the input array
      Examples:
      jsonToStrings(jsonArray("[true, \"two\", 3.0, 4, null]")) = ["true", "two", "3.0", "4", null]
    • jsonGetKeys

      public static String[] jsonGetKeys(org.json.JSONObject jsonObject)
      Returns an array giving keys for each key-value pair in a JSON object. The members of a JSON object are not ordered, so no order can be guaranteed in the output array.
      Parameters:
      jsonObject - JSON object
      Returns:
      string array containing keys of object
      Examples:
      jsonGetKeys(jsonObject("{\"one\", 1, \"two\", 2, \"three\", 3}")) = ["one", "two", "three"]