JsonParser does not document exception handling

[elharo]

JsonParser.parseAndClose and similar methods do not document which exceptions are thrown under what circumstances. The Jackson and GSON subclasses are in fact throwing different exceptions, IO and IllegalArgument to name two, for the same input. This needs to be documented and made consistent.

[chingor13]

We should probably add another test to https://github.com/googleapis/google-http-java-client/blob/master/google-http-client-test/src/main/java/com/google/api/client/test/json/AbstractJsonParserTest.java on the handling of invalid JSON.

[elharo]

That sounds like a good idea.

[hiranya911]

Also related to this is that the same parser input may or may not throw depending on the underlying library used. For example given a plain text input like String input = "not json";, Jackson would throw, but Gson would not. Some of this is due to the differences in the parsers themselves (Gson is lot more lenient by default, although this can be configured). But it would be nice if the JsonFactory abstraction can hide such differences better.

[elharo]

GSON is not as configurable as its docs claim. In particular, the API doc for setLenient doesn't appear to match its actual behavior.

[hiranya911]

At least the simple case below works as expected when setLenient(true) is not set:

JsonReader reader = new JsonReader(new StringReader("not json"));
reader.hasNext();

This throws:

com.google.gson.stream.MalformedJsonException: Use JsonReader.setLenient(true) to accept malformed JSON at line 1 column 1 path $
	at com.google.gson.stream.JsonReader.syntaxError(JsonReader.java:1564)
	at com.google.gson.stream.JsonReader.checkLenient(JsonReader.java:1405)
	at com.google.gson.stream.JsonReader.doPeek(JsonReader.java:594)
	at com.google.gson.stream.JsonReader.hasNext(JsonReader.java:415)

[elharo]

I'd like to introduce a JsonException class to distinguish I/O errors from JSON parsing errors since a JSON syntax violation is not an I/O error. However this would not be API compatible. :-(

[lesv]

@BenWhitehead @vam-google Should this be assigned to one of you?

[Capstan]

In the monorepo, I am attempting to migrate the entirety from Jackson and Jackson2 to Gson, in part because this repo has already deleted Jackson support and in part because of pressure from security. I am running into this case (and others documented in googleapis/google-api-java-client#1779). Do you all have a general plan for what you would do here if you were to tackle it?

My choices are to instrument the consumers' code (where I can figure out where it's relevant, which is difficult) to handle the additional IllegalArgumentException, or catch and rethrow in the GsonParser via a patch to be upstreamed. If you were going to aim at the latter or something similar, I'd be more inclined to approach things that way, so that the wide change can be more safely applied.