blob: 9efbe1bcc00ae85852a288b28673e58ee4baf769 [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="client_sdk, ">
<title> Client SDK Java • Eclipse Ditto • a digital twin framework</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="Client SDK Java">{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">
<!-- Sidebar Column -->
<div class="col-md-3" id="tg-sb-sidebar">
<ul id="mysidebar" class="nav">
<li class="sidebarTitle">
<label for="docVersion">Eclipse Ditto version:</label>
<div class="select-wrapper">
<select id="docVersion" name="docVersion">
<option value="">development</option>
<option value="1.0">1.0</option>
<option value="1.1">1.1</option>
<option value="1.2">1.2</option>
<option value="1.3">1.3</option>
<option value="1.4">1.4</option>
</select>
</div>
<div id="dev-warning">
<div markdown="span" class="alert alert-warning" role="alert" style="font-size:0.6em"><i class="fa fa-warning"></i> <b>Important:</b> This documentation reflects the latest 'development'. You might want to choose a released version.</div>
</div>
</li>
<li class="subfolders">
<a href="#"><span></span>Introduction</a>
<ul>
<li><a href="intro-overview.html">Overview</a></li>
<li><a href="intro-digitaltwins.html">Digital twins</a></li>
<li><a href="intro-hello-world.html">Hello world</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>Release Notes</a>
<ul>
<li><a href="release_notes_130.html">1.3.0</a></li>
<li><a href="release_notes_121.html">1.2.1</a></li>
<li><a href="release_notes_120.html">1.2.0</a></li>
<li><a href="release_notes_115.html">1.1.5</a></li>
<li><a href="release_notes_113.html">1.1.3</a></li>
<li><a href="release_notes_112.html">1.1.2</a></li>
<li><a href="release_notes_111.html">1.1.1</a></li>
<li><a href="release_notes_110.html">1.1.0</a></li>
<li><a href="release_notes_100.html">1.0.0</a></li>
<li><a href="release_notes_090.html">0.9.0</a></li>
<li><a href="release_notes_080.html">0.8.0</a></li>
<li class="subfolders">
<a href="#"><span></span>Milestone releases</a>
<ul>
<li><a href="release_notes_100-M2.html">1.0.0-M2</a></li>
<li><a href="release_notes_100-M1a.html">1.0.0-M1a</a></li>
<li><a href="release_notes_090-M2.html">0.9.0-M2</a></li>
<li><a href="release_notes_090-M1.html">0.9.0-M1</a></li>
<li><a href="release_notes_080-M3.html">0.8.0-M3</a></li>
<li><a href="release_notes_080-M2.html">0.8.0-M2</a></li>
<li><a href="release_notes_080-M1.html">0.8.0-M1</a></li>
<li><a href="release_notes_030-M2.html">0.3.0-M2</a></li>
<li><a href="release_notes_030-M1.html">0.3.0-M1</a></li>
<li><a href="release_notes_020-M1.html">0.2.0-M1</a></li>
<li><a href="release_notes_010-M3.html">0.1.0-M3</a></li>
<li><a href="release_notes_010-M1.html">0.1.0-M1</a></li>
</ul>
</li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>Installation</a>
<ul>
<li><a href="installation-building.html">Building Ditto</a></li>
<li><a href="installation-running.html">Running Ditto</a></li>
<li><a href="installation-operating.html">Operating Ditto</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>Basic concepts</a>
<ul>
<li><a href="basic-overview.html">Overview</a></li>
<li class="subfolders">
<a href="#"><span></span>Model entities</a>
<ul>
<li><a href="basic-thing.html">Thing</a></li>
<li><a href="basic-acl.html">Access Control List (ACL)</a></li>
<li><a href="basic-feature.html">Feature</a></li>
<li><a href="basic-policy.html">Policy</a></li>
<li><a href="basic-namespaces-and-names.html">Namespaces and Names</a></li>
<li><a href="basic-metadata.html">Thing Metadata</a></li>
<li><a href="basic-errors.html">Errors</a></li>
</ul>
</li>
<li><a href="basic-auth.html">Authentication and Authorization</a></li>
<li><a href="basic-messages.html">Messages</a></li>
<li><a href="basic-signals.html">Signals</a></li>
<li class="subfolders">
<a href="#"><span></span>Signal types</a>
<ul>
<li><a href="basic-signals-command.html">Command</a></li>
<li><a href="basic-signals-commandresponse.html">Command response</a></li>
<li><a href="basic-signals-errorresponse.html">Error response</a></li>
<li><a href="basic-signals-event.html">Event</a></li>
</ul>
</li>
<li><a href="basic-apis.html">APIs</a></li>
<li><a href="basic-connections.html">Connections</a></li>
<li><a href="basic-placeholders.html">Placeholders</a></li>
<li><a href="basic-changenotifications.html">Change notifications</a></li>
<li><a href="basic-rql.html">RQL expressions</a></li>
<li><a href="basic-enrichment.html">Signal enrichment</a></li>
<li><a href="basic-search.html">Search</a></li>
<li><a href="basic-acknowledgements.html">Acknowledgements / QoS</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>Architecture</a>
<ul>
<li><a href="architecture-overview.html">Overview</a></li>
<li class="subfolders">
<a href="#"><span></span>Services</a>
<ul>
<li><a href="architecture-services-policies.html">Policies</a></li>
<li><a href="architecture-services-things.html">Things</a></li>
<li><a href="architecture-services-things-search.html">Things-Search</a></li>
<li><a href="architecture-services-connectivity.html">Connectivity</a></li>
<li><a href="architecture-services-concierge.html">Concierge</a></li>
<li><a href="architecture-services-gateway.html">Gateway</a></li>
</ul>
</li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>HTTP API</a>
<ul>
<li><a href="httpapi-overview.html">Overview</a></li>
<li><a href="httpapi-concepts.html">Concepts</a></li>
<li><a href="httpapi-search.html">Search</a></li>
<li><a href="httpapi-messages.html">Messages</a></li>
<li><a href="httpapi-protocol-bindings-websocket.html">WebSocket protocol binding</a></li>
<li><a href="httpapi-sse.html">Server sent events</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>Connectivity API</a>
<ul>
<li><a href="connectivity-overview.html">Overview</a></li>
<li><a href="connectivity-manage-connections.html">Manage connections</a></li>
<li><a href="connectivity-protocol-bindings-amqp091.html">AMQP 0.9.1 protocol binding</a></li>
<li><a href="connectivity-protocol-bindings-amqp10.html">AMQP 1.0 protocol binding</a></li>
<li><a href="connectivity-protocol-bindings-mqtt.html">MQTT 3.1.1 protocol binding</a></li>
<li><a href="connectivity-protocol-bindings-mqtt5.html">MQTT 5 protocol binding</a></li>
<li><a href="connectivity-protocol-bindings-http.html">HTTP 1.1 protocol binding</a></li>
<li><a href="connectivity-protocol-bindings-kafka2.html">Kafka 2.x protocol binding</a></li>
<li><a href="connectivity-mapping.html">Payload mapping</a></li>
<li><a href="connectivity-header-mapping.html">Header mapping</a></li>
<li><a href="connectivity-tls-certificates.html">TLS certificates</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>Client SDK</a>
<ul>
<li><a href="client-sdk-overview.html">Overview</a></li>
<li class="active"><a href="client-sdk-java.html">Java</a></li>
<li><a href="client-sdk-javascript.html">JavaScript</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>Ditto Protocol</a>
<ul>
<li><a href="protocol-overview.html">Overview</a></li>
<li><a href="protocol-twinlive.html">Twin/live channel</a></li>
<li><a href="protocol-specification.html">Specification</a></li>
<li><a href="protocol-specification-topic.html">Protocol topic</a></li>
<li><a href="protocol-specification-things.html">Things group</a></li>
<li class="subfolders">
<a href="#"><span></span>→ commands/events</a>
<ul>
<li><a href="protocol-specification-things-create-or-modify.html">Create/Modify</a></li>
<li><a href="protocol-specification-things-retrieve.html">Retrieve</a></li>
<li><a href="protocol-specification-things-delete.html">Delete</a></li>
<li><a href="protocol-specification-acks.html">Acknowledgements</a></li>
<li><a href="protocol-specification-errors.html">Errors</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>→ search/messages</a>
<ul>
<li><a href="protocol-specification-things-search.html">Search</a></li>
<li><a href="protocol-specification-things-messages.html">Messages</a></li>
</ul>
</li>
<li><a href="protocol-specification-policies.html">Policies group</a></li>
<li class="subfolders">
<a href="#"><span></span>→ commands/events</a>
<ul>
<li><a href="protocol-specification-policies-create-or-modify.html">Create/Modify</a></li>
<li><a href="protocol-specification-policies-retrieve.html">Retrieve</a></li>
<li><a href="protocol-specification-policies-delete.html">Delete</a></li>
</ul>
</li>
<li><a href="protocol-bindings.html">Bindings</a></li>
<li><a href="protocol-examples.html">Examples</a></li>
<li class="subfolders">
<a href="#"><span></span>→ Things examples</a>
<ul>
<li><a href="protocol-examples-creatething.html">Create a Thing</a></li>
<li><a href="protocol-examples-deletething.html">Delete a Thing</a></li>
<li><a href="protocol-examples-modifything.html">Modify a Thing</a></li>
<li><a href="protocol-examples-retrievething.html">Retrieve a Thing</a></li>
<li><a href="protocol-examples-retrievethings.html">Retrieve multiple Things</a></li>
<li><a href="protocol-examples-modifypolicyid.html">Modify the Policy ID of a Thing</a></li>
<li><a href="protocol-examples-createattributes.html">Create Attributes</a></li>
<li><a href="protocol-examples-deleteattributes.html">Delete Attributes</a></li>
<li><a href="protocol-examples-modifyattributes.html">Modify Attributes</a></li>
<li><a href="protocol-examples-retrieveattributes.html">Retrieve Attributes</a></li>
<li><a href="protocol-examples-createattribute.html">Create a single Attribute</a></li>
<li><a href="protocol-examples-deleteattribute.html">Delete a single Attribute</a></li>
<li><a href="protocol-examples-modifyattribute.html">Modify a single Attribute</a></li>
<li><a href="protocol-examples-retrieveattribute.html">Retrieve a single Attribute</a></li>
<li><a href="protocol-examples-createthingdefinition.html">Create a Definition</a></li>
<li><a href="protocol-examples-deletethingdefinition.html">Delete a Definition</a></li>
<li><a href="protocol-examples-modifythingdefinition.html">Modify a Definition</a></li>
<li><a href="protocol-examples-retrievethingdefinition.html">Retrieve a Definition</a></li>
<li><a href="protocol-examples-createfeatures.html">Create Features</a></li>
<li><a href="protocol-examples-deletefeatures.html">Delete Features</a></li>
<li><a href="protocol-examples-modifyfeatures.html">Modify Features</a></li>
<li><a href="protocol-examples-retrievefeatures.html">Retrieve Features</a></li>
<li><a href="protocol-examples-createfeature.html">Create a single Feature</a></li>
<li><a href="protocol-examples-deletefeature.html">Delete a single Feature</a></li>
<li><a href="protocol-examples-modifyfeature.html">Modify a single Feature</a></li>
<li><a href="protocol-examples-retrievefeature.html">Retrieve a single Feature</a></li>
<li><a href="protocol-examples-createdefinition.html">Create Feature Definition</a></li>
<li><a href="protocol-examples-deletedefinition.html">Delete Feature Definition</a></li>
<li><a href="protocol-examples-modifydefinition.html">Modify Feature Definition</a></li>
<li><a href="protocol-examples-retrievedefinition.html">Retrieve Feature Definition</a></li>
<li><a href="protocol-examples-createproperties.html">Create Feature Properties</a></li>
<li><a href="protocol-examples-deleteproperties.html">Delete Feature Properties</a></li>
<li><a href="protocol-examples-modifyproperties.html">Modify Feature Properties</a></li>
<li><a href="protocol-examples-retrieveproperties.html">Retrieve Feature Properties</a></li>
<li><a href="protocol-examples-createproperty.html">Create a single Property</a></li>
<li><a href="protocol-examples-deleteproperty.html">Delete a single Property</a></li>
<li><a href="protocol-examples-modifyproperty.html">Modify a single Property</a></li>
<li><a href="protocol-examples-retrieveproperty.html">Retrieve a single Property</a></li>
<li><a href="protocol-examples-errorresponses.html">Error responses</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>→ Policies examples</a>
<ul>
<li><a href="protocol-examples-policies-createpolicy.html">Create a Policy</a></li>
<li><a href="protocol-examples-policies-deletepolicy.html">Delete a Policy</a></li>
<li><a href="protocol-examples-policies-modifypolicy.html">Modify a Policy</a></li>
<li><a href="protocol-examples-policies-retrievepolicy.html">Retrieve a Policy</a></li>
<li><a href="protocol-examples-policies-modifypolicyentries.html">Modify entries</a></li>
<li><a href="protocol-examples-policies-retrievepolicyentries.html">Retrieve entries</a></li>
<li><a href="protocol-examples-policies-createpolicyentry.html">Create a single entry</a></li>
<li><a href="protocol-examples-policies-deletepolicyentry.html">Delete a single entry</a></li>
<li><a href="protocol-examples-policies-modifypolicyentry.html">Modify a single entry</a></li>
<li><a href="protocol-examples-policies-retrievepolicyentry.html">Retrieve a single entry</a></li>
<li><a href="protocol-examples-policies-modifysubjects.html">Modify subjects</a></li>
<li><a href="protocol-examples-policies-retrievesubjects.html">Retrieve subjects</a></li>
<li><a href="protocol-examples-policies-createsubject.html">Create a single subject</a></li>
<li><a href="protocol-examples-policies-deletesubject.html">Delete a single subject</a></li>
<li><a href="protocol-examples-policies-modifysubject.html">Modify a single subject</a></li>
<li><a href="protocol-examples-policies-retrievesubject.html">Retrieve a single subject</a></li>
<li><a href="protocol-examples-policies-modifyresources.html">Modify resources</a></li>
<li><a href="protocol-examples-policies-retrieveresources.html">Retrieve resources</a></li>
<li><a href="protocol-examples-policies-createresource.html">Create a single resource</a></li>
<li><a href="protocol-examples-policies-deleteresource.html">Delete a single resource</a></li>
<li><a href="protocol-examples-policies-modifyresource.html">Modify a single resource</a></li>
<li><a href="protocol-examples-policies-retrieveresource.html">Retrieve a single resource</a></li>
<li><a href="protocol-examples-policies-errorresponses.html">Error responses</a></li>
</ul>
</li>
<li><a href="protocol-examples-search.html">→ Search examples</a></li>
</ul>
</li>
<li><a href="sandbox.html">Sandbox</a></li>
<li><a href="presentations.html">Presentations</a></li>
<li><a href="glossary.html">Glossary</a></li>
<li><a href="feedback.html">Feedback</a></li>
<p class="external">
<a href="#" id="collapseAll">Collapse All</a> | <a href="#" id="expandAll">Expand All</a>
</p>
</ul>
<!-- this highlights the active parent class in the sidebar. this is critical so that the parent expands when you're viewing a page. This must appear below the sidebar code above. Otherwise, if placed inside customscripts.js, the script runs before the sidebar code runs and the class never gets inserted.-->
<script>$("li.active").parents('li').toggleClass("active");
</script>
</div>
<!-- Content Column -->
<div class="col-md-9" id="tg-sb-content">
<div class="post-header">
<h1 class="post-title-main">Client SDK Java</h1>
</div>
<div class="post-content">
<!-- 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>
<p>A client SDK for Java in order to interact with digital twins provided by an Eclipse Ditto backend.</p>
<h2 id="features">Features</h2>
<ul>
<li>Digital twin management: CRUD (create, read, update, delete) of Ditto <a href="https://www.eclipse.org/ditto/basic-thing.html">things</a></li>
<li><a href="https://www.eclipse.org/ditto/basic-changenotifications.html">Change notifications</a>:
consume notifications whenever a “watched” digital twin is modified</li>
<li>Send/receive <a href="https://www.eclipse.org/ditto/basic-messages.html">messages</a> to/from devices connected via a digital twin</li>
<li>Use the <a href="https://www.eclipse.org/ditto/protocol-twinlive.html#live">live channel</a> in order to react on commands directed
to devices targeting their “live” state</li>
</ul>
<h2 id="communication-channel">Communication channel</h2>
<p>The Ditto Java client interacts with an Eclipse Ditto backend via Ditto’s
<a href="https://www.eclipse.org/ditto/httpapi-protocol-bindings-websocket.html">WebSocket</a> sending and receiving messages
in <a href="https://www.eclipse.org/ditto/protocol-overview.html">Ditto Protocol</a>.</p>
<h2 id="usage">Usage</h2>
<p>Maven coordinates:</p>
<div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt">&lt;dependency&gt;</span>
<span class="nt">&lt;groupId&gt;</span>org.eclipse.ditto<span class="nt">&lt;/groupId&gt;</span>
<span class="nt">&lt;artifactId&gt;</span>ditto-client<span class="nt">&lt;/artifactId&gt;</span>
<span class="nt">&lt;version&gt;</span>${ditto-client.version}<span class="nt">&lt;/version&gt;</span>
<span class="nt">&lt;/dependency&gt;</span>
</code></pre></div></div>
<h3 id="instantiate--configure-a-new-ditto-client">Instantiate &amp; configure a new Ditto client</h3>
<p>To configure your Ditto client instance, use the <code class="highlighter-rouge">org.eclipse.ditto.client.configuration</code> package in order to</p>
<ul>
<li>create instances of <code class="highlighter-rouge">AuthenticationProvider</code> and <code class="highlighter-rouge">MessagingProvider</code></li>
<li>create a <code class="highlighter-rouge">DittoClient</code> instance</li>
</ul>
<p>For example:</p>
<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">ProxyConfiguration</span> <span class="n">proxyConfiguration</span> <span class="o">=</span>
<span class="n">ProxyConfiguration</span><span class="o">.</span><span class="na">newBuilder</span><span class="o">()</span>
<span class="o">.</span><span class="na">proxyHost</span><span class="o">(</span><span class="s">"localhost"</span><span class="o">)</span>
<span class="o">.</span><span class="na">proxyPort</span><span class="o">(</span><span class="mi">3128</span><span class="o">)</span>
<span class="o">.</span><span class="na">build</span><span class="o">();</span>
<span class="n">AuthenticationProvider</span> <span class="n">authenticationProvider</span> <span class="o">=</span>
<span class="n">AuthenticationProviders</span><span class="o">.</span><span class="na">clientCredentials</span><span class="o">(</span><span class="n">ClientCredentialsAuthenticationConfiguration</span><span class="o">.</span><span class="na">newBuilder</span><span class="o">()</span>
<span class="o">.</span><span class="na">clientId</span><span class="o">(</span><span class="s">"my-oauth-client-id"</span><span class="o">)</span>
<span class="o">.</span><span class="na">clientSecret</span><span class="o">(</span><span class="s">"my-oauth-client-secret"</span><span class="o">)</span>
<span class="o">.</span><span class="na">scopes</span><span class="o">(</span><span class="s">"offline_access email"</span><span class="o">)</span>
<span class="o">.</span><span class="na">tokenEndpoint</span><span class="o">(</span><span class="s">"https://my-oauth-provider/oauth/token"</span><span class="o">)</span>
<span class="c1">// optionally configure a proxy server</span>
<span class="o">.</span><span class="na">proxyConfiguration</span><span class="o">(</span><span class="n">proxyConfiguration</span><span class="o">)</span>
<span class="o">.</span><span class="na">build</span><span class="o">());</span>
<span class="n">MessagingProvider</span> <span class="n">messagingProvider</span> <span class="o">=</span>
<span class="n">MessagingProviders</span><span class="o">.</span><span class="na">webSocket</span><span class="o">(</span><span class="n">WebSocketMessagingConfiguration</span><span class="o">.</span><span class="na">newBuilder</span><span class="o">()</span>
<span class="o">.</span><span class="na">endpoint</span><span class="o">(</span><span class="s">"wss://ditto.eclipse.org"</span><span class="o">)</span>
<span class="o">.</span><span class="na">jsonSchemaVersion</span><span class="o">(</span><span class="n">JsonSchemaVersion</span><span class="o">.</span><span class="na">V_2</span><span class="o">)</span>
<span class="c1">// optionally configure a proxy server or a truststore containing the trusted CAs for SSL connection establishment</span>
<span class="o">.</span><span class="na">proxyConfiguration</span><span class="o">(</span><span class="n">proxyConfiguration</span><span class="o">)</span>
<span class="o">.</span><span class="na">trustStoreConfiguration</span><span class="o">(</span><span class="n">TrustStoreConfiguration</span><span class="o">.</span><span class="na">newBuilder</span><span class="o">()</span>
<span class="o">.</span><span class="na">location</span><span class="o">(</span><span class="n">TRUSTSTORE_LOCATION</span><span class="o">)</span>
<span class="o">.</span><span class="na">password</span><span class="o">(</span><span class="n">TRUSTSTORE_PASSWORD</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">build</span><span class="o">(),</span> <span class="n">authenticationProvider</span><span class="o">);</span>
<span class="n">DittoClient</span> <span class="n">client</span> <span class="o">=</span> <span class="n">DittoClients</span><span class="o">.</span><span class="na">newInstance</span><span class="o">(</span><span class="n">messagingProvider</span><span class="o">);</span>
</code></pre></div></div>
<h3 id="use-the-ditto-client">Use the Ditto client</h3>
<h4 id="manage-twins">Manage twins</h4>
<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">client</span><span class="o">.</span><span class="na">twin</span><span class="o">().</span><span class="na">create</span><span class="o">(</span><span class="s">"org.eclipse.ditto:new-thing"</span><span class="o">).</span><span class="na">handle</span><span class="o">((</span><span class="n">createdThing</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">createdThing</span> <span class="o">!=</span> <span class="kc">null</span><span class="o">)</span> <span class="o">{</span>
<span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"Created new thing: "</span> <span class="o">+</span> <span class="n">createdThing</span><span class="o">);</span>
<span class="o">}</span> <span class="k">else</span> <span class="o">{</span>
<span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"Thing could not be created due to: "</span> <span class="o">+</span> <span class="n">throwable</span><span class="o">.</span><span class="na">getMessage</span><span class="o">());</span>
<span class="o">}</span>
<span class="k">return</span> <span class="n">client</span><span class="o">.</span><span class="na">twin</span><span class="o">().</span><span class="na">forId</span><span class="o">(</span><span class="n">thingId</span><span class="o">).</span><span class="na">putAttribute</span><span class="o">(</span><span class="s">"first-updated-at"</span><span class="o">,</span> <span class="n">OffsetDateTime</span><span class="o">.</span><span class="na">now</span><span class="o">().</span><span class="na">toString</span><span class="o">());</span>
<span class="o">}).</span><span class="na">get</span><span class="o">();</span> <span class="c1">// this will block the thread! work asynchronously whenever possible!</span>
</code></pre></div></div>
<h4 id="subscribe-for-change-notifications">Subscribe for change notifications</h4>
<p>In order to subscribe for <a href="basic-signals-event.html">events</a> emitted by Ditto after a twin was modified, start the
consumption on the <code class="highlighter-rouge">twin</code> channel:</p>
<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">client</span><span class="o">.</span><span class="na">twin</span><span class="o">().</span><span class="na">startConsumption</span><span class="o">().</span><span class="na">get</span><span class="o">();</span>
<span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"Subscribed for Twin events"</span><span class="o">);</span>
<span class="n">client</span><span class="o">.</span><span class="na">twin</span><span class="o">().</span><span class="na">registerForThingChanges</span><span class="o">(</span><span class="s">"my-changes"</span><span class="o">,</span> <span class="n">change</span> <span class="o">-&gt;</span> <span class="o">{</span>
<span class="k">if</span> <span class="o">(</span><span class="n">change</span><span class="o">.</span><span class="na">getAction</span><span class="o">()</span> <span class="o">==</span> <span class="n">ChangeAction</span><span class="o">.</span><span class="na">CREATED</span><span class="o">)</span> <span class="o">{</span>
<span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"An existing Thing was modified: "</span> <span class="o">+</span> <span class="n">change</span><span class="o">.</span><span class="na">getThing</span><span class="o">());</span>
<span class="c1">// perform custom actions ..</span>
<span class="o">}</span>
<span class="o">});</span>
</code></pre></div></div>
<p>There is also the possibility here to apply <em>server side filtering</em> of which events will get delivered to the client:</p>
<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">client</span><span class="o">.</span><span class="na">twin</span><span class="o">().</span><span class="na">startConsumption</span><span class="o">(</span>
<span class="n">Options</span><span class="o">.</span><span class="na">Consumption</span><span class="o">.</span><span class="na">filter</span><span class="o">(</span><span class="s">"gt(features/temperature/properties/value,23.0)"</span><span class="o">)</span>
<span class="o">).</span><span class="na">get</span><span class="o">();</span>
<span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"Subscribed for Twin events"</span><span class="o">);</span>
<span class="n">client</span><span class="o">.</span><span class="na">twin</span><span class="o">().</span><span class="na">registerForFeaturePropertyChanges</span><span class="o">(</span><span class="s">"my-feature-changes"</span><span class="o">,</span> <span class="s">"temperature"</span><span class="o">,</span> <span class="s">"value"</span><span class="o">,</span> <span class="n">change</span> <span class="o">-&gt;</span> <span class="o">{</span>
<span class="c1">// perform custom actions ..</span>
<span class="o">});</span>
</code></pre></div></div>
<h5 id="subscribe-to-enriched-change-notifications">Subscribe to enriched change notifications</h5>
<div class="bs-callout bs-callout-primary">Available since Ditto <strong>1.1.0</strong></div>
<p>In order to use <a href="basic-enrichment.html">enrichment</a> in the Ditto Java client, the <code class="highlighter-rouge">startConsumption()</code> call can be
enhanced with the additional extra fields:</p>
<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">client</span><span class="o">.</span><span class="na">twin</span><span class="o">().</span><span class="na">startConsumption</span><span class="o">(</span>
<span class="n">Options</span><span class="o">.</span><span class="na">Consumption</span><span class="o">.</span><span class="na">extraFields</span><span class="o">(</span><span class="n">JsonFieldSelector</span><span class="o">.</span><span class="na">newInstance</span><span class="o">(</span><span class="s">"attributes/location"</span><span class="o">))</span>
<span class="o">).</span><span class="na">get</span><span class="o">();</span>
<span class="n">client</span><span class="o">.</span><span class="na">twin</span><span class="o">().</span><span class="na">registerForThingChanges</span><span class="o">(</span><span class="s">"my-enriched-changes"</span><span class="o">,</span> <span class="n">change</span> <span class="o">-&gt;</span> <span class="o">{</span>
<span class="n">Optional</span><span class="o">&lt;</span><span class="n">JsonObject</span><span class="o">&gt;</span> <span class="n">extra</span> <span class="o">=</span> <span class="n">change</span><span class="o">.</span><span class="na">getExtra</span><span class="o">();</span>
<span class="c1">// perform custom actions, making use of the 'extra' data ..</span>
<span class="o">});</span>
</code></pre></div></div>
<p>In combination with a <code class="highlighter-rouge">filter</code>, the extra fields may also be used as part of such a filter:</p>
<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">client</span><span class="o">.</span><span class="na">twin</span><span class="o">().</span><span class="na">startConsumption</span><span class="o">(</span>
<span class="n">Options</span><span class="o">.</span><span class="na">Consumption</span><span class="o">.</span><span class="na">extraFields</span><span class="o">(</span><span class="n">JsonFieldSelector</span><span class="o">.</span><span class="na">newInstance</span><span class="o">(</span><span class="s">"attributes/location"</span><span class="o">)),</span>
<span class="n">Options</span><span class="o">.</span><span class="na">Consumption</span><span class="o">.</span><span class="na">filter</span><span class="o">(</span><span class="s">"eq(attributes/location,\"kitchen\")"</span><span class="o">)</span>
<span class="o">).</span><span class="na">get</span><span class="o">();</span>
<span class="c1">// register the callbacks...</span>
</code></pre></div></div>
<h4 id="sendreceive-messages">Send/receive messages</h4>
<p>Register for receiving messages with the subject <code class="highlighter-rouge">hello.world</code> on any thing:</p>
<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">client</span><span class="o">.</span><span class="na">live</span><span class="o">().</span><span class="na">registerForMessage</span><span class="o">(</span><span class="s">"globalMessageHandler"</span><span class="o">,</span> <span class="s">"hello.world"</span><span class="o">,</span> <span class="n">message</span> <span class="o">-&gt;</span> <span class="o">{</span>
<span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"Received Message with subject "</span> <span class="o">+</span> <span class="n">message</span><span class="o">.</span><span class="na">getSubject</span><span class="o">());</span>
<span class="n">message</span><span class="o">.</span><span class="na">reply</span><span class="o">()</span>
<span class="o">.</span><span class="na">statusCode</span><span class="o">(</span><span class="n">HttpStatusCode</span><span class="o">.</span><span class="na">IM_A_TEAPOT</span><span class="o">)</span>
<span class="o">.</span><span class="na">payload</span><span class="o">(</span><span class="s">"Hello, I'm just a Teapot!"</span><span class="o">)</span>
<span class="o">.</span><span class="na">send</span><span class="o">();</span>
<span class="o">});</span>
</code></pre></div></div>
<p>Send a message with the subject <code class="highlighter-rouge">hello.world</code> to the thing with ID <code class="highlighter-rouge">org.eclipse.ditto:new-thing</code>:</p>
<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">client</span><span class="o">.</span><span class="na">live</span><span class="o">().</span><span class="na">forId</span><span class="o">(</span><span class="s">"org.eclipse.ditto:new-thing"</span><span class="o">)</span>
<span class="o">.</span><span class="na">message</span><span class="o">()</span>
<span class="o">.</span><span class="na">from</span><span class="o">()</span>
<span class="o">.</span><span class="na">subject</span><span class="o">(</span><span class="s">"hello.world"</span><span class="o">)</span>
<span class="o">.</span><span class="na">payload</span><span class="o">(</span><span class="s">"I am a Teapot"</span><span class="o">)</span>
<span class="o">.</span><span class="na">send</span><span class="o">(</span><span class="n">String</span><span class="o">.</span><span class="na">class</span><span class="o">,</span> <span class="o">(</span><span class="n">response</span><span class="o">,</span> <span class="n">throwable</span><span class="o">)</span> <span class="o">-&gt;</span>
<span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"Got response: "</span> <span class="o">+</span> <span class="n">response</span><span class="o">.</span><span class="na">getPayload</span><span class="o">().</span><span class="na">orElse</span><span class="o">(</span><span class="kc">null</span><span class="o">))</span>
<span class="o">);</span>
</code></pre></div></div>
<h4 id="manage-policies">Manage policies</h4>
<div class="bs-callout bs-callout-primary">Available since Ditto <strong>1.1.0</strong></div>
<p>Read a policy:</p>
<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">Policy</span> <span class="n">retrievedPolicy</span> <span class="o">=</span> <span class="n">client</span><span class="o">.</span><span class="na">policies</span><span class="o">().</span><span class="na">retrieve</span><span class="o">(</span><span class="n">PolicyId</span><span class="o">.</span><span class="na">of</span><span class="o">(</span><span class="s">"org.eclipse.ditto:new-policy"</span><span class="o">))</span>
<span class="o">.</span><span class="na">get</span><span class="o">();</span> <span class="c1">// this will block the thread! work asynchronously whenever possible!</span>
</code></pre></div></div>
<p>Create a policy:</p>
<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">Policy</span> <span class="n">newPolicy</span> <span class="o">=</span> <span class="n">Policy</span><span class="o">.</span><span class="na">newBuilder</span><span class="o">(</span><span class="n">PolicyId</span><span class="o">.</span><span class="na">of</span><span class="o">(</span><span class="s">"org.eclipse.ditto:new-policy"</span><span class="o">))</span>
<span class="o">.</span><span class="na">forLabel</span><span class="o">(</span><span class="s">"DEFAULT"</span><span class="o">)</span>
<span class="o">.</span><span class="na">setSubject</span><span class="o">(</span><span class="n">Subject</span><span class="o">.</span><span class="na">newInstance</span><span class="o">(</span><span class="n">SubjectIssuer</span><span class="o">.</span><span class="na">newInstance</span><span class="o">(</span><span class="s">"nginx"</span><span class="o">),</span> <span class="s">"ditto"</span><span class="o">))</span>
<span class="o">.</span><span class="na">setGrantedPermissions</span><span class="o">(</span><span class="n">PoliciesResourceType</span><span class="o">.</span><span class="na">policyResource</span><span class="o">(</span><span class="s">"/"</span><span class="o">),</span> <span class="s">"READ"</span><span class="o">,</span> <span class="s">"WRITE"</span><span class="o">)</span>
<span class="o">.</span><span class="na">setGrantedPermissions</span><span class="o">(</span><span class="n">PoliciesResourceType</span><span class="o">.</span><span class="na">thingResource</span><span class="o">(</span><span class="s">"/"</span><span class="o">),</span> <span class="s">"READ"</span><span class="o">,</span> <span class="s">"WRITE"</span><span class="o">)</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">policies</span><span class="o">().</span><span class="na">create</span><span class="o">(</span><span class="n">newPolicy</span><span class="o">)</span>
<span class="o">.</span><span class="na">get</span><span class="o">();</span> <span class="c1">// this will block the thread! work asynchronously whenever possible!</span>
</code></pre></div></div>
<p>Updating and deleting policies is also possible via the Java client API, please follow the API and the JavaDoc.</p>
<h4 id="search-for-things">Search for things</h4>
<div class="bs-callout bs-callout-primary">Available since Ditto <strong>1.1.0</strong></div>
<p>Search for things using the Java 8 <code class="highlighter-rouge">java.util.Stream</code> API:</p>
<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">client</span><span class="o">.</span><span class="na">twin</span><span class="o">().</span><span class="na">search</span><span class="o">()</span>
<span class="o">.</span><span class="na">stream</span><span class="o">(</span><span class="n">queryBuilder</span> <span class="o">-&gt;</span> <span class="n">queryBuilder</span><span class="o">.</span><span class="na">namespace</span><span class="o">(</span><span class="s">"org.eclipse.ditto"</span><span class="o">)</span>
<span class="o">.</span><span class="na">filter</span><span class="o">(</span><span class="s">"eq(attributes/location,'kitchen')"</span><span class="o">)</span> <span class="c1">// apply RQL expression here</span>
<span class="o">.</span><span class="na">options</span><span class="o">(</span><span class="n">builder</span> <span class="o">-&gt;</span> <span class="n">builder</span><span class="o">.</span><span class="na">sort</span><span class="o">(</span><span class="n">s</span> <span class="o">-&gt;</span> <span class="n">s</span><span class="o">.</span><span class="na">desc</span><span class="o">(</span><span class="s">"thingId"</span><span class="o">)).</span><span class="na">size</span><span class="o">(</span><span class="mi">1</span><span class="o">))</span>
<span class="o">)</span>
<span class="o">.</span><span class="na">forEach</span><span class="o">(</span><span class="n">foundThing</span> <span class="o">-&gt;</span> <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"Found thing: "</span> <span class="o">+</span> <span class="n">foundThing</span><span class="o">));</span>
</code></pre></div></div>
<p>Use an <a href="basic-rql.html">RQL</a> query in order to filter for the searched things.</p>
<p>Search for things using the reactive streams <code class="highlighter-rouge">org.reactivestreams.Publisher</code> API:</p>
<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">Publisher</span><span class="o">&lt;</span><span class="n">List</span><span class="o">&lt;</span><span class="n">Thing</span><span class="o">&gt;&gt;</span> <span class="n">publisher</span> <span class="o">=</span> <span class="n">client</span><span class="o">.</span><span class="na">twin</span><span class="o">().</span><span class="na">search</span><span class="o">()</span>
<span class="o">.</span><span class="na">publisher</span><span class="o">(</span><span class="n">queryBuilder</span> <span class="o">-&gt;</span> <span class="n">queryBuilder</span><span class="o">.</span><span class="na">namespace</span><span class="o">(</span><span class="s">"org.eclipse.ditto"</span><span class="o">)</span>
<span class="o">.</span><span class="na">filter</span><span class="o">(</span><span class="s">"eq(attributes/location,'kitchen')"</span><span class="o">)</span> <span class="c1">// apply RQL expression here</span>
<span class="o">.</span><span class="na">options</span><span class="o">(</span><span class="n">builder</span> <span class="o">-&gt;</span> <span class="n">builder</span><span class="o">.</span><span class="na">sort</span><span class="o">(</span><span class="n">s</span> <span class="o">-&gt;</span> <span class="n">s</span><span class="o">.</span><span class="na">desc</span><span class="o">(</span><span class="s">"thingId"</span><span class="o">)).</span><span class="na">size</span><span class="o">(</span><span class="mi">1</span><span class="o">))</span>
<span class="o">);</span>
<span class="c1">// integrate the publisher in the reactive streams library of your choice, e.g. Akka streams:</span>
<span class="n">akka</span><span class="o">.</span><span class="na">stream</span><span class="o">.</span><span class="na">javadsl</span><span class="o">.</span><span class="na">Source</span><span class="o">&lt;</span><span class="n">Thing</span><span class="o">,</span> <span class="n">NotUsed</span><span class="o">&gt;</span> <span class="n">things</span> <span class="o">=</span> <span class="n">akka</span><span class="o">.</span><span class="na">stream</span><span class="o">.</span><span class="na">javadsl</span><span class="o">.</span><span class="na">Source</span><span class="o">.</span><span class="na">fromPublisher</span><span class="o">(</span><span class="n">publisher</span><span class="o">)</span>
<span class="o">.</span><span class="na">flatMapConcat</span><span class="o">(</span><span class="nl">Source:</span><span class="o">:</span><span class="n">from</span><span class="o">);</span>
<span class="c1">// .. proceed working with the Akka Source ..</span>
</code></pre></div></div>
<h4 id="request-and-issue-acknowledgements">Request and issue acknowledgements</h4>
<div class="bs-callout bs-callout-primary">Available since Ditto <strong>1.1.0</strong></div>
<p><a href="basic-acknowledgements.html#requesting-acks">Requesting acknowledgements</a> is possible in the Ditto Java
client in the following way:</p>
<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">DittoHeaders</span> <span class="n">dittoHeaders</span> <span class="o">=</span> <span class="n">DittoHeaders</span><span class="o">.</span><span class="na">newBuilder</span><span class="o">()</span>
<span class="o">.</span><span class="na">acknowledgementRequest</span><span class="o">(</span>
<span class="n">AcknowledgementRequest</span><span class="o">.</span><span class="na">of</span><span class="o">(</span><span class="n">DittoAcknowledgementLabel</span><span class="o">.</span><span class="na">PERSISTED</span><span class="o">),</span>
<span class="n">AcknowledgementRequest</span><span class="o">.</span><span class="na">of</span><span class="o">(</span><span class="n">AcknowledgementLabel</span><span class="o">.</span><span class="na">of</span><span class="o">(</span><span class="s">"my-custom-ack"</span><span class="o">))</span>
<span class="o">)</span>
<span class="o">.</span><span class="na">timeout</span><span class="o">(</span><span class="s">"5s"</span><span class="o">)</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">twin</span><span class="o">().</span><span class="na">forId</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">"org.eclipse.ditto:my-thing"</span><span class="o">))</span>
<span class="o">.</span><span class="na">putAttribute</span><span class="o">(</span><span class="s">"counter"</span><span class="o">,</span> <span class="mi">42</span><span class="o">,</span> <span class="n">Options</span><span class="o">.</span><span class="na">dittoHeaders</span><span class="o">(</span><span class="n">dittoHeaders</span><span class="o">))</span>
<span class="o">.</span><span class="na">whenComplete</span><span class="o">((</span><span class="n">aVoid</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="k">instanceof</span> <span class="n">AcknowledgementsFailedException</span><span class="o">)</span> <span class="o">{</span>
<span class="n">Acknowledgements</span> <span class="n">acknowledgements</span> <span class="o">=</span> <span class="o">((</span><span class="n">AcknowledgementsFailedException</span><span class="o">)</span> <span class="n">throwable</span><span class="o">).</span><span class="na">getAcknowledgements</span><span class="o">();</span>
<span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"Acknowledgements could not be fulfilled: "</span> <span class="o">+</span> <span class="n">acknowledgements</span><span class="o">);</span>
<span class="o">}</span>
<span class="o">});</span>
</code></pre></div></div>
<p><a href="basic-acknowledgements.html#issuing-acknowledgements">Issuing requested acknowledgements</a> can be done like this
whenever a <code class="highlighter-rouge">Change</code> callback is invoked with a change notification:</p>
<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">client</span><span class="o">.</span><span class="na">twin</span><span class="o">().</span><span class="na">registerForThingChanges</span><span class="o">(</span><span class="s">"REG1"</span><span class="o">,</span> <span class="n">change</span> <span class="o">-&gt;</span> <span class="o">{</span>
<span class="n">change</span><span class="o">.</span><span class="na">handleAcknowledgementRequest</span><span class="o">(</span><span class="n">AcknowledgementLabel</span><span class="o">.</span><span class="na">of</span><span class="o">(</span><span class="s">"my-custom-ack"</span><span class="o">),</span> <span class="n">ackHandle</span> <span class="o">-&gt;</span>
<span class="n">ackHandle</span><span class="o">.</span><span class="na">acknowledge</span><span class="o">(</span><span class="n">HttpStatusCode</span><span class="o">.</span><span class="na">NOT_FOUND</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="o">.</span><span class="na">set</span><span class="o">(</span><span class="s">"error-detail"</span><span class="o">,</span> <span class="s">"Could not be found"</span><span class="o">)</span>
<span class="o">.</span><span class="na">build</span><span class="o">()</span>
<span class="o">)</span>
<span class="o">);</span>
<span class="o">});</span>
</code></pre></div></div>
<h2 id="further-examples">Further examples</h2>
<p>For further examples on how to use the Ditto client, please have a look at the class
<a href="https://github.com/eclipse/ditto-clients/blob/master/java/src/test/java/org/eclipse/ditto/client/DittoClientUsageExamples.java">DittoClientUsageExamples</a>
which is configured to connect to the <a href="https://ditto.eclipse.org">Ditto sandbox</a>.</p>
<div class="tags">
<b>Tags: </b>
</div>
</div>
<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>