Package burp.api.montoya.utilities.json

Interface JsonUtils

public interface JsonUtils

This interface enables you to access convenient methods to read and manipulate JSON. All the methods accept a JSON String and a location. Some methods accept an additional JSON argument that you can use to modify the supplied JSON String.

Location syntax:

• .
  The location elements are delimited by a period character
• [n]
  Specifies the nth item in a JSON array
• []
  Specifies the last element in a JSON array
• key
  Identifies keyed entry in a JSON object

Note: Indices are zero based.

For example, when applied to the JSON below:

account.[0].user.name would select "Peter Wiener"

account.[].user.name would select "Carlos Montoya"

account.[1].user.addresses.[] would select "Address 6"

     {
         "account": [
              {
                  "user": {
                      "name": "Peter Wiener",
                      "addresses": [
                          "Address 1",
                          "Address 2",
                          "Address 3"
                      ]
                  }
              },
              {
                  "user": {
                      "name": "Carlos Montoya",
                      "addresses": [
                          "Address 4",
                          "Address 5",
                          "Address 6"
                      ]
                  }
              }
         ]
     }
 

Remarks

Methods that take in JSON accept single quotes in place of double quotes.

If your use case is more complex than this interface allows, see JsonNode and its inheritors.

Method Summary

Modifier and Type	Method	Description
String	add(String sourceJson, String location, String newJson)	Uses the location to create a new JSON string with the newJson added to the sourceJson.
boolean	isValidJson(String sourceJson)	Checks if the supplied sourceJson can be parsed into one of the base JSON types - string, number, boolean, array, object or null.
String	read(String sourceJson, String location)	Uses the location to work out where to read from the sourceJson.
Boolean	readBoolean(String sourceJson, String location)	Uses the location to work out where to read a Boolean value from the provided sourceJson.
Double	readDouble(String sourceJson, String location)	Uses the location to work out where to read a number as a Double value from the sourceJson.
Long	readLong(String sourceJson, String location)	Uses the location to work out where to read a number as a Long value from the sourceJson.
String	readString(String sourceJson, String location)	Uses the location to work out where to read a String value from the sourceJson.
String	remove(String sourceJson, String location)	Creates a new JSON string where the data at the provided location is removed form the sourceJson.
String	update(String sourceJson, String location, String newJson)	Uses the location to create a new JSON string where the sourceJson is updated with the newJson.

Method Details

add

String add(String sourceJson,
 String location,
 String newJson)

Uses the location to create a new JSON string with the newJson added to the sourceJson.

Parameters:

sourceJson - The JSON to add the newJson to.

location - Identifies where to add the newJson.

newJson - The new JSON to add to the source.

Returns:

A new string with the modified JSON.

Throws:

JsonException - If the location is invalid.

JsonParseException - If either the sourceJson or newJson are not valid JSON.

update

String update(String sourceJson,
 String location,
 String newJson)

Uses the location to create a new JSON string where the sourceJson is updated with the newJson.

Parameters:

sourceJson - The JSON that will be updated by the newJson.

location - Identifies where the update should occur on the sourceJson.

newJson - The new JSON to use in the location.

Returns:

A new string with the modified JSON.

Throws:

JsonException - If the location is invalid.

JsonParseException - If either the sourceJson or newJson are not valid JSON.

remove

String remove(String sourceJson,
 String location)

Creates a new JSON string where the data at the provided location is removed form the sourceJson.

Parameters:

sourceJson - The JSON that will have data removed.

location - Identifies where to remove the JSON.

Returns:

A new string with the data at the provided location removed from sourceJson.

Throws:

JsonException - If the location is invalid.

JsonParseException - If the sourceJson is not valid JSON.

read

String read(String sourceJson,
 String location)

Uses the location to work out where to read from the sourceJson.

Parameters:

sourceJson - The JSON to read some data from.

location - Identifies where to read from the sourceJson.

Returns:

The JSON read at the given location as a JSON string.

Throws:

JsonException - If the location is invalid.

JsonParseException - If the sourceJson is not valid JSON.

readBoolean

Boolean readBoolean(String sourceJson,
 String location)

Uses the location to work out where to read a Boolean value from the provided sourceJson.

Parameters:

sourceJson - The JSON to read from.

location - Identifies where to read from the sourceJson.

Returns:

The boolean value at the given location, or null if it is not a Boolean, or if it is not present.

Throws:

JsonException - If the location is invalid.

JsonParseException - If the sourceJson is not valid JSON.

readDouble

Double readDouble(String sourceJson,
 String location)

Uses the location to work out where to read a number as a Double value from the sourceJson.

Note: A double value in Java represents a floating point number.

Parameters:

sourceJson - The JSON to read from.

location - Identifies where to read from the sourceJson

Returns:

The number value as a Double at the given location, or null if it not a Double, or if it is not present.

Throws:

JsonException - If the location is invalid.

JsonParseException - If the sourceJson is not valid JSON.

readLong

Long readLong(String sourceJson,
 String location)

Uses the location to work out where to read a number as a Long value from the sourceJson.

Note: A long value in Java represents a mathematical integer - Reading a floating point number with this method will round it down.

Parameters:

sourceJson - The JSON to read from.

location - Identifies where to read from the sourceJson

Returns:

The number value as a Long at the given location, or null if it not a Long, or if it is not present.

Throws:

JsonException - If the location is invalid.

JsonParseException - If the sourceJson is not valid JSON.

readString

String readString(String sourceJson,
 String location)

Uses the location to work out where to read a String value from the sourceJson.

Parameters:

sourceJson - The JSON to read from.

location - Identifies where to read from the sourceJson

Returns:

The string value at the given location, or null if it not a String, or if it is not present.

Throws:

JsonException - If the location is invalid.

JsonParseException - If the sourceJson is not valid JSON.

isValidJson

boolean isValidJson(String sourceJson)

Checks if the supplied sourceJson can be parsed into one of the base JSON types - string, number, boolean, array, object or null.

Note: Passing in null will return false, whereas "null" will return true.

Note: To pass in a JSON string, surround it in single or double quotes ("'foo'" or "\"foo\"").

Parameters:

sourceJson - The JSON string to check

Returns:

True if this parser can parse the JSON string into one of the base JSON types. False otherwise or if sourceJson is null.