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?