Expose parseJSON() status enum and messages

[bmel]

Problem

Currently, the native function parseJSON() returns a uint32 code. All we know is that 0u means OK and all other values mean error... but not more than that.

Moreover, whenever called with invalid JSONs, parseJSON() will log an error message to appLog, like this:

08 Aug 2017 19:38:56.777 [32134] ERROR #splapplog,J[0],P[0],dataset0.genedge3_outOf_JsonToTuple,QUERY_JSON M[JsonReader.h:parseJSON:457]  - Missing a comma or '}' after an object member.

But a calling app likely needs to log according to its own logging standard, such as:

08 Aug 2017 19:38:56.779 [32134] ERROR #splapptrc,J[0],P[0],dataset0.genedge3_outOf_JsonToTuple M[CheckedJsonParsing.spl:appTrc:33]  - 
Code: STP100 (JSON-parse-error), Description: Error while parsing JSON (showing first 120 characters):
    { "customer_id" : "Invalid JSON, missing comma", "long" : "39.4" "lat" : 42, "timestamp" : "2017-06-20 09:10:10", "is-ha (...)
Cause: Missing a comma or '}' after an object member.

Thus, the messages logged by parseJSON() are not useful in the app context, at best. What's more - they can unnecessarily clutter the logs.

Compare this with functions (Java, C, ...) that parse numbers out of strings. These functions do not log error messages every time they are called with a string which cannot be interpreted as a number. After all, the caller may be using the function to merely check if the string is a number in the first place. Logging is left to the calling apps.

Similarly, XML parsers don't simply log every error, but rather give access to, or return, a report object with the encountered errors.

Moreover, queryJSON(), as opposed to parseJSON, returns a status and does not log when there is e.g. a type mismatch error. This is the desired behavior, and parseJSON() should adopt it.

Request

The function parseJSON() should grant access to error details, rather than itself logging errors to appLog(). (As it happens, the internally used rapidjson lib does have an error code enum, and it even has error messages with i18n.)

Possible approach

1. 'Report' the status back to the caller in an additional mutable status enum arg:

   void parseJSON(rstring const& jsonString, ParseStatus & status, const Index & jsonIndex)

2. Then, also provide a function for getting an error message by ParseStatus enum value and locale. For now, our product (Streaming Pipelines) is only available in English (US), but it would be the right thing to already have the locale in the API, even if i18n is postponed for now:

   rstring getMessage(const ParseStatus & status, rstring locale)

[leongor]

I've created PR with the required additions: https://github.com/IBMStreams/streamsx.json/pull/85

[leongor]

Merged - can be closed.

[rnostream]

85 merged