Update JSON API

Rationale

Currently we have an JSON implementation that supports:

• null
• boolean
• Number except BigDecimal
• String
• JsonArray
• JsonObject
• byte[]

The ECMA-404 does not specify the byte[], however this data type is quite useful and is indeed covered on RFC-7493. The RFC-7493 specifies 2 extra data types useful for data interchange:

• byte[] encoded as Base64 String
• Date encoded as ISO8601 e.g.: 2011-10-05T14:48:00.000Z

By extending the current types JsonObject and JsonArray to support Dates using the later RFC then we will have an implementation that fully complies both to the ECMA and RFC specs. This implementation solve several problems such as having an standardized way of encoding Dates and binary data. This ensures that Verticles and modules can "understand" these new types across the whole Vert.x ecosystem since the encoding is well known.

This change does not solve the "un-marshaling" of Dates back to the languages native types. The RFC only refers to encoding but no reference is done about decoding. For most APIs this is enough since both parties should have an agreement on what to expect as the payload of the JSON therefore a String field known to be encoded as Date can be parsed back to the language native data type.

Proposed API change

JsonObject

The proposal is to add the following methods to this class:

• JsonObject put(String key, java.util.Date date)
• Date getDate(String key)
• Date getDate(String key, java.util.Date defaultDate)

The expected behavior for the getters is to try to parse the String using the well defined format from the RFC and return the Date value or throw a JsonDecodeException if the value is not a valid string.

JsonArray

The proposal is to add the following methods to this class:

• JsonArray add(java.util.Date date)
• Date getDate(int pos)

The expected behavior for the getters is to try to parse the String using the well defined format from the RFC and return the Date value or throw a JsonDecodeException if the value is not a valid string.