Class Json
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 TypeMethodDescriptionstatic org.json.JSONArray
Converts the supplied string to a JSONArray which can be interrogated further.static org.json.JSONArray
jsonArrayOpt
(String txt) 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
jsonObject
(String txt) Converts the supplied string to a JSONObject which can be interrogated further.static org.json.JSONObject
jsonObjectOpt
(String txt) 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.
-
Method Details
-
jsonObject
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
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
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
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
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
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"]
-