Issue #611: Added protocol specification for acknowledgments. Extende…

…d the TopicPath.Criterion enum accordingly.

Signed-off-by: Juergen Fickel <juergen.fickel@bosch-si.com>

documentation/src/main/resources/jsonschema/protocol-ack.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "description": "The Ditto Protocol ACK/NACK is sent in response to an event.",
+  "title": "Ditto Protocol acknowledgement",
+  "properties": {
+    "topic": {
+      "type": "string",
+      "description": "Contains the same topic as the commands which this response correlates to."
+    },
+    "headers": {
+      "type": "object",
+      "description": "Additional headers.",
+      "properties": {
+        "correlation-id": {
+          "type": "string",
+          "description": "The correlation-id header is used for linking one message with another. It typically links a reply message with its requesting message."
+        },
+        "version": {
+          "type": "integer",
+          "description": "Determines the version of the *Things* payload.",
+          "minimum": 1,
+          "maximum": 2
+        }
+      },
+      "required": [ "correlation-id" ]
+    },
+    "path": {
+      "type": "string",
+      "description": "A Path that references a part of a Thing which is affected by this ACK.\nExamples:\n * `/feature/location/properties/longitude` (a single sensor value)\n * `/` (the whole Thing)"
+    },
+    "value": {
+      "type": ["object","string","number","array","boolean"],
+      "description": "The _value_ field contains the optional payload of the ACK."
+    },
+    "status": {
+      "type": "integer",
+      "description": "The status code that indicates the result of the ACK. The semantics of the used status codes are based on the [HTTP status codes](https://tools.ietf.org/html/rfc7231#section-6)."
+    }
+  },
+  "required": [ "topic", "headers", "path", "status" ]
+}

documentation/src/main/resources/pages/ditto/protocol-examples.md

@@ -57,3 +57,22 @@ If Ditto triggers an event (e.g. Thing created, Attribute modified) as a result
   "revision": 1
 }
 ```
+
+### ACK (Acknowledgement)
+A command issuer can require a response and specify the acknowledgements (ACKs) which have to be successfully fulfilled
+to regard the command as successfully executed.
+Below an example is given for a successfully fulfilled ACK (status 200).
+
+```json
+{
+  "topic": "com.acme/thing_name_3141/things/twin/acks/custom-ack",
+  "headers": {
+    "correlation-id": "a780b7b5-fdd2-4864-91fc-80df6bb0a636"
+  },
+  "path": "/",
+  "value": {
+    ...
+  },
+  "status": 200
+}
+```

documentation/src/main/resources/pages/ditto/protocol-specification-topic.md

@@ -128,3 +128,9 @@ An entity (e.g. a Thing) or an aspect of an entity was
 
 For the *messages* criterion the *action* segment specifies the message subject and can be freely chosen by the sender 
 provided that it conforms to [RFC-3986](https://tools.ietf.org/html/rfc3986) (URI).
+
+### ACK/NACK criterion actions
+For *acks* criterion the *action* segment specifies the identifier which is defined by the system which issued the ACK.
+The criterion has to match the regular expression `[a-zA-Z0-9-_]{3,64}`, i. e. letters of the latin alphabet, numbers,
+dashes and underscores.
+

documentation/src/main/resources/pages/ditto/protocol-specification.md

@@ -107,3 +107,11 @@ Some Protocol messages (for example **responses**) contain a HTTP status code wh
 
 When [signal enrichment](basic-enrichment.html) was used in order to ask for `extraFields` to be included, the
 Ditto Protocol message contains a field `extra` containing a JSON object with the selected extra fields.
+
+## ACK
+Requests can specify a number of acknowledgements (ACKs) which have to be successfully fulfilled to regard the request
+(command) as successfully executed.
+
+An ACK is formatted as JSON object (`content-type=application/json`) and must correspond to the following JSON schema:
+
+{% include docson.html schema="jsonschema/protocol-ack.json" %}

protocol-adapter/src/main/java/org/eclipse/ditto/protocoladapter/TopicPath.java

@@ -181,7 +181,14 @@ enum Criterion {
 
         MESSAGES("messages"),
 
-        ERRORS("errors");
+        ERRORS("errors"),
+
+        /**
+         * Criterion for the topic path of a n acknowledgement (ACK).
+         *
+         * @since 1.1.0
+         */
+        ACKS("acks");
 
         private final String name;