added streaming protocol usage example to history documentation

Signed-off-by: Thomas Jaeckle <thomas.jaeckle@bosch.io>
eclipse-ditto · Feb 6, 2023 · 63efb2b · 63efb2b
1 parent bedaaee
commit 63efb2b
Show file tree

Hide file tree

Showing 7 changed files with 91 additions and 112 deletions.
diff --git a/.run/ConnectivityService.run.xml b/.run/ConnectivityService.run.xml
@@ -1,31 +1,15 @@
-<!--
-  ~ Copyright (c) 2022 Contributors to the Eclipse Foundation
-  ~
-  ~ See the NOTICE file(s) distributed with this work for additional
-  ~ information regarding copyright ownership.
-  ~
-  ~ This program and the accompanying materials are made available under the
-  ~ terms of the Eclipse Public License 2.0 which is available at
-  ~ http://www.eclipse.org/legal/epl-2.0
-  ~
-  ~ SPDX-License-Identifier: EPL-2.0
-  -->
 <component name="ProjectRunConfigurationManager">
   <configuration default="false" name="ConnectivityService" type="Application" factoryName="Application" folderName="Ditto" nameIsGenerated="true">
     <envs>
       <env name="LOG_LEVEL_APPLICATION" value="INFO" />
+      <env name="CLEANUP_HISTORY_RETENTION_DURATION" value="6d" />
+      <env name="CONNECTION_EVENT_HISTORICAL_HEADERS_TO_PERSIST.0" value="ditto-originator" />
     </envs>
     <option name="MAIN_CLASS_NAME" value="org.eclipse.ditto.connectivity.service.ConnectivityService" />
     <module name="ditto-connectivity-service" />
     <option name="VM_PARAMETERS" value="-Xms512m -Xmx512m --add-opens java.base/java.nio=ALL-UNNAMED --add-opens java.base/sun.nio.ch=ALL-UNNAMED --add-opens java.base/sun.security.util=ALL-UNNAMED" />
-    <extension name="coverage">
-      <pattern>
-        <option name="PATTERN" value="org.eclipse.ditto.services.connectivity.*" />
-        <option name="ENABLED" value="true" />
-      </pattern>
-    </extension>
     <method v="2">
       <option name="Make" enabled="true" />
     </method>
   </configuration>
-</component>
+</component>
diff --git a/.run/Ditto.run.xml b/.run/Ditto.run.xml
@@ -1,15 +1,3 @@
-<!--
-  ~ Copyright (c) 2022 Contributors to the Eclipse Foundation
-  ~
-  ~ See the NOTICE file(s) distributed with this work for additional
-  ~ information regarding copyright ownership.
-  ~
-  ~ This program and the accompanying materials are made available under the
-  ~ terms of the Eclipse Public License 2.0 which is available at
-  ~ http://www.eclipse.org/legal/epl-2.0
-  ~
-  ~ SPDX-License-Identifier: EPL-2.0
-  -->
 <component name="ProjectRunConfigurationManager">
   <configuration default="false" name="Ditto" type="CompoundRunConfigurationType">
     <toRun name="PoliciesService" type="Application" />

diff --git a/.run/GatewayService.run.xml b/.run/GatewayService.run.xml
@@ -1,15 +1,3 @@
-<!--
-  ~ Copyright (c) 2022 Contributors to the Eclipse Foundation
-  ~
-  ~ See the NOTICE file(s) distributed with this work for additional
-  ~ information regarding copyright ownership.
-  ~
-  ~ This program and the accompanying materials are made available under the
-  ~ terms of the Eclipse Public License 2.0 which is available at
-  ~ http://www.eclipse.org/legal/epl-2.0
-  ~
-  ~ SPDX-License-Identifier: EPL-2.0
-  -->
 <component name="ProjectRunConfigurationManager">
   <configuration default="false" name="GatewayService" type="Application" factoryName="Application" folderName="Ditto">
     <envs>
@@ -18,12 +6,6 @@
     <option name="MAIN_CLASS_NAME" value="org.eclipse.ditto.gateway.service.starter.GatewayService" />
     <module name="ditto-gateway-service" />
     <option name="VM_PARAMETERS" value="-Xms512m -Xmx512m -Dcom.sun.management.jmxremote.port=9301 -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false" />
-    <extension name="coverage">
-      <pattern>
-        <option name="PATTERN" value="org.eclipse.ditto.services.gateway.starter.*" />
-        <option name="ENABLED" value="true" />
-      </pattern>
-    </extension>
     <method v="2">
       <option name="Make" enabled="true" />
     </method>

