Explicitly parse JSON string vs JSON.deserialize

Question

The JSON2Apex web tool offers 2 methods of parsing of the JSON string: one uses JSON.deserialize method, and the other creates parser and iterates over the input json. The second option can be enabled by checking "Create explicit parse code" in the tool.

QUESTION

In what cases would a developer prefer explicit parsing to a simple JSON.deserialize? If we compare both options the later seems to be much clear and less verbose which makes code more readable.

Explicit parsing

public class JSON2Apex {

    public class User {
        public String name {get;set;} 
        public String twitter {get;set;} 

        public User(JSONParser parser) {
            while (parser.nextToken() != System.JSONToken.END_OBJECT) {
                if (parser.getCurrentToken() == System.JSONToken.FIELD_NAME) {
                    String text = parser.getText();
                    if (parser.nextToken() != System.JSONToken.VALUE_NULL) {
                        if (text == 'name') {
                            name = parser.getText();
                        } else if (text == 'twitter') {
                            twitter = parser.getText();
                        } else {
                            System.debug(LoggingLevel.WARN, 'User consuming unrecognized property: '+text);
                            consumeObject(parser);
                        }
                    }
                }
            }
        }
    }

    public User user {get;set;} 

    public JSON2Apex(JSONParser parser) {
        while (parser.nextToken() != System.JSONToken.END_OBJECT) {
            if (parser.getCurrentToken() == System.JSONToken.FIELD_NAME) {
                String text = parser.getText();
                if (parser.nextToken() != System.JSONToken.VALUE_NULL) {
                    if (text == 'user') {
                        user = new User(parser);
                    } else {
                        System.debug(LoggingLevel.WARN, 'JSON2Apex consuming unrecognized property: '+text);
                        consumeObject(parser);
                    }
                }
            }
        }
    }


    public static JSON2Apex parse(String json) {
        System.JSONParser parser = System.JSON.createParser(json);
        return new JSON2Apex(parser);
    }

    public static void consumeObject(System.JSONParser parser) {
        Integer depth = 0;
        do {
            System.JSONToken curr = parser.getCurrentToken();
            if (curr == System.JSONToken.START_OBJECT || 
                curr == System.JSONToken.START_ARRAY) {
                depth++;
            } else if (curr == System.JSONToken.END_OBJECT ||
                curr == System.JSONToken.END_ARRAY) {
                depth--;
            }
        } while (depth > 0 && parser.nextToken() != null);
    }




}

JSON.deserialize

public class JSON2Apex {

    public class User {
        public String name;
        public String twitter;
    }

    public User user;


    public static JSON2Apex parse(String json) {
        return (JSON2Apex) System.JSON.deserialize(json, JSON2Apex.class);
    }
}

Answer 1

Apex code has reserved names (keywords) and special variable rules (e.g. cannot start with a number, can't have __, etc) that you can't use in JSON objects. You don't want to use explicit mode if you can help it, because it has worse performance compared to JSON.deserialize, but it gets around compilation errors if you have a JSON string like:

{ "title": "Writing JSON", "abstract": "A short document about how to use JSON." }

This would compile to:

public class JSON2Apex {
  public String title;
  public String abstract;
}

But abstract is a reserved keyword. You can't deploy this code to Salesforce. By changing the code:

public class JSON2Apex {
  public String title;
  public String abstract_x;
}

The code can then compile, but you need explicit parsing in order to translate abstract in the JSON string to abstract_x in Apex.