JSONStreams (Java Application API for IBM Streams)
Date: 2020-08-07

com.ibm.streamsx.topology.json

## Class JSONStreams

- java.lang.Object
- - com.ibm.streamsx.topology.json.JSONStreams

-     public class JSONStreams
      extends java.lang.Object

  Utilities for JSON streams. A JSON stream is a stream of JSON objects represented by the class `com.ibm.json.java.JSONObject`. When a JSON value that is an array or value (not an object) needs to be present on the stream, the approach is to represent it as a object with the key `payload` containing the array or value.
  A JSON stream can be `published` so that IBM Streams applications implemented in different languages can subscribe to it.
  See Also:
    http://www.json.org - JSON (JavaScript Object Notation) is a lightweight data-interchange format.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `JSONStreams.DeserializeJSON` Function to deserialize a String to a JSONObject.
    `static class` | `JSONStreams.SerializeJSON` Function to serialize a JSONObject to a String.
    `static class` | `JSONStreams.ToJSON<T extends JSONAble>` Function to convert a `JSONAble` tuple to a `JSONObject`, using `JSONAble.toJSON()`.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `PAYLOAD` JSON key for arrays and values.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `JSONStreams()`

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static TStream<com.ibm.json.java.JSONObject>` | `deserialize(TStream<java.lang.String> stream)` Declare a stream of JSON objects from a stream of serialized JSON tuples.
    `static TStream<com.ibm.json.java.JSONObject>` | `flattenArray(TStream<com.ibm.json.java.JSONObject> stream, java.lang.String arrayKey, java.lang.String... additionalKeys)` Declare a stream that flattens an array present in the input tuple.
    `static TStream<java.lang.String>` | `serialize(TStream<com.ibm.json.java.JSONObject> stream)` Create a stream of serialized JSON objects as String tuples.
    `static <T extends JSONAble> TStream<com.ibm.json.java.JSONObject>` | `toJSON(TStream<T> stream)` Declare a stream of JSON objects from a stream of Java objects that implement `JSONAble`.
    `static SPLStream` | `toSPL(TStream<com.ibm.json.java.JSONObject> stream)` Convert a JSON stream to an SPLStream.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### PAYLOAD

          public static final java.lang.String PAYLOAD

      JSON key for arrays and values. When JSON is an array or a value (not an object) it is represented as a `JSONObject` tuple with an attribute (key) "payload" containing the array or value.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### JSONStreams

          public JSONStreams()

  - ### Method Detail

    - #### toSPL

          public static SPLStream toSPL(TStream<com.ibm.json.java.JSONObject> stream)

      Convert a JSON stream to an SPLStream.
      Parameters:
        `stream` - JSON stream to be converted.
      Returns:
        SPLStream with schema `JSONSchemas.JSON`.

    - #### serialize

          public static TStream<java.lang.String> serialize(TStream<com.ibm.json.java.JSONObject> stream)

      Create a stream of serialized JSON objects as String tuples.
      Parameters:
        `stream` - Stream containing the JSON objects.
      Returns:
        Stream that will contain the serialized JSON values.

    - #### deserialize

          public static TStream<com.ibm.json.java.JSONObject> deserialize(TStream<java.lang.String> stream)

      Declare a stream of JSON objects from a stream of serialized JSON tuples. If the serialized JSON is a simple value or an array, then a JSON object is created, with a single attribute `payload` containing the deserialized value.
      Parameters:
        `stream` - Stream containing the JSON serialized values.
      Returns:
        Stream that will contain the JSON objects.

    - #### toJSON

          public static <T extends JSONAble> TStream<com.ibm.json.java.JSONObject> toJSON(TStream<T> stream)

      Declare a stream of JSON objects from a stream of Java objects that implement `JSONAble`.
      Parameters:
        `stream` - Stream containing `JSONAble` tuples.
      Returns:
        Stream that will contain the JSON objects.

    - #### flattenArray

          public static TStream<com.ibm.json.java.JSONObject> flattenArray(TStream<com.ibm.json.java.JSONObject> stream,
                                                                           java.lang.String arrayKey,
                                                                           java.lang.String... additionalKeys)

      Declare a stream that flattens an array present in the input tuple. For each tuple on `stream` the key `arrayKey` and its value are extracted and if it is an array then each element in the array will be present on the returned stream as an individual tuple.
      If an array element is a JSON object it will be placed on returned stream, otherwise a JSON object will be placed on the returned stream with the key `payload` containing the element's value.
      If `arrayKey` is not present, is not an array or is an empty array then no tuples will result on the returned stream.

      Any additional keys (`additionalKeys`) that are specified are copied (with their value) into each JSON object on the returned stream from the input tuple, unless the flattened tuple already contains a value for the key.
      If an addition key is not in the input tuple, then it is not copied into the flattened tuples.

      For example, with a JSON object input tuple of:

           {"ts":"13:28:07", "sensors":
             [
               {"temperature": 34.2},
               {"rainfall": 12.96}
             ]
           }

      and a call of `flattenArray(stream, "sensors", "ts")` would result in two tuples:

           {"temperature": 34.2, "ts": "13:28:07"}
           {"rainfall": 12.96, "ts": "13:28:07"}

      With a JSON input tuple containing an array of simple values:

           {"ts":"13:43:09", "unit": "C", "readings":
             [
               33.9,
               33.8,
               34.1
             ]
           }

      and a call of `flattenArray(stream, "readings", "ts", "unit")` would result in three tuples:

           {"payload": 33.9, "ts": "13:43:09", "unit":"C"}
           {"payload": 33.8, "ts": "13:43:09", "unit":"C"}
           {"payload": 34.1, "ts": "13:43:09", "unit":"C"}

      Parameters:
        `stream` - Steam containing tuples with an array to be flattened.
        `arrayKey` - Key of the array in each input tuple.
        `additionalKeys` - Additional keys that copied from the input tuple into each resultant tuple from the array
      Returns:
        Stream containing tuples flattened from input tuple.