UTIL_JsonPath
Class · Group: Utilities
global inherited sharing class UTIL_JsonPathUtility class to streamline parsing nested JSON data structures. Provides methods to navigate and extract data from JSON using dot notation paths, with support for type-safe value retrieval and existence checks. Adapted from open-force.
Since: 1.0
Example:
UTIL_JsonPath json = new UTIL_JsonPath('{"account": {"name": "Acme", "active": true}}');
String name = json.get('account.name').getStringValue();
Boolean active = json.get('account.active').getBooleanValue();
Boolean exists = json.exists('account.name');Methods
| Method | Description |
|---|---|
| global Boolean exists(String path) | Checks if a path exists in the JSON data structure. |
| global UTIL_JsonPath findNode(String path) | Navigates to a subtree in the JSON data using a dot notation path. |
| global UTIL_JsonPath get(String path) | Retrieves a subtree in the JSON data using a dot notation path. |
| global Boolean getBooleanValue() | Converts the wrapped JSON data to a Boolean. |
| global Datetime getDatetimeValue() | Converts the wrapped JSON data to a Datetime, supporting ISO-8601 strings or timestamps (Long). |
| global Date getDateValue() | Converts the wrapped JSON data to a Date, supporting ISO-8601 strings or timestamps (Long). |
| global Decimal getDecimalValue() | Converts the wrapped JSON data to a Decimal. |
| global Id getIdValue() | Converts the wrapped JSON data to a Salesforce Id, validating the string format. |
| global Integer getIntegerValue() | Converts the wrapped JSON data to an Integer. |
| global String getStringValue() | Converts the wrapped JSON data to a String, excluding objects and arrays. |
| global Boolean isArray() | Checks if the wrapped JSON data is an array (List). |
| global Boolean isObject() | Checks if the wrapped JSON data is an object (Map). |
| global String toStringPretty() | Serializes the wrapped JSON data to a pretty-printed JSON string. |
| global UTIL_JsonPath(String jsonData) | Constructs a UTIL_JsonPath instance from a serialized JSON string. |
Inner Classes
| Class | Description |
|---|---|
| MissingKeyException | Custom exception thrown when a JSON path key cannot be resolved. |
Method Details
UTIL_JsonPath
global UTIL_JsonPath(String jsonData)Constructs a UTIL_JsonPath instance from a serialized JSON string.
Parameters:
jsonData(String) - The JSON string to parse.
Since: 1.0
Example:
UTIL_JsonPath instance = new UTIL_JsonPath('value');exists
global Boolean exists(String path)Checks if a path exists in the JSON data structure.
Parameters:
path(String) - The dot notation path to check.
Returns: Boolean - True if the path exists, false otherwise.
Since: 1.0
Example:
UTIL_JsonPath json = new UTIL_JsonPath('{"data": {"items": [{"id": 1}]}}');
Boolean existsFirst = json.exists('data.items[0]');
Boolean existsSecond = json.exists('data.items[1]');findNode
global UTIL_JsonPath findNode(String path)Navigates to a subtree in the JSON data using a dot notation path.
Parameters:
path(String) - The dot notation path to the desired subtree.
Returns: UTIL_JsonPath - A UTIL_JsonPath instance wrapping the targeted subtree, or null if the path does not exist.
Since: 1.0
Example:
UTIL_JsonPath result = instance.findNode('value');get
global UTIL_JsonPath get(String path)Retrieves a subtree in the JSON data using a dot notation path.
Supports paths with array indices (e.g., data.items[1]) and object keys.
Parameters:
path(String) - The dot notation path to the desired data.
Returns: UTIL_JsonPath - A UTIL_JsonPath instance wrapping the targeted subtree.
Throws:
- ListException - If an array index is out of bounds.
- MissingKeyException - If a key in the path does not exist in the JSON object.
- UTIL_Exceptions.IllegalStateException - If an array index is applied to a non-array node or a key is applied to a non-object node.
Since: 1.0
Example:
UTIL_JsonPath json = new UTIL_JsonPath('{"data": {"items": [{"id": 1}, {"id": 2}]}}');
UTIL_JsonPath item = json.get('data.items[1]');
String id = item.getStringValue();getBooleanValue
global Boolean getBooleanValue()Converts the wrapped JSON data to a Boolean.
Returns: Boolean - The value as a Boolean.
Throws:
- TypeException - If the value is not a Boolean or convertible string.
Since: 1.0
Example:
UTIL_JsonPath json = new UTIL_JsonPath('{"isActive": true}');
Boolean isActive = json.get('isActive').getBooleanValue();getDatetimeValue
global Datetime getDatetimeValue()Converts the wrapped JSON data to a Datetime, supporting ISO-8601 strings or timestamps (Long).
Returns: Datetime - The value as a Datetime.
Throws:
- TypeException - If the value is not a String or Long.
Since: 1.0
Example:
UTIL_JsonPath json = new UTIL_JsonPath('{"timestamp": 1625097600000}');
Datetime dt = json.get('timestamp').getDatetimeValue();getDateValue
global Date getDateValue()Converts the wrapped JSON data to a Date, supporting ISO-8601 strings or timestamps (Long).
Returns: Date - The value as a Date.
Throws:
- TypeException - If the value is not a String or Long.
Since: 1.0
Example:
UTIL_JsonPath json = new UTIL_JsonPath('{"date": "2021-07-01"}');
Date dt = json.get('date').getDateValue();getDecimalValue
global Decimal getDecimalValue()Converts the wrapped JSON data to a Decimal.
Returns: Decimal - The value as a Decimal.
Throws:
- TypeException - If the value is not a Decimal or convertible string.
Since: 1.0
Example:
UTIL_JsonPath json = new UTIL_JsonPath('{"amount": "123.45"}');
Decimal amount = json.get('amount').getDecimalValue();getIdValue
global Id getIdValue()Converts the wrapped JSON data to a Salesforce Id, validating the string format.
Returns: Id - The value as an Id.
Throws:
- StringException - If the string is not a valid Salesforce Id.
- TypeException - If the value is not a string.
Since: 1.0
Example:
UTIL_JsonPath json = new UTIL_JsonPath('{"recordId": "001xx0000000000AAA"}');
Id recordId = json.get('recordId').getIdValue();getIntegerValue
global Integer getIntegerValue()Converts the wrapped JSON data to an Integer.
Returns: Integer - The value as an Integer.
Throws:
- TypeException - If the value is not an Integer, Decimal, or convertible string.
Since: 1.0
Example:
UTIL_JsonPath json = new UTIL_JsonPath('{"count": "42"}');
Integer count = json.get('count').getIntegerValue();getStringValue
global String getStringValue()Converts the wrapped JSON data to a String, excluding objects and arrays.
Returns: String - The value as a String.
Throws:
- TypeException - If the value is a JSON object or array.
Since: 1.0
Example:
UTIL_JsonPath json = new UTIL_JsonPath('{"name": "John"}');
String name = json.get('name').getStringValue();isArray
global Boolean isArray() global Boolean isObject() global String toStringPretty()Checks if the wrapped JSON data is an array (List ).
Returns: Boolean - True if the value is a JSON array, false otherwise.
Since: 1.0
Example:
UTIL_JsonPath json = new UTIL_JsonPath('[{"id": 1}]');
Boolean result = json.isArray();isObject
global Boolean isObject()Checks if the wrapped JSON data is an object (Map ).
Returns: Boolean - True if the value is a JSON object, false otherwise.
Since: 1.0
Example:
UTIL_JsonPath json = new UTIL_JsonPath('{"key": "value"}');
Boolean result = json.isObject();toStringPretty
global String toStringPretty()Serializes the wrapped JSON data to a pretty-printed JSON string.
Returns: String - A formatted JSON string.
Since: 1.0
Example:
UTIL_JsonPath json = new UTIL_JsonPath('{"key": "value"}');
String result = json.toStringPretty();