Merge pull request #571 from bsinno/bugfix/outgoing-mapping-js-status

Added status to incoming and outgoing javascript mappings

documentation/src/main/resources/pages/ditto/connectivity-mapping.md

@@ -267,19 +267,21 @@ Ditto comes with a few helper functions, which makes writing the mapping scripts
  * @param {string} path - The path which is affected by the message, e.g.: "/attributes"
  * @param {Object.<string, string>} dittoHeaders - The headers Object containing all Ditto Protocol header values
  * @param {*} [value] - The value to apply / which was applied (e.g. in a "modify" action)
+ * @param {number} status - The status code that indicates the result of the command.
  * @returns {DittoProtocolMessage} dittoProtocolMessage - 
  *  the mapped Ditto Protocol message or 
  *  <code>null</code> if the message could/should not be mapped
  */
-let buildDittoProtocolMsg = function(namespace, id, group, channel, criterion, action, path, dittoHeaders, value) {
+function buildDittoProtocolMsg(namespace, id, group, channel, criterion, action, path, dittoHeaders, value, status) {
 
     let dittoProtocolMsg = {};
     dittoProtocolMsg.topic = namespace + "/" + id + "/" + group + "/" + channel + "/" + criterion + "/" + action;
     dittoProtocolMsg.path = path;
     dittoProtocolMsg.headers = dittoHeaders;
     dittoProtocolMsg.value = value;
+    dittoProtocolMsg.status = status;
     return dittoProtocolMsg;
-};
+}
 
 /**
  * Builds an external message from the passed parameters.
@@ -291,15 +293,15 @@ let buildDittoProtocolMsg = function(namespace, id, group, channel, criterion, a
  *  the mapped external message
  *  or <code>null</code> if the message could/should not be mapped
  */
-let buildExternalMsg = function(headers, textPayload, bytePayload, contentType) {
+function buildExternalMsg(headers, textPayload, bytePayload, contentType) {
 
     let externalMsg = {};
     externalMsg.headers = headers;
     externalMsg.textPayload = textPayload;
     externalMsg.bytePayload = bytePayload;
     externalMsg.contentType = contentType;
     return externalMsg;
-};
+}
 
 /**
  * Transforms the passed ArrayBuffer to a String interpreting the content of the passed arrayBuffer as unsigned 8
@@ -308,39 +310,39 @@ let buildExternalMsg = function(headers, textPayload, bytePayload, contentType)
  * @param {ArrayBuffer} arrayBuffer the ArrayBuffer to transform to a String
  * @returns {String} the transformed String
  */
-let arrayBufferToString = function(arrayBuffer) {
+function arrayBufferToString(arrayBuffer) {
 
     return String.fromCharCode.apply(null, new Uint8Array(arrayBuffer));
-};
+}
 
 /**
  * Transforms the passed String to an ArrayBuffer using unsigned 8 bit integers.
  *
  * @param {String} string the String to transform to an ArrayBuffer
  * @returns {ArrayBuffer} the transformed ArrayBuffer
  */
-let stringToArrayBuffer = function(string) {
+function stringToArrayBuffer(string) {
 
     let buf = new ArrayBuffer(string.length);
     let bufView = new Uint8Array(buf);
     for (let i=0, strLen=string.length; i<strLen; i++) {
         bufView[i] = string.charCodeAt(i);
     }
     return buf;
-};
+}
 
 /**
  * Transforms the passed ArrayBuffer to a {ByteBuffer} (from bytebuffer.js library which needs to be loaded).
  *
  * @param {ArrayBuffer} arrayBuffer the ArrayBuffer to transform
  * @returns {ByteBuffer} the transformed ByteBuffer
  */
-let asByteBuffer = function(arrayBuffer) {
+function asByteBuffer(arrayBuffer) {
 
     let byteBuffer = new ArrayBuffer(arrayBuffer.byteLength);
     new Uint8Array(byteBuffer).set(new Uint8Array(arrayBuffer));
     return dcodeIO.ByteBuffer.wrap(byteBuffer);
-};
+}
 ```
 
 ### Mapping incoming messages
@@ -379,12 +381,13 @@ function mapToDittoProtocolMsg(
         action,
         path,
         dittoHeaders,
-        value
+        value,
+        status
     );
 }
 ```
 