diff --git a/.run/PoliciesService.run.xml b/.run/PoliciesService.run.xml
@@ -1,31 +1,16 @@
-<!--
-  ~ Copyright (c) 2022 Contributors to the Eclipse Foundation
-  ~
-  ~ See the NOTICE file(s) distributed with this work for additional
-  ~ information regarding copyright ownership.
-  ~
-  ~ This program and the accompanying materials are made available under the
-  ~ terms of the Eclipse Public License 2.0 which is available at
-  ~ http://www.eclipse.org/legal/epl-2.0
-  ~
-  ~ SPDX-License-Identifier: EPL-2.0
-  -->
 <component name="ProjectRunConfigurationManager">
   <configuration default="false" name="PoliciesService" type="Application" factoryName="Application" folderName="Ditto" nameIsGenerated="true">
     <envs>
       <env name="LOG_LEVEL_APPLICATION" value="INFO" />
+      <env name="CLEANUP_HISTORY_RETENTION_DURATION" value="5d" />
+      <env name="POLICY_EVENT_HISTORICAL_HEADERS_TO_PERSIST.0" value="ditto-originator" />
+      <env name="POLICY_EVENT_HISTORICAL_HEADERS_TO_PERSIST.1" value="correlation-id" />
     </envs>
     <option name="MAIN_CLASS_NAME" value="org.eclipse.ditto.policies.service.starter.PoliciesService" />
     <module name="ditto-policies-service" />
     <option name="VM_PARAMETERS" value="-Xms512m -Xmx512m" />
-    <extension name="coverage">
-      <pattern>
-        <option name="PATTERN" value="org.eclipse.ditto.services.policies.starter.*" />
-        <option name="ENABLED" value="true" />
-      </pattern>
-    </extension>
     <method v="2">
       <option name="Make" enabled="true" />
     </method>
   </configuration>
-</component>
+</component>
diff --git a/.run/SearchService.run.xml b/.run/SearchService.run.xml
@@ -1,15 +1,3 @@
-<!--
-  ~ Copyright (c) 2022 Contributors to the Eclipse Foundation
-  ~
-  ~ See the NOTICE file(s) distributed with this work for additional
-  ~ information regarding copyright ownership.
-  ~
-  ~ This program and the accompanying materials are made available under the
-  ~ terms of the Eclipse Public License 2.0 which is available at
-  ~ http://www.eclipse.org/legal/epl-2.0
-  ~
-  ~ SPDX-License-Identifier: EPL-2.0
-  -->
 <component name="ProjectRunConfigurationManager">
   <configuration default="false" name="SearchService" type="Application" factoryName="Application" folderName="Ditto" nameIsGenerated="true">
     <envs>
@@ -23,12 +11,6 @@
     <option name="MAIN_CLASS_NAME" value="org.eclipse.ditto.thingsearch.service.starter.SearchService" />
     <module name="ditto-thingsearch-service" />
     <option name="VM_PARAMETERS" value="-Xms512m -Xmx512m" />
-    <extension name="coverage">
-      <pattern>
-        <option name="PATTERN" value="org.eclipse.ditto.services.thingsearch.starter.*" />
-        <option name="ENABLED" value="true" />
-      </pattern>
-    </extension>
     <method v="2">
       <option name="Make" enabled="true" />
     </method>

diff --git a/.run/ThingsService.run.xml b/.run/ThingsService.run.xml
@@ -1,31 +1,14 @@
-<!--
-  ~ Copyright (c) 2022 Contributors to the Eclipse Foundation
-  ~
-  ~ See the NOTICE file(s) distributed with this work for additional
-  ~ information regarding copyright ownership.
-  ~
-  ~ This program and the accompanying materials are made available under the
-  ~ terms of the Eclipse Public License 2.0 which is available at
-  ~ http://www.eclipse.org/legal/epl-2.0
-  ~
-  ~ SPDX-License-Identifier: EPL-2.0
-  -->
 <component name="ProjectRunConfigurationManager">
   <configuration default="false" name="ThingsService" type="Application" factoryName="Application" folderName="Ditto" nameIsGenerated="true">
     <envs>
       <env name="LOG_LEVEL_APPLICATION" value="INFO" />
+      <env name="CLEANUP_HISTORY_RETENTION_DURATION" value="24h" />
     </envs>
     <option name="MAIN_CLASS_NAME" value="org.eclipse.ditto.things.service.starter.ThingsService" />
     <module name="ditto-things-service" />
     <option name="VM_PARAMETERS" value="-Xms512m -Xmx512m" />
-    <extension name="coverage">
-      <pattern>
-        <option name="PATTERN" value="org.eclipse.ditto.services.things.starter.*" />
-        <option name="ENABLED" value="true" />
-      </pattern>
-    </extension>
     <method v="2">
       <option name="Make" enabled="true" />
     </method>
   </configuration>
