[eclipse-ditto#964] added documentation about announcements in genera…

…l and the specifically added "subjectDeletion" announcement

Signed-off-by: Thomas Jaeckle <thomas.jaeckle@bosch.io>

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

@@ -24,7 +24,7 @@ entries:
         output: web
         folderitems:
           - title: 2.0.0
-            url: /release_notes_200.html
+            url: /release_notes_next.html
             output: web
           - title: 1.5.1
             url: /release_notes_151.html
@@ -184,6 +184,9 @@ entries:
                   - title: Event
                     url: /basic-signals-event.html
                     output: web
+                  - title: Announcement
+                    url: /basic-signals-announcement.html
+                    output: web
 
           - title: APIs
             url: /basic-apis.html
@@ -395,6 +398,9 @@ entries:
                   - title: Delete
                     url: /protocol-specification-policies-delete.html
                     output: web
+                  - title: Announcement
+                    url: /protocol-specification-policies-announcement.html
+                    output: web
 
           - title: Bindings
             url: /protocol-bindings.html

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

@@ -0,0 +1,25 @@
+{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "description": "An Ditto Protocol announcement announces an event before it actually happens.",
+  "title": "Ditto Protocol announcement",
+  "properties": {
+    "topic": {
+      "type": "string",
+      "description": "Contains the topic of the announcement, ending with the announcement name."
+    },
+    "headers": {
+      "type": "object",
+      "description": "Additional headers."
+    },
+    "path": {
+      "type": "string",
+      "description": "The path is always the empty path `/` for an announcement."
+    },
+    "value": {
+      "type": ["object","string","number","array","boolean"],
+      "description": "The _value_ field contains the optional payload of the announcement."
+    }
+  },
+  "required": [ "topic", "headers", "path" ]
+}

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

@@ -265,9 +265,10 @@ This is an example `"replyTarget"` containing both header mapping and expected r
 Targets are used to connect to messages brokers / external systems in order to publish messages **to them**.
 
 Target messages can be of the following type:
-* [messages](basic-messages.html)
-* [events](basic-signals-event.html)
-* [live commands/responses/events](protocol-twinlive.html)
+* [Thing messages](basic-messages.html)
+* [Thing events](basic-signals-event.html)
+* [Thing live commands/responses/events](protocol-twinlive.html)
+* [Policy announcements](protocol-specification-policies-announcement.html)
 
 Targets contain:
 * one address (that is interpreted differently depending on the [connection type](#connection-types), e.g. as queue, topic, etc.),
@@ -285,10 +286,11 @@ following parameters can additionally be provided when specifying the `topics` o
 
 | Description | Topic | [Filter by namespaces](basic-changenotifications.html#by-namespaces) | [Filter by RQL expression](basic-changenotifications.html#by-rql-expression) |
 |-------------|-----------------|------------------|-----------|
-| Subscribe for [events/change notifications](basic-changenotifications.html) | `_/_/things/twin/events` | ✔ | ✔ |
-| Subscribe for [messages](basic-messages.html) | `_/_/things/live/messages` | ✔ | ❌ |
-| Subscribe for [live commands](protocol-twinlive.html) | `_/_/things/live/commands` | ✔ | ❌ |
-| Subscribe for [live events](protocol-twinlive.html) | `_/_/things/live/events` | ✔ | ✔ |
+| Subscribe for [Thing events/change notifications](basic-changenotifications.html) | `_/_/things/twin/events` | ✔ | ✔ |
+| Subscribe for [Thing messages](basic-messages.html) | `_/_/things/live/messages` | ✔ | ❌ |
+| Subscribe for [Thing live commands](protocol-twinlive.html) | `_/_/things/live/commands` | ✔ | ❌ |
+| Subscribe for [Thing live events](protocol-twinlive.html) | `_/_/things/live/events` | ✔ | ✔ |
+| Subscribe for [Policy announcements](protocol-specification-policies-announcement.html) | `_/_/policies/announcements` | ✔ | ❌ |
 
 The parameters are specified similar to HTTP query parameters, the first one separated with a `?` and all following ones
 with `&`. You need to URL-encode the filter values before using them in a configuration.
@@ -315,10 +317,11 @@ to the topic. This is supported for all topics:
 
 | Description | Topic | [Enrich by extra fields](basic-enrichment.html) |
 |-------------|-----------------|------------------|
-| Subscribe for [events/change notifications](basic-changenotifications.html) | `_/_/things/twin/events` | ✔ |
-| Subscribe for [messages](basic-messages.html) | `_/_/things/live/messages` | ✔ |
-| Subscribe for [live commands](protocol-twinlive.html) | `_/_/things/live/commands` | ✔ |
-| Subscribe for [live events](protocol-twinlive.html) | `_/_/things/live/events` | ✔ |
+| Subscribe for [Thing events/change notifications](basic-changenotifications.html) | `_/_/things/twin/events` | ✔ |
+| Subscribe for [Thing messages](basic-messages.html) | `_/_/things/live/messages` | ✔ |
+| Subscribe for [Thing live commands](protocol-twinlive.html) | `_/_/things/live/commands` | ✔ |
+| Subscribe for [Thing live events](protocol-twinlive.html) | `_/_/things/live/events` | ✔ |
+| Subscribe for [Policy announcements](protocol-specification-policies-announcement.html) | `_/_/policies/announcements` | ❌ |
 
 Example:
 ```json

documentation/src/main/resources/pages/ditto/basic-signals-announcement.md

@@ -0,0 +1,15 @@
+---
+title: Announcement
+keywords: announcement, signal
+tags: [signal]
+permalink: basic-signals-announcement.html
+---
+
+Announcements are special signals which are published in order to announce something before it actually happens.  
+For example, before an [event](basic-signals-event.html) is created and published, an announcement could signal that
+the event will happen soon.
+
+Announcements have the following characteristics:
+* they are **not** persisted/appended into any data store
+* they are published to interested and authorized parties via the [WebSocket API](httpapi-protocol-bindings-websocket.html) as
+  well as [connection targets](basic-connections.html#targets) via [change notifications](basic-changenotifications.html).

documentation/src/main/resources/pages/ditto/basic-signals-event.md

@@ -13,4 +13,5 @@ Events are one of the centerpieces of Ditto:
 * they are published in the Ditto cluster, so other Ditto back end services can react on them (e.g. in order to update
   the search index) and
 * they are published to interested and authorized parties via the [WebSocket API](httpapi-protocol-bindings-websocket.html) as
-  well as via [HTTP Server Sent Events](httpapi-sse.html) as [change notifications](basic-changenotifications.html).
+  well as via [HTTP Server Sent Events](httpapi-sse.html) as well as [connection targets](basic-connections.html#targets) 
+  via [change notifications](basic-changenotifications.html).

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

@@ -8,8 +8,9 @@ permalink: basic-signals.html
 Ditto has a concept called `Signal` which combines common functionality of
 * [Commands](basic-signals-command.html),
 * [Command Responses](basic-signals-commandresponse.html),
-* [Error Responses](basic-signals-errorresponse.html) and
-* [Events](basic-signals-event.html).
+* [Error Responses](basic-signals-errorresponse.html),
+* [Events](basic-signals-event.html) and
+* [Announcements](basic-signals-announcement.html).
 
 Such common functionality is for example that all those have header fields in which they can be for example correlated
 to each other. 
@@ -52,6 +53,7 @@ other parts of the system.
    Interested parties can subscribe for such **events** and follow the evolving entity.
 
 {% include note.html
-   content="Events caused by commands from a **[connection](basic-connections.html)** are not published
+   content="Events caused by commands from a **[connection](basic-connections.html)** or a 
+            [websocket session](httpapi-protocol-bindings-websocket.html) are not published
             **to the same origin**. The connection can receive a response, but will not additionally get an event."
 %}

documentation/src/main/resources/pages/ditto/httpapi-protocol-bindings-websocket.md

@@ -149,21 +149,32 @@ WebSocket session, the following text message has to be sent to the backend: `ST
 
 From then on the WebSocket session will receive all live events it is entitled to see.
 
+### Request policy announcements
+
+In order to subscribe for [Policy announcements](protocol-specification-policies-announcement.html) which can be 
+published to a WebSocket session, the following text message has to be sent to the backend: 
+`START-SEND-POLICY-ANNOUNCEMENTS`
+
+From then on the WebSocket session will receive all announcements related to policies related to the authenticated 
+subjects of the websocket session.
+
 ### Overview
 
 The following table shows which WebSocket protocol message are supported:
 
 | Description | Request message | Response message |
 |-------------|-----------------|------------------|
 | Refresh JWT based authentication |  `JWT-TOKEN` | `-` |
-| Subscribe for [events/change notifications](basic-changenotifications.html) | `START-SEND-EVENTS` | `START-SEND-EVENTS:ACK` |
-| Stop receiving change notifications | `STOP-SEND-EVENTS` | `STOP-SEND-EVENTS:ACK` |
-| Subscribe for [messages](basic-messages.html) | `START-SEND-MESSAGES` | `START-SEND-MESSAGES:ACK` |
-| Stop receiving messages | `STOP-SEND-MESSAGES` | `STOP-SEND-MESSAGES:ACK` |
-| Subscribe for [live commands](protocol-twinlive.html) | `START-SEND-LIVE-COMMANDS` | `START-SEND-LIVE-COMMANDS:ACK` |
-| Stop receiving live commands | `STOP-SEND-LIVE-COMMANDS` | `STOP-SEND-LIVE-COMMANDS:ACK` |
-| Subscribe for [live events](protocol-twinlive.html) | `START-SEND-LIVE-EVENTS` | `START-SEND-LIVE-EVENTS:ACK` |
-| Stop receiving live commands | `STOP-SEND-LIVE-EVENTS` | `STOP-SEND-LIVE-EVENTS:ACK` |
+| Subscribe for [Thing events/change notifications](basic-changenotifications.html) | `START-SEND-EVENTS` | `START-SEND-EVENTS:ACK` |
+| Stop receiving Thing change notifications | `STOP-SEND-EVENTS` | `STOP-SEND-EVENTS:ACK` |
+| Subscribe for [Thing messages](basic-messages.html) | `START-SEND-MESSAGES` | `START-SEND-MESSAGES:ACK` |
+| Stop receiving Thing messages | `STOP-SEND-MESSAGES` | `STOP-SEND-MESSAGES:ACK` |
+| Subscribe for [Thing live commands](protocol-twinlive.html) | `START-SEND-LIVE-COMMANDS` | `START-SEND-LIVE-COMMANDS:ACK` |
+| Stop receiving Thing live commands | `STOP-SEND-LIVE-COMMANDS` | `STOP-SEND-LIVE-COMMANDS:ACK` |
+| Subscribe for [Thing live events](protocol-twinlive.html) | `START-SEND-LIVE-EVENTS` | `START-SEND-LIVE-EVENTS:ACK` |
+| Stop receiving Thing live commands | `STOP-SEND-LIVE-EVENTS` | `STOP-SEND-LIVE-EVENTS:ACK` |
+| Subscribe for [Policy announcements](protocol-specification-policies-announcement.html) | `START-SEND-POLICY-ANNOUNCEMENTS` | `START-SEND-POLICY-ANNOUNCEMENTS:ACK` |
+| Stop receiving Policy announcements | `STOP-SEND-POLICY-ANNOUNCEMENTS` | `STOP-SEND-POLICY-ANNOUNCEMENTS:ACK` |
 
 ### Authentication
 
@@ -183,10 +194,11 @@ to the request message. This is supported for all request messages:
 
 | Description | Request message | [Enrich by extra fields](basic-enrichment.html) |
 |-------------|-----------------|------------------|
-| Subscribe for [events/change notifications](basic-changenotifications.html) | `START-SEND-EVENTS` | ✔ |
-| Subscribe for [messages](basic-messages.html) | `START-SEND-MESSAGES` | ✔ |
-| Subscribe for [live commands](protocol-twinlive.html) | `START-SEND-LIVE-COMMANDS` | ✔ |
-| Subscribe for [live events](protocol-twinlive.html) | `START-SEND-LIVE-EVENTS` | ✔ |
+| Subscribe for [Thing events/change notifications](basic-changenotifications.html) | `START-SEND-EVENTS` | ✔ |
+| Subscribe for [Thing messages](basic-messages.html) | `START-SEND-MESSAGES` | ✔ |
+| Subscribe for [Thing live commands](protocol-twinlive.html) | `START-SEND-LIVE-COMMANDS` | ✔ |
+| Subscribe for [Thing live events](protocol-twinlive.html) | `START-SEND-LIVE-EVENTS` | ✔ |
+| Subscribe for [Policy announcements](protocol-specification-policies-announcement.html) | `START-SEND-POLICY-ANNOUNCEMENTS` | ❌ |
 
 Analog to the [filtering](#filtering) the parameter is defined like an HTTP query parameter, e.g.:
 ```
@@ -201,10 +213,11 @@ following parameters can additionally be provided when sending the WebSocket pro
 
 | Description | Request message | [Filter by namespaces](basic-changenotifications.html#by-namespaces) | [Filter by RQL expression](basic-changenotifications.html#by-rql-expression) |
 |-------------|-----------------|------------------|-----------|
-| Subscribe for [events/change notifications](basic-changenotifications.html) | `START-SEND-EVENTS` | ✔ | ✔ |
-| Subscribe for [messages](basic-messages.html) | `START-SEND-MESSAGES` | ✔ | ❌ |
-| Subscribe for [live commands](protocol-twinlive.html) | `START-SEND-LIVE-COMMANDS` | ✔ | ❌ |
-| Subscribe for [live events](protocol-twinlive.html) | `START-SEND-LIVE-EVENTS` | ✔ | ✔ |
+| Subscribe for [Thing events/change notifications](basic-changenotifications.html) | `START-SEND-EVENTS` | ✔ | ✔ |
+| Subscribe for [Thing messages](basic-messages.html) | `START-SEND-MESSAGES` | ✔ | ❌ |
+| Subscribe for [Thing live commands](protocol-twinlive.html) | `START-SEND-LIVE-COMMANDS` | ✔ | ❌ |
+| Subscribe for [Thing live events](protocol-twinlive.html) | `START-SEND-LIVE-EVENTS` | ✔ | ✔ |
+| Subscribe for [Policy announcements](protocol-specification-policies-announcement.html) | `START-SEND-POLICY-ANNOUNCEMENTS` | ✔ | ❌ |
 
 The parameters are specified similar to HTTP query parameters, the first one separated with a `?` and all following ones
 with `&`.  You have to URL encode the filter values before using them in a configuration.

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

@@ -20,4 +20,4 @@ is composed of multiple correlated Protocol messages.
 Therefore, each Protocol message contains a `correlation-id` which can be used to associate related Protocol messages.
 
 The [Signals](basic-signals.html#communication-pattern) chapter already describes the basic communication pattern of
-**commands**, **responses** and **events**.
+**commands**, **responses**, **events** and **announcements**.

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

@@ -0,0 +1,34 @@
+---
+title: Policies - Announcement protocol specification
+keywords: protocol, specification, announcement, policy
+tags: [protocol]
+permalink: protocol-specification-policies-announcement.html
+---
+
+{% include note.html content="The *topic path* of policy commands contains no *channel* element. 
+See the [specification](protocol-specification-policies.html#ditto-protocol-topic-structure-for-policies) for details. " %}
+
+## Policy announcements
+
+A Policy announcement contains the announcement name as last part of the topic:
+```
+<namespace>/<policyName>/policies/announcements/<announcement-name>
+```
+
+The Ditto Protocol representation of an `Announcement` is specified as follows:
+
+{% include docson.html schema="jsonschema/protocol-announcement.json" %}
+
+The following Policy announcements are currently supported:
+
+### SubjectDeletionAnnouncement
+
+Announcement indicating that some subjects of a policy are deleted or about to be deleted soon.
+
+| Field     | Value                   |
+|-----------|-------------------------|
+| **topic** | `<namespace>/<policyName>/policies/announcements/subjectDeletion` |
+| **path**  | `/`     |
+| **value** |  `JsonObject` containing<br/>* `deletedAt` timestamp (as ISO-8601 `string`)<br/>* `subjectIds` of policy [subjects](basic-policy.html#subjects) which will soon be deleted (`JsonArray` of subjects `string`s)|
+
+

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

@@ -17,11 +17,14 @@ A valid topic consists of five elements, describing the policy affected by this
 1. `namespace`: the namespace of the Policy.
 2. `policyName`: the name of the Policy.
 3. `group`: the group for addressing Policies is `policies`.
-4. `criterion`: the type of Protocol message addressing Policies is `commands`.
-5. `action`: the action executed on the Policy:
+4. `criterion`: the type of Protocol messages addressing Policies is `commands`, 
+    for [announcements](basic-signals-announcement.html) it is 
+   [`announcements`](protocol-specification-policies-announcement.html).
+5. `action`: the action executed on the Policy via `commands` criterion:
        [`create/modify`](protocol-specification-policies-create-or-modify.html),
        [`retrieve`](protocol-specification-policies-retrieve.html) or
        [`delete`](protocol-specification-policies-delete.html).
+6. `subject`: for [announcements](basic-signals-announcement.html) the `subject` contains the announcement name
 
 {% include note.html content="The topic path of the *policies* group does not contain a channel unlike the *things* group." %}
 

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

@@ -17,6 +17,7 @@ Examples for valid topic paths are:
 * `org.eclipse.ditto/fancy-car-42/things/live/messages/hello.world`
 * `org.eclipse.ditto/fancy-policy-1/policies/commands/create`
 * `org.eclipse.ditto/fancy-policy-1/policies/commands/delete`
+* `org.eclipse.ditto/fancy-policy-1/policies/announcements/subjectDeletion`
 
 ## Namespace
 
@@ -83,7 +84,7 @@ the defined `{channel}`.
 
 ### Commands criterion
 
-*commands* are sent to Ditto in order to do something, either on the digital twin or on a real connected device.
+*commands* are sent to Ditto in order to do something, either on the digital twin or on a real connected device.  
 They are separated in ModifyCommands for creating, modifying, deleting and QueryCommands for retrieving.
 
 For each command Ditto processed a command response is created.
@@ -93,19 +94,19 @@ Command responses have the same topic path as the commands which they answer to.
 
 ### Events criterion
 
-*events* are emitted by Ditto for each command which successfully *modified* an entity.
+*events* are emitted by Ditto for each command which successfully *modified* an entity.  
 Each ModifyCommand causes a specific Event type to be published for which interested parties can subscribe themselves.
 
 ### Search criterion
 
-*search* requests can only be put on the *twin channel*.
+*search* requests can only be put on the *twin channel*.  
 They contain a query string defining on which data to search in the population of all **digital twins**.
 Ditto respects the [authorization](basic-auth.html) information while searching for the requested data and returns the
 search result as paged list of search hits.
 
 ### Messages criterion
 
-*messages* are always exchanged via the *live channel*.
+*messages* are always exchanged via the *live channel*.  
 They carry a custom payload and can be answered by another, correlated message.
 
 ### Errors criterion
@@ -119,12 +120,17 @@ They contain a *status integer* which reflects an HTTP status code with the same
 have to be successfully fulfilled to regard the command as successfully executed.
 
 *acks* can be returned in response to [events](#events-criterion) which have defined in their `headers`, that specific 
-acknowledgement labels were required by the issuing command.<br/>
+acknowledgement labels were required by the issuing command.  
 Acks contain a *status integer* which reflects a status code with the same semantics as in HTTP, reflecting whether the
-ack was successful (2xx status range) or not (4xx or 5xx status range).<br/>
+ack was successful (2xx status range) or not (4xx or 5xx status range).  
 Acks contain *headers* which include at least the `correlation-id` of the command/event to acknowledge, and optionally 
 contain a custom *payload*. 
 
+### Announcement criterion
+
+*announcements* are published by Ditto prior to an *event* taking place.  
+They are created by Ditto and are e.g. published a configured amount of time before an event will likely happen.
+
 
 ## Action (optional)
 
@@ -174,3 +180,6 @@ For *acks* criterion, the *action* segment specifies the identifier, which is de
 The criterion has to match the regular expression `[a-zA-Z0-9-_:]{3,100}`, i.e. letters of the Latin alphabet, numbers,
 dashes, and underscores.
 
+### Announcement criterion actions
+
+For the *announcement* criterion, the *action* segment specifies the announcement name.