Merge pull request #662 from bosch-io/doc/release-notes-110

Added release notes and blogpost for Ditto 1.1.0

documentation/src/main/resources/_config.yml

@@ -116,3 +116,5 @@ docVersions:
     basePath: ""
   - label: "1.0"
     basePath: "1.0"
+  - label: "1.1"
+    basePath: "1.1"

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

@@ -24,6 +24,9 @@ entries:
     output: web
     folderitems:
 
+    - title: 1.1.0
+      url: /release_notes_110.html
+      output: web
     - title: 1.0.0
       url: /release_notes_100.html
       output: web

documentation/src/main/resources/_posts/2020-04-16-connecting-to-ttn-via-mqtt.md

@@ -21,7 +21,9 @@ automatically update digital twins of devices connected via LoRaWAN to the TTN b
 You can find the slides [here](slides/2020_04_16-ttn-virtual-conference/index.html).
 
 This blogpost helps setting up this kind of connection and shall also be used as a step-by-step tutorial during
- the workshop. 
+ the workshop.
+
+{% include youtube.html youtube-id="D33JrN2RWiI" width="560" height="315" %} 
 
 ## Requirements
 

documentation/src/main/resources/_posts/2020-04-29-release-announcement-110.md

@@ -0,0 +1,63 @@
+---
+title: "Announcing Eclipse Ditto Release 1.1.0"
+published: true
+permalink: 2020-04-29-release-announcement-110.html
+layout: post
+author: thomas_jaeckle
+tags: [blog]
+hide_sidebar: true
+sidebar: false
+toc: false
+---
+
+Today, approximately 4 months after Eclipse Ditto's [1.0.0](2019-12-12-release-announcement-100.html) release, 
+the team is happy to announce the first minor (feature) update of Ditto `1.0`:<br/>
+**Eclipse Ditto 1.1.0**
+
+The Ditto team was quite busy, 1.1.0 focuses on the following areas:
+
+* Management of [Policies](basic-policy.html) via [Ditto Protocol](protocol-specification-policies.html)
+    * Addition of policy APIs in Ditto [Java client](client-sdk-java.html)
+* Possibility to [search](basic-search.html) via [Ditto Protocol](protocol-specification-things-search.html)
+    * Addition of search APIs in Ditto [Java client](client-sdk-java.html)
+* Enrich published Ditto events/message via additional [custom fields](basic-enrichment.html) of the affected thing
+    * Addition of enrichment APIs in Ditto [Java client](client-sdk-java.html)
+* Support for establishing managed [connections](basic-connections.html) via [MQTT 5](connectivity-protocol-bindings-mqtt5.html)
+* End-2-end [acknowledgements](basic-acknowledgements.html) preparing Ditto to enable "at least once" processing
+    * Addition of acknowledgement APIs in Ditto [Java client](client-sdk-java.html) 
+* Officially documented [pre-authenticated](installation-operating.html#pre-authentication) authentication mechanism
+* Use of Java 11 for running Ditto containers
+* Deprecation of API version 1 (authorization via [ACL](basic-acl.html) mechanism)
+* Use of CBOR as cluster internal replacement for JSON serialization
+* Further improvements on increasing throughput
+
+Please have a look at the [1.1.0 release notes](release_notes_110.html) for a more detailed information on the release.
+
+
+## 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/).
+
+Also the [Ditto Java client](client-sdk-java.html)'s artifacts were published to Maven central.
+
+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/)
+
+
+## Kubernetes ready: Helm chart
+
+In order to run Eclipse Ditto in a Kubernetes environment, best rely on the official 
+[Helm chart](https://hub.helm.sh/charts/eclipse-iot/ditto) and deploy Ditto via the Helm package manager.
+
+
+<br/>
+<br/>
+{% include image.html file="ditto.svg" alt="Ditto" max-width=500 %}
+--<br/>
+The Eclipse Ditto team

documentation/src/main/resources/pages/ditto/client-sdk-java.md

@@ -62,7 +62,7 @@ AuthenticationProvider authenticationProvider =
 MessagingProvider messagingProvider =
     MessagingProviders.webSocket(WebSocketMessagingConfiguration.newBuilder()
         .endpoint("wss://ditto.eclipse.org")
-        .jsonSchemaVersion(JsonSchemaVersion.V_1)
+        .jsonSchemaVersion(JsonSchemaVersion.V_2)
         // optionally configure a proxy server or a truststore containing the trusted CAs for SSL connection establishment
         .proxyConfiguration(proxyConfiguration)
         .trustStoreConfiguration(TrustStoreConfiguration.newBuilder()
@@ -91,6 +91,9 @@ client.twin().create("org.eclipse.ditto:new-thing").handle((createdThing, throwa
 
 #### Subscribe for change notifications
 
+In order to subscribe for [events](basic-signals-event.html) emitted by Ditto after a twin was modified, start the 
+consumption on the `twin` channel:
+
 ```java
 client.twin().startConsumption().get();
 System.out.println("Subscribed for Twin events");
@@ -102,6 +105,46 @@ client.twin().registerForThingChanges("my-changes", change -> {
 });
 ```
 
+There is also the possibility here to apply *server side filtering* of which events will get delivered to the client:
+
+```java
+client.twin().startConsumption(
+   Options.Consumption.filter("gt(features/temperature/properties/value,23.0)")
+).get();
+System.out.println("Subscribed for Twin events");
+client.twin().registerForFeaturePropertyChanges("my-feature-changes", "temperature", "value", change -> {
+   // perform custom actions ..
+});
+```
+
+##### Subscribe to enriched change notifications
+
+{% include callout.html content="Available since Ditto **1.1.0**" type="primary" %}
+
+In order to use [enrichment](basic-enrichment.html) in the Ditto Java client, the `startConsumption()` call can be
+enhanced with the additional extra fields:
+
+```java
+client.twin().startConsumption(
+   Options.Consumption.extraFields(JsonFieldSelector.newInstance("attributes/location"))
+).get();
+client.twin().registerForThingChanges("my-enriched-changes", change -> {
+   Optional<JsonObject> extra = change.getExtra();
+   // perform custom actions, making use of the 'extra' data ..
+});
+```
+
+In combination with a `filter`, the extra fields may also be used as part of such a filter:
+
+```java
+client.twin().startConsumption(
+   Options.Consumption.extraFields(JsonFieldSelector.newInstance("attributes/location")),
+   Options.Consumption.filter("eq(attributes/location,\"kitchen\")")
+).get();
+// register the callbacks...
+```
+
+
 #### Send/receive messages
 
 Register for receiving messages with the subject `hello.world` on any thing:
@@ -129,7 +172,103 @@ client.live().forId("org.eclipse.ditto:new-thing")
    );
 ```
 
-## Further Examples
+#### Manage policies
+
+{% include callout.html content="Available since Ditto **1.1.0**" type="primary" %}
+
+Read a policy:
+```java
+Policy retrievedPolicy = client.policies().retrieve(PolicyId.of("org.eclipse.ditto:new-policy"))
+   .get(); // this will block the thread! work asynchronously whenever possible!
+```
+
+Create a policy:
+```java
+Policy newPolicy = Policy.newBuilder(PolicyId.of("org.eclipse.ditto:new-policy"))
+   .forLabel("DEFAULT")
+   .setSubject(Subject.newInstance(SubjectIssuer.newInstance("nginx"), "ditto"))
+   .setGrantedPermissions(PoliciesResourceType.policyResource("/"), "READ", "WRITE")
+   .setGrantedPermissions(PoliciesResourceType.thingResource("/"), "READ", "WRITE")
+   .build();
+
+client.policies().create(newPolicy)
+   .get(); // this will block the thread! work asynchronously whenever possible!
+```
+
+Updating and deleting policies is also possible via the Java client API, please follow the API and the JavaDoc.
+
+#### Search for things
+
+{% include callout.html content="Available since Ditto **1.1.0**" type="primary" %}
+
+Search for things using the Java 8 `java.util.Stream` API:
+```java
+client.twin().search()
+   .stream(queryBuilder -> queryBuilder.namespace("org.eclipse.ditto")
+      .filter("eq(attributes/location,'kitchen')") // apply RQL expression here
+      .options(builder -> builder.sort(s -> s.desc("thingId")).size(1))
+   )
+   .forEach(foundThing -> System.out.println("Found thing: " + foundThing));
+```
+
+Use an [RQL](basic-rql.html) query in order to filter for the searched things.
+
+Search for things using the reactive streams `org.reactivestreams.Publisher` API:
+```java
+Publisher<List<Thing>> publisher = client.twin().search()
+   .publisher(queryBuilder -> queryBuilder.namespace("org.eclipse.ditto")
+      .filter("eq(attributes/location,'kitchen')") // apply RQL expression here
+      .options(builder -> builder.sort(s -> s.desc("thingId")).size(1))
+   );
+// integrate the publisher in the reactive streams library of your choice, e.g. Akka streams:
+akka.stream.javadsl.Source<Thing, NotUsed> things = akka.stream.javadsl.Source.fromPublisher(publisher)
+   .flatMapConcat(Source::from);
+// .. proceed working with the Akka Source ..
+```
+
+
+#### Request and issue acknowledgements
+
+{% include callout.html content="Available since Ditto **1.1.0**" type="primary" %}
+
+[Requesting acknowledgements](basic-acknowledgements.html#requesting-acknowledgements) is possible in the Ditto Java 
+client in the following way:
+
+```java
+DittoHeaders dittoHeaders = DittoHeaders.newBuilder()
+   .acknowledgementRequest(
+      AcknowledgementRequest.of(DittoAcknowledgementLabel.PERSISTED),
+      AcknowledgementRequest.of(AcknowledgementLabel.of("my-custom-ack"))
+   )
+   .timeout("5s")
+   .build();
+
+client.twin().forId(ThingId.of("org.eclipse.ditto:my-thing"))
+   .putAttribute("counter", 42, Options.dittoHeaders(dittoHeaders))
+   .whenComplete((aVoid, throwable) -> {
+      if (throwable instanceof AcknowledgementsFailedException) {
+         Acknowledgements acknowledgements = ((AcknowledgementsFailedException) throwable).getAcknowledgements();
+         System.out.println("Acknowledgements could not be fulfilled: " + acknowledgements);
+      }   
+   });
+```
+
+[Issuing requested acknowledgements](basic-acknowledgements.html#issuing-acknowledgements) can be done like this 
+whenever a `Change` callback is invoked with a change notification:
+
+```java
+client.twin().registerForThingChanges("REG1", change -> {
+   change.handleAcknowledgementRequest(AcknowledgementLabel.of("my-custom-ack"), ackHandle ->
+      ackHandle.acknowledge(HttpStatusCode.NOT_FOUND, JsonObject.newBuilder()
+         .set("error-detail", "Could not be found")
+         .build()
+      )
+   );
+});
+```
+
+
+## Further examples
 
 For further examples on how to use the Ditto client, please have a look at the class 
 [DittoClientUsageExamples](https://github.com/eclipse/ditto-clients/blob/master/java/src/test/java/org/eclipse/ditto/client/DittoClientUsageExamples.java)

documentation/src/main/resources/pages/ditto/release_notes_110.md

@@ -0,0 +1,136 @@
+---
+title: Release notes 1.1.0
+tags: [release_notes]
+keywords: release notes, announcements, changelog
+summary: "Version 1.1.0 of Eclipse Ditto, released on 29.04.2020"
+permalink: release_notes_110.html
+---
+
+The first minor (feature adding) release of Eclipse Ditto 1 is finally here: **1.1.0**.
+
+It is API and [binary compatible](https://github.com/eclipse/ditto/blob/master/documentation/src/main/resources/architecture/DADR-0005-semantic-versioning.md)
+to Eclipse Ditto 1.0.0.
+
+## What's in this release?
+
+
+### Changelog
+
+Compared to the latest release [1.0.0](release_notes_100.html), the following changes, new features and
+bugfixes were added.
+
+
+#### Changes
+
+##### [Java 11 as runtime environment](https://github.com/eclipse/ditto/issues/308)
+
+The default Java runtime for Ditto's Docker containers was switched from Java 8 to Java 11 which should have some 
+benefits in storing Strings in memory (this was already added in Java 9).
+
+Language features of newer Java versions can now be used in the "services" part of Ditto, the Java APIs and models relevant 
+for [semantic versioning](https://github.com/eclipse/ditto/blob/master/documentation/src/main/resources/architecture/DADR-0005-semantic-versioning.md) 
+are still compatible to Java 8.
+
+##### [CBOR as Ditto internal serialization provider](https://github.com/eclipse/ditto/pull/598)
+
+As a bachelor thesis, [Erik Escher](https://github.com/erikescher) evaluated mechanisms to improve the serialization 
+overhead done in Ditto clusters.
+
+His findings using [CBOR](https://cbor.io) as an alternative to plain JSON resulted an approximate 10% improvement on 
+roundtrip times and throughput.
+The Ditto team was happy to accept his pull request, again improving overall performance in Ditto.
+
+##### [More strict Content-Type parsing for HTTP request payload](https://github.com/eclipse/ditto/pull/650)
+
+In the past, Ditto did not evaluate the HTTP `Content-Type` header of HTTP requests sending along payload. As this 
+can be a potential security issue (e.g. in scope of CORS requests), the `Content-Type` is now strictly enforced to
+be of `application/json` wherever Ditto only accepts JSON request payload. 
+
+
+#### New features
+
+##### [Management of policies via Ditto Protocol and in Java client](https://github.com/eclipse/ditto/issues/554)
+
+The [policy](basic-policy.html) entities can now - in addition to their HTTP API - be managed via the 
+[Ditto Protocol](protocol-specification-policies.html). That means also via 
+[WebSocket](httpapi-protocol-bindings-websocket.html) and [connections](basic-connections.html) (e.g. AMQP, MQTT, ..).
+
+APIs for [policy management](client-sdk-java.html#manage-policies) were also added to the 
+[Ditto Java Client](https://github.com/eclipse/ditto-clients/pull/46).
+
+##### [Searching things via Ditto Protocol and in Java client](https://github.com/eclipse/ditto/issues/575)
+
+New [Ditto Protocol for search](protocol-specification-things-search.html) was added in order to define a search query
+via the Ditto Protocol and also get results via an asynchronous channel. As a result, searching for things is now also
+possible via [WebSocket](httpapi-protocol-bindings-websocket.html) and [connections](basic-connections.html) 
+(e.g. AMQP, MQTT, ..).
+
+APIs for [searching things](client-sdk-java.html#search-for-things) were also added to the 
+[Ditto Java Client](https://github.com/eclipse/ditto-clients/pull/53).
+
+##### [Enriching messages and events before publishing to external subscribers](https://github.com/eclipse/ditto/issues/561)
+
+When subscribing [change notifications](basic-changenotifications.html) or for messages to publish to external system or
+deliver via [WebSocket](httpapi-protocol-bindings-websocket.html) it is now possible to [enrich](basic-enrichment.html) 
+the payload with additional "extra fields" from the thing which was affected by the change.
+
+This can be useful when e.g. only a sensor value of a device changes, but your application also needs to be aware of 
+additional context of the affected thing (e.g. a location which does not change with each sensor update).
+
+APIs for [enriching changes](client-sdk-java.html#subscribe-to-enriched-change-notifications) were also added to the 
+[Ditto Java Client](https://github.com/eclipse/ditto-clients/pull/43).
+
+##### [Establish connections to MQTT 5 brokers](https://github.com/eclipse/ditto/issues/561)
+
+The Ditto community (namely [Alexander Wellbrock (w4tsn)](https://github.com/w4tsn) from 
+[othermo GmbH](https://www.othermo.de)) contributed MQTT 5 support to Ditto's connectivity capabilities.<br/>
+With that is is possible to also establish connections to MQTT 5 brokers and even apply 
+[header mapping](connectivity-header-mapping.html) and e.g. responses via MQTT 5's `user properties` approach.
+
+Thank you very much for this great contribution.
+
+##### [End-2-end acknowledgements](https://github.com/eclipse/ditto/issues/611)
+
+Until now, messages consumed by Eclipse Ditto were processed without a guarantee. That is being addressed with this
+first feature addition, the model and logic in order to request and emit [acknowledgements](basic-acknowledgements.html).
+
+The follow-up issue [#661](https://github.com/eclipse/ditto/issues/661) will automatically handle acknowledgements 
+in Ditto managed connections, configured for connection sources and targets, providing QoS 1 (at least once) semantic
+for message processing in Ditto via connections.
+
+APIs for [requesting and issuing acknowledgements](client-sdk-java.html#request-and-issue-acknowledgements) were also 
+added to the [Ditto Java Client](https://github.com/eclipse/ditto-clients/pull/56).
+
+##### [Pre-authenticated authentication mechanism](https://github.com/eclipse/ditto/issues/560)
+
+Officially added+[documented](installation-operating.html#pre-authentication) support of how Ditto external 
+authentication providers may be configured to authenticate users in Ditto by adding them as an HTTP reverse proxy in 
+front of Ditto.
+
+
+#### Deprecations
+
+##### [API version 1 deprecation](https://github.com/eclipse/ditto/pull/608)
+
+Now that Ditto has a full replacement for [ACLs](basic-acl.html), namely [policies](basic-policy.html) which now can 
+also be managed via the [Ditto Protocol](protocol-specification-policies.html) and the 
+[Ditto Java client](client-sdk-java.html), it is time to deprecate the APIs around the ACL mechanism.
+
+Starting with Ditto 1.1.0, usage of the API in version `1` (e.g. contained in HTTP URLs as `/api/1/things...`) is 
+deprecated.<br/>
+API version 1 and ACLs will very likely be removed in Ditto `2.0`.
+
+So when you start using Ditto, please make sure to use API version `2` (using policies as 
+[authorization mechanism](basic-auth.html#authorization)) from the very beginning.
+
+
+#### Bugfixes
+
+Several bugs in Ditto 1.0.0 were fixed for 1.1.0.<br/>
+This is a complete list of the 
+[merged pull requests](https://github.com/eclipse/ditto/pulls?q=is%3Apr+milestone%3A1.1.0), including the fixed bugs.
+
+
+### Migration notes
+
+Do not apply when updating from Eclipse Ditto 1.0.0 to 1.1.0.