-</component>
+</component>
diff --git a/documentation/src/main/resources/pages/ditto/basic-history.md b/documentation/src/main/resources/pages/ditto/basic-history.md
@@ -12,11 +12,11 @@ Starting with **Eclipse Ditto 3.2.0**, APIs for retrieving the history of the fo
 
 The capabilities of these APIs are the following:
 
-| Entity     | Retrieving entity at a specific revision or timestamp | Streaming modification events of an entity specifying from/to revision/timestamp |
-|------------|-------------------------------------------------------|----------------------------------------------------------------------------------|
-| Thing      | ✓                                                     | ✓                                                                                |
-| Policy     | ✓                                                     | ✓                                                                                |
-| Connection | ✓                                                     | no                                                                               |
+| Entity     | [Retrieving entity at a specific revision or timestamp](#retrieving-entity-from-history) | [Streaming modification events of an entity specifying from/to revision/timestamp](#streaming-historical-events-of-entity) |
+|------------|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------|
+| Thing      | ✓                                                                                        | ✓                                                                                                                          |
+| Policy     | ✓                                                                                        | ✓                                                                                                                          |
+| Connection | ✓                                                                                        | no                                                                                                                         |
 
 {% include note.html content="Ditto's history API capabilities are not comparable with the features of a time series database.
     E.g. no aggregations on or compactions of the historical data can be done." %}
@@ -53,7 +53,7 @@ curl -u ditto:ditto 'http://localhost:8080/api/2/policies/org.eclipse.ditto:poli
   --header 'at-historical-revision: 1'
 
 # Access a connection:
-curl -u ditto:ditto 'http://localhost:8080/api/2/connections/some-connection-1' \
+curl -u devops:foobar 'http://localhost:8080/api/2/connections/some-connection-1' \
   --header 'at-historical-revision: 1'
 ```
 
@@ -78,7 +78,7 @@ curl -u ditto:ditto 'http://localhost:8080/api/2/policies/org.eclipse.ditto:poli
   --header 'at-historical-timestamp: 2022-10-24T06:11:15Z'
 
 # Access a connection:
-curl -u ditto:ditto 'http://localhost:8080/api/2/connections/some-connection-1' \
+curl -u devops:foobar 'http://localhost:8080/api/2/connections/some-connection-1' \
   --header 'at-historical-timestamp: 2022-10-24T07:11Z'
 ```
 
@@ -144,6 +144,81 @@ Please inspect the [protocol specification of DittoProtocol messages for streami
 to find out how to stream historical (persisted) events via DittoProtocol.  
 Using the DittoProtocol, historical events can be streamed either via WebSocket or connections.
 
+Example protocol interaction for retrieving the persisted events of a thing:
+
+**First:** Subscribe for the persisted events of a thing
+```json
+{
+  "topic": "org.eclipse.ditto/thing-2/things/twin/streaming/subscribeForPersistedEvents",
+  "path": "/",
+  "headers": {},
+  "value": {
+    "fromHistoricalRevision": 1,
+    "toHistoricalRevision": 10
+  }
+}
+```
+
+Alternatively to `fromHistoricalRevision` and `toHistoricalRevision`, also a timestamp based range may be used:
+`fromHistoricalTimestamp` and `toHistoricalTimestamp`.  
+The "to" can be omitted in order to receive all events up to the current revision or timestamp.
+
+As a result, the following `created` event is received as response:
+```json
+{
+  "topic": "org.eclipse.ditto/thing-2/things/twin/streaming/created",
+  "path": "/",
+  "headers": {},
+  "value": {
+    "subscriptionId": "0"
+  }
+}
+```
+
+**Second:** Once the streaming subscription is confirmed to be created, request demand (of how many events to get streamed), 
+referencing the `subscriptionId`:
+```json
+{
+  "topic": "org.eclipse.ditto/thing-2/things/twin/streaming/request",
+  "path": "/",
+  "headers": {},
+  "value": {
+    "subscriptionId": "0",
+    "demand": 25
+  }
+}
+```
+
+The backend will start sending the requested persisted events as `next` messages: 
+```json
+{
+  "topic": "org.eclipse.ditto/thing-2/things/twin/streaming/next",
+  "path": "/",
+  "headers": {},
+  "value": {
+    "subscriptionId": "0",
+    "item": {
+
+    }
+  }
+}
+```
+
+It will do so either until all existing events were sent, in that case a `complete` event is sent:
+```json
+{
+  "topic": "org.eclipse.ditto/thing-2/things/twin/streaming/complete",
+  "path": "/",
+  "headers": {},
+  "value": {
+    "subscriptionId": "0"
+  }
+}
+```
+
+Or it will stop after the `demand` was fulfilled, waiting for the requester to claim more demand with a new `request` 
+message.
+
 
 ## Configuring historical headers to persist