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.
The following are methods for JSONParser. All are instance methods.
public Void clearCurrentToken()
Type: Void
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.
public Blob getBlobValue()
Type: Blob
The current token must be of type JSONToken.VALUE_STRING and must be Base64-encoded.
public Boolean getBooleanValue()
Type: Boolean
The current token must be of type JSONToken.VALUE_TRUE or JSONToken.VALUE_FALSE.
String JSONContent = '{"isActive":true}'; JSONParser parser = JSON.createParser(JSONContent); // Advance to the start object marker. parser.nextToken(); // Advance to the next value. parser.nextValue(); // Get the Boolean value. Boolean isActive = parser.getBooleanValue();
public String getCurrentName()
Type: String
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.
String JSONContent = '{"firstName":"John"}'; JSONParser parser = JSON.createParser(JSONContent); // Advance to the start object marker. parser.nextToken(); // Advance to the next value. parser.nextValue(); // Get the field name for the current value. String fieldName = parser.getCurrentName(); // Get the textual representation // of the value. String fieldValue = parser.getText();
public System.JSONToken getCurrentToken()
Type: System.JSONToken
String JSONContent = '{"firstName":"John"}'; JSONParser parser = JSON.createParser(JSONContent); // Advance to the next token. while (parser.nextToken() != null) { System.debug('Current token: ' + parser.getCurrentToken()); }
public Datetime getDatetimeValue()
Type: Datetime
The current token must be of type JSONToken.VALUE_STRING and must represent a Datetime value in the ISO-8601 format.
String JSONContent = '{"transactionDate":"2011-03-22T13:01:23"}'; JSONParser parser = JSON.createParser(JSONContent); // Advance to the start object marker. parser.nextToken(); // Advance to the next value. parser.nextValue(); // Get the transaction date. Datetime transactionDate = parser.getDatetimeValue();
public Date getDateValue()
Type: Date
The current token must be of type JSONToken.VALUE_STRING and must represent a Date value in the ISO-8601 format.
String JSONContent = '{"dateOfBirth":"2011-03-22"}'; JSONParser parser = JSON.createParser(JSONContent); // Advance to the start object marker. parser.nextToken(); // Advance to the next value. parser.nextValue(); // Get the date of birth. Date dob = parser.getDateValue();
public Decimal getDecimalValue()
Type: Decimal
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.
String JSONContent = '{"GPA":3.8}'; JSONParser parser = JSON.createParser(JSONContent); // Advance to the start object marker. parser.nextToken(); // Advance to the next value. parser.nextValue(); // Get the GPA score. Decimal gpa = parser.getDecimalValue();
public Double getDoubleValue()
Type: Double
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.
String JSONContent = '{"GPA":3.8}'; JSONParser parser = JSON.createParser(JSONContent); // Advance to the start object marker. parser.nextToken(); // Advance to the next value. parser.nextValue(); // Get the GPA score. Double gpa = parser.getDoubleValue();
public ID getIdValue()
Type: ID
The current token must be of type JSONToken.VALUE_STRING and must be a valid ID.
String JSONContent = '{"recordId":"001R0000002nO6H"}'; JSONParser parser = JSON.createParser(JSONContent); // Advance to the start object marker. parser.nextToken(); // Advance to the next value. parser.nextValue(); // Get the record ID. ID recordID = parser.getIdValue();
public Integer getIntegerValue()
Type: Integer
The current token must be of type JSONToken.VALUE_NUMBER_INT and must represent an Integer.
String JSONContent = '{"recordCount":10}'; JSONParser parser = JSON.createParser(JSONContent); // Advance to the start object marker. parser.nextToken(); // Advance to the next value. parser.nextValue(); // Get the record count. Integer count = parser.getIntegerValue();
public System.JSONToken getLastClearedToken()
Type: System.JSONToken
public Long getLongValue()
Type: Long
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 .
String JSONContent = '{"recordCount":2097531021}'; JSONParser parser = JSON.createParser(JSONContent); // Advance to the start object marker. parser.nextToken(); // Advance to the next value. parser.nextValue(); // Get the record count. Long count = parser.getLongValue();
public String getText()
Type: String
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.
public Time getTimeValue()
Type: Time
The current token must be of type JSONToken.VALUE_STRING and must represent a Time value in the ISO-8601 format.
String JSONContent = '{"arrivalTime":"18:05"}'; JSONParser parser = JSON.createParser(JSONContent); // Advance to the start object marker. parser.nextToken(); // Advance to the next value. parser.nextValue(); // Get the arrival time. Time arrivalTime = parser.getTimeValue();
public Boolean hasCurrentToken()
Type: Boolean
public System.JSONToken nextToken()
Type: System.JSONToken
Advances the stream enough to determine the type of the next token, if any.
public System.JSONToken nextValue()
Type: System.JSONToken
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.
public Object readValueAs(System.Type apexType)
Type: Object
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.
public class Person { public String name; public String phone; }
// JSON string that contains a Person object. String JSONContent = '{"person":{' + '"name":"John Smith",' + '"phone":"555-1212"}}'; JSONParser parser = JSON.createParser(JSONContent); // Make calls to nextToken() // to point to the second // start object marker. parser.nextToken(); parser.nextToken(); parser.nextToken(); // Retrieve the Person object // from the JSON string. Person obj = (Person)parser.readValueAs( Person.class); System.assertEquals( obj.name, 'John Smith'); System.assertEquals( obj.phone, '555-1212');
public Object readValueAsStrict(System.Type apexType)
Type: Object
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.
public class Person { public String name; public String phone; }
// JSON string that contains a Person object. String JSONContent = '{"person":{' + '"name":"John Smith",' + '"phone":"555-1212"}}'; JSONParser parser = JSON.createParser(JSONContent); // Make calls to nextToken() // to point to the second // start object marker. parser.nextToken(); parser.nextToken(); parser.nextToken(); // Retrieve the Person object // from the JSON string. Person obj = (Person)parser.readValueAsStrict( Person.class); System.assertEquals( obj.name, 'John Smith'); System.assertEquals( obj.phone, '555-1212');