Apex Reference Guide
jNewer Version Available
JSONParser Class
Namespace
Usage
Use the System.JSONParser methods to parse a response that's returned from a call to an external service that is in JSON format, such as a JSON-encoded response of a Web service callout.
JSONParser Methods
The following are methods for JSONParser. All are instance methods.
clearCurrentToken()
Signature
public Void clearCurrentToken()
Return Value
Type: Void
Usage
After this method is called, a call to hasCurrentToken returns false and a call to getCurrentToken returns null. You can retrieve the cleared token by calling getLastClearedToken.
getBlobValue()
Signature
public Blob getBlobValue()
Return Value
Type: Blob
Usage
The current token must be of type JSONToken.VALUE_STRING and must be Base64-encoded.
getBooleanValue()
Signature
public Boolean getBooleanValue()
Return Value
Type: Boolean
Usage
The current token must be of type JSONToken.VALUE_TRUE or JSONToken.VALUE_FALSE.
1String JSONContent =
2 '{"isActive":true}';
3JSONParser parser =
4 JSON.createParser(JSONContent);
5// Advance to the start object marker.
6parser.nextToken();
7// Advance to the next value.
8parser.nextValue();
9// Get the Boolean value.
10Boolean isActive = parser.getBooleanValue();getCurrentName()
Signature
public String getCurrentName()
Return Value
Type: String
Usage
If the current token is of type JSONToken.FIELD_NAME, this method returns the same value as getText. If the current token is a value, this method returns the field name that precedes this token. For other values such as array values or root-level values, this method returns null.
The following example parses a sample JSON string. It advances to the field value and retrieves its corresponding field name.
Example
1String JSONContent = '{"firstName":"John"}';
2JSONParser parser =
3 JSON.createParser(JSONContent);
4// Advance to the start object marker.
5parser.nextToken();
6// Advance to the next value.
7parser.nextValue();
8// Get the field name for the current value.
9String fieldName = parser.getCurrentName();
10// Get the textual representation
11// of the value.
12String fieldValue = parser.getText();getCurrentToken()
Signature
public System.JSONToken getCurrentToken()
Return Value
Type: System.JSONToken
Usage
1String JSONContent = '{"firstName":"John"}';
2JSONParser parser =
3 JSON.createParser(JSONContent);
4// Advance to the next token.
5while (parser.nextToken() != null) {
6 System.debug('Current token: ' +
7 parser.getCurrentToken());
8}getDatetimeValue()
Signature
public Datetime getDatetimeValue()
Return Value
Type: Datetime
Usage
The current token must be of type JSONToken.VALUE_STRING and must represent a Datetime value in the ISO-8601 format.
1String JSONContent =
2'{"transactionDate":"2011-03-22T13:01:23"}';
3JSONParser parser =
4 JSON.createParser(JSONContent);
5// Advance to the start object marker.
6parser.nextToken();
7// Advance to the next value.
8parser.nextValue();
9// Get the transaction date.
10Datetime transactionDate =
11 parser.getDatetimeValue();getDateValue()
Signature
public Date getDateValue()
Return Value
Type: Date
Usage
The current token must be of type JSONToken.VALUE_STRING and must represent a Date value in the ISO-8601 format.
1String JSONContent =
2 '{"dateOfBirth":"2011-03-22"}';
3JSONParser parser =
4 JSON.createParser(JSONContent);
5// Advance to the start object marker.
6parser.nextToken();
7// Advance to the next value.
8parser.nextValue();
9// Get the date of birth.
10Date dob = parser.getDateValue();getDecimalValue()
Signature
public Decimal getDecimalValue()
Return Value
Type: Decimal
Usage
The current token must be of type JSONToken.VALUE_NUMBER_FLOAT or JSONToken.VALUE_NUMBER_INT and is a numerical value that can be converted to a value of type Decimal.
1String JSONContent =
2 '{"GPA":3.8}';
3JSONParser parser =
4 JSON.createParser(JSONContent);
5// Advance to the start object marker.
6parser.nextToken();
7// Advance to the next value.
8parser.nextValue();
9// Get the GPA score.
10Decimal gpa = parser.getDecimalValue();getDoubleValue()
Signature
public Double getDoubleValue()
Return Value
Type: Double
Usage
The current token must be of type JSONToken.VALUE_NUMBER_FLOAT and is a numerical value that can be converted to a value of type Double.
1String JSONContent =
2 '{"GPA":3.8}';
3JSONParser parser =
4 JSON.createParser(JSONContent);
5// Advance to the start object marker.
6parser.nextToken();
7// Advance to the next value.
8parser.nextValue();
9// Get the GPA score.
10Double gpa = parser.getDoubleValue();getIdValue()
Signature
public ID getIdValue()
Return Value
Type: ID
Usage
The current token must be of type JSONToken.VALUE_STRING and must be a valid ID.
1String JSONContent =
2 '{"recordId":"001R0000002nO6H"}';
3JSONParser parser =
4 JSON.createParser(JSONContent);
5// Advance to the start object marker.
6parser.nextToken();
7// Advance to the next value.
8parser.nextValue();
9// Get the record ID.
10ID recordID = parser.getIdValue();getIntegerValue()
Signature
public Integer getIntegerValue()
Return Value
Type: Integer
Usage
The current token must be of type JSONToken.VALUE_NUMBER_INT and must represent an Integer.
1String JSONContent =
2 '{"recordCount":10}';
3JSONParser parser =
4 JSON.createParser(JSONContent);
5// Advance to the start object marker.
6parser.nextToken();
7// Advance to the next value.
8parser.nextValue();
9// Get the record count.
10Integer count = parser.getIntegerValue();getLastClearedToken()
Signature
public System.JSONToken getLastClearedToken()
Return Value
Type: System.JSONToken
getLongValue()
Signature
public Long getLongValue()
Return Value
Type: Long
Usage
The current token must be of type JSONToken.VALUE_NUMBER_INT and is a numerical value that can be converted to a value of type Long .
1String JSONContent =
2 '{"recordCount":2097531021}';
3JSONParser parser =
4 JSON.createParser(JSONContent);
5// Advance to the start object marker.
6parser.nextToken();
7// Advance to the next value.
8parser.nextValue();
9// Get the record count.
10Long count = parser.getLongValue();getText()
Signature
public String getText()
Return Value
Type: String
Usage
No current token exists, and therefore this method returns null, if nextToken has not been called yet for the first time or if the parser has reached the end of the input stream.
getTimeValue()
Signature
public Time getTimeValue()
Return Value
Type: Time
Usage
The current token must be of type JSONToken.VALUE_STRING and must represent a Time value in the ISO-8601 format.
1String JSONContent =
2 '{"arrivalTime":"18:05"}';
3JSONParser parser =
4 JSON.createParser(JSONContent);
5// Advance to the start object marker.
6parser.nextToken();
7// Advance to the next value.
8parser.nextValue();
9// Get the arrival time.
10Time arrivalTime = parser.getTimeValue();hasCurrentToken()
Signature
public Boolean hasCurrentToken()
Return Value
Type: Boolean
nextToken()
Signature
public System.JSONToken nextToken()
Return Value
Type: System.JSONToken
Usage
Advances the stream enough to determine the type of the next token, if any.
nextValue()
Signature
public System.JSONToken nextValue()
Return Value
Type: System.JSONToken
Usage
Advances the stream enough to determine the type of the next token that is of a value type, if any, including a JSON array and object start and end markers.
readValueAs(apexType)
Signature
public Object readValueAs(System.Type apexType)
Parameters
- apexType
- Type: System.Type
- The apexType argument specifies the type of the object that this method returns after deserializing the current value.
Return Value
Type: Object
Usage
If the JSON content contains attributes not present in the System.Type argument, such as a missing field or object, deserialization fails in some circumstances. When deserializing JSON content into a custom object or an sObject using Salesforce API version 34.0 or earlier, this method throws a runtime exception when passed extraneous attributes. When deserializing JSON content into an Apex class in any API version, or into an object in API version 35.0 or later, no exception is thrown. When no exception is thrown, this method ignores extraneous attributes and parses the rest of the JSON content.
Example
1public class Person {
2 public String name;
3 public String phone;
4}1// JSON string that contains a Person object.
2String JSONContent =
3 '{"person":{' +
4 '"name":"John Smith",' +
5 '"phone":"555-1212"}}';
6JSONParser parser =
7 JSON.createParser(JSONContent);
8// Make calls to nextToken()
9// to point to the second
10// start object marker.
11parser.nextToken();
12parser.nextToken();
13parser.nextToken();
14// Retrieve the Person object
15// from the JSON string.
16Person obj =
17 (Person)parser.readValueAs(
18 Person.class);
19System.assertEquals(
20 obj.name, 'John Smith');
21System.assertEquals(
22 obj.phone, '555-1212');readValueAsStrict(apexType)
Signature
public Object readValueAsStrict(System.Type apexType)
Parameters
- apexType
- Type: System.Type
- The apexType argument specifies the type of the object that this method returns after deserializing the current value.
Return Value
Type: Object
Usage
If the JSON content contains attributes not present in the System.Type argument, such as a missing field or object, deserialization fails in some circumstances. When deserializing JSON content with extraneous attributes into an Apex class, this method throws an exception in all API versions. However, no exception is thrown when you use this method to deserialize JSON content into a custom object or an sObject.
1public class Person {
2 public String name;
3 public String phone;
4}1// JSON string that contains a Person object.
2String JSONContent =
3 '{"person":{' +
4 '"name":"John Smith",' +
5 '"phone":"555-1212"}}';
6JSONParser parser =
7 JSON.createParser(JSONContent);
8// Make calls to nextToken()
9// to point to the second
10// start object marker.
11parser.nextToken();
12parser.nextToken();
13parser.nextToken();
14// Retrieve the Person object
15// from the JSON string.
16Person obj =
17 (Person)parser.readValueAsStrict(
18 Person.class);
19System.assertEquals(
20 obj.name, 'John Smith');
21System.assertEquals(
22 obj.phone, '555-1212');