Desired feature properties added to things model

With the upcoming release of Eclipse Ditto version 1.5.0 desired feature properties are introduced to the things model for API versions later than 1. The desired properties for features are added on the same level of the model as the feature properties and can reflect for example feature property updates ,which are intended, but not yet applied.

A fully-fledged JSON representation of a feature with desired properties is shown below:

{
    "lamp": {
        "definition": [ "com.mycompany.fb:Lamp:1.0.0" ],
        "properties": {
            "configuration": {
                "on": true,
                "location": {
                    "longitude": 34.052235,
                    "latitude": -118.243683
                }
            },
            "status": {
                "on": false,
                "color": {
                    "red": 128,
                    "green": 255,
                    "blue": 0
                }
            }
        },
        "desiredProperties": {
            "configuration": {
                "on": false
            }
        }
    }
}

Operations on desired feature properties

  • CRUD operations
    • You can create multiple desired properties of a feature or just single ones.
    • You can retrieve all desired properties of a feature or just single ones.
    • You can modify all desired properties of a feature or just single ones.
    • You can delete all desired properties of a feature or just single ones.
  • Search
    • You can search for things with specific desired properties with RQL-functions.
    • You can search for things, which have existent desired properties for a feature.
  • Get notified on changes
    • You can receive events for changes done to the desired properties of things you’re authorized to read.
    • You can enrich and filter the events you want to receive, for changes done to the desired properties.

Executing CRUD operations on desired feature properties

CRUD operations can be executed either via the Ditto HTTP API versions later than 1 or via ditto-protocol messages.

Possible CRUD operations for desired feature properties via ditto-protocol:

Using the ditto-client to manage desired feature properties

The desired feature properties can also be retrieved, modified and deleted via the Ditto Java Client. With the upcoming (Ditto Java Client version 1.5.0), no special CRUD operations for desired feature properties are implemented in the client. Thus, the operations have to be executed via creating ditto-protocol messages manually in the client.

Example for creating/modifying desired feature properties of a thing via the ditto-client:

final Adaptable modifyFeatureDesiredProperties =
                Adaptable.newBuilder(TopicPath.newBuilder(ThingId.of("com.mycompany.fb:Car:1.0.0"))
                        .things()
                        .twin()
                        .commands()
                        .modify()
                        .build())
                        .withPayload(Payload.newBuilder(
                                JsonPointer.of("/features/lamp/desiredProperties"))
                                .withValue(JsonObject.newBuilder().set("on", false).build())
                                .build()).build();

        client.sendDittoProtocol(modifyFeatureDesiredProperties).whenComplete(((adaptable, throwable) -> {
            if (throwable != null) {
                LOGGER.error("Received error while sending ModifyFeatureDesiredProperties: '{}' ",
                        throwable.toString());
            } else {
                LOGGER.info("Received response for ModifyFeatureDesiredProperties: '{}'", adaptable);
            }
        }));

Feedback?

Please get in touch if you have feedback or questions towards this new concept of desired properties.



Ditto

–
The Eclipse Ditto team