[GitHub] incubator-quarks pull request #154: [WIP] Quarks 176 - Update Javadoc for Mq...

[dlaboss <gi...@git.apache.org>]

Github user dlaboss commented on a diff in the pull request:

    https://github.com/apache/incubator-quarks/pull/154#discussion_r70704776
  
    --- Diff: connectors/mqtt/src/main/java/quarks/connectors/mqtt/iot/MqttDevice.java ---
    @@ -45,7 +45,21 @@ Licensed to the Apache Software Foundation (ASF) under one
      * The connector doesn't presume a particular pattern for 
      * Device MQTT "event" topic and "command" topics though default
      * patterns are provided.
    + * </p>
      * <p>
    + * MqttDevice supports payload in String and Json formats.
    + * For command messages, JsonObject is returned with structure as follows:
    + * <br>
    + * <pre>
    + * {
    + *     "command" : "<<Command is extracted from command topic provided in config file>>",
    + *     "tsms" : "<<Current time stamp in milliseconds>>",
    + *     "format" : "<<json or string provided in command topic>>",
    + *     "payload" : "<<Actual payload as JsonObject or String>>"
    + * }
    + * </pre>
    + * <br><br>
    + * </p>
    --- End diff --
    
    so sorry for the delay.
    1. Correct.  The topic suffix defines the required payload fmt and MqttDevice currently only supports /fmt/json.
    2. See scripts/apps/sensorAnalytics/README.  You can edit the sensorAnalytics.properties file there to tell the sample to use a public MQTT server as noted there.
    3. Correct, that overload of events() specifies tuple independent eventId and qos values and serializes the tuple to JSON and sends a MQTT message with that JSON as its payload.
    
    The fact that a JsonObject is both a stream tuple and payload in different contexts adds to the confusion imo :-/  Let me see if I can clarify things by more clearly separating the protocol from the API.
    
    The MqttDevice's MQTT protocol is defined by the "command" and "eventId" MQTT topics and MQTT message payload content. 
    
    MqttDevice defines default MQTT topic formats for eventId messages and command messages but an organization / service / interoperating group of applications are free to define their own topic formats subject to the minimum requirements described in MqttDevice's javadoc.
    
    An "event" is a MQTT message whose payload is JSON, published to an "eventId" topic.  The definition of a particular event id's JSON contents is entirely up to the application; the JSON content is opaque to MqttDevice.
    
    Depending on which MqttDevice.events() method is used, the JSON is either the serialized TStream<JsonObject> tuple, or the serialized JsonObject that the application generates from the TStream<JsonObject> tuple.
    
    A "command" is a MQTT message whose payload is JSON, published to a "command" topic.  The definition of a particular command's JSON contents is entirely up to the application; the JSON content is opaque to MqttDevice.
    
    MqttDevice packages a received "command" MQTT message into a TStream<JsonObject> tuple whose contents are defined by IotDevice.command().  The tuple's CMD_FORMAT is "json" and its CMD_PAYLOAD is a JsonObject generated from the MQTT message's JSON payload.
    
    Hope that helps :-)


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---