blob: 42219b62e77a515471fd9f139ace82786cccf7c6 [file] [log] [blame]
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="description" content="">
<meta name="keywords" content="blog, ">
<title> Desired Feature Properties </title>
<link rel="stylesheet" href="css/syntax.css">
<link rel="stylesheet" type="text/css" href="//cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css" crossorigin="anonymous">
<link rel="stylesheet" href="css/modern-business.css">
<link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/css/bootstrap.min.css" crossorigin="anonymous">
<link rel="stylesheet" href="css/customstyles.css">
<link rel="stylesheet" href="css/boxshadowproperties.css">
<link rel="stylesheet" href="css/theme-ditto.css">
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:400,700|Source+Code+Pro:300,600|Titillium+Web:400,600,700">
<script src="//cdnjs.cloudflare.com/ajax/libs/jquery/2.1.4/jquery.min.js" crossorigin="anonymous"></script>
<script src="//cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/js/bootstrap.min.js" crossorigin="anonymous"></script>
<script src="//cdnjs.cloudflare.com/ajax/libs/anchor-js/2.0.0/anchor.min.js" crossorigin="anonymous"></script>
<script src="js/toc.js"></script>
<script src="js/customscripts.js"></script>
<script type="application/ld+json">
{
"@context": "http://schema.org",
"@type": "Organization",
"url": "https://eclipse.org/ditto/",
"logo": "https://eclipse.org/ditto/images/ditto.svg"
}
</script>
<link rel="icon" type="image/png" href="images/favicon-16x16.png" sizes="16x16">
<link rel="icon" type="image/png" href="images/favicon-32x32.png" sizes="32x32">
<link rel="icon" type="image/png" href="images/favicon-96x96.png" sizes="96x96">
<link rel="alternate" type="application/rss+xml" title="Eclipse Ditto Blog" href="https://www.eclipse.org/ditto/feed.xml">
<!-- Eclipse Foundation cookie consent: -->
<link rel="stylesheet" type="text/css" href="//www.eclipse.org/eclipse.org-common/themes/solstice/public/stylesheets/vendor/cookieconsent/cookieconsent.min.css" />
<script src="//www.eclipse.org/eclipse.org-common/themes/solstice/public/javascript/vendor/cookieconsent/default.min.js"></script>
<script>
$(document).ready(function() {
$("#tg-sb-link").click(function() {
$("#tg-sb-sidebar").toggle();
$("#tg-sb-content").toggleClass('col-md-9');
$("#tg-sb-content").toggleClass('col-md-12');
$("#tg-sb-icon").toggleClass('fa-toggle-on');
$("#tg-sb-icon").toggleClass('fa-toggle-off');
});
});
</script>
</head>
<script>
(function(w,d,s,l,i){
w[l]=w[l]||[];
w[l].push({'gtm.start':
new Date().getTime(),event:'gtm.js'});
var f=d.getElementsByTagName(s)[0],
j=d.createElement(s),
dl=l!='dataLayer'?'&l='+l:'';
j.async=true;
j.src='https://www.googletagmanager.com/gtm.js?id='+i+dl;
f.parentNode.insertBefore(j,f);
})(window,document,'script','dataLayer','GTM-5WLCZXC');
</script>
<body>
<!-- Navigation -->
<nav class="navbar navbar-inverse navbar-fixed-top">
<div class="container topnavlinks">
<div class="navbar-header">
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target="#bs-example-navbar-collapse-1">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-ditto-home" href="index.html">&nbsp;<img src="images/ditto_allwhite_symbolonly.svg" class="ditto-navbar-symbol" alt="Home"> <img src="images/ditto_allwhite_textonly.svg" class="ditto-navbar-symbol-text" alt="Ditto"></a>
</div>
<div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1">
<ul class="nav navbar-nav navbar-right">
<!-- toggle sidebar button -->
<!--<li><a id="tg-sb-link" href="#"><i id="tg-sb-icon" class="fa fa-toggle-on"></i> Nav</a></li>-->
<!-- entries without drop-downs appear here -->
<li><a href="blog.html">Blog</a></li>
<li><a href="intro-overview.html">Documentation</a></li>
<li><a href="http-api-doc.html">HTTP API</a></li>
<li><a href="sandbox.html">Sandbox</a></li>
<li><a href="https://github.com/eclipse/ditto" target="_blank">GitHub</a></li>
<li><a href="https://github.com/eclipse/ditto-examples" target="_blank">GitHub examples</a></li>
<!-- entries with drop-downs appear here -->
<!-- conditional logic to control which topnav appears for the audience defined in the configuration file.-->
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Links<b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="https://projects.eclipse.org/projects/iot.ditto" target="_blank">Eclipse Ditto Project</a></li>
<li><a href="https://www.eclipse.org/forums/index.php/f/364/" target="_blank">Forum</a></li>
<li><a href="https://ci.eclipse.org/ditto/" target="_blank">Jenkins</a></li>
<li><a href="https://dev.eclipse.org/mhonarc/lists/ditto-dev/" target="_blank">Mailing list archives</a></li>
<li><a href="https://gitter.im/eclipse/ditto" target="_blank">Gitter.im chat</a></li>
</ul>
</li>
<!--comment out this block if you want to hide search-->
<li>
<!--start search-->
<div id="search-demo-container">
<input type="text" id="search-input" placeholder="search...">
<ul id="results-container"></ul>
</div>
<script src="//cdnjs.cloudflare.com/ajax/libs/simple-jekyll-search/0.0.9/jekyll-search.js" type="text/javascript"></script>
<script type="text/javascript">
SimpleJekyllSearch.init({
searchInput: document.getElementById('search-input'),
resultsContainer: document.getElementById('results-container'),
dataSource: 'search.json',
searchResultTemplate: '<li><a href="{url}" title="Desired Feature Properties">{title}</a></li>',
noResultsText: 'No results found.',
limit: 10,
fuzzy: true,
})
</script>
<!--end search-->
</li>
</ul>
</div>
</div>
<!-- /.container -->
</nav>
<!-- Page Content -->
<div class="container">
<div id="main">
<!-- Content Row -->
<div class="row">
<!-- Content Column -->
<div class="col-md-12" id="tg-sb-content">
<!-- Look the author details up from the site config. -->
<!-- Output author details if some exist. -->
<!-- Output author details if some exist. -->
<!---->
<!--<span>-->
<!--&lt;!&ndash; Mugshot. &ndash;&gt;-->
<!--<img src="https://www.gravatar.com/avatar/3c657b46dc4d006056091942068f6ad7?s=135" alt="A photo of David Schwilk" />-->
<!--&lt;!&ndash; Personal Info. &ndash;&gt;-->
<!--Written by <a href="https://github.com/derschwilk" target="_blank">David Schwilk</a>-->
<!--</span>-->
<!---->
<article class="post" itemscope itemtype="http://schema.org/BlogPosting">
<header class="post-header">
<h1 class="post-title" itemprop="name headline">Desired Feature Properties</h1>
<p class="post-meta">Published by <img src="https://www.gravatar.com/avatar/3c657b46dc4d006056091942068f6ad7?s=135" alt="A photo of David Schwilk" style="width:50px;border-radius:50%;display:inline-block;margin-right:5px;" /><span itemprop="author" itemscope itemtype="http://schema.org/Person"><span itemprop="name"><a href="https://github.com/derschwilk" target="_blank">David Schwilk</a> </span></span> on <time datetime="2020-11-11T00:00:00+00:00" itemprop="datePublished">Nov 11, 2020</time> - Tags:
<a href="tag_blog.html">blog</a>
</p>
</header>
<div class="post-content" itemprop="articleBody">
<!-- this handles the automatic toc. use ## for subheads to auto-generate the on-page minitoc. if you use html tags, you must supply an ID for the heading element in order for it to appear in the minitoc. -->
<script>
$( document ).ready(function() {
// Handler for .ready() called.
$('#toc').toc({ minimumHeaders: 0, listType: 'ul', showSpeed: 0, headers: 'h2,h3,h4' });
/* this offset helps account for the space taken up by the floating toolbar. */
$('#toc').on('click', 'a', function() {
var target = $(this.getAttribute('href'))
, scroll_target = target.offset().top
$(window).scrollTop(scroll_target - 10);
return false
})
});
</script>
<div id="toc"></div>
<h2 id="desired-feature-properties-added-to-things-model">Desired feature properties added to things model</h2>
<p>With the upcoming release of Eclipse Ditto <strong>version 1.5.0</strong>
<a href="basic-feature.html#feature-desired-properties">desired feature properties</a> are introduced to the things model for
<strong>API versions later than 1</strong>. The <em>desired properties</em> 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.</p>
<div class="alert alert-info" role="alert"><i class="fa fa-info-circle"></i> <b>Note:</b> Further logics for desired feature properties might be implemented in future Ditto
versions.</div>
<p>A fully-fledged JSON representation of a feature with desired properties is shown below:</p>
<div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="s2">"lamp"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="s2">"definition"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="s2">"com.mycompany.fb:Lamp:1.0.0"</span><span class="w"> </span><span class="p">],</span><span class="w">
</span><span class="s2">"properties"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="s2">"configuration"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="s2">"on"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span><span class="w">
</span><span class="s2">"location"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="s2">"longitude"</span><span class="p">:</span><span class="w"> </span><span class="mf">34.052235</span><span class="p">,</span><span class="w">
</span><span class="s2">"latitude"</span><span class="p">:</span><span class="w"> </span><span class="mf">-118.243683</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">},</span><span class="w">
</span><span class="s2">"status"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="s2">"on"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span><span class="w">
</span><span class="s2">"color"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="s2">"red"</span><span class="p">:</span><span class="w"> </span><span class="mi">128</span><span class="p">,</span><span class="w">
</span><span class="s2">"green"</span><span class="p">:</span><span class="w"> </span><span class="mi">255</span><span class="p">,</span><span class="w">
</span><span class="s2">"blue"</span><span class="p">:</span><span class="w"> </span><span class="mi">0</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">},</span><span class="w">
</span><span class="s2">"desiredProperties"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="s2">"configuration"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="s2">"on"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre></div></div>
<h2 id="operations-on-desired-feature-properties">Operations on desired feature properties</h2>
<ul>
<li><strong>CRUD operations</strong>
<ul>
<li>You can create multiple desired properties of a feature or just single ones.</li>
<li>You can retrieve all desired properties of a feature or just single ones.</li>
<li>You can modify all desired properties of a feature or just single ones.</li>
<li>You can delete all desired properties of a feature or just single ones.</li>
</ul>
</li>
<li><strong>Search</strong>
<ul>
<li>You can <a href="httpapi-search.html">search</a> for things with specific desired properties with <a href="basic-rql.html">RQL-functions</a>.</li>
<li>You can search for things, which have <a href="basic-rql.html#exists">existent</a> desired properties for a feature.</li>
</ul>
</li>
<li><strong>Get notified on changes</strong>
<ul>
<li>You can <a href="basic-signals-event.html">receive events</a> for changes done to the desired properties of things
you’re authorized to read.</li>
<li>You can <a href="basic-enrichment.html">enrich</a> and <a href="basic-changenotifications.html#filtering">filter</a> the
events you want to receive, for changes done to the desired properties.</li>
</ul>
</li>
</ul>
<h3 id="executing-crud-operations-on-desired-feature-properties">Executing CRUD operations on desired feature properties</h3>
<p>CRUD operations can be executed either via the <a href="httpapi-concepts.html">Ditto HTTP API</a> <strong>versions later than 1</strong> or via
<a href="protocol-overview.html">ditto-protocol</a> messages.</p>
<p><em>Possible CRUD operations for desired feature properties via ditto-protocol</em>:</p>
<ul>
<li><a href="protocol-examples-retrievedesiredproperties.html">Retrieve all desired properties of a feature via ditto-protocol</a></li>
<li><a href="protocol-examples-retrievedesiredproperty.html">Retrieve a single desired property of a feature via ditto-protocol</a></li>
<li><a href="protocol-examples-modifydesiredproperties.html">Create/Modify all desired properties of a feature via ditto-protocol</a></li>
<li><a href="protocol-examples-modifydesiredproperty.html">Create/Modify a single desired property of a feature via ditto-protocol</a></li>
<li><a href="protocol-examples-deletedesiredproperties.html">Delete all desired properties of a feature via ditto-protocol</a></li>
<li><a href="protocol-examples-deletedesiredproperty.html">Delete a single desired property of a feature via ditto-protocol</a></li>
</ul>
<h3 id="using-the-ditto-client-to-manage-desired-feature-properties">Using the ditto-client to manage desired feature properties</h3>
<p>The desired feature properties can also be retrieved, modified and deleted via the <a href="client-sdk-java.html">Ditto Java Client</a>.
With the upcoming (<strong>Ditto Java Client version 1.5.0</strong>), no special CRUD operations for
desired feature properties are implemented in the client. Thus, the operations have to be executed via creating
<strong>ditto-protocol messages</strong> manually in the client.</p>
<p>Example for creating/modifying desired feature properties of a thing via the ditto-client:</p>
<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">final</span> <span class="n">Adaptable</span> <span class="n">modifyFeatureDesiredProperties</span> <span class="o">=</span>
<span class="n">Adaptable</span><span class="o">.</span><span class="na">newBuilder</span><span class="o">(</span><span class="n">TopicPath</span><span class="o">.</span><span class="na">newBuilder</span><span class="o">(</span><span class="n">ThingId</span><span class="o">.</span><span class="na">of</span><span class="o">(</span><span class="s">"com.mycompany.fb:Car:1.0.0"</span><span class="o">))</span>
<span class="o">.</span><span class="na">things</span><span class="o">()</span>
<span class="o">.</span><span class="na">twin</span><span class="o">()</span>
<span class="o">.</span><span class="na">commands</span><span class="o">()</span>
<span class="o">.</span><span class="na">modify</span><span class="o">()</span>
<span class="o">.</span><span class="na">build</span><span class="o">())</span>
<span class="o">.</span><span class="na">withPayload</span><span class="o">(</span><span class="n">Payload</span><span class="o">.</span><span class="na">newBuilder</span><span class="o">(</span>
<span class="n">JsonPointer</span><span class="o">.</span><span class="na">of</span><span class="o">(</span><span class="s">"/features/lamp/desiredProperties"</span><span class="o">))</span>
<span class="o">.</span><span class="na">withValue</span><span class="o">(</span><span class="n">JsonObject</span><span class="o">.</span><span class="na">newBuilder</span><span class="o">().</span><span class="na">set</span><span class="o">(</span><span class="s">"on"</span><span class="o">,</span> <span class="kc">false</span><span class="o">).</span><span class="na">build</span><span class="o">())</span>
<span class="o">.</span><span class="na">build</span><span class="o">()).</span><span class="na">build</span><span class="o">();</span>
<span class="n">client</span><span class="o">.</span><span class="na">sendDittoProtocol</span><span class="o">(</span><span class="n">modifyFeatureDesiredProperties</span><span class="o">).</span><span class="na">whenComplete</span><span class="o">(((</span><span class="n">adaptable</span><span class="o">,</span> <span class="n">throwable</span><span class="o">)</span> <span class="o">-&gt;</span> <span class="o">{</span>
<span class="k">if</span> <span class="o">(</span><span class="n">throwable</span> <span class="o">!=</span> <span class="kc">null</span><span class="o">)</span> <span class="o">{</span>
<span class="n">LOGGER</span><span class="o">.</span><span class="na">error</span><span class="o">(</span><span class="s">"Received error while sending ModifyFeatureDesiredProperties: '{}' "</span><span class="o">,</span>
<span class="n">throwable</span><span class="o">.</span><span class="na">toString</span><span class="o">());</span>
<span class="o">}</span> <span class="k">else</span> <span class="o">{</span>
<span class="n">LOGGER</span><span class="o">.</span><span class="na">info</span><span class="o">(</span><span class="s">"Received response for ModifyFeatureDesiredProperties: '{}'"</span><span class="o">,</span> <span class="n">adaptable</span><span class="o">);</span>
<span class="o">}</span>
<span class="o">}));</span>
</code></pre></div></div>
<h2 id="feedback">Feedback?</h2>
<p>Please <a href="feedback.html">get in touch</a> if you have feedback or questions towards this new concept of desired properties.</p>
<p><br />
<br /></p>
<figure><img class="docimage" src="images/ditto.svg" alt="Ditto" style="max-width: 500px" /></figure>
<p><br />
The Eclipse Ditto team</p>
</div>
</article>
<hr class="shaded"/>
<footer>
<div class="row">
<div class="col-lg-12 footer">
<div class="logo">
<a href="https://eclipse.org"><img src="images/eclipse_foundation_logo.svg" alt="Eclipse logo"/></a>
</div>
<p class="notice">
&copy;2020 Eclipse Ditto.
Site last generated: Dec 9, 2020 <br />
</p>
<div class="quickLinks">
<a href="https://www.eclipse.org/legal/privacy.php" target="_blank">
&gt; Privacy Policy
</a>
<a href="https://www.eclipse.org/legal/termsofuse.php" target="_blank">
&gt; Terms of Use
</a>
<a href="https://www.eclipse.org/legal/copyright.php" target="_blank">
&gt; Copyright Agent
</a>
<a href="https://www.eclipse.org/legal" target="_blank">
&gt; Legal
</a>
<a href="https://www.eclipse.org/legal/epl-2.0/" target="_blank">
&gt; License
</a>
<a href="https://eclipse.org/security" target="_blank">
&gt; Report a Vulnerability
</a>
</div>
</div>
</div>
</footer>
</div>
<!-- /.row -->
</div>
<!-- /.container -->
</div>
<!-- /#main -->
</div>
</body>
</html>