Package io.deephaven.json.jackson

Interface JacksonProvider

All Superinterfaces:
NamedObjectProcessor.Provider, ObjectProcessor.Provider
public interface JacksonProvider extends NamedObjectProcessor.Provider
A JSON value processor implementation using Jackson>.

This implementation allows users to efficiently parse / destructure a JSON value (from a supported input type) into writable chunks according to the type(s) as specified by its Value type. This is done using the Jackson streaming API JsonParser (as opposed to the databind / object mapping API, which must first create intermediate objects).

The "simple" types are self-explanatory. For example, the StringValue represents a String output type, and (by default) expects a JSON string as input; the IntValue represents an int output type, and (by default) expects a JSON number as input. The allowed JSON input types can be specified via allowed types; users are encouraged to use the strictest type they can according to how their JSON data is serialized.

The most common "complex" type is ObjectValue, which expects to parse a JSON object of known fields. The object contains ObjectValue.fields(), which represent other values. The fields are recursively resolved and flattened into the ObjectProcessor.outputTypes(). For example, a JSON object, which itself contains another JSON object 

 {
   "city": "Plymouth",
   "point": {
       "latitude": 45.018269,
       "longitude": -93.473892
   }
 }
when represented with structuring as one might expect (ObjectValue(StringValue, ObjectValue(DoubleValue, DoubleValue))), will produce output types representing [String, double, double]. Furthermore, the field names and delimiter "_" will be used by default to provide the names ["city", "point_latitude", "point_longitude"].

The ArrayValue represents a variable-length array, which expects to parse a JSON array where each element is expected to have the same element type. (This is in contrast to JSON arrays more generally, where each element of the array can be a different JSON value type.) The output type will be the output type(s) of the element type as the component type of a native array, Type.arrayType(). For example, if we used the previous example as the array component type, it will produce output types representing [String[], double[], double[]] (the names will remain unchanged).

The TupleValue represents a fixed number of value types, which expects to parse a fixed-length JSON array where each element corresponds to the same-indexed value type. The values are recursively resolved and flattened into the ObjectProcessor.outputTypes(); for example, the earlier example's data could be re-represented as the JSON array 

 ["Plymouth", 45.018269, -93.473892]
and structured as one might expect (TupleValue(StringValue, DoubleValue, DoubleValue)), and will produce output types representing [String, double, double]. Even though no field names are present in the JSON value, users may set names for each element (and will otherwise inherit integer-indexed default names).

The TypedObjectValue represents a union of object values where the first field is type-discriminating. For example, the following might be modelled as a type-discriminated object with type-discriminating field "type", shared "symbol" StringValue, "quote" object of "bid" DoubleValue and an "ask" DoubleValue, and "trade" object containing a "price" DoubleValue and a "size" LongValue. 

 {
   "type": "quote",
   "symbol": "BAR",
   "bid": 10.01,
   "ask": 10.05
 }
 {
   "type": "trade",
   "symbol": "FOO",
   "price": 70.03,
   "size": 42
 }
The output types are first the type-discriminating field, then the shared fields (if any), followed by the individual object value fields; with the above example, that would result in output types [String, String, double, double, double long] and names ["type", "symbol", "quote_bid", "quote_ask", "trade_price", "trade_size"].

The ObjectEntriesValue represents a variable-length object, which expects to parse a JSON object where each key-value entry has a common value type. The output type will be the key and value element types as a component of native arrays (Type.arrayType()). For example, a JSON object, whose values are also JSON objects 

 {
   "Plymouth": {
       "latitude": 45.018269,
       "longitude": -93.473892
   },
   "New York": {
       "latitude": 40.730610,
       "longitude": -73.935242
   }
 }
when represented with structuring as one might expect (ObjectEntriesValue(StringValue, ObjectValue(DoubleValue, DoubleValue))), will produce output types representing [String[], double[], double[]], and names ["Key", "latitude", "longitude"].

The AnyValue type represents a TreeNode output; this requires that the Jackson databinding API be available on the classpath. This is useful for initial modelling and debugging purposes.