Merge pull request #539 from bsinno/feature/connection-status

Extend connectivity payload mapping capabilities

Author: dguggemos

documentation/src/main/resources/_data/sidebars/ditto_sidebar.yml

@@ -35,6 +35,9 @@ entries:
       - title: Milestone releases
         output: web
         subfolderitems:
+        - title: 1.0.0-M2
+          url: /release_notes_100-M2.html
+          output: web
         - title: 1.0.0-M1a
           url: /release_notes_100-M1a.html
           output: web

documentation/src/main/resources/_posts/2019-11-04-milestone-announcement-100-M2.md

@@ -0,0 +1,42 @@
+---
+title: "Announcing Ditto Milestone 1.0.0-M2"
+published: true
+permalink: 2019-11-04-milestone-announcement-100-M2.html
+layout: post
+author: thomas_jaeckle
+tags: [blog]
+hide_sidebar: true
+sidebar: false
+toc: false
+---
+
+The second and last milestone of the upcoming release 
+[1.0.0](https://projects.eclipse.org/projects/iot.ditto/releases/1.0.0) was released today.
+
+Have a look at the Milestone [1.0.0-M2 release notes](release_notes_100-M2.html) for what changed in detail.
+
+The main changes and new features since the last release [1.0.0-M1a release notes](release_notes_100-M1a.html) are
+
+* invoking custom foreign HTTP endpoints as a result of events/messages
+* ability to reflect Eclipse Hono's device connection state in Ditto's things
+* support for OpenID Connect / OAuth2.0 based authentication in Ditto Java Client
+* configurbale throttling of max. consumed WebSocket commands / time interval
+
+## Artifacts
+
+The new Java artifacts have been published at the [Eclipse Maven repository](https://repo.eclipse.org/content/repositories/ditto/)
+as well as [Maven central](https://repo1.maven.org/maven2/org/eclipse/ditto/).
+
+The Docker images have been pushed to Docker Hub:
+* [eclipse/ditto-policies](https://hub.docker.com/r/eclipse/ditto-policies/)
+* [eclipse/ditto-things](https://hub.docker.com/r/eclipse/ditto-things/)
+* [eclipse/ditto-things-search](https://hub.docker.com/r/eclipse/ditto-things-search/)
+* [eclipse/ditto-gateway](https://hub.docker.com/r/eclipse/ditto-gateway/)
+* [eclipse/ditto-connectivity](https://hub.docker.com/r/eclipse/ditto-connectivity/)
+* [eclipse/ditto-concierge](https://hub.docker.com/r/eclipse/ditto-concierge/)
+
+<br/>
+<br/>
+{% include image.html file="ditto.svg" alt="Ditto" max-width=500 %}
+--<br/>
+The Eclipse Ditto team

documentation/src/main/resources/jsonschema/connection.json

@@ -179,15 +179,22 @@
             "title": "Header mapping configuration",
             "description": "Headers to map for each incoming message (after the optional payload transformation) from the source's protocol headers to internal DittoHeaders.",
             "additionalProperties": false,
-            "patternProperties":
-            {
-              "^.+$":
-              {
+            "patternProperties": {
+              "^.+$": {
                 "title": "header value",
                 "description": "The key is the internal DittoHeader key to set, the value can make use of placeholders in order to access external header values via `{{ header:[any-header-name] }}`, the Thing ID via `{{ thing:id }}` or to access the DittoProtocol topic via `{{ topic:[topic-placeholder-attr] }}`.",
                 "type": "string"
               }
             }
+          },
+          "payloadMapping": {
+            "$id": "/properties/sources/items/properties/payloadMapping",
+            "type": "array",
+            "description": "References the IDs of payload mappers defined in the payload mapping definitions that are applied to messages received via this source.",
+            "items": {
+              "title": "Payload definition reference",
+              "type": "string"
+            }
           }
         }
       }
@@ -255,15 +262,22 @@
             "title": "Header mapping configuration",
             "description": "Headers to map for each outgoing message (after the optional payload transformation) from the internal DittoHeaders to the targets's protocol headers.",
             "additionalProperties": false,
-            "patternProperties":
-            {
-              "^.+$":
-              {
+            "patternProperties": {
+              "^.+$": {
                 "title": "header value",
                 "description": "The key is the external header key to set, the value can make use of placeholder in order to access DittoHeader values via `{{ header:[any-header-name] }}`, the Thing ID via `{{ thing:id }}` or to access the DittoProtocol topic via `{{ topic:[topic-placeholder-attr] }}`.",
                 "type": "string"
               }
             }
+          },
+          "payloadMapping": {
+            "$id": "/properties/targets/items/properties/payloadMapping",
+            "type": "array",
+            "description": "References the IDs of payload mappers defined in the payload mapping definitions that are applied to messages received via this target.",
+            "items": {
+              "title": "Payload definition reference",
+              "type": "string"
+            }
           }
         }
       }
@@ -311,45 +325,45 @@
       "title": "Specific config",
       "description": "Depending on the configured connection type, there might be protocol specific configuration options or tuning settings available. These can be configured in the specific config object. The specific config object is interpreted as a key value based map of setting properties.",
       "additionalProperties": false,
-      "patternProperties":
-      {
-        "^.+$":
-        {
+      "patternProperties": {
+        "^.+$": {
           "title": "Setting value",
           "description": "Setting value",
           "type": "string"
         }
       }
     },
-    "mappingContext": {
-      "$id": "/properties/mappingContext",
+    "mappingDefinitions": {
+      "$id": "/properties/mappingDefinitions",
       "type": "object",
-      "title": "The mapping context for this connection",
-      "properties": {
-        "mappingEngine": {
-          "$id": "/properties/mappingContext/properties/mappingEngine",
-          "type": "string",
-          "title": "Mapping engine",
-          "description": "The Mapping engine defines which kind of mapping processor is instantiated for this connection. Currently you can choose between \"javascript\" and a full qualified java class name implementing the MessageMapper interface. If you go for the second option, make sure the implementation class is available in CLASSPATH."
-        },
-        "options": {
-          "$id": "/properties/mappingContext/properties/options",
-          "type": "object",
-          "title": "Options",
-          "description": "The mapping options contain specific configuration settings for the selected mapping engine. The options object is interpreted as a key value based map of setting properties.",
-          "additionalProperties": false,
-          "patternProperties":
-          {
-            "^.+$":
-            {
-              "title": "Setting value",
-              "description": "Setting value",
-              "type": "string"
+      "additionalProperties": {
+        "type": "object",
+        "description": "The payload mapping definitions.",
+        "properties": {
+          "mappingEngine": {
+            "$id": "/properties/mappingDefinitions/properties/mappingEngine",
+            "type": "string",
+            "title": "Mapping engine",
+            "description": "The Mapping engine defines which kind of mapping processor is instantiated for this connection. Currently you can choose between `Ditto`, `JavaScript`, `Normalized` and `ConnectionStatus`. The payload mapper documentation provides a detailed description of available mappers or how to bring your own mapper."
+          },
+          "options": {
+            "$id": "/properties/mappingDefinitions/properties/options",
+            "type": "object",
+            "title": "Options",
+            "description": "The mapping options contain specific configuration settings for the selected mapping engine. The options object is interpreted as a key value based map of setting properties.",
+            "additionalProperties": false,
+            "patternProperties": {
+              "^.+$": {
+                "title": "Setting value",
+                "description": "Setting value",
+                "type": "string"
+              }
             }
           }
-        }
-      },
-      "required": [ "mappingEngine", "options"]
+        },
+        "additionalProperties": false,
+        "required": [ "mappingEngine" ]
+      }
     }
   },
   "additionalProperties": false,

documentation/src/main/resources/pages/ditto/basic-connections.md

@@ -219,9 +219,9 @@ A connection source can only receive data for Things to which it has WRITE right
 Some [connection types](#connection-types) require specific configuration which are not supported for other connection types.
 Those are put into the `specificConfig` field.
 
-### Mapping context
+### Payload Mapping
 
-For more information on the `mappingContext` see the corresponding [Payload Mapping Documentation](connectivity-mapping.html).
+For more information on mapping message payloads see the corresponding [Payload Mapping Documentation](connectivity-mapping.html).
 
 ## Placeholders
 

documentation/src/main/resources/pages/ditto/basic-feature.md

@@ -56,16 +56,18 @@ The following snippet shows a Feature with the ID "arbitrary-feature" and a defi
 
 ```json
 {
-    "arbitrary-feature": {
-        "definition": [ "org.eclipse.ditto:complex-type:1.0.0" ],
-        "properties": {
-            "connected": true,
-            "complexProperty": {
-                "street": "my street",
-                "house no": 42
-            }
+  "arbitrary-feature": {
+    "definition": [ "org.eclipse.ditto:complex-type:1.0.0" ],
+    "properties": {
+      "status": {
+        "connected": true,
+        "complexProperty": {
+          "street": "my street",
+          "house no": 42
         }
+      }
     }
+  }
 }
 ```
 

documentation/src/main/resources/pages/ditto/connectivity-manage-connections.md

@@ -299,16 +299,36 @@ Clears all currently stored connection logs.
 
 ## Payload mapping configuration
 
-To enable a custom [payload mapping](connectivity-mapping.html) for a specific connection, you have to configure a
-mapping context in the connection configuration object. The following snippet shows an example `mappingContext`. This
-configuration must be embedded in the connection configuration as shown in the [Connections](basic-connections.html) section.
+To enable a custom [payload mapping](connectivity-mapping.html) for a specific source or target of a connection, you 
+have to configure a payload mapping definition in the connection configuration object. The following snippet shows an 
+example `mappingDefinitions`. This configuration must be embedded in the connection configuration as shown in the 
+[Connections](basic-connections.html) section. These payload mapping definitions are then referenced by its ID 
+(the key of the JSON object) in the sources and targets of the connection using the field `payloadMapping`. 
+If no payload mapping or definition is provided, the [Ditto message mapping](connectivity-mapping.html#ditto-mapper) 
+is used as the default.  
 
 ```json
-"mappingContext": {
-    "mappingEngine": "JavaScript",
-    "options": {
-      "incomingScript": "..",
-      "outgoingScript": ".."
+{
+  ...
+  "mappingDefinitions": {
+    "customJs": {                     // (1)
+      "mappingEngine": "JavaScript",  // (2)
+      "options": {                    // (3)
+        "incomingScript": "..",
+        "outgoingScript": ".."
+      }
+    }
+  },
+  "sources": [
+    {
+      "addresses": "source",
+      "payloadMapping": ["customJs"]  
     }
-  }
+  ]
+  ...
+}
 ```
+
+- (1) This ID can be used in sources and targets of the connection to reference this payload mapping definition.
+- (2) The `mappingEngine` defines the underlying `MessageMapper` implementation.
+- (3) The `options` are used to configure the mapper instance to your needs.