-The result of the function has to be an JavaScript object in [Ditto Protocol](protocol-overview.html) or an array of 
+The result of the function has to be a JavaScript object in [Ditto Protocol](protocol-overview.html) or an array of 
 such JavaScript objects. That's where the helper method `Ditto.buildDittoProtocolMsg` is useful: it explicitly 
 defines which parameters are required for the Ditto Protocol message.
 
@@ -405,6 +408,7 @@ can be mapped to external messages by implementing the following JavaScript func
  * @param {string} path - The path which is affected by the message, e.g.: "/attributes"
  * @param {Object.<string, string>} dittoHeaders - The headers Object containing all Ditto Protocol header values
  * @param {*} [value] - The value to apply / which was applied (e.g. in a "modify" action)
+ * @param {number} status - The status code that indicates the result of the command.
  * @returns {(ExternalMessage|Array<ExternalMessage>)} externalMessage -
  *  The mapped external message,
  *  an array of external messages or
@@ -419,7 +423,8 @@ function mapFromDittoProtocolMsg(
     action,
     path,
     dittoHeaders,
-    value
+    value,
+    status
 ) {
 
     // ###

services/connectivity/mapping/src/main/resources/javascript/ditto-scope.js

@@ -5,6 +5,7 @@
  * @property {string} path - The path containing the info what to change / what changed
  * @property {Object.<string, string>} headers - The Ditto headers
  * @property {*} value - The value to change to / changed value
+ * @property {number} status - The status code that indicates the result of the command.
  */
 
 /**
@@ -20,97 +21,99 @@
  * Defines the Ditto scope containing helper methods.
  */
 let Ditto = (function () {
-    /**
-     * Builds a Ditto Protocol message from the passed parameters.
-     * @param {string} namespace - The namespace of the entity in java package notation, e.g.: "org.eclipse.ditto"
-     * @param {string} id - The ID of the entity
-     * @param {string} group - The affected group/entity, one of: "things"
-     * @param {string} channel - The channel for the signal, one of: "twin"|"live"
-     * @param {string} criterion - The criterion to apply, one of: "commands"|"events"|"search"|"messages"|"errors"
-     * @param {string} action - The action to perform, one of: "create"|"retrieve"|"modify"|"delete"
-     * @param {string} path - The path which is affected by the message, e.g.: "/attributes"
-     * @param {Object.<string, string>} dittoHeaders - The headers Object containing all Ditto Protocol header values
-     * @param {*} [value] - The value to apply / which was applied (e.g. in a "modify" action)
-     * @returns {DittoProtocolMessage} dittoProtocolMessage(s) -
-     *  The mapped Ditto Protocol message or
-     *  <code>null</code> if the message could/should not be mapped
-     */
-    let buildDittoProtocolMsg = function(namespace, id, group, channel, criterion, action, path, dittoHeaders, value) {
+  /**
+   * Builds a Ditto Protocol message from the passed parameters.
+   * @param {string} namespace - The namespace of the entity in java package notation, e.g.: "org.eclipse.ditto"
+   * @param {string} id - The ID of the entity
+   * @param {string} group - The affected group/entity, one of: "things"
+   * @param {string} channel - The channel for the signal, one of: "twin"|"live"
+   * @param {string} criterion - The criterion to apply, one of: "commands"|"events"|"search"|"messages"|"errors"
+   * @param {string} action - The action to perform, one of: "create"|"retrieve"|"modify"|"delete"
+   * @param {string} path - The path which is affected by the message, e.g.: "/attributes"
+   * @param {Object.<string, string>} dittoHeaders - The headers Object containing all Ditto Protocol header values
+   * @param {*} [value] - The value to apply / which was applied (e.g. in a "modify" action)
+   * @param {number} status - The status code that indicates the result of the command.
+   * @returns {DittoProtocolMessage} dittoProtocolMessage(s) -
+   *  The mapped Ditto Protocol message or
+   *  <code>null</code> if the message could/should not be mapped
+   */
+  function buildDittoProtocolMsg(namespace, id, group, channel, criterion, action, path, dittoHeaders, value, status) {
 
-        let dittoProtocolMsg = {};
-        dittoProtocolMsg.topic = namespace + "/" + id + "/" + group + "/" + channel + "/" + criterion + "/" + action;
-        dittoProtocolMsg.path = path;
-        dittoProtocolMsg.headers = dittoHeaders;
-        dittoProtocolMsg.value = value;
-        return dittoProtocolMsg;
-    };
+    let dittoProtocolMsg = {};
+    dittoProtocolMsg.topic = namespace + "/" + id + "/" + group + "/" + channel + "/" + criterion + "/" + action;
+    dittoProtocolMsg.path = path;
+    dittoProtocolMsg.headers = dittoHeaders;
+    dittoProtocolMsg.value = value;
+    dittoProtocolMsg.status = status;
+    return dittoProtocolMsg;
+  }
 
-    /**
-     * Builds an external message from the passed parameters.
-     * @param {Object.<string, string>} headers - The external headers Object containing header values
-     * @param {string} [textPayload] - The external mapped String
-     * @param {ArrayBuffer} [bytePayload] - The external mapped bytes as ArrayBuffer
-     * @param {string} [contentType] - The returned Content-Type
-     * @returns {ExternalMessage} externalMessage -
-     *  The mapped external message or
-     *  <code>null</code> if the message could/should not be mapped
-     */
-    let buildExternalMsg = function(headers, textPayload, bytePayload, contentType) {
+  /**
+   * Builds an external message from the passed parameters.
+   * @param {Object.<string, string>} headers - The external headers Object containing header values
+   * @param {string} [textPayload] - The external mapped String
+   * @param {ArrayBuffer} [bytePayload] - The external mapped bytes as ArrayBuffer
+   * @param {string} [contentType] - The returned Content-Type
+   * @returns {ExternalMessage} externalMessage -
+   *  The mapped external message or
+   *  <code>null</code> if the message could/should not be mapped
+   */
+  function buildExternalMsg(headers, textPayload, bytePayload, contentType) {
 
-        let externalMsg = {};
-        externalMsg.headers = headers;
-        externalMsg.textPayload = textPayload;
-        externalMsg.bytePayload = bytePayload;
-        externalMsg.contentType = contentType;
-        return externalMsg;
-    };
+    let externalMsg = {};
+    externalMsg.headers = headers;
+    externalMsg.textPayload = textPayload;
+    externalMsg.bytePayload = bytePayload;
+    externalMsg.contentType = contentType;
+    return externalMsg;
+  }
 
-    /**
-     * Transforms the passed ArrayBuffer to a String interpreting the content of the passed arrayBuffer as unsigned 8
-     * bit integers.
-     *
-     * @param {ArrayBuffer} arrayBuffer the ArrayBuffer to transform to a String
-     * @returns {String} the transformed String
-     */
-    let arrayBufferToString = function(arrayBuffer) {
+  /**
+   * Transforms the passed ArrayBuffer to a String interpreting the content of the passed arrayBuffer as unsigned 8
+   * bit integers.
+   *
+   * @param {ArrayBuffer} arrayBuffer the ArrayBuffer to transform to a String
+   * @returns {String} the transformed String
+   */
+  function arrayBufferToString(arrayBuffer) {
 
-        return String.fromCharCode.apply(null, new Uint8Array(arrayBuffer));
-    };
+    return String.fromCharCode.apply(null, new Uint8Array(arrayBuffer));
+  }
 
-    /**
-     * Transforms the passed String to an ArrayBuffer using unsigned 8 bit integers.
-     *
-     * @param {String} string the String to transform to an ArrayBuffer
-     * @returns {ArrayBuffer} the transformed ArrayBuffer
-     */
-    let stringToArrayBuffer = function(string) {
+  /**
+   * Transforms the passed String to an ArrayBuffer using unsigned 8 bit integers.
+   *
+   * @param {String} string the String to transform to an ArrayBuffer
+   * @returns {ArrayBuffer} the transformed ArrayBuffer
+   */
+  function stringToArrayBuffer(string) {
 
-        let buf = new ArrayBuffer(string.length);
-        let bufView = new Uint8Array(buf);
-        for (let i=0, strLen=string.length; i<strLen; i++) {
-            bufView[i] = string.charCodeAt(i);
-        }
-        return buf;
-    };
+    let buf = new ArrayBuffer(string.length);
+    let bufView = new Uint8Array(buf);
+    for (let i = 0, strLen = string.length; i < strLen; i++) {
+      bufView[i] = string.charCodeAt(i);
+    }
+    return buf;
+  }
 
-    /**
-     * Transforms the passed ArrayBuffer to a {ByteBuffer} (from bytebuffer.js library which needs to be loaded).
-     *
-     * @param {ArrayBuffer} arrayBuffer the ArrayBuffer to transform
-     * @returns {ByteBuffer} the transformed ByteBuffer
-     */
-    let asByteBuffer = function(arrayBuffer) {
+  /**
+   * Transforms the passed ArrayBuffer to a {ByteBuffer} (from bytebuffer.js library which needs to be loaded).
+   *
+   * @param {ArrayBuffer} arrayBuffer the ArrayBuffer to transform
+   * @returns {ByteBuffer} the transformed ByteBuffer
+   */
+  function asByteBuffer(arrayBuffer) {
 
-        let byteBuffer = new ArrayBuffer(arrayBuffer.byteLength);
-        new Uint8Array(byteBuffer).set(new Uint8Array(arrayBuffer));
-        return dcodeIO.ByteBuffer.wrap(byteBuffer);
-    };
+    let byteBuffer = new ArrayBuffer(arrayBuffer.byteLength);
+    new Uint8Array(byteBuffer).set(new Uint8Array(arrayBuffer));
+    return dcodeIO.ByteBuffer.wrap(byteBuffer);
+  }
 
-    return {
-        buildDittoProtocolMsg: buildDittoProtocolMsg,
-        buildExternalMsg: buildExternalMsg,
-        arrayBufferToString: arrayBufferToString,
-        stringToArrayBuffer: stringToArrayBuffer,
-        asByteBuffer: asByteBuffer
-    }
+  return {
+    buildDittoProtocolMsg: buildDittoProtocolMsg,
+    buildExternalMsg: buildExternalMsg,
+    arrayBufferToString: arrayBufferToString,
+    stringToArrayBuffer: stringToArrayBuffer,
+    asByteBuffer: asByteBuffer
+  }
 })();

services/connectivity/mapping/src/main/resources/javascript/incoming-mapping.js

@@ -10,36 +10,37 @@
  *  <code>null</code> if the message could/should not be mapped
  */
 function mapToDittoProtocolMsg(
-    headers,
-    textPayload,
-    bytePayload,
-    contentType
+  headers,
+  textPayload,
+  bytePayload,
+  contentType
 ) {
 
-    // ###
-    // Insert your mapping logic here:
-    if (contentType === 'application/vnd.eclipse.ditto+json') {
-        let dittoProtocolMsg = JSON.parse(textPayload);
-        Object.assign(dittoProtocolMsg.headers, headers);
-        return dittoProtocolMsg;
-    }
-    if (headers) {
-        return null; // returning 'null' means that the message will be dropped
-        // TODO replace with something useful
-    }
-    // ###
+  // ###
+  // Insert your mapping logic here:
+  if (contentType === 'application/vnd.eclipse.ditto+json') {
+    let dittoProtocolMsg = JSON.parse(textPayload);
+    Object.assign(dittoProtocolMsg.headers, headers);
+    return dittoProtocolMsg;
+  }
+  if (headers) {
+    return null; // returning 'null' means that the message will be dropped
+    // TODO replace with something useful
+  }
+  // ###
 
-    return Ditto.buildDittoProtocolMsg(
-        namespace,
-        id,
-        group,
-        channel,
-        criterion,
-        action,
-        path,
-        dittoHeaders,
-        value
-    );
+  return Ditto.buildDittoProtocolMsg(
+    namespace,
+    id,
+    group,
+    channel,
+    criterion,
+    action,
+    path,
+    dittoHeaders,
+    value,
+    status
+  );
 }
 
 /**
@@ -52,10 +53,10 @@ function mapToDittoProtocolMsg(
  */
 function mapToDittoProtocolMsgWrapper(externalMsg) {
 
-    let headers = externalMsg.headers;
-    let textPayload = externalMsg.textPayload;
-    let bytePayload = externalMsg.bytePayload;
-    let contentType = externalMsg.contentType;
+  let headers = externalMsg.headers;
+  let textPayload = externalMsg.textPayload;
+  let bytePayload = externalMsg.bytePayload;
+  let contentType = externalMsg.contentType;
 
-    return mapToDittoProtocolMsg(headers, textPayload, bytePayload, contentType);
+  return mapToDittoProtocolMsg(headers, textPayload, bytePayload, contentType);
 }