2020-10-08-asynchronous-client-creation.html - gerrit/www.eclipse.org/ditto - Git at Google

 <!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>  Asynchronous Client Creation in Ditto Java Client 1.3.0 </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="Eclipse 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">
                     <img src="images/GitHub-Mark-Light-32px.png" alt="Sources at GitHub">
                   </a></li>


                   <li><a href="https://github.com/eclipse/ditto-clients" target="_blank">
                     <img src="images/GitHub-Mark-Light-32px.png" alt="SDK sources at GitHub">SDKs
                   </a></li>


                   <li><a href="https://github.com/eclipse/ditto-examples" target="_blank">
                     <img src="images/GitHub-Mark-Light-32px.png" alt="Example sources at 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="Asynchronous Client Creation in Ditto Java Client 1.3.0">{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/d923944b6a8c76e411ff838fb19acfa7?s=135" alt="A photo of Yufei Cai" />-->

 <!--&lt;!&ndash; Personal Info. &ndash;&gt;-->
     <!--Written by <a href="https://github.com/yufei-cai" target="_blank">Yufei Cai</a>-->
 <!--</span>-->
 <!---->

 <article class="post" itemscope itemtype="http://schema.org/BlogPosting">

     <header class="post-header">
         <h1 class="post-title" itemprop="name headline">Asynchronous Client Creation in Ditto Java Client 1.3.0</h1>
         <p class="post-meta">Published by <img src="https://www.gravatar.com/avatar/d923944b6a8c76e411ff838fb19acfa7?s=135" alt="A photo of Yufei Cai" 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/yufei-cai" target="_blank">Yufei Cai</a> </span></span> on <time datetime="2020-10-08T00:00:00+00:00" itemprop="datePublished">Oct 8, 2020</time> - Tags:


             <a href="tag_blog.html">blog</a>


         </p>


     </header>

     <div class="post-content" itemprop="articleBody">


         <p>Before <a href="https://github.com/eclipse/ditto-clients/tree/master/java">Ditto Java Client</a> 1.3.0,
 a client object connects to a configured Ditto back-end during its creation.</p>

 <div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// create a client object and block until it connects to the Ditto back-end.</span>
 <span class="kd">final</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>

 <p>There are several problems with the approach.</p>
 <ol>
   <li>The calling thread blocks waiting for IO, namely the authentication process
 and establishment of a websocket.</li>
   <li>If the client is configured to reconnect, then an incorrect end-ponit configuration
 makes the factory method block forever.</li>
   <li>If the client is not configured to reconnect, then the factory method will throw
 an exception. But it is not possible to give the client reference to the exception
 handler, since the client creation did not complete. Consequently the exception handler
 has no simple way to free all resources allocated for the client.</li>
 </ol>

 <p>1.3.0 addresses these problems by introducing an asynchronous client creation interface.</p>

 <div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">public</span> <span class="kd">final</span> <span class="kd">class</span> <span class="nc">DittoClients</span> <span class="o">{</span>

     <span class="kd">public</span> <span class="kd">static</span> <span class="n">DisconnectedDittoClient</span> <span class="nf">newDisconnectedInstance</span><span class="o">(</span><span class="n">MessagingProvider</span> <span class="n">mp</span><span class="o">);</span>
 <span class="o">}</span>

 <span class="kd">public</span> <span class="kd">interface</span> <span class="nc">DisconnectedDittoClient</span> <span class="o">{</span>

     <span class="n">CompletionStage</span><span class="o">&lt;</span><span class="n">DittoClient</span><span class="o">&gt;</span> <span class="nf">connect</span><span class="o">();</span>

     <span class="kt">void</span> <span class="nf">destroy</span><span class="o">();</span>
 <span class="o">}</span>
 </code></pre></div></div>

 <p>The method <code class="highlighter-rouge">DittoClients.newDisconnectedInstance(MessagingProvider)</code> creates a <code class="highlighter-rouge">DisconnectedDittoClient</code>
 object. The <code class="highlighter-rouge">DisconnectedDittoClient</code> has references to all resources allocated for the client and
 can free them via the <code class="highlighter-rouge">destroy()</code> method. The <code class="highlighter-rouge">DisconnectedDittoClient</code> object offers no method to
 interact with the Ditto API. By calling <code class="highlighter-rouge">connect()</code>, one obtains a future that yields a familiar
 <code class="highlighter-rouge">DittoClient</code> object upon completion. One might use the asynchronous client creation interface thus:</p>

 <div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">final</span> <span class="n">DisconnectedDittoClient</span> <span class="n">disconnectedClient</span> <span class="o">=</span>
     <span class="n">DittoClients</span><span class="o">.</span><span class="na">newDisconnectedInstance</span><span class="o">(</span><span class="n">messagingProvider</span><span class="o">);</span>

 <span class="n">disconnectedClient</span><span class="o">.</span><span class="na">connect</span><span class="o">()</span>
     <span class="o">.</span><span class="na">thenAccept</span><span class="o">(</span><span class="k">this</span><span class="o">::</span><span class="n">startUsingDittoClient</span><span class="o">)</span>
     <span class="o">.</span><span class="na">exceptionally</span><span class="o">(</span><span class="n">exception</span> <span class="o">-&gt;</span> <span class="o">{</span>
         <span class="k">this</span><span class="o">.</span><span class="na">handleConnectionFailure</span><span class="o">(</span><span class="n">exception</span><span class="o">);</span>
         <span class="n">disconnectedClient</span><span class="o">.</span><span class="na">destroy</span><span class="o">();</span>
         <span class="k">return</span> <span class="kc">null</span><span class="o">;</span>
     <span class="o">});</span>
 </code></pre></div></div>

 <p>The asynchronous client creation interface has the following advantages.</p>

 <ol>
   <li>
     <p>The calling thread does not block.</p>
   </li>
   <li>
     <p>Even if configured to reconnect, the user can receive connection errors via
 the connection error handler in <code class="highlighter-rouge">MessagingConfiguration</code> and shut down the client
 at will.</p>
   </li>
   <li>
     <p>When initial reconnection is disabled, the method <code class="highlighter-rouge">DisconnectedDittoClient.connect()</code>
 returns a failed future on connection error. It is possible to reference the
 <code class="highlighter-rouge">DittoDisconnectedClient</code> object in the future’s error handler, where the client can
 be destroyed.</p>
   </li>
 </ol>

 <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;2021 Eclipse Ditto™.
                          Site last generated: Apr 8, 2021 <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>
	<!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> Asynchronous Client Creation in Ditto Java Client 1.3.0 </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"> <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="Eclipse 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">
	<img src="images/GitHub-Mark-Light-32px.png" alt="Sources at GitHub">
	</a></li>





	<li><a href="https://github.com/eclipse/ditto-clients" target="_blank">
	<img src="images/GitHub-Mark-Light-32px.png" alt="SDK sources at GitHub">SDKs
	</a></li>





	<li><a href="https://github.com/eclipse/ditto-examples" target="_blank">
	<img src="images/GitHub-Mark-Light-32px.png" alt="Example sources at 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="Asynchronous Client Creation in Ditto Java Client 1.3.0">{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>-->
	<!--<!– Mugshot. –>-->
	<!--<img src="https://www.gravatar.com/avatar/d923944b6a8c76e411ff838fb19acfa7?s=135" alt="A photo of Yufei Cai" />-->

	<!--<!– Personal Info. –>-->
	<!--Written by <a href="https://github.com/yufei-cai" target="_blank">Yufei Cai</a>-->
	<!--</span>-->
	<!---->

	<article class="post" itemscope itemtype="http://schema.org/BlogPosting">

	<header class="post-header">
	<h1 class="post-title" itemprop="name headline">Asynchronous Client Creation in Ditto Java Client 1.3.0</h1>
	<p class="post-meta">Published by <img src="https://www.gravatar.com/avatar/d923944b6a8c76e411ff838fb19acfa7?s=135" alt="A photo of Yufei Cai" 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/yufei-cai" target="_blank">Yufei Cai</a> </span></span> on <time datetime="2020-10-08T00:00:00+00:00" itemprop="datePublished">Oct 8, 2020</time> - Tags:



	<a href="tag_blog.html">blog</a>




	</p>


	</header>

	<div class="post-content" itemprop="articleBody">





	<p>Before <a href="https://github.com/eclipse/ditto-clients/tree/master/java">Ditto Java Client</a> 1.3.0,
	a client object connects to a configured Ditto back-end during its creation.</p>

	<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// create a client object and block until it connects to the Ditto back-end.</span>
	<span class="kd">final</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>

	<p>There are several problems with the approach.</p>
	<ol>
	<li>The calling thread blocks waiting for IO, namely the authentication process
	and establishment of a websocket.</li>
	<li>If the client is configured to reconnect, then an incorrect end-ponit configuration
	makes the factory method block forever.</li>
	<li>If the client is not configured to reconnect, then the factory method will throw
	an exception. But it is not possible to give the client reference to the exception
	handler, since the client creation did not complete. Consequently the exception handler
	has no simple way to free all resources allocated for the client.</li>
	</ol>

	<p>1.3.0 addresses these problems by introducing an asynchronous client creation interface.</p>

	<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">public</span> <span class="kd">final</span> <span class="kd">class</span> <span class="nc">DittoClients</span> <span class="o">{</span>

	<span class="kd">public</span> <span class="kd">static</span> <span class="n">DisconnectedDittoClient</span> <span class="nf">newDisconnectedInstance</span><span class="o">(</span><span class="n">MessagingProvider</span> <span class="n">mp</span><span class="o">);</span>
	<span class="o">}</span>

	<span class="kd">public</span> <span class="kd">interface</span> <span class="nc">DisconnectedDittoClient</span> <span class="o">{</span>

	<span class="n">CompletionStage</span><span class="o"><</span><span class="n">DittoClient</span><span class="o">></span> <span class="nf">connect</span><span class="o">();</span>

	<span class="kt">void</span> <span class="nf">destroy</span><span class="o">();</span>
	<span class="o">}</span>
	</code></pre></div></div>

	<p>The method <code class="highlighter-rouge">DittoClients.newDisconnectedInstance(MessagingProvider)</code> creates a <code class="highlighter-rouge">DisconnectedDittoClient</code>
	object. The <code class="highlighter-rouge">DisconnectedDittoClient</code> has references to all resources allocated for the client and
	can free them via the <code class="highlighter-rouge">destroy()</code> method. The <code class="highlighter-rouge">DisconnectedDittoClient</code> object offers no method to
	interact with the Ditto API. By calling <code class="highlighter-rouge">connect()</code>, one obtains a future that yields a familiar
	<code class="highlighter-rouge">DittoClient</code> object upon completion. One might use the asynchronous client creation interface thus:</p>

	<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">final</span> <span class="n">DisconnectedDittoClient</span> <span class="n">disconnectedClient</span> <span class="o">=</span>
	<span class="n">DittoClients</span><span class="o">.</span><span class="na">newDisconnectedInstance</span><span class="o">(</span><span class="n">messagingProvider</span><span class="o">);</span>

	<span class="n">disconnectedClient</span><span class="o">.</span><span class="na">connect</span><span class="o">()</span>
	<span class="o">.</span><span class="na">thenAccept</span><span class="o">(</span><span class="k">this</span><span class="o">::</span><span class="n">startUsingDittoClient</span><span class="o">)</span>
	<span class="o">.</span><span class="na">exceptionally</span><span class="o">(</span><span class="n">exception</span> <span class="o">-></span> <span class="o">{</span>
	<span class="k">this</span><span class="o">.</span><span class="na">handleConnectionFailure</span><span class="o">(</span><span class="n">exception</span><span class="o">);</span>
	<span class="n">disconnectedClient</span><span class="o">.</span><span class="na">destroy</span><span class="o">();</span>
	<span class="k">return</span> <span class="kc">null</span><span class="o">;</span>
	<span class="o">});</span>
	</code></pre></div></div>

	<p>The asynchronous client creation interface has the following advantages.</p>

	<ol>
	<li>
	<p>The calling thread does not block.</p>
	</li>
	<li>
	<p>Even if configured to reconnect, the user can receive connection errors via
	the connection error handler in <code class="highlighter-rouge">MessagingConfiguration</code> and shut down the client
	at will.</p>
	</li>
	<li>
	<p>When initial reconnection is disabled, the method <code class="highlighter-rouge">DisconnectedDittoClient.connect()</code>
	returns a failed future on connection error. It is possible to reference the
	<code class="highlighter-rouge">DittoDisconnectedClient</code> object in the future’s error handler, where the client can
	be destroyed.</p>
	</li>
	</ol>

	<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">
	©2021 Eclipse Ditto™.
	Site last generated: Apr 8, 2021 <br />
	</p>
	<div class="quickLinks">
	<a href="https://www.eclipse.org/legal/privacy.php" target="_blank">
	> Privacy Policy
	</a>
	<a href="https://www.eclipse.org/legal/termsofuse.php" target="_blank">
	> Terms of Use
	</a>
	<a href="https://www.eclipse.org/legal/copyright.php" target="_blank">
	> Copyright Agent
	</a>
	<a href="https://www.eclipse.org/legal" target="_blank">
	> Legal
	</a>
	<a href="https://www.eclipse.org/legal/epl-2.0/" target="_blank">
	> License
	</a>
	<a href="https://eclipse.org/security" target="_blank">
	> Report a Vulnerability
	</a>
	</div>
	</div>
	</div>
	</footer>


	</div>
	<!-- /.row -->
	</div>
	<!-- /.container -->
	</div>
	<!-- /#main -->
	</div>

	</body>
	</html>