| <rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom"><channel><title>Apache Dubbo – Dubbo Developer Guide</title><link>https://dubbo.apache.org/en/docs/v2.7/dev/</link><description>Recent content in Dubbo Developer Guide on Apache Dubbo</description><generator>Hugo -- gohugo.io</generator><language>en</language><atom:link href="https://dubbo.apache.org/en/docs/v2.7/dev/index.xml" rel="self" type="application/rss+xml"/><item><title>Docs: Source Code Build</title><link>https://dubbo.apache.org/en/docs/v2.7/dev/build/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/en/docs/v2.7/dev/build/</guid><description> |
| <h2 id="checkout">Checkout</h2> |
| <p>checkout the lastest project source code with commands blow:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-sh" data-lang="sh"><span style="display:flex;"><span>git clone https://github.com/apache/dubbo.git dubbo |
| </span></span></code></pre></div><h2 id="branches">Branches</h2> |
| <p>We use <code>master</code> as the major branch for new feature development, and use other branches for maintenance. Tags for all versions can be checked via <a href="https://github.com/apache/dubbo/tags">https://github.com/apache/dubbo/tags</a>.</p> |
| <h2 id="building">Building</h2> |
| <p>Dubbo relies on <a href="http://maven.apache.org">maven</a> as the building tool.</p> |
| <p>Requirements:</p> |
| <ul> |
| <li>Java above 1.8 version</li> |
| <li>Maven version 2.2.1 or above</li> |
| </ul> |
| <p>The following <code>MAVEN_OPTS</code>should be configured before building:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-sh" data-lang="sh"><span style="display:flex;"><span><span style="color:#b58900">export</span> <span style="color:#268bd2">MAVEN_OPTS</span><span style="color:#719e07">=</span>-Xmx1024m -XX:MaxPermSize<span style="color:#719e07">=</span>512m |
| </span></span></code></pre></div><p>build with below command:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-sh" data-lang="sh"><span style="display:flex;"><span>mvn clean install |
| </span></span></code></pre></div><p>skip testing using below building command:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-sh" data-lang="sh"><span style="display:flex;"><span>mvn install -Dmaven.test.skip |
| </span></span></code></pre></div><h2 id="building-jar-package-of-source-code">Building jar package of source code</h2> |
| <p>build Dubbo source code jar package with below command.</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-sh" data-lang="sh"><span style="display:flex;"><span>mvn clean source:jar install -Dmaven.test.skip |
| </span></span></code></pre></div><p>and modify the dubbo dependency in your sample project to the SANPSHOT version of the local repository, and then use remote debugger to debug dubbo.</p> |
| <h2 id="ide-support">IDE support</h2> |
| <p>use below command to generate IDE.</p> |
| <h3 id="intellij-idea">Intellij Idea</h3> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-sh" data-lang="sh"><span style="display:flex;"><span>mvn idea:idea |
| </span></span></code></pre></div><h3 id="eclipse">Eclipse</h3> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-sh" data-lang="sh"><span style="display:flex;"><span>mvn eclipse:eclipse |
| </span></span></code></pre></div><p>Importing into eclipse</p> |
| <p>Firstly, a maven repository needs to be configured in eclipse. Define <code>M2_REPO</code> and point it to the local maven repository by clicking <code>Preferences -&gt; Java -&gt; Build Path -&gt; Classpath</code>.</p> |
| <p>Use the following maven command as well:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-sh" data-lang="sh"><span style="display:flex;"><span>mvn eclipse:configure-workspace -Declipse.workspace<span style="color:#719e07">=</span>/path/to/the/workspace/ |
| </span></span></code></pre></div><ol> |
| <li>view the source code through <a href="https://github.com/apache/dubbo">https://github.com/apache/dubbo</a></li> |
| <li>path under UNIX is ${HOME}/.m2/repository, path under Windows is C:\Documents and Settings&lt;user&gt;.m2\repository</li> |
| </ol></description></item><item><title>Docs: Framework Design</title><link>https://dubbo.apache.org/en/docs/v2.7/dev/design/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/en/docs/v2.7/dev/design/</guid><description> |
| <h2 id="overall-design">Overall design</h2> |
| <p><img src="https://dubbo.apache.org/imgs/dev/dubbo-framework.jpg" alt="/dev-guide/images/dubbo-framework.jpg"></p> |
| <p>Image description:</p> |
| <ul> |
| <li>Left area with light blue background shows service consumer interfaces, Right area with light green background shows service provider interfaces, center area shows both side interfaces.</li> |
| <li>The image is divided into 10 layers from the bottom to the top, and the layers are one-way dependence. The black arrow on the right represents the dependency between layers, and each layer can be stripped from the upper layer to be reused, the Service and Config layers are API, and the other layers are SPI.</li> |
| <li>Green boxes are extension interfaces, blue boxes are implementation classes, image only shows implementation class of associated layers.</li> |
| <li>The blue dashed line is the initialization process, which is assembly chain when starting, red line for the method call process, which is calling chain when running, purple triangle arrow is inherited, can treat subclass as the same node of parent class, text of lines are the method invocation.</li> |
| </ul> |
| <h2 id="layer-description">Layer description</h2> |
| <ul> |
| <li><strong>config layer</strong>: external config interface, <code>ServiceConfig</code> and <code>ReferenceConfig</code> is the center of the layer, you can directly initialize config class, also can generate config class by spring.</li> |
| <li><strong>proxy layer</strong>: transparent proxy of service interface, generate client Stub of service and server Skeletion of service, <code>ServiceProxy</code> is the center, extension interface is <code>ProxyFactory</code>.</li> |
| <li><strong>registry layer</strong>: encapsulation of service registry and discovery, service URL is the center, extension interfaces are <code>RegistryFactory</code>, <code>Registry</code> and <code>RegistryService</code>.</li> |
| <li><strong>cluster layer</strong>: encapsulation of cluster of muliple providers and load balance, and bridging registration center, <code>Invoker</code> is the center, extension interfaces are <code>Cluster</code>, <code>Directory</code>, <code>Router</code>, <code>LoadBalance</code>.</li> |
| <li><strong>monitor layer</strong>: monitor of RPC call times and call execute time, <code>Statistics</code> is the center, extension interface are <code>MonitorFactory</code>, <code>Monitor</code>, <code>MonitorService</code></li> |
| <li><strong>protocol layer</strong>: encapsulation of RPC, <code>Invocation</code> and <code>Result</code> are the center, extension interfaces are <code>Protocol</code>, <code>Invoker</code>, <code>Exporter</code></li> |
| <li><strong>exchange layer</strong>: encapsulation of request and response, synchronous transfer asynchronous, <code>Request</code> and <code>Response</code> are the center, extension interfaces are <code>Exchanger</code>, <code>ExchangeChannel</code>, <code>ExchangeClient</code>, <code>ExchangeServer</code></li> |
| <li><strong>transport layer</strong>: abstraction of mina and netty, <code>Message</code> is the center, extension interfaces are <code>Channel</code>, <code>Transporter</code>, <code>Client</code>, <code>Server</code>, <code>Codec</code></li> |
| <li><strong>serialize layer</strong>: reusable tools, extension interfaces are <code>Serialization</code>, <code>ObjectInput</code>, <code>ObjectOutput</code>, <code>ThreadPool</code></li> |
| </ul> |
| <h2 id="relationship-description">Relationship description</h2> |
| <ul> |
| <li>In RPC, Protocol is the core layer, it means that you can complete RPC calling by Protocol + Invoker + Exporter, then filter at the main process of Invoker.</li> |
| <li>Consumer and Provider are abstraction concepts, just want you have a more intuitive understanding of which classes belong to the client and server side, the reason not use Client and Server is that Dubbo uses Provider, Consumer, Registry, Monitor divide logical topology node in many scenes, keep the concept of unity.</li> |
| <li>Cluster is external concept, the purpose of Cluster is that make various Invoker disguise to one Invoker, so that we just pay attention to the Invoker in Protocol layer, adding Cluster or removing Cluster will not affect other layers, because we don&rsquo;t need Cluster when only have one provider.</li> |
| <li>The Proxy layer encapsulates the transparent proxy for all interfaces, and in other layers with Invoker as the center, turn Invoker into interface, or turn interface implementation into Invoker by Proxy only when exposuring to user. RPC still work even removing Proxy layer, but not so transparent, making remote service calling don&rsquo;t look like local service calling.</li> |
| <li>Remoting is the implemetation of Dubbo protocols, you can remove Remoting if choosing RMI. The Remoting is divided into Transport layer and Exchange layer, Transport layer is responsible for one-way message transmission, it&rsquo;s abstraction of Mina, Netty, Grizzly, it also can extend UDP transmission. The Exchange layer encapsulates the Request-Response semantics over the transport layer.</li> |
| <li>Actually Registry and Monitor are not at the same layer, they are independent nodes, draw them together by layer just for global view.</li> |
| </ul> |
| <h2 id="modules-packaging">Modules packaging</h2> |
| <p><img src="https://dubbo.apache.org/imgs/dev/dubbo-modules.jpg" alt="/dev-guide/images/dubbo-modules.jpg"></p> |
| <p>Modules description:</p> |
| <ul> |
| <li><strong>dubbo-common module</strong>: includes Util classes and common modules.</li> |
| <li><strong>dubbo-remoting module</strong>: is Dubbo protocol implementation, no need to use this module if using RMI for RPC.</li> |
| <li><strong>dubbo-rpc module</strong>: abstraction of various protocols, and dynamic proxy, only one to one call, not concerned with the management of cluster.</li> |
| <li><strong>dubbo-cluster module</strong>: disguise many service providers as one provider, including load balancing, fault tolerance, routing, etc. the address list of clusters can be either static or send by registry.</li> |
| <li><strong>dubbo-registry module</strong>: Based on the cluster of registry send address and the abstraction of various registry centers.</li> |
| <li><strong>dubbo-monitor module</strong>: statistics of service call times, call time, call chain tracked services.</li> |
| <li><strong>dubbo-config module</strong>: is Dubbo external API, users use Dubbo by Config, hide Dubbo details.</li> |
| <li><strong>dubbo-container module</strong>: is a Standlone container, just use Main method to load Spring, because usually service no need Tomcat/JBoss features.</li> |
| </ul> |
| <p>Package dividing according to the layer structure, and the difference with layer dividing:</p> |
| <ul> |
| <li>container is service container, for service running deployment, not showed in the image.</li> |
| <li>protocol layer and proxy layer are placed in RPC module, they are the core of RPC module, you can use these 2 layers complete RPC call when only have 1 provider.</li> |
| <li>transport layer and exchange layer are placed in remoting module, for RPC call base comminucation.</li> |
| <li>serialize layer is placed in common module, for reuse.</li> |
| </ul> |
| <h2 id="dependence-relationship">Dependence relationship</h2> |
| <p><img src="https://dubbo.apache.org/imgs/dev/dubbo-relation.jpg" alt="/dev-guide/images/dubbo-relation.jpg"></p> |
| <p>Image description:</p> |
| <ul> |
| <li>The boxes in image, Protocol, Cluster, Proxy, Service, Container, Registry, Monitor represent layer or module, the blues mean interactive with business, the greens mean only internal interactive with Dubbo.</li> |
| <li>The backgroud boxes in image, Consumer, Provider, Registry, Monitor represent deployment logical topology node.</li> |
| <li>The blue dashed line in the image is called for initialization, the red dashed line is called asynchronously for runtime, and the red line is called synchronously for runtime.</li> |
| <li>The image only includes RPC layer, don&rsquo;t includes Remoting layer, the whole Remoting hides in Protocol layer.</li> |
| </ul> |
| <h2 id="call-chain">Call chain</h2> |
| <p>Expand the red call chain of the overall design map:</p> |
| <p><img src="https://dubbo.apache.org/imgs/dev/dubbo-extension.jpg" alt="/dev-guide/images/dubbo-extension.jpg"></p> |
| <h2 id="expose-service-sequence">Expose service sequence</h2> |
| <p>Expand the initialization chain of service provider exposes service which at the left of the overall design map, the sequence diagram shows below:</p> |
| <p><img src="https://dubbo.apache.org/imgs/dev/dubbo-export.jpg" alt="/dev-guide/images/dubbo-export.jpg"></p> |
| <h2 id="reference-service-sequence">Reference service sequence</h2> |
| <p>Expand the initialization chain of service consumer references service which at the right of the overall design map, the sequence diagram shows below:</p> |
| <p><img src="https://dubbo.apache.org/imgs/dev/dubbo-refer.jpg" alt="/dev-guide/images/dubbo-refer.jpg"></p> |
| <h2 id="domain-model">Domain model</h2> |
| <p>The core domain models of Dubbo:</p> |
| <ul> |
| <li>Protocol is service domain, it is the main function entrance of Invoker exposure and reference, it is responsible for the life cycle management of Invoker.</li> |
| <li>Invoker is entity domain, it is the core model of Dubbo, all the other models are disturbed, or converted to it, it represents an executable, you can call it by calling invoke, it can be a local implementation, a remote implementation, or a cluster implementation.</li> |
| <li>Invocation is session domain, it holds variables in the calling process, such as the method name, the parameters, and so on.</li> |
| </ul> |
| <h2 id="base-design-principle">Base design principle</h2> |
| <ul> |
| <li>Use Microkernel + Plugin design pattern，Microkernel only responsible for assembly Plugin, the functions of Dubbo are implemented by extension points, it means that all functions of Dubbo can be replaced by self defined extension by user.</li> |
| <li>Use URL to be the startdard format of config information, all extension points transfer config information by URL.</li> |
| </ul> |
| <p>More design principles refer to: <a href="../principals">Framework design principle</a></p></description></item><item><title>Docs: SPI Loading</title><link>https://dubbo.apache.org/en/docs/v2.7/dev/spi/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/en/docs/v2.7/dev/spi/</guid><description> |
| <h2 id="spi-config">SPI Config</h2> |
| <h3 id="source">Source:</h3> |
| <p>Dubbo SPI is inherited from standard JDK SPI(Service Provider Interface) and makes it more powerful.</p> |
| <p>Dubbo fixed below issues of the standard JDK SPI:</p> |
| <ul> |
| <li>The standard JDK SPI will load and instantize all the implementations at once. It will be a waste of resources if one implementation is timecosted, but never be used.</li> |
| <li>We can&rsquo;t accquire the SPI name, if loading the SPI implementation is failed.For example: standard JDK ScriptEngine, get script type by invoking method getName(). RubyScriptEngine class will load failed if the depenency jar jruby.jar is missing, and the real error info will be lost. When user executes ruby scripts, the program throws exception that doesn&rsquo;t support ruby, but it is not the real cause.</li> |
| <li>Enhance the SPI functionality by supporting IoC and AOP, one SPI can be easily injected by another SPI simply using setter.</li> |
| </ul> |
| <h3 id="appointment">Appointment:</h3> |
| <p>In the jar file containing extension class <sup id="fnref:1"><a href="#fn:1" class="footnote-ref" role="doc-noteref">1</a></sup>, places a config file <code>META-INF/dubbo/full interface name</code>, file content pattern: <code>SPI name=the fully qualified name for the extension class</code>, use new line seperator for multiple implementation.</p> |
| <h3 id="example">Example:</h3> |
| <p>To extend Dubbo Protocol, place a text file in the extension jar file: <code>META-INF/dubbo/org.apache.dubbo.rpc.Protocol</code>, content:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-properties" data-lang="properties"><span style="display:flex;"><span>xxx<span style="color:#719e07">=</span><span style="color:#2aa198">com.alibaba.xxx.XxxProtocol</span> |
| </span></span></code></pre></div><p>content of the implementation <sup id="fnref:2"><a href="#fn:2" class="footnote-ref" role="doc-noteref">2</a></sup>:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#719e07">package</span> com.alibaba.xxx<span style="color:#719e07">;</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">import</span> org.apache.dubbo.rpc.Protocol<span style="color:#719e07">;</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">class</span> <span style="color:#268bd2">XxxProtocol</span> <span style="color:#268bd2">implements</span> Protocol <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">// ... |
| </span></span></span><span style="display:flex;"><span><span style="color:#586e75"></span><span style="color:#719e07">}</span> |
| </span></span></code></pre></div><h3 id="configuration-in-config-module">Configuration in config module</h3> |
| <p>In Dubbo config module, all SPI points have related attributes or labels, we can choose the specific SPI implementation by using its name. Like:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:protocol</span> name=<span style="color:#2aa198">&#34;xxx&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><h2 id="spi-features">SPI Features</h2> |
| <h3 id="spi-auto-wrap">SPI Auto Wrap</h3> |
| <p>Auto wrap the SPI&rsquo;s Wrapper class. <code>ExtensionLoader</code> loads the SPI implementation, if the SPI has a copy instructor, it will be regarded as the SPI&rsquo;s Wrapper class.</p> |
| <p>Wrapper class content:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#719e07">package</span> com.alibaba.xxx<span style="color:#719e07">;</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">import</span> org.apache.dubbo.rpc.Protocol<span style="color:#719e07">;</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">class</span> <span style="color:#268bd2">XxxProtocolWrapper</span> <span style="color:#268bd2">implements</span> Protocol <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> Protocol impl<span style="color:#719e07">;</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">public</span> <span style="color:#268bd2">XxxProtocolWrapper</span><span style="color:#719e07">(</span>Protocol protocol<span style="color:#719e07">)</span> <span style="color:#719e07">{</span> impl <span style="color:#719e07">=</span> protocol<span style="color:#719e07">;</span> <span style="color:#719e07">}</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">//after interface method is executed, the method in extension will be executed |
| </span></span></span><span style="display:flex;"><span><span style="color:#586e75"></span> <span style="color:#268bd2">public</span> <span style="color:#dc322f">void</span> <span style="color:#268bd2">refer</span><span style="color:#719e07">()</span> <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">//... some operation |
| </span></span></span><span style="display:flex;"><span><span style="color:#586e75"></span> impl<span style="color:#719e07">.</span>refer<span style="color:#719e07">();</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">// ... some operation |
| </span></span></span><span style="display:flex;"><span><span style="color:#586e75"></span> <span style="color:#719e07">}</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">// ... |
| </span></span></span><span style="display:flex;"><span><span style="color:#586e75"></span><span style="color:#719e07">}</span> |
| </span></span></code></pre></div><p>Wrapper class also implements the same SPI interface, but Wrapper is not the real implementation. It is used for wrap the real implementation returned from the <code>ExtensionLoader</code>. The real returned instance by <code>ExtensionLoader</code> is the Wrapper class instance, Wrapper holder the real SPI implementation class.</p> |
| <p>There can be many Wrapper for one spi, simply add one if you need.</p> |
| <p>With Wrapper class, you will be able to move same logics into Wrapper for all SPIs. Newly added Wrapper class add external logics for all SPIs, looks like AOP, Wrapper acts as a proxy for SPI.</p> |
| <h3 id="spi-auto-load">SPI Auto Load</h3> |
| <p>when loading the SPI, Dubbo will auto load the depency SPI. When one SPI implementation contains attribute which is also an SPI of another type,<code>ExtensionLoader</code> will automatically load the depency SPI. <code>ExtensionLoader</code> knows all the members of the specific SPI by scanning the setter method of all implementation class.</p> |
| <p>Demo: two SPI <code>CarMaker</code>（car maker）、<code>WheelMaker</code> (wheel maker)</p> |
| <p>Intefaces look like:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">interface</span> <span style="color:#268bd2">CarMaker</span> <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> Car <span style="color:#268bd2">makeCar</span><span style="color:#719e07">();</span> |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">}</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">interface</span> <span style="color:#268bd2">WheelMaker</span> <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> Wheel <span style="color:#268bd2">makeWheel</span><span style="color:#719e07">();</span> |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">}</span> |
| </span></span></code></pre></div><p><code>CarMaker</code>&rsquo;s implementation:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">class</span> <span style="color:#268bd2">RaceCarMaker</span> <span style="color:#268bd2">implements</span> CarMaker <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> WheelMaker wheelMaker<span style="color:#719e07">;</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">public</span> <span style="color:#dc322f">void</span> <span style="color:#268bd2">setWheelMaker</span><span style="color:#719e07">(</span>WheelMaker wheelMaker<span style="color:#719e07">)</span> <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">this</span><span style="color:#719e07">.</span>wheelMaker <span style="color:#719e07">=</span> wheelMaker<span style="color:#719e07">;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">}</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">public</span> Car <span style="color:#268bd2">makeCar</span><span style="color:#719e07">()</span> <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">// ... |
| </span></span></span><span style="display:flex;"><span><span style="color:#586e75"></span> Wheel wheel <span style="color:#719e07">=</span> wheelMaker<span style="color:#719e07">.</span>makeWheel<span style="color:#719e07">();</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">// ... |
| </span></span></span><span style="display:flex;"><span><span style="color:#586e75"></span> <span style="color:#719e07">return</span> <span style="color:#719e07">new</span> RaceCar<span style="color:#719e07">(</span>wheel<span style="color:#719e07">,</span> <span style="color:#719e07">...);</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">}</span> |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">}</span> |
| </span></span></code></pre></div><p>when <code>ExtensionLoader</code> loads <code>CarMaker</code>&rsquo;s implementation <code>RaceCarMaker</code>, the method <code>setWheelMaker</code> needs paramType <code>WheelMaker</code> which is also a SPI, It will be automatically loaded.</p> |
| <p>This brings a new question:How <code>ExtensionLoader</code> determines which implementation to use when load the injected SPI. As for this demo, when existing multi <code>WheelMaker</code> implementation, which one should the <code>ExtensionLoader</code> chooses.</p> |
| <p>Good question, we will explain it in the following chapter: SPI Auto Adaptive.</p> |
| <h3 id="spi-auto-adaptive">SPI Auto Adaptive</h3> |
| <p>The depency SPI that <code>ExtensionLoader</code> injects is an instance of <code>Adaptive</code>, the real spi implementation is known until the adaptive instance is executed.</p> |
| <p>Dubbo use URL (containing Key-Value) to pass the configuration.</p> |
| <p>The SPI method invocation has the URL parameter（Or Entity that has URL attribute）</p> |
| <p>In this way depended SPI can get configuration from URL, after config all SPI key needed, configuration information will be passed from outer by URL. URL acts as a bus when passing the config information.</p> |
| <p>Demo: two SPI <code>CarMaker</code>、<code>WheelMaker</code></p> |
| <p>interface looks like:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">interface</span> <span style="color:#268bd2">CarMaker</span> <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> Car <span style="color:#268bd2">makeCar</span><span style="color:#719e07">(</span>URL url<span style="color:#719e07">);</span> |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">}</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">interface</span> <span style="color:#268bd2">WheelMaker</span> <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> Wheel <span style="color:#268bd2">makeWheel</span><span style="color:#719e07">(</span>URL url<span style="color:#719e07">);</span> |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">}</span> |
| </span></span></code></pre></div><p><code>CarMaker</code>&rsquo;s implementation:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">class</span> <span style="color:#268bd2">RaceCarMaker</span> <span style="color:#268bd2">implements</span> CarMaker <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> WheelMaker wheelMaker<span style="color:#719e07">;</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">public</span> <span style="color:#dc322f">void</span> <span style="color:#268bd2">setWheelMaker</span><span style="color:#719e07">(</span>WheelMaker wheelMaker<span style="color:#719e07">)</span> <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">this</span><span style="color:#719e07">.</span>wheelMaker <span style="color:#719e07">=</span> wheelMaker<span style="color:#719e07">;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">}</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">public</span> Car <span style="color:#268bd2">makeCar</span><span style="color:#719e07">(</span>URL url<span style="color:#719e07">)</span> <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">// ... |
| </span></span></span><span style="display:flex;"><span><span style="color:#586e75"></span> Wheel wheel <span style="color:#719e07">=</span> wheelMaker<span style="color:#719e07">.</span>makeWheel<span style="color:#719e07">(</span>url<span style="color:#719e07">);</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">// ... |
| </span></span></span><span style="display:flex;"><span><span style="color:#586e75"></span> <span style="color:#719e07">return</span> <span style="color:#719e07">new</span> RaceCar<span style="color:#719e07">(</span>wheel<span style="color:#719e07">,</span> <span style="color:#719e07">...);</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">}</span> |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">}</span> |
| </span></span></code></pre></div><p>when execute the code above</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#586e75">// ... |
| </span></span></span><span style="display:flex;"><span><span style="color:#586e75"></span>Wheel wheel <span style="color:#719e07">=</span> wheelMaker<span style="color:#719e07">.</span>makeWheel<span style="color:#719e07">(</span>url<span style="color:#719e07">);</span> |
| </span></span><span style="display:flex;"><span><span style="color:#586e75">// ... |
| </span></span></span></code></pre></div><p>, the injected <code>Adaptive</code> object determine which <code>WheelMaker</code>&rsquo;s <code>makeWheel</code> method will be executed by predefined Key. Such as <code>wheel.type</code>, key <code>url.get(&quot;wheel.type&quot;)</code> will determine <code>WheelMake</code> implementation. The logic of<code>Adaptive</code> instance of fixed, getting the predefined Key of the URL, dynamically creating the real implementation and execute it.</p> |
| <p>For Dubbo, the SPI <code>Adaptive</code> implementation in <code>ExtensionLoader</code> is dynamically created when dubbo is loading the SPI. Get the Key from URL, the Key will be provided through <code>@Adaptive</code> annotation for the interface method definition.</p> |
| <p>Below is Dubbo Transporter SPI codes:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">interface</span> <span style="color:#268bd2">Transporter</span> <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@Adaptive</span><span style="color:#719e07">({</span><span style="color:#2aa198">&#34;server&#34;</span><span style="color:#719e07">,</span> <span style="color:#2aa198">&#34;transport&#34;</span><span style="color:#719e07">})</span> |
| </span></span><span style="display:flex;"><span> Server <span style="color:#268bd2">bind</span><span style="color:#719e07">(</span>URL url<span style="color:#719e07">,</span> ChannelHandler handler<span style="color:#719e07">)</span> <span style="color:#268bd2">throws</span> RemotingException<span style="color:#719e07">;</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@Adaptive</span><span style="color:#719e07">({</span><span style="color:#2aa198">&#34;client&#34;</span><span style="color:#719e07">,</span> <span style="color:#2aa198">&#34;transport&#34;</span><span style="color:#719e07">})</span> |
| </span></span><span style="display:flex;"><span> Client <span style="color:#268bd2">connect</span><span style="color:#719e07">(</span>URL url<span style="color:#719e07">,</span> ChannelHandler handler<span style="color:#719e07">)</span> <span style="color:#268bd2">throws</span> RemotingException<span style="color:#719e07">;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">}</span> |
| </span></span></code></pre></div><p>for the method bind(), Adaptive will firstly search <code>server</code> key, if no Key were founded then will search <code>transport</code> key, to determine the implementation that the proxy represent for.</p> |
| <h3 id="spi-auto-activation">SPI Auto Activation</h3> |
| <p>As for Collections SPI, such as: <code>Filter</code>, <code>InvokerListener</code>, <code>ExportListener</code>, <code>TelnetHandler</code>, <code>StatusChecker</code> etc, multi implementations can be loaded at one time. User can simplify configuration by using auto activation, Like:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#719e07">import</span> org.apache.dubbo.common.extension.Activate<span style="color:#719e07">;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">import</span> org.apache.dubbo.rpc.Filter<span style="color:#719e07">;</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">@Activate</span> <span style="color:#586e75">// Active for any condition |
| </span></span></span><span style="display:flex;"><span><span style="color:#586e75"></span><span style="color:#268bd2">public</span> <span style="color:#268bd2">class</span> <span style="color:#268bd2">XxxFilter</span> <span style="color:#268bd2">implements</span> Filter <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">// ... |
| </span></span></span><span style="display:flex;"><span><span style="color:#586e75"></span><span style="color:#719e07">}</span> |
| </span></span></code></pre></div><p>Or:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#719e07">import</span> org.apache.dubbo.common.extension.Activate<span style="color:#719e07">;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">import</span> org.apache.dubbo.rpc.Filter<span style="color:#719e07">;</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">@Activate</span><span style="color:#719e07">(</span><span style="color:#2aa198">&#34;xxx&#34;</span><span style="color:#719e07">)</span> <span style="color:#586e75">// when configed xxx parameter and the parameter has a valid value,the SPI is activated, for example configed cache=&#34;lru&#34;, auto acitivate CacheFilter. |
| </span></span></span><span style="display:flex;"><span><span style="color:#586e75"></span><span style="color:#268bd2">public</span> <span style="color:#268bd2">class</span> <span style="color:#268bd2">XxxFilter</span> <span style="color:#268bd2">implements</span> Filter <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">// ... |
| </span></span></span><span style="display:flex;"><span><span style="color:#586e75"></span><span style="color:#719e07">}</span> |
| </span></span></code></pre></div><p>Or:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#719e07">import</span> org.apache.dubbo.common.extension.Activate<span style="color:#719e07">;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">import</span> org.apache.dubbo.rpc.Filter<span style="color:#719e07">;</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">@Activate</span><span style="color:#719e07">(</span>group <span style="color:#719e07">=</span> <span style="color:#2aa198">&#34;provider&#34;</span><span style="color:#719e07">,</span> value <span style="color:#719e07">=</span> <span style="color:#2aa198">&#34;xxx&#34;</span><span style="color:#719e07">)</span> <span style="color:#586e75">// only activate for provider, group can be &#34;provider&#34; or &#34;consumer&#34; |
| </span></span></span><span style="display:flex;"><span><span style="color:#586e75"></span><span style="color:#268bd2">public</span> <span style="color:#268bd2">class</span> <span style="color:#268bd2">XxxFilter</span> <span style="color:#268bd2">implements</span> Filter <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">// ... |
| </span></span></span><span style="display:flex;"><span><span style="color:#586e75"></span><span style="color:#719e07">}</span> |
| </span></span></code></pre></div><div class="footnotes" role="doc-endnotes"> |
| <hr> |
| <ol> |
| <li id="fn:1"> |
| <p>Note: The config file here is in you own jar file, not in dubbo release jar file, Dubbo will scan all jar files with the same filename in classpath and then merge them together&#160;<a href="#fnref:1" class="footnote-backref" role="doc-backlink">&#x21a9;&#xfe0e;</a></p> |
| </li> |
| <li id="fn:2"> |
| <p>Note: SPI will be loaded in singleton pattern(Please ensure thread safety), cached in <code>ExtensionLoader</code>&#160;<a href="#fnref:2" class="footnote-backref" role="doc-backlink">&#x21a9;&#xfe0e;</a></p> |
| </li> |
| </ol> |
| </div></description></item><item><title>Docs: Implementation details</title><link>https://dubbo.apache.org/en/docs/v2.7/dev/implementation/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/en/docs/v2.7/dev/implementation/</guid><description> |
| <h2 id="initialization-details">Initialization details</h2> |
| <h3 id="service-parsing">Service parsing</h3> |
| <p>Based on <code>META-INF/spring.handlers</code> config in dubbo.jar, Spring calls <code>DubboNamespaceHandler</code> when meeting dubbo namespace.</p> |
| <p>All Dubbo tags are parsed by <code>DubboBeanDefinitionParser</code>, based on one to one attribute mapping, the XML label is parsed as a Bean object.</p> |
| <p>Transfer Bean object to URL, and transfer all attributes of Bean to URL parameters when <code>ServiceConfig.export()</code> or <code>ReferenceConfig.get()</code> initialization.</p> |
| <p>Then pase URL to <a href="../impls/protocol">Protocol extension point</a>, based on <a href="../spi/">Extension point adaptive mechanism</a> of extension point, processing service exposure or reference for different protocols according to URL protocol header.</p> |
| <h3 id="service-exposure">Service Exposure</h3> |
| <h4 id="1-only-expose-service-port">1. Only expose service port:</h4> |
| <p>Direct exposing to provider when have not Registry, <sup id="fnref:1"><a href="#fn:1" class="footnote-ref" role="doc-noteref">1</a></sup>, the URL format which parsing by <code>ServiceConfig</code>: |
| <code>dubbo://service-host/com.foo.FooService?version=1.0.0</code>.</p> |
| <p>Based on extension point adaptive mechanism, call <code>export()</code> method of <code>DubboProtocol</code> and open server port by identifying <code>dubbo://</code> protocol header of URL.</p> |
| <h4 id="2-expose-to-registry">2. Expose to Registry:</h4> |
| <p>Expose provider address to Registry <sup id="fnref:2"><a href="#fn:2" class="footnote-ref" role="doc-noteref">2</a></sup>, the URL format which parsing by <code>ServiceConfig</code>: <code>registry://registry-host/org.apache.dubbo.registry.RegistryService?export=URL.encode(&quot;dubbo://service-host/com.foo.FooService?version=1.0.0&quot;)</code>，</p> |
| <p>Based on extension point adaptive mechanism, call <code>export()</code> method of <code>RegistryProtocol</code> by identifying <code>registry://</code> protocol header, register the provider URL parameter of <code>export</code> to Registry.</p> |
| <p>Resend to <code>Protocol</code> extension point to do exposure: <code>dubbo://service-host/com.foo.FooService?version=1.0.0</code>, then based on extension point adaptive mechanism, call <code>export()</code> method of <code>DubboProtocol</code> and open server port by identifying <code>dubbo://</code> protocol header of provider URL.</p> |
| <h3 id="service-reference">Service Reference</h3> |
| <h4 id="1-direct-connect-service">1. Direct connect service</h4> |
| <p>Direct connect provider when have not Registry <sup id="fnref:3"><a href="#fn:3" class="footnote-ref" role="doc-noteref">3</a></sup>, the URL format which parsing by <code>ReferenceConfig</code>: <code>dubbo://service-host/com.foo.FooService?version=1.0.0</code>.</p> |
| <p>Based on extension point adaptive mechanism, call <code>refer()</code> method of <code>DubboProtocol</code> by identifying <code>dubbo://</code> protocol header of URL, and return provider reference.</p> |
| <h4 id="2-service-registry-discovery">2. Service Registry discovery</h4> |
| <p>Discover provider address by Registry <sup id="fnref:4"><a href="#fn:4" class="footnote-ref" role="doc-noteref">4</a></sup>, the URL format which parsing by <code>ReferenceConfig</code>: |
| <code>registry://registry-host/org.apache.dubbo.registry.RegistryService?refer=URL.encode(&quot;consumer://consumer-host/com.foo.FooService?version=1.0.0&quot;)</code>.</p> |
| <p>Based on extension point adaptive mechanism, call <code>refer()</code> method of <code>RegistryProtocol</code> by identifying <code>registry://</code> protocol header of URL, then based on the condition of parameter of <code>refer</code> to search provider URL, for example: <code>dubbo://service-host/com.foo.FooService?version=1.0.0</code>.</p> |
| <p>Then based on extension point adaptive mechanism, call <code>refer()</code> method of <code>DubboProtocol</code> to get provider reference by identifying <code>dubbo://</code> protocol header of provider URL.</p> |
| <p>Then <code>RegistryProtocol</code> disguise various provider references to single provider by <code>Cluster</code> extension point and return.</p> |
| <h3 id="service-filter">Service Filter</h3> |
| <p>Based on extension point adaptive mechanism, all <code>Protocol</code> extension points are auto wrapped <code>Wrapper</code> class.</p> |
| <p>Based on <code>ProtocolFilterWrapper</code> class, make all <code>Filter</code> as chain, call the real reference at the end of the chain.</p> |
| <p>Based on <code>ProtocolListenerWrapper</code> class, make all <code>InvokerListener</code> and <code>ExporterListener</code> as list, perform call back before and after exposure and reference.</p> |
| <p>All additional functions would be implementated by <code>Filter</code>, including Monitor.</p> |
| <h2 id="rpc-details">RPC details</h2> |
| <h3 id="the-detail-process-of-exposing-service-by-service-provider">The detail process of exposing service by service provider</h3> |
| <p><img src="https://dubbo.apache.org/imgs/dev/dubbo_rpc_export.jpg" alt="/dev-guide/images/dubbo_rpc_export.jpg"></p> |
| <p>The above image shows the main process of exposing service by service provider:</p> |
| <p>First <code>ServiceConfig</code> class get the actual class <code>ref</code> that provides service(e.g. 如：HelloWorldImpl), then generating a <code>AbstractProxyInvoker</code> instance by the <code>getInvoker</code> method of <code>ProxyFactory</code> class, to this step, complete the transformation of specific service to <code>Invoker</code>, next is the process of converting <code>Invoker</code> to <code>Exporter</code>.</p> |
| <p>The key of Dubbo processing service exposure is the process of converting <code>Invoker</code> to <code>Exporter</code>, the red part in the above image. Here we introduce the implementation of the two typical protocols, Dubbo and RMI:</p> |
| <h4 id="dubbo-implementation">Dubbo implementation</h4> |
| <p>The transformation from <code>Invoker</code> of Dubbo protocol to <code>Exporter</code> takes place in the <code>export</code> method of <code>DubboProtocol</code> class, it mainly opens the socket to listen service and receive all kinds of requests sent by the client, and the communication details are implementated by Dubbo itself.</p> |
| <h4 id="rmi-implementation">RMI implementation</h4> |
| <p>The transformation from <code>Invoker</code> of RMI protocol to <code>Exporter</code> takes place in the <code>export</code> method of <code>RmiProtocol</code> class, the RMI service is implementated by Spring, Dubbo or JDK, and the communication details are implementated by JDK, which saves a lot of work.</p> |
| <h3 id="the-detail-process-of-serving-service-for-service-consumer">The detail process of serving service for service consumer</h3> |
| <p><img src="https://dubbo.apache.org/imgs/dev/dubbo_rpc_refer.jpg" alt="/dev-guide/images/dubbo_rpc_refer.jpg"></p> |
| <p>The above image is the main process of service consumption:</p> |
| <p>First, the <code>init</code> method of <code>ReferenceConfig</code> class calls the <code>refer</code> method of <code>Protocol</code> to generate <code>Invoker</code> instance(such as the red part in the above image), which is the key of service consumption. Then the <code>Invoker</code> is converted to the interface required by the client (such as: HelloWorld).</p> |
| <p>For each protocol such as RMI/Dubbo/Web service, the details they call <code>refer</code> method generate <code>Invoker</code> instance are similar to the previous section.</p> |
| <h3 id="invoker-everywhere">Invoker everywhere</h3> |
| <p>Because of <code>Invoker</code> is a very important concept in the Dubbo domain model, many of the design ideas are close to it. This makes <code>Invoker</code> permeate the entire implementation code, and it&rsquo;s really easy to mix up for people who have just started Dubbo.</p> |
| <p>Let&rsquo;s use a simple image below to describe the 2 important <code>Invoker</code>: service provider <code>Invoker</code> and service consumer <code>Invoker</code>:</p> |
| <p><img src="https://dubbo.apache.org/imgs/dev/dubbo_rpc_invoke.jpg" alt="/dev-guide/images/dubbo_rpc_invoke.jpg"></p> |
| <p>To better explain the above image, we provide the below code examples of service consumption and providers:</p> |
| <p>Service consumer code:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">class</span> <span style="color:#268bd2">DemoClientAction</span> <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">private</span> DemoService demoService<span style="color:#719e07">;</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">public</span> <span style="color:#dc322f">void</span> <span style="color:#268bd2">setDemoService</span><span style="color:#719e07">(</span>DemoService demoService<span style="color:#719e07">)</span> <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">this</span><span style="color:#719e07">.</span>demoService <span style="color:#719e07">=</span> demoService<span style="color:#719e07">;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">}</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">public</span> <span style="color:#dc322f">void</span> <span style="color:#268bd2">start</span><span style="color:#719e07">()</span> <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> String hello <span style="color:#719e07">=</span> demoService<span style="color:#719e07">.</span>sayHello<span style="color:#719e07">(</span><span style="color:#2aa198">&#34;world&#34;</span><span style="color:#719e07">);</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">}</span> |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">}</span> |
| </span></span></code></pre></div><p>The <code>DemoService</code> in above code is the proxy of service consumer in above image, user can call <code>Invoker</code> <sup id="fnref:5"><a href="#fn:5" class="footnote-ref" role="doc-noteref">5</a></sup> which implementate the real RPC by the proxy.</p> |
| <p>Service provider code:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">class</span> <span style="color:#268bd2">DemoServiceImpl</span> <span style="color:#268bd2">implements</span> DemoService <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">public</span> String <span style="color:#268bd2">sayHello</span><span style="color:#719e07">(</span>String name<span style="color:#719e07">)</span> <span style="color:#268bd2">throws</span> RemoteException <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">return</span> <span style="color:#2aa198">&#34;Hello &#34;</span> <span style="color:#719e07">+</span> name<span style="color:#719e07">;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">}</span> |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">}</span> |
| </span></span></code></pre></div><p>The above class would be encapsulated to be a <code>AbstractProxyInvoker</code> instance, and create a new <code>Exporter</code> instance, then find corresponding <code>Exporter</code> instance and call its corresponding <code>AbstractProxyInvoker</code> instance when network communication layer recieve request, so that real call service provider code. There are some other <code>Invoker</code> classes, but the above 2 are the most important.</p> |
| <h2 id="remote-communication-details">Remote communication details</h2> |
| <h3 id="protocol-header-agreement">Protocol header agreement</h3> |
| <p><img src="https://dubbo.apache.org/imgs/dev/dubbo_protocol_header.png" alt="/dev-guide/images/dubbo_protocol_header.jpg"></p> |
| <ul> |
| <li> |
| <p>Magic - Magic High &amp; Magic Low (16 bits)</p> |
| <p>Identify protocol version, Dubbo protocol: 0xdabb</p> |
| </li> |
| <li> |
| <p>Req/Res (1 bit)</p> |
| <p>Identify a request or response. request: 1; response: 0.</p> |
| </li> |
| <li> |
| <p>2 Way (1 bit)</p> |
| <p>Only useful when Req/Res is 1(request), identifying if you expect to return a value from the server. Set to 1 if a return value from the server is required.</p> |
| </li> |
| <li> |
| <p>Event (1 bit)</p> |
| <p>Identifies whether it is an event message, for example, a heartbeat event. Set to 1 if this is an event.</p> |
| </li> |
| <li> |
| <p>Serialization ID (5 bit)</p> |
| <p>Identifies the serialization type: for example, the value of fastjson is 6.</p> |
| </li> |
| <li> |
| <p>Status (8 bits)</p> |
| <p>Only useful when Req/Res is 0 (response), used to identify the status of the response</p> |
| <ul> |
| <li>20 - OK</li> |
| <li>30 - CLIENT_TIMEOUT</li> |
| <li>31 - SERVER_TIMEOUT</li> |
| <li>40 - BAD_REQUEST</li> |
| <li>50 - BAD_RESPONSE</li> |
| <li>60 - SERVICE_NOT_FOUND</li> |
| <li>70 - SERVICE_ERROR</li> |
| <li>80 - SERVER_ERROR</li> |
| <li>90 - CLIENT_ERROR</li> |
| <li>100 - SERVER_THREADPOOL_EXHAUSTED_ERROR</li> |
| </ul> |
| </li> |
| <li> |
| <p>Request ID (64 bits)</p> |
| <p>Identifies the only request, the type is long.</p> |
| </li> |
| <li> |
| <p>Data Length (32 bits)</p> |
| <p>The length of the serialized content (variable part), counted in bytes, the type is int.</p> |
| </li> |
| <li> |
| <p>Variable Part</p> |
| <p>After being serialized by a specific serialization type (identified by the serialization ID), each part is a byte [] or byte.</p> |
| <ul> |
| <li>If it is a request packet (Req/Res = 1), each part is: |
| <ul> |
| <li>Dubbo version</li> |
| <li>Service name</li> |
| <li>Service version</li> |
| <li>Method name</li> |
| <li>Method parameter types</li> |
| <li>Method arguments</li> |
| <li>Attachments</li> |
| </ul> |
| </li> |
| <li>If it is a response packet (Req/Res = 0), each part is: |
| <ul> |
| <li>Return value&rsquo;s type (byte), identifying the type of value returned from the server: |
| <ul> |
| <li>Return null: RESPONSE_NULL_VALUE 2</li> |
| <li>Normal response value: RESPONSE_VALUE 1</li> |
| <li>Exception: RESPONSE_WITH_EXCEPTION 0</li> |
| </ul> |
| </li> |
| <li>Return value: response bytes returned from the server</li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| <p><strong>Note:</strong> For the variable part, when uses json serialization in current version of Dubbo framework, an additional line break is added as a separator between each part of the content. Please add a new line break after each part of the variable part, such as:</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-fallback" data-lang="fallback"><span style="display:flex;"><span>Dubbo version bytes (line break) |
| </span></span><span style="display:flex;"><span>Service name bytes (line break) |
| </span></span><span style="display:flex;"><span>... |
| </span></span></code></pre></div><h3 id="thread-dispatch-model">Thread dispatch model</h3> |
| <p><img src="https://dubbo.apache.org/imgs/dev/dubbo-protocol.jpg" alt="/dev-guide/images/dubbo-protocol.jpg"></p> |
| <ul> |
| <li>Dispather: <code>all</code>, <code>direct</code>, <code>message</code>, <code>execution</code>, <code>connection</code></li> |
| <li>ThreadPool: <code>fixed</code>, <code>cached</code></li> |
| </ul> |
| <div class="footnotes" role="doc-endnotes"> |
| <hr> |
| <ol> |
| <li id="fn:1"> |
| <p>is <code>&lt;dubbo:service regisrty=&quot;N/A&quot; /&gt;</code> or <code>&lt;dubbo:registry address=&quot;N/A&quot; /&gt;</code>&#160;<a href="#fnref:1" class="footnote-backref" role="doc-backlink">&#x21a9;&#xfe0e;</a></p> |
| </li> |
| <li id="fn:2"> |
| <p>is <code>&lt;dubbo:registry address=&quot;zookeeper://10.20.153.10:2181&quot; /&gt;</code>&#160;<a href="#fnref:2" class="footnote-backref" role="doc-backlink">&#x21a9;&#xfe0e;</a></p> |
| </li> |
| <li id="fn:3"> |
| <p>is <code>&lt;dubbo:reference url=&quot;dubbo://service-host/com.foo.FooService?version=1.0.0&quot; /&gt;</code>&#160;<a href="#fnref:3" class="footnote-backref" role="doc-backlink">&#x21a9;&#xfe0e;</a></p> |
| </li> |
| <li id="fn:4"> |
| <p>is <code>&lt;dubbo:registry address=&quot;zookeeper://10.20.153.10:2181&quot; /&gt;</code>&#160;<a href="#fnref:4" class="footnote-backref" role="doc-backlink">&#x21a9;&#xfe0e;</a></p> |
| </li> |
| <li id="fn:5"> |
| <p>is one of <code>DubboInvoker</code>, <code>HessianRpcInvoker</code>, <code>InjvmInvoker</code>, <code>RmiInvoker</code>, <code>WebServiceInvoker</code>&#160;<a href="#fnref:5" class="footnote-backref" role="doc-backlink">&#x21a9;&#xfe0e;</a></p> |
| </li> |
| </ol> |
| </div></description></item><item><title>Docs: Dubbo Design Principals</title><link>https://dubbo.apache.org/en/docs/v2.7/dev/principals/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/en/docs/v2.7/dev/principals/</guid><description> |
| <p>The design principles in this chapter are taken from a series of articles published by Liang Fei on javaeye.</p></description></item><item><title>Docs: SPI Extension Implementations</title><link>https://dubbo.apache.org/en/docs/v2.7/dev/impls/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/en/docs/v2.7/dev/impls/</guid><description> |
| <p>SPI extension interface is used for system integration, it&rsquo;s also useful for dubbo contributor to extend dubbo functionality.</p></description></item><item><title>Docs: Public Agreement</title><link>https://dubbo.apache.org/en/docs/v2.7/dev/contract/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/en/docs/v2.7/dev/contract/</guid><description> |
| <p>This document is Dubbo public agreement, we expect all extension points comply with it.</p> |
| <h2 id="url">URL</h2> |
| <ul> |
| <li>All extension points must include URL parameter, design URL as a context information which throughouts the whole extension point design system.</li> |
| <li>URL standard style: <code>protocol://username:password@host:port/path?key=value&amp;key=value</code></li> |
| </ul> |
| <h2 id="logging">Logging</h2> |
| <ul> |
| <li>Print <code>ERROR</code> log for unrecoverable and NEED TO ALARM situation.</li> |
| <li>Print <code>WARN</code> log for recoverable exception or transient state inconsistency.</li> |
| <li>Print <code>INFO</code> log for normally status.</li> |
| </ul></description></item><item><title>Docs: Versions</title><link>https://dubbo.apache.org/en/docs/v2.7/dev/release/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/en/docs/v2.7/dev/release/</guid><description> |
| <p><strong>New feature development</strong> and <strong>stability improvement</strong> are equally important to product. But adding new features will affect stability, dubbo uses the following version development pattern to achieve a good balance.</p> |
| <h2 id="two-versions-evolving-at-the-same-time">Two versions evolving at the same time</h2> |
| <ul> |
| <li>BugFix Version：low version，e.g. <code>2.4.x</code>. This is called the GA version, which can be applied in production. We are supposed only to fix bugs in this version, and increase the third version number when release.</li> |
| <li>Feature Version：high version, e.g. <code>2.5.x</code>. We add new features to this version, so applications have opportunities try new features.</li> |
| </ul> |
| <p>When features in <code>2.5.x</code> are proved stable enough, we will announce <code>2.5.x</code> as a beta release.</p> |
| <p>When <code>2.5.x</code> proved stable after enough test on enough applications：</p> |
| <ul> |
| <li><code>2.5.x</code>, the GA Version, only do BugFix, the main version to be used. We can try to promote applications to upgrade to GA at the desired time.</li> |
| <li><code>2.4.x</code>, no longer maintained. When bugs appear, applications have no choice but upgrade to the latest stable version- Sunset Clause</li> |
| <li>We create a new branch <code>2.6.0</code> based on <code>2.5.x</code> for new features.</li> |
| </ul> |
| <h2 id="pros">Pros</h2> |
| <ul> |
| <li>GA Version are promised stable: |
| <ul> |
| <li>only BugFix</li> |
| <li>GA Version got enough tests before promotion</li> |
| </ul> |
| </li> |
| <li>New features can respond quickly in Feature Version and allow applications to try that</li> |
| <li>Significantly reduces development and maintenance costs</li> |
| </ul> |
| <h2 id="the-responsibilities-of-users">The responsibilities of users</h2> |
| <p>Users should always keep in track with the GA Version, make sure all bugs were fixed.</p> |
| <p>There is a fake proposition: regular upgrades bring more risks. Here&rsquo;s the reasons:</p> |
| <ul> |
| <li>GA remains stable after a trial period.</li> |
| <li>Bugs find on GA will be fixed immediately.</li> |
| <li>Comparing with the on-need-upgrade (only upgrade when find a serious problem, and may span multiple versions), upgrade periodically can flat risk. Experienced a long cycle of large projects, students will have such an experience, the tripartite library version does not upgrade for a long time, the result of the problem had to upgrade to the new version (across multiple versions) a huge risk.</li> |
| </ul></description></item><item><title>Docs: Checklist</title><link>https://dubbo.apache.org/en/docs/v2.7/dev/checklist/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/en/docs/v2.7/dev/checklist/</guid><description> |
| <h2 id="checklist-before-release">Checklist before release</h2> |
| <ul> |
| <li>github milestones</li> |
| <li>github change lists</li> |
| <li>Travis CI</li> |
| <li>test code</li> |
| <li>find bugs</li> |
| </ul> |
| <h2 id="checklist-for-bigfix-versions">Checklist for bigfix versions</h2> |
| <ul> |
| <li>Create a <em>github issue</em> before coding</li> |
| <li>Create <em>unit test</em> before bugfix</li> |
| <li>Review</li> |
| <li>Test your code (Normal process / Abnormal process)</li> |
| <li>Record your design on <em>github issue</em></li> |
| <li>Complete javadoc and comment in code</li> |
| <li>Manager for every version, responsible for scope and check</li> |
| </ul></description></item><item><title>Docs: Bad Smell</title><link>https://dubbo.apache.org/en/docs/v2.7/dev/code-smell/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/en/docs/v2.7/dev/code-smell/</guid><description> |
| <p>Ugly Dubbo design or implementation will be record here.</p> |
| <h2 id="url-convertion">URL Convertion</h2> |
| <h3 id="1-point-to-point-service-export-and-refer">1. Point to Point Service export and refer</h3> |
| <p>service directly export：</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-fallback" data-lang="fallback"><span style="display:flex;"><span>EXPORT(dubbo://provider-address/com.xxx.XxxService?version=1.0.0&#34;) |
| </span></span></code></pre></div><p>service directly refer：</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-fallback" data-lang="fallback"><span style="display:flex;"><span>REFER(dubbo://provider-address/com.xxx.XxxService?version=1.0.0) |
| </span></span></code></pre></div><h3 id="2-export-servie-by-registry">2. Export servie by registry</h3> |
| <p>export service to registry：</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-fallback" data-lang="fallback"><span style="display:flex;"><span>EXPORT(registry://registry-address/org.apache.dubbo.registry.RegistrySerevice?registry=dubbo&amp;export=ENCODE(dubbo://provider-address/com.xxx.XxxService?version=1.0.0)) |
| </span></span></code></pre></div><p>accquire registry：</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-fallback" data-lang="fallback"><span style="display:flex;"><span>url.setProtocol(url.getParameter(&#34;registry&#34;, &#34;dubbo&#34;)) |
| </span></span><span style="display:flex;"><span>GETREGISTRY(dubbo://registry-address/org.apache.dubbo.registry.RegistrySerevice) |
| </span></span></code></pre></div><p>registry service address：</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-fallback" data-lang="fallback"><span style="display:flex;"><span>url.getParameterAndDecoded(&#34;export&#34;)) |
| </span></span><span style="display:flex;"><span>REGISTER(dubbo://provider-address/com.xxx.XxxService?version=1.0.0) |
| </span></span></code></pre></div><h3 id="3-refer-service-from-registry">3. Refer service from registry</h3> |
| <p>refer service from registry：</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-fallback" data-lang="fallback"><span style="display:flex;"><span>REFER(registry://registry-address/org.apache.dubbo.registry.RegistrySerevice?registry=dubbo&amp;refer=ENCODE(version=1.0.0)) |
| </span></span></code></pre></div><p>accquire registry：</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-fallback" data-lang="fallback"><span style="display:flex;"><span>url.setProtocol(url.getParameter(&#34;registry&#34;, &#34;dubbo&#34;)) |
| </span></span><span style="display:flex;"><span>GETREGISTRY(dubbo://registry-address/org.apache.dubbo.registry.RegistrySerevice) |
| </span></span></code></pre></div><p>subscribe service address：</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-fallback" data-lang="fallback"><span style="display:flex;"><span>url.addParameters(url.getParameterAndDecoded(&#34;refer&#34;)) |
| </span></span><span style="display:flex;"><span>SUBSCRIBE(dubbo://registry-address/com.xxx.XxxService?version=1.0.0) |
| </span></span></code></pre></div><p>notify service address：</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-fallback" data-lang="fallback"><span style="display:flex;"><span>url.addParameters(url.getParameterAndDecoded(&#34;refer&#34;)) |
| </span></span><span style="display:flex;"><span>NOTIFY(dubbo://provider-address/com.xxx.XxxService?version=1.0.0) |
| </span></span></code></pre></div><h3 id="4-registry-push-route-rule">4. Registry push route rule</h3> |
| <p>registry push route rule：</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-fallback" data-lang="fallback"><span style="display:flex;"><span>NOTIFY(route://registry-address/com.xxx.XxxService?router=script&amp;type=js&amp;rule=ENCODE(function{...})) |
| </span></span></code></pre></div><p>accquire routers：</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-fallback" data-lang="fallback"><span style="display:flex;"><span>url.setProtocol(url.getParameter(&#34;router&#34;, &#34;script&#34;)) |
| </span></span><span style="display:flex;"><span>GETROUTE(script://registry-address/com.xxx.XxxService?type=js&amp;rule=ENCODE(function{...})) |
| </span></span></code></pre></div><h3 id="5-load-route-rule-from-file">5. Load route rule from file</h3> |
| <p>load route rule from file：</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-fallback" data-lang="fallback"><span style="display:flex;"><span>GETROUTE(file://path/file.js?router=script) |
| </span></span></code></pre></div><p>accquire routers：</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-fallback" data-lang="fallback"><span style="display:flex;"><span>url.setProtocol(url.getParameter(&#34;router&#34;, &#34;script&#34;)).addParameter(&#34;type&#34;, SUFFIX(file)).addParameter(&#34;rule&#34;, READ(file)) |
| </span></span><span style="display:flex;"><span>GETROUTE(script://path/file.js?type=js&amp;rule=ENCODE(function{...})) |
| </span></span></code></pre></div><h2 id="invoke-parameters">Invoke parameters</h2> |
| <ul> |
| <li>path service path</li> |
| <li>group service group</li> |
| <li>version service version</li> |
| <li>dubbo current dubbo release version</li> |
| <li>token verify token</li> |
| <li>timeout invocation timeout</li> |
| </ul> |
| <h2 id="spi-loading">SPI Loading</h2> |
| <h3 id="1-spi-auto-adaptive">1. SPI Auto Adaptive</h3> |
| <p>When ExtensionLoader loads SPI, It will check spi attributes(using set method) . If one attribute is SPI, ExtensionLoader will load the SPI implementation. Auto injected object is an adaptive instance（proxy） ,because the real implementation is confirmed only in execution stage.。when adaptive spi is invoked, Dubbo will choose the real implementation and executes it. Dubbo choose the right implementation according to the parameters that the mehod defines.</p> |
| <p>All the inner SPIs that Dubbo defines have the URL parameter defined for the method invocation. Adaptive SPI uses URL to determine which implementation is needed. One specific Key and Value in the URL confirms the usage of the specific implementation, All these is done by adding <code>@Adaptive</code> annotation.</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#268bd2">@Extension</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">interface</span> <span style="color:#268bd2">Car</span> <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@Adaptive</span><span style="color:#719e07">({</span><span style="color:#2aa198">&#34;http://10.20.160.198/wiki/display/dubbo/car.type&#34;</span><span style="color:#719e07">,</span> <span style="color:#2aa198">&#34;http://10.20.160.198/wiki/display/dubbo/transport.type&#34;</span><span style="color:#719e07">})</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">public</span> <span style="color:#268bd2">run</span><span style="color:#719e07">(</span>URL url<span style="color:#719e07">,</span> Type1 arg1<span style="color:#719e07">,</span> Type2 arg2<span style="color:#719e07">);</span> |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">}</span> |
| </span></span></code></pre></div><p>For the rules above，ExtensionLoader will create a adaptive instance for each SPI injected.</p> |
| <p>ExtensionLoader generated adaptive classes look like ：</p> |
| <div class="highlight"><pre tabindex="0" style="color:#93a1a1;background-color:#002b36;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-java" data-lang="java"><span style="display:flex;"><span><span style="color:#719e07">package</span> &lt;package name <span style="color:#719e07">for</span> SPI interface<span style="color:#719e07">&gt;;</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">class</span> &lt;<span style="color:#268bd2">SPI</span> <span style="color:#268bd2">interface</span> <span style="color:#268bd2">name</span><span style="color:#719e07">&gt;</span>$Adpative <span style="color:#268bd2">implements</span> <span style="color:#719e07">&lt;</span>SPI interface<span style="color:#719e07">&gt;</span> <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">public</span> <span style="color:#719e07">&lt;</span>contains <span style="color:#268bd2">@Adaptive</span> annotation method<span style="color:#719e07">&gt;(&lt;</span>parameters<span style="color:#719e07">&gt;)</span> <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">if</span><span style="color:#719e07">(</span>parameters containing URL Type<span style="color:#719e07">?)</span> using URL parameter |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">else</span> <span style="color:#268bd2">if</span><span style="color:#719e07">(</span>method returns URL<span style="color:#719e07">)</span> using the <span style="color:#719e07">return</span> URL |
| </span></span><span style="display:flex;"><span> # <span style="color:#719e07">&lt;</span><span style="color:#719e07">else</span> <span style="color:#719e07">throw</span> exception<span style="color:#719e07">,</span>inject SPI fail！<span style="color:#719e07">&gt;</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">if</span><span style="color:#719e07">(</span>URL accquired <span style="color:#719e07">==</span> <span style="color:#cb4b16">null</span><span style="color:#719e07">)</span> <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">throw</span> <span style="color:#719e07">new</span> IllegalArgumentException<span style="color:#719e07">(</span><span style="color:#2aa198">&#34;url == null&#34;</span><span style="color:#719e07">);</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">}</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> According to the Key order from <span style="color:#268bd2">@Adaptive</span> annotation，get the Value from the URL as the real SPI name |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">if</span> no value is found then use the <span style="color:#719e07">default</span> SPI implementation。If no SPI point， <span style="color:#719e07">throw</span> <span style="color:#719e07">new</span> IllegalStateException<span style="color:#719e07">(</span><span style="color:#2aa198">&#34;Fail to get extension&#34;</span><span style="color:#719e07">);</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> Invoke the method using the spi and <span style="color:#719e07">return</span> the result<span style="color:#719e07">.</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">}</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">public</span> <span style="color:#719e07">&lt;</span>method having annotation <span style="color:#268bd2">@Adaptive</span><span style="color:#719e07">&gt;(&lt;</span>parameters<span style="color:#719e07">&gt;)</span> <span style="color:#719e07">{</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">throw</span> <span style="color:#719e07">new</span> UnsupportedOperationException<span style="color:#719e07">(</span><span style="color:#2aa198">&#34;is not adaptive method!&#34;</span><span style="color:#719e07">);</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">}</span> |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">}</span> |
| </span></span></code></pre></div><p><code>@Adaptive</code> annotation usage：</p> |
| <p>If no value is configed for those Keys in URL，default SPI implementation is used。For example ，String[] {&ldquo;key1&rdquo;, &ldquo;key2&rdquo;}，firstly Dubbo will look up value for key1 and use it as SPI name;if key1 value is not founded then look up for key2，if value of key2 is also not found ,then use default spi implementation. If no default implementation is configed, then the method will throw IllegalStateException。if not configed , then default implement is lower case of the interface class full package name. For Extension interface <code>org.apache.dubbo.xxx.YyyInvokerWrapper</code> , default value is <code>new String[] {&quot;yyy.invoker.wrapper&quot;}</code></p> |
| <h2 id="callback-function">Callback Function</h2> |
| <h3 id="1-parameter-callback">1. Parameter Callback</h3> |
| <p>main theory ： in the persistent connection for one consumer-&gt;provider，export a service in Consumer side，provider side can reversely call the instance in consumer side.</p> |
| <p>Implement details：</p> |
| <ul> |
| <li>For exchanging interface instance in transmition, auto export and auto refer is implemented in DubboCodec . Need to seperate business logic and codec logic.</li> |
| <li>you will need to judge whether needing callback when getting exporter from invocation，if needed, get the callback instance id from the attachments. By using this method, consumer side can implement the callback interface with different implementations.</li> |
| </ul> |
| <h3 id="2-event-notification">2. Event Notification</h3> |
| <p>main theory ： when Consumer executing invoke method，judging if any configuration for onreturn/onerror&hellip; put the method for onreturn to the callback list of the async invocatioin.</p> |
| <p>Implement details：parameters is passed using URL，but string-object is not supported for URL, so the method is stored in staticMap，it needs to be optimized.</p> |
| <h2 id="lazy-connection">Lazy Connection</h2> |
| <p>DubboProtocol specific features, default disabled</p> |
| <p>When client creating proxy for server, do not establish TCP persistent connection at first, only init the connecton when data is needing transmision.</p> |
| <p>This feather will disable the connection retry policy , resend the data again(if connection is lost when sending data ,try to establish a new connection to send data)</p> |
| <h2 id="share-connection">Share Connection</h2> |
| <p>DubboProtocol specific features, default enabled。</p> |
| <p>JVM A export many services，JVM B refer more than one services of A，Share Connection means those different services invocations between A and B uses the same TCP connection to transmit data, reducing server connections.</p> |
| <p>Implement details：when using share connection for the same address，you need pay more attention to the invoker&rsquo;s destroy action.on one hand, you should close the connection when all the invokers refering the same address is destroyed, on another hand ,you should not close the connection when not all of the invokers are destroyed. In design implementation, we uses a strategy called reference count , we create a connection called Lazy connection for exceptions not affacting business when closing the connection just in case.</p> |
| <h2 id="sticky-policy">sticky policy</h2> |
| <p>when existing many providers and configing the sticky policy，invocation will be sent to the same provider as last invocation. Sticky Policy opens the lazy attribute of connection, for avoiding open useless connectons.</p> |
| <h2 id="provider-selecting-logic">provider selecting logic</h2> |
| <ol start="0"> |
| <li>existing multi providers，firstly select by Loadbalance 。If the selected provider is available ,then just doing the invocation</li> |
| <li>If the selected provider is not available in stage 1, then choose from the remaining ,if available then doing the inovation</li> |
| <li>If all providers are not available , rescan the list(not choosen invoker first),juding if any provider is available, if existing,doing the invocatiion.</li> |
| <li>If no available provider in stage 3, then the next invoker of the invoker of stage 1 will be choosen(if not the last one),avoiding collision.</li> |
| </ol></description></item><item><title>Docs: Coding Convention</title><link>https://dubbo.apache.org/en/docs/v2.7/dev/coding/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/en/docs/v2.7/dev/coding/</guid><description> |
| <h2 id="code-style">Code style</h2> |
| <p>The source and JavaDoc of Dubbo follow below specifications:</p> |
| <ul> |
| <li><a href="http://www.oracle.com/technetwork/java/codeconvtoc-136057.html">Code Conventions for the Java Programming Language</a></li> |
| <li><a href="http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html">How to Write Doc Comments for the Javadoc Tool</a></li> |
| </ul> |
| <h2 id="exception-and-logging">Exception and Logging</h2> |
| <ul> |
| <li>Log more context information as possible, such as error reason, error server address, client address, registry center address, dubbo version and so on.</li> |
| <li>Try to put the main cause at the front, and display all other context information with key-value paris after it.</li> |
| <li>Log is not printed where the exception is thrown, log level is determined by the final exception handler, and must print log when dicarding exception.</li> |
| <li><code>ERROR</code> log means NEED TO ALARM, <code>WARN</code> log means COULD AUTO RECOVERY, <code>INFO</code> long mean NORMAL.</li> |
| <li>Suggestion: config <code>ERROR</code> log in Monitor center for real-time alarm, summary and send <code>WARN</code> log weekly.</li> |
| <li><code>RpcException</code> is the ONLY external exception of Dubbo，all internal exceptions mush be transfered to <code>RpcException</code> if need to throw out to user.</li> |
| <li><code>RpcException</code> CAN NOT have sub-class, all types of information are identified with ErrorCode in order to keep compatible.</li> |
| </ul> |
| <h2 id="configuration-and-url">Configuration and URL</h2> |
| <ul> |
| <li>Use initials and camelCase for multiple words for object properties <sup id="fnref:1"><a href="#fn:1" class="footnote-ref" role="doc-noteref">1</a></sup>.</li> |
| <li>Use lowercase and split by &lsquo;-&rsquo; for multiple words for config properties <sup id="fnref:2"><a href="#fn:2" class="footnote-ref" role="doc-noteref">2</a></sup>.</li> |
| <li>Use lowercase and split by &lsquo;.&rsquo; for multiple words for URL properties <sup id="fnref:3"><a href="#fn:3" class="footnote-ref" role="doc-noteref">3</a></sup>.</li> |
| <li>Use URL transfer parameters as possible, Don&rsquo;t define Map or other types, config information also transfer to URL style.</li> |
| <li>Minimize URL nesting to keep URL simplicity.</li> |
| </ul> |
| <h2 id="unit-testing-and-integration-testing">Unit testing and integration testing</h2> |
| <ul> |
| <li>Use JUnit and EasyMock for unit testing, use TestNG for integration testing, use DBUnit for database testing.</li> |
| <li>Don&rsquo;t put large integration test case in unit testing for running speed of unit test case.</li> |
| <li>Use <code>try...finally</code> or <code>tearDown</code> to release resource for all test cases of unit testing.</li> |
| <li>Minimize test case that with <code>while</code> loop which need waiting repsonse, use to make the logic in timer as function for timer and net testing.</li> |
| <li>For fail-safe testing, unified use <code>LogUtil</code> assertion log output.</li> |
| </ul> |
| <h2 id="extension-point-base-class-and-aop">Extension point base class and AOP</h2> |
| <ul> |
| <li>AOP class should be named as <code>XxxWrapper</code>，Base class should be named as <code>AbstractXxx</code>.</li> |
| <li>Use AOP for combine relationship between extension points, <code>ExtensionLoader</code> only loads extension points, including AOP extension.</li> |
| <li>Try to use Ioc inject dependency of extension points, Don&rsquo;t direct dependent on factory method of <code>ExtensionLoader</code>.</li> |
| <li>Try to use AOP implement the common action of extension points, instead of using base class, such as the <code>isAvailable</code> checking before load balancing, which is independent of load balance. Close the URL paramters which no need to check.</li> |
| <li>Use base class for abstaction for a variety of similar types, such as RMI, Hessian 3rd protocols which have generated interface proxy, only transfer interface proxy to <code>Invoker</code> to complete bridging, and public base class can do the logic.</li> |
| <li>The base class is also part of the SPI, and each extension should have a convenient base class support.</li> |
| </ul> |
| <h2 id="module-and-packaging">Module and packaging</h2> |
| <ul> |
| <li>Base on reusability for packaging, dividing the interface, base class and large implementation into separate modules.</li> |
| <li>Put all interfaces under the base package of module, and put base classes in support subpackage, different implementations are placed under the subpackage named by extension point.</li> |
| <li>Try to keep subpackage dependent on parent package, NOT reverse.</li> |
| </ul> |
| <div class="footnotes" role="doc-endnotes"> |
| <hr> |
| <ol> |
| <li id="fn:1"> |
| <p>Java convention&#160;<a href="#fnref:1" class="footnote-backref" role="doc-backlink">&#x21a9;&#xfe0e;</a></p> |
| </li> |
| <li id="fn:2"> |
| <p>Spring convention&#160;<a href="#fnref:2" class="footnote-backref" role="doc-backlink">&#x21a9;&#xfe0e;</a></p> |
| </li> |
| <li id="fn:3"> |
| <p>Dubbo convention&#160;<a href="#fnref:3" class="footnote-backref" role="doc-backlink">&#x21a9;&#xfe0e;</a></p> |
| </li> |
| </ol> |
| </div></description></item><item><title>Docs: Compatibility Test</title><link>https://dubbo.apache.org/en/docs/v2.7/dev/tck/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/en/docs/v2.7/dev/tck/</guid><description> |
| <p>Dubbo&rsquo;s protocol, communication, serialization, registry, load balancing and other SPI all offer alternative strategies for different application scenarios while our test cases are very scattered. Ours is always uncertain whether it can satisfy the complete contract of the extension point when users need to add a new implementation.</p> |
| <p>Thus we need to use TCK (Technology Compatibility Kit) for the core extension points. When users add a new implementaion, compatibility with the rest of the framework can be ensured with TCK. This can effectively improve the overall health and also facilitate the access of the third party extenders, which accelerates the maturity of the open source community.</p> |
| <p>Xingzhi from the open source community is already working on this part. His preliminary idea is to build a TCK framework for Dubbo drawing on the CDI-TCK of JBoss first, then realize the TCK implementing case of Dubbo.</p> |
| <p>Reference：http://docs.jboss.org/cdi/tck/reference/1.0.1-Final/html/introduction.html</p> |
| <p>Anyone interested is welcomed to work on this together.</p> |
| <h4 id="protocol-tck">Protocol TCK</h4> |
| <blockquote> |
| <p>TODO</p> |
| </blockquote> |
| <h4 id="registry-tck">Registry TCK</h4> |
| <blockquote> |
| <p>TODO</p> |
| </blockquote></description></item></channel></rss> |
