improved filter examples

Signed-off-by: Philipp Michalski <Philipp.Michalski@bosch-si.com>

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

@@ -25,8 +25,9 @@ to see, but to filter for specific criteria, events may be filtered on the Ditto
 The above mentioned different APIs provide their own mechanisms on how to define such filters, but they all share the
 common functionality of based on which information events may be filtered.
 
-{% include note.html content="All filters are specified in an URL query format, therefore their values must be URL
-encoded before sending them to the backend!" %}
+{% include note.html content="All filters are specified in an URL query format, therefore their values should be URL
+encoded before sending them to the backend. The equal (=) and the ampersand (&) character must be encoded in any RQL
+filter!" %}
 
 ### By namespaces
 
@@ -38,8 +39,7 @@ in namespaces of interest are considered and thus only events of these Things ar
 
 For example, one would only subscribe for events occurring in 2 specific namespaces by defining:
 ```
-// raw: 'namespaces=org.eclipse.ditto.one,org.eclipse.ditto.two'
-namespaces=org.eclipse.ditto.one%2Corg.eclipse.ditto.two
+namespaces=org.eclipse.ditto.one,org.eclipse.ditto.two
 ```
 
 ### By RQL expression
@@ -56,14 +56,17 @@ This provides the opportunity to formulate filters like the following:
 
 Only emit events when attribute "count" was changed to a value greater than 42:
 ```
-// raw: filter=gt(attributes/count,42)
-filter=gt(attributes%2Fcount%2C42)
+filter=gt(attributes/count,42)
 ```
 
 Only emit events for Things starting with myThing when a feature "lamp" was modified:
 ```
-// raw: filter=and(like(thingId,"org.eclipse.ditto:myThing*"),exists(features/lamp))
-filter=and(like(thingId%2C%22org.eclipse.ditto%3AmyThing*%22)%2Cexists(features%2Flamp))
+filter=and(like(thingId,"org.eclipse.ditto:myThing*"),exists(features/lamp))
+```
+
+A string match filter that needs URL encoding as the matched value contains characters that must be escaped.
+```
+filter=gt(attributes/manufacturer,"ACME %26 Sons")
 ```
 
 You get the idea of how mighty this becomes by utilizing Ditto's [RQL expressions](basic-rql.html).

documentation/src/main/resources/pages/ditto/connectivity-protocol-bindings-amqp091.md

@@ -88,7 +88,7 @@ would match an attribute "counter" to be greater than 42. Additionally it would
 {
   "address": "<exchange_name>/<routing_key>",
   "topics": [
-    "_/_/things/twin/events?namespaces=org.eclipse.ditto&filter=gt(attributes%2Fcounter%2C42)",
+    "_/_/things/twin/events?namespaces=org.eclipse.ditto&filter=gt(attributes/counter,42)",
     "_/_/things/live/messages?namespaces=org.eclipse.ditto"
   ],
   "authorizationContext": ["ditto:outbound-auth-subject", "..."]

documentation/src/main/resources/pages/ditto/connectivity-protocol-bindings-amqp10.md

@@ -88,7 +88,7 @@ would match an attribute "counter" to be greater than 42. Additionally it would
 {
   "address": "<target>",
   "topics": [
-    "_/_/things/twin/events?namespaces=org.eclipse.ditto&filter=gt(attributes%2Fcounter%2C42)",
+    "_/_/things/twin/events?namespaces=org.eclipse.ditto&filter=gt(attributes/counter,42)",
     "_/_/things/live/messages?namespaces=org.eclipse.ditto"
   ],
   "authorizationContext": ["ditto:outbound-auth-subject", "..."]

documentation/src/main/resources/pages/ditto/connectivity-protocol-bindings-mqtt.md

@@ -111,7 +111,7 @@ would match an attribute "counter" to be greater than 42. Additionally it would
 {
   "address": "address": "eclipse-ditto-sandbox/{%raw%}{{ thing:id }}{%endraw%}",
   "topics": [
-    "_/_/things/twin/events?namespaces=org.eclipse.ditto&filter=gt(attributes%2Fcounter%2C42)",
+    "_/_/things/twin/events?namespaces=org.eclipse.ditto&filter=gt(attributes/counter,42)",
     "_/_/things/live/messages?namespaces=org.eclipse.ditto"
   ],
   "authorizationContext": ["ditto:outbound-auth-subject", "..."]

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

@@ -174,5 +174,5 @@ with `&`.  You have to URL encode the filter values before using them in a confi
 For example this way the WebSocket session would register for all events in the namespace `org.eclipse.ditto` and which
 would match an attribute "counter" to be greater than 42:
 ```
-START-SEND-EVENTS?namespaces=org.eclipse.ditto&filter=gt(attributes%2Fcounter%2C42)
+START-SEND-EVENTS?namespaces=org.eclipse.ditto&filter=gt(attributes/counter,42)
 ```

documentation/src/main/resources/pages/ditto/httpapi-sse.md

@@ -54,7 +54,8 @@ several possibilities listed in the sections below.
 All of the query parameters below can be combined, so that you can for example formulate that only events from a certain
 namespace with a specific RQL expression should be emitted which could look like:
 ```
-http://localhost:8080/api/<1|2>/things?namespaces=org.eclipse.ditto.one%2Corg.eclipse.test&filter=gt(attributes%2Fcounter%2C42)
+http://localhost:8080/api/<1|2>/things?namespaces=org.eclipse.ditto.one,org.eclipse.test&filter=gt
+(attributes/counter,42)
 ```
 
 #### Specify the Thing IDs
@@ -82,7 +83,7 @@ As described in [change notifications](basic-changenotifications.html#by-namespa
 for changes done in certain namespaces. At the SSE API, simply specify the `namespaces` parameter and provide a comma
 separated list of which namespaces to select, e.g.:
 ```
-http://localhost:8080/api/<1|2>/things?namespaces=org.eclipse.ditto.one%2Corg.eclipse.test
+http://localhost:8080/api/<1|2>/things?namespaces=org.eclipse.ditto.one,org.eclipse.test
 ```
 
 #### Filtering by RQL expression
@@ -91,7 +92,7 @@ As also described in [change notifications](basic-changenotifications.html#by-rq
 to specify an RQL expression expressing on which occasions to emit an event via the SSE API. Simply specify the `filter`
 parameter with an [RQL expression](basic-rql.html), e.g.:
 ```
-http://localhost:8080/api/<1|2>/things?filter=gt(attributes%2Fcounter%2C42)
+http://localhost:8080/api/<1|2>/things?filter=gt(attributes/counter,42)
 ```