| <rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom"><channel><title>Apache Dubbo – RPC protocol</title><link>https://dubbo.apache.org/en/docs3-v2/java-sdk/reference-manual/protocol/</link><description>Recent content in RPC protocol on Apache Dubbo</description><generator>Hugo -- gohugo.io</generator><language>en</language><atom:link href="https://dubbo.apache.org/en/docs3-v2/java-sdk/reference-manual/protocol/index.xml" rel="self" type="application/rss+xml"/><item><title>Docs3-V2: Protocol Overview</title><link>https://dubbo.apache.org/en/docs3-v2/java-sdk/reference-manual/protocol/overview/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/en/docs3-v2/java-sdk/reference-manual/protocol/overview/</guid><description> |
| <p>Dubbo3 provides Triple (Dubbo3) and Dubbo2 protocols, which are native protocols of the Dubbo framework. In addition, Dubbo3 also integrates many third-party protocols and incorporates them into Dubbo&rsquo;s programming and service governance system. |
| Including gRPC, Thrift, JsonRPC, Hessian2, REST, etc. The following focuses on the Triple and Dubbo2 protocols.</p> |
| <h2 id="protocol-description">protocol description</h2> |
| <p>The Triple protocol is the main protocol launched by Dubbo3. Triple means the third generation. Through the evolution of the Dubbo1.0/Dubbo2.0 two-generation protocol and the wave of technology standardization brought by cloud native, the new Dubbo3 protocol Triple came into being.</p> |
| <h3 id="select-the-rpc-protocol">Select the RPC protocol</h3> |
| <p>The protocol is the core of RPC, which regulates the content and format of data transmission in the network. In addition to the necessary request and response data, it usually contains additional control data, such as the serialization method of a single request, timeout period, compression method, and authentication information.</p> |
| <p>The content of the agreement consists of three parts</p> |
| <ul> |
| <li>Data exchange format: Define the byte stream content of RPC request and response objects in network transmission, also known as serialization mode</li> |
| <li>Protocol structure: defines the list of fields, the semantics of each field, and the arrangement of different fields</li> |
| <li>Protocols define how data is transmitted across networks by defining rules, formats, and semantics. A successful RPC requires both ends of the communication to be able to read and write network byte streams and convert objects according to the protocol. If the two ends cannot reach an agreement on the protocol used, there will be chickens talking with ducks, which cannot meet the needs of long-distance communication.</li> |
| </ul> |
| <p><img src="https://dubbo.apache.org/imgs/v3/concepts/triple-protocol.png" alt="Protocol Selection"></p> |
| <p>The design of the RPC protocol needs to consider the following:</p> |
| <ul> |
| <li>Versatility: Unified binary format, cross-language, cross-platform, multi-transport layer protocol support</li> |
| <li>Extensibility: protocol adds fields, upgrades, supports user extensions and additional business metadata</li> |
| <li>Performance: As fast as it can be</li> |
| <li>Penetration: can be identified and forwarded by various terminal devices: gateways, proxy servers, etc. |
| Generally, versatility and high performance cannot be achieved at the same time, and protocol designers need to make certain trade-offs.</li> |
| </ul> |
| <h3 id="http11-protocol">HTTP/1.1 protocol</h3> |
| <p>Compared with the private RPC protocol directly built on the TCP transport layer, the remote call solution built on HTTP will have better versatility, such as WebServices or REST architecture, using HTTP + JSON can be said to be a de facto standard solution .</p> |
| <p>Choosing to build on top of HTTP has two biggest advantages:</p> |
| <ul> |
| <li>The semantics and scalability of HTTP well meet the requirements of RPC calls.</li> |
| <li>Versatility, the HTTP protocol is supported by almost all devices on the network, and has good protocol penetration.</li> |
| </ul> |
| <p>But there are also obvious problems:</p> |
| <ul> |
| <li>In a typical Request-Response model, there can only be one waiting Request request on a link at a time. HOL will be generated.</li> |
| <li>Human Readable Headers, using a more general, human-readable header transfer format, but with considerably poorer performance</li> |
| <li>No direct Server Push support, need to use workarounds such as Polling Long-Polling</li> |
| </ul> |
| <h3 id="grpc-protocol">gRPC protocol</h3> |
| <p>The above mentioned the advantages and disadvantages of building the RPC protocol on top of the HTTP and TCP protocols. Compared with Dubbo built on the TCP transport layer, Google chose to define gRPC directly on top of the HTTP/2 protocol. |
| The advantages of gRPC are inherited from HTTP2 and Protobuf.</p> |
| <ul> |
| <li>The HTTP2-based protocol is simple enough, with low learning costs for users, and naturally has server push/multiplexing/flow control capabilities</li> |
| <li>Protobuf-based multi-language cross-platform binary compatibility, providing powerful unified cross-language capabilities</li> |
| <li>The ecology based on the protocol itself is relatively rich, the natural support protocol of components such as k8s/etcd, and the de facto protocol standard of cloud native</li> |
| </ul> |
| <p>But there are also some problems</p> |
| <ul> |
| <li>The support for service governance is relatively basic, and it is more inclined to the basic RPC function. The protocol layer lacks the necessary unified definition, and it is not easy for users to use it directly.</li> |
| <li>The serialization method of strong binding protobuf requires high learning cost and transformation cost. For the existing monolingual users, the migration cost cannot be ignored</li> |
| </ul> |
| <h3 id="finally-choose-the-triple-protocol">Finally choose the Triple protocol</h3> |
| <p>In the end, we chose to be compatible with gRPC and use HTTP2 as the transport layer to build a new protocol, which is Triple.</p> |
| <p>The rise of containerized applications and microservices has led to the development of techniques optimized for workload content. The traditional communication protocols (RESTFUL or other HTTP-based custom protocols) used in the client are difficult to meet the convenience requirements of the application in terms of performance, maintainability, scalability, and security. A cross-language, modular protocol will gradually become a new application development protocol standard. Since the gRPC protocol became a CNCF project in 2017, more and more infrastructure and businesses including k8s and etcd have begun to use the gRPC ecosystem. As a cloud-native microservice framework, Dubbo&rsquo;s new protocol is also perfectly compatible with gRPC . Moreover, Triple will also enhance and supplement some imperfect parts of the gRPC protocol.</p> |
| <p>So, does the Triple protocol solve the series of problems we mentioned above?</p> |
| <ul> |
| <li>In terms of performance: The Triple protocol adopts the strategy of separating metadata and payload, so that intermediate devices, such as gateways, can be avoided to parse and deserialize payload, thereby reducing response time.</li> |
| <li>In terms of routing support, since metadata supports users to add custom headers, users can more conveniently divide clusters or perform routing according to headers, so that when publishing, there is more flexibility in switching grayscale or disaster recovery.</li> |
| <li>In terms of security, it supports encrypted transmission capabilities such as two-way TLS authentication (mTLS).</li> |
| <li>In terms of ease of use, in addition to supporting Protobuf serialization recommended by native gRPC, Triple supports other serializations such as Hessian/JSON in a general way, allowing users to upgrade to the Triple protocol more conveniently. For the original Dubbo service, modifying or adding the Triple protocol only needs to add a line of protocol configuration in the code block declaring the service, and the transformation cost is almost zero.</li> |
| </ul> |
| <h2 id="triple-protocol">Triple protocol</h2> |
| <p><img src="https://dubbo.apache.org/imgs/v3/concepts/triple.png" alt="Triple protocol communication method"></p> |
| <p>status quo</p> |
| <ul> |
| <li> |
| <ol> |
| <li>Fully compatible with grpc, client/server can connect with native grpc client</li> |
| </ol> |
| </li> |
| <li> |
| <ol start="2"> |
| <li>At present, it has been verified by large-scale production practice and has reached the production level</li> |
| </ol> |
| </li> |
| </ul> |
| <p>Features and advantages</p> |
| <ul> |
| <li> |
| <ol> |
| <li>Capable of cross-language intercommunication. Both the traditional multi-language multi-SDK mode and the Mesh cross-language mode require a more general and scalable data transmission format.</li> |
| </ol> |
| </li> |
| <li> |
| <ol start="2"> |
| <li>Provide a more complete request model. In addition to the Request/Response model, it should also support Streaming and Bidirectional.</li> |
| </ol> |
| </li> |
| <li> |
| <ol start="3"> |
| <li>Easy to expand, high penetration, including but not limited to Tracing / Monitoring and other support, should also be recognized by devices at all levels, gateway facilities, etc. can identify data packets, friendly to Service Mesh deployment, and reduce the difficulty of understanding for users.</li> |
| </ol> |
| </li> |
| <li> |
| <ol start="4"> |
| <li>Multiple serialization methods support and smooth upgrade</li> |
| </ol> |
| </li> |
| <li> |
| <ol start="5"> |
| <li>Support Java users to upgrade without awareness, no need to define cumbersome IDL files, and only need to simply modify the protocol name to easily upgrade to the Triple protocol</li> |
| </ol> |
| </li> |
| </ul> |
| <h3 id="triple-protocol-content-introduction">Triple protocol content introduction</h3> |
| <p>Further extension based on the grpc protocol</p> |
| <ul> |
| <li>Service-Version → &ldquo;tri-service-version&rdquo; {Dubbo service version}</li> |
| <li>Service-Group → &ldquo;tri-service-group&rdquo; {Dubbo service group}</li> |
| <li>Tracing-ID → &ldquo;tri-trace-traceid&rdquo; {tracing id}</li> |
| <li>Tracing-RPC-ID → &ldquo;tri-trace-rpcid&rdquo; {_span id _}</li> |
| <li>Cluster-Info → &ldquo;tri-unit-info&rdquo; {cluster infomation}</li> |
| </ul> |
| <p>Among them, Service-Version and Service-Group respectively identify the version and group information of the Dubbo service, because the path of grpc declares the service name and method name, compared with the Dubbo protocol, it lacks version and group information; Tracing-ID, Tracing- RPC-ID is used for full-link tracking capabilities, which respectively represent tracing id and span id information; Cluster-Info represents cluster information, which can be used to build some flexible service management capabilities related to routing such as cluster division.</p> |
| <h3 id="triple-streaming">Triple Streaming</h3> |
| <p>Compared with the traditional unary method, the Triple protocol has more streaming RPC capabilities currently provided</p> |
| <ul> |
| <li>What scenario is Streaming used for?</li> |
| </ul> |
| <p>In some application scenarios such as large file transmission and live broadcast, the consumer or provider needs to transmit a large amount of data with the peer. Since the amount of data in these cases is very large, there is no way to transmit it in one RPC packet. Transmission, so for these data packets, we need to fragment the data packets and transmit them through multiple RPC calls. If we transmit these split RPC data packets in parallel, then the relevant data packets after reaching the peer end It is unordered, and the received data needs to be sorted and spliced, and the related logic will be very complicated. But if we serially transmit the split RPC packets, the corresponding network transmission RTT and data processing delay will be very large.</p> |
| <p>In order to solve the above problems, and to transmit a large amount of data between the consumer and the provider in a pipelined manner, the Streaming RPC model came into being.</p> |
| <p>Through the Streaming RPC method of the Triple protocol, multiple user-mode long connections, Stream, will be established between the consumer and the provider. Multiple Streams can exist on the same TCP connection at the same time, and each Stream is identified by a StreamId, and the data packets on a Stream will be read and written sequentially.</p> |
| <h3 id="summarize">Summarize</h3> |
| <p>In the world of APIs, the most important trend is the rise of standardized technologies. The Triple protocol is the main protocol launched by Dubbo3. It adopts a layered design, and its data exchange format is developed based on the Protobuf (Protocol Buffers) protocol, which has excellent serialization/deserialization efficiency. Of course, it also supports multiple serialization methods and many development languages. In the transport layer protocol, Triple chose HTTP/2, which has greatly improved its transmission efficiency compared with HTTP/1.1. In addition, as a mature open standard, HTTP/2 has rich security and flow control capabilities, and has good interoperability. Triple can not only be used for server-side service calls, but also support the interaction between browsers, mobile apps, and IoT devices and back-end services. At the same time, the Triple protocol seamlessly supports all service management capabilities of Dubbo3.</p> |
| <p>Under the trend of Cloud Native, the interoperability requirements between cross-platform, cross-vendor, and cross-environment systems will inevitably give rise to RPC technology based on open standards, and gRPC conforms to the historical trend and has been more and more widely used. In the field of microservices, the proposal and implementation of the Triple protocol is a big step for Dubbo3 to move towards cloud-native microservices.</p> |
| <p>##Dubbo2</p> |
| <h3 id="protocol-spec">Protocol SPEC</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>Identifies dubbo protocol with value: 0xdabb</p> |
| </li> |
| <li> |
| <p>Req/Res (1 bit)</p> |
| <p>Identifies this is 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), expect for a return value from server or not. Set to 1 if need a return value from server.</p> |
| </li> |
| </ul> |
| <p>-Event (1 bit)</p> |
| <p>Identifies an event message or not, for example, heartbeat event. Set to 1 if this is an event.</p> |
| <p>-Serialization ID (5 bits)</p> |
| <p>Identifies serialization type: the value for fastjson is 6.</p> |
| <ul> |
| <li> |
| <p>Status (8 bits)</p> |
| <p>Only useful when Req/Res is 0 (Response), identifies the status of 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 an unique request. Numeric (long).</p> |
| </li> |
| <li> |
| <p>Data Length (32)</p> |
| <p>Length of the content (the variable part) after serialization, counted by bytes. Numeric (integer).</p> |
| </li> |
| </ul> |
| <p>-Variable Part</p> |
| <p>Each part is a byte[] after serialization with specific serialization type, identifies by Serialization ID.</p> |
| <p>Every part is a byte[] after serialization with specific serialization type, identifies by Serialization ID</p> |
| <ol> |
| <li> |
| <p>If the content is a Request (Req/Res = 1), each part consists of the content, in turn is:</p> |
| <ul> |
| <li>Dubbo version</li> |
| <li>Service name</li> |
| <li>Service version |
| -Method name |
| -Method parameter types |
| -Method arguments |
| -Attachments</li> |
| </ul> |
| </li> |
| <li> |
| <p>If the content is a Response (Req/Res = 0), each part consists of the content, in turn is:</p> |
| <ul> |
| <li>Return value type, identifies what kind of value returns from server side: RESPONSE_NULL_VALUE - 2, RESPONSE_VALUE - 1, RESPONSE_WITH_EXCEPTION - 0.</li> |
| <li>Return value, the real value returns from server.</li> |
| </ul> |
| </li> |
| </ol> |
| <blockquote> |
| <p>For the (Variable Part) variable length part, when the current version of the dubbo framework uses json serialization, an extra line break is added between each part of the content as a separator. Please add an extra line break after each part of the Variable Part, such as :</p> |
| </blockquote> |
| <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 (newline) |
| </span></span></code></pre></div></description></item><item><title>Docs3-V2: Dubbo protocol</title><link>https://dubbo.apache.org/en/docs3-v2/java-sdk/reference-manual/protocol/dubbo/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/en/docs3-v2/java-sdk/reference-manual/protocol/dubbo/</guid><description> |
| <h2 id="feature-description">Feature description</h2> |
| <p>Dubbo&rsquo;s default protocol uses a single long connection and NIO asynchronous communication, which is suitable for small data volume and large concurrent service calls, and the situation where the number of service consumer machines is much larger than the number of service provider machines.</p> |
| <p>Conversely, Dubbo&rsquo;s default protocol is not suitable for services that transmit large amounts of data, such as file transfers, video transfers, etc., unless the request volume is very low.</p> |
| <p><img src="https://dubbo.apache.org/imgs/user/dubbo-protocol.jpg" alt="dubbo-protocol.jpg"></p> |
| <ul> |
| <li>Transporter: mina, netty, grizzy</li> |
| <li>Serialization: dubbo, hessian2, java, json</li> |
| <li>Dispatcher: all, direct, message, execution, connection</li> |
| <li>ThreadPool: fixed, cached</li> |
| </ul> |
| <p>Default protocol, using tbremoting interaction based on netty <code>3.2.5.Final</code> and hessian2 <code>3.2.1-fixed-2(Alibaba embed version)</code>.</p> |
| <ul> |
| <li>Number of connections: single connection</li> |
| <li>Connection method: long connection</li> |
| <li>Transport protocol: TCP</li> |
| <li>Transmission method: NIO asynchronous transmission</li> |
| <li>Serialization: Hessian binary serialization</li> |
| <li>Scope of application: The incoming and outgoing parameter data packets are small (recommended to be less than 100K), the number of consumers is more than that of the provider, and a single consumer cannot fill the provider. Try not to use the dubbo protocol to transfer large files or very large strings.</li> |
| <li>Applicable scenario: regular remote service method call</li> |
| </ul> |
| <p><strong>constraint</strong></p> |
| <ul> |
| <li>Parameters and return values need to implement <code>Serializable</code> interface</li> |
| <li>Parameters and return values cannot be customized to implement <code>List</code>, <code>Map</code>, <code>Number</code>, <code>Date</code>, <code>Calendar</code> and other interfaces, only the implementations that come with JDK can be used, because hessian will do special processing and customize the implementation All attribute values in the class are lost.</li> |
| <li>Hessian serialization, only pass member attribute values and value types, do not pass methods or static variables, compatibility <strong>provided by Wu Yajun</strong></li> |
| </ul> |
| <table> |
| <thead> |
| <tr> |
| <th>Data communication</th> |
| <th>Situation</th> |
| <th>Results</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td>A-&gt;B</td> |
| <td>Class A has one more attribute (or class B has one less attribute)</td> |
| <td>No exception is thrown, the value of the attribute with more A, B does not, and the others are normal</td> |
| </tr> |
| <tr> |
| <td>A-&gt;B</td> |
| <td>enumeration A has one more enumeration (or B has one less enumeration)</td> |
| <td>A uses the extra enumeration for transmission</td> |
| </tr> |
| <tr> |
| <td>A-&gt;B</td> |
| <td>Enumeration A has one more enumeration (or B has one less enumeration)</td> |
| <td>A does not use the extra enumeration for transmission</td> |
| </tr> |
| <tr> |
| <td>A-&gt;B</td> |
| <td>The attributes of A and B have the same name but different types</td> |
| <td>Throw an exception</td> |
| </tr> |
| <tr> |
| <td>A-&gt;B</td> |
| <td>The serialId is different</td> |
| <td>Normal transmission</td> |
| </tr> |
| </tbody> |
| </table> |
| <p>The method added to the interface has no impact on the client. If the method is not required by the client, the client does not need to redeploy. The addition of attributes in input parameters and result sets has no effect on the client. If the client does not need new attributes, there is no need to redeploy.</p> |
| <p>Changes in input parameters and result set attribute names have no impact on client serialization, but if the client is not redeployed, regardless of input or output, the attribute values with changed attribute names cannot be obtained.</p> |
| <p><strong>Summarize</strong></p> |
| <ul> |
| <li>The server and the client do not need to be completely consistent with the domain objects, but follow the principle of maximum matching.</li> |
| <li>An exception will be thrown: one more type of enumeration value and one less type, just use a different one, or the attribute name is the same, but the type is different.</li> |
| </ul> |
| <h2 id="scenes-to-be-used">scenes to be used</h2> |
| <p>It is suitable for service calls with large concurrent and small data volumes, and the service consumer is much larger than the service provider.</p> |
| <h2 id="how-to-use">How to use</h2> |
| <h3 id="configuration-protocol">Configuration protocol</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-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:protocol</span> name=<span style="color:#2aa198">&#34;dubbo&#34;</span> port=<span style="color:#2aa198">&#34;20880&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><h3 id="set-the-default-protocol">Set the default protocol</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-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:provider</span> protocol=<span style="color:#2aa198">&#34;dubbo&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><h3 id="set-the-protocol-of-a-service">Set the protocol of a service</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-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:service</span> interface=<span style="color:#2aa198">&#34;...&#34;</span> protocol=<span style="color:#2aa198">&#34;dubbo&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><h3 id="multiport">Multiport</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-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:protocol</span> id=<span style="color:#2aa198">&#34;dubbo1&#34;</span> name=<span style="color:#2aa198">&#34;dubbo&#34;</span> port=<span style="color:#2aa198">&#34;20880&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:protocol</span> id=<span style="color:#2aa198">&#34;dubbo2&#34;</span> name=<span style="color:#2aa198">&#34;dubbo&#34;</span> port=<span style="color:#2aa198">&#34;20881&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><h3 id="configure-protocol-options">Configure protocol options</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-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:protocol</span> name=<span style="color:#2aa198">&#34;dubbo&#34;</span> port=<span style="color:#2aa198">&#34;9090&#34;</span> server=<span style="color:#2aa198">&#34;netty&#34;</span> client=<span style="color:#2aa198">&#34;netty&#34;</span> codec=<span style="color:#2aa198">&#34;dubbo&#34;</span> serialization=<span style="color:#2aa198">&#34;hessian2&#34;</span> charset=<span style="color:#2aa198">&#34;UTF-8&#34;</span> threadpool=<span style="color:#2aa198">&#34;fixed&#34;</span> threads=<span style="color:#2aa198">&#34;100 &#34;</span> queues=<span style="color:#2aa198">&#34;0&#34;</span> iothreads=<span style="color:#2aa198">&#34;9&#34;</span> buffer=<span style="color:#2aa198">&#34;8192&#34;</span> accepts=<span style="color:#2aa198">&#34;1000&#34;</span> payload=<span style="color:#2aa198">&#34;8388608&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><h3 id="multi-connection-configuration">Multi-connection configuration</h3> |
| <p>By default, the Dubbo protocol uses a single long connection per service, per provider and per consumer. If the amount of data is large, multiple connections can be used.</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:service</span> interface=<span style="color:#2aa198">&#34;...&#34;</span> connections=<span style="color:#2aa198">&#34;1&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:reference</span> interface=<span style="color:#2aa198">&#34;...&#34;</span> connections=<span style="color:#2aa198">&#34;1&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><ul> |
| <li><code>&lt;dubbo:service connections=&quot;0&quot;&gt;</code> or <code>&lt;dubbo:reference connections=&quot;0&quot;&gt;</code> means that the service uses JVM shared persistent connection. <strong>default</strong></li> |
| <li><code>&lt;dubbo:service connections=&quot;1&quot;&gt;</code> or <code>&lt;dubbo:reference connections=&quot;1&quot;&gt;</code> means that the service uses independent persistent connections.</li> |
| <li><code>&lt;dubbo:service connections=&quot;2&quot;&gt;</code> or <code>&lt;dubbo:reference connections=&quot;2&quot;&gt;</code> means that the service uses two independent persistent connections.</li> |
| </ul> |
| <p>In order to prevent being hung up by a large number of connections, the maximum number of receiving connections can be limited on the service provider to achieve self-protection of the service provider.</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;dubbo&#34;</span> accepts=<span style="color:#2aa198">&#34;1000&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><h2 id="common-problem">common problem</h2> |
| <h3 id="q1">Q1</h3> |
| <p>Why should there be more consumers than providers?</p> |
| <p>Because the dubbo protocol uses a single long connection, assuming that the network is a gigabit network card <strong>1024Mbit=128MByte</strong>, according to the test experience data, each connection can only be filled up to 7MByte (different environments may be different, for reference), theoretically 1 A service provider needs 20 service consumers to fill up the network card.</p> |
| <h3 id="q2">Q2</h3> |
| <p>Why can&rsquo;t I send large packets?</p> |
| <p>Because the dubbo protocol uses a single long connection, if the data packet size of each request is 500KByte, assuming that the network is a Gigabit network card<strong>1024Mbit=128MByte</strong>, each connection can be up to 7MByte (different environments may be different), a single service provides The maximum TPS (transactions per second) of the latter is: 128MByte / 500KByte = 262. The maximum TPS (transactions per second) for a single consumer to call a single service provider is: 7MByte / 500KByte = 14. If acceptable, you can consider using it, otherwise the network will become a bottleneck.</p> |
| <h3 id="q3">Q3</h3> |
| <p>Why use asynchronous single long connection?</p> |
| <p>Because the current situation of the service is that there are few service providers, usually only a few machines, but many service consumers, the entire website may be accessing the service. For example, Morgan’s provider has only 6 providers, but there are hundreds of consumers. Or, there are 150 million calls per day. If the conventional Hessian service is used, the service provider is easily overwhelmed. Through a single connection, it is guaranteed that a single consumer will not overwhelm the provider, long-term connection, reducing connection handshake verification, etc. And use asynchronous IO, reuse thread pool, prevent C10K problem.</p></description></item><item><title>Docs3-V2: Triple Protocol</title><link>https://dubbo.apache.org/en/docs3-v2/java-sdk/reference-manual/protocol/triple/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/en/docs3-v2/java-sdk/reference-manual/protocol/triple/</guid><description/></item><item><title>Docs3-V2: Rest protocol</title><link>https://dubbo.apache.org/en/docs3-v2/java-sdk/reference-manual/protocol/rest/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/en/docs3-v2/java-sdk/reference-manual/protocol/rest/</guid><description> |
| <p>Support for REST calls based on the standard Java REST API - JAX-RS 2.0 (short for Java API for RESTful Web Services)</p> |
| <h3 id="quick-start">Quick Start</h3> |
| <p>It is relatively simple to develop a REST-style service in dubbo. Let&rsquo;s take a simple service for registered users as an example.</p> |
| <p>The function of this service is to provide the following URL (note: this URL is not fully in line with REST style, but it is simpler and more practical)</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>http://localhost:8080/users/register |
| </span></span></code></pre></div><p>And any client can POST a JSON string containing user information to the above URL to complete user registration.</p> |
| <p>First, develop the interface of the service</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">UserService</span> { |
| </span></span><span style="display:flex;"><span> <span style="color:#dc322f">void</span> <span style="color:#268bd2">registerUser</span>(User user); |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>Then, develop the implementation of the service</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">@Path</span>(<span style="color:#2aa198">&#34;users&#34;</span>) |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">class</span> <span style="color:#268bd2">UserServiceImpl</span> <span style="color:#268bd2">implements</span> UserService { |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@POST</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@Path</span>(<span style="color:#2aa198">&#34;register&#34;</span>) |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@Consumes</span>({MediaType. APPLICATION_JSON}) |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">public</span> <span style="color:#dc322f">void</span> <span style="color:#268bd2">registerUser</span>(User user) { |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">// save the user...</span> |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>The above implementation is very simple, but since the REST service is to be published to a specified URL for access by clients of any language or even browsers, several standard annotations of JAX-RS are added here for related configuration.</p> |
| <p>@Path(&ldquo;users&rdquo;): Specifies that the relative path of the URL to access UserService is /users, ie http://localhost:8080/users</p> |
| <p>@Path(&ldquo;register&rdquo;): Specifies that the relative path of the URL to access the registerUser() method is /register, combined with the path specified by the previous @Path for UserService, the full path to call UserService.register() is http://localhost :8080/users/register</p> |
| <p>@POST: Specifies to access registerUser() with the HTTP POST method</p> |
| <p>@Consumes({MediaType.APPLICATION_JSON}): Specifies that registerUser() receives data in JSON format. The REST framework will automatically deserialize the JSON data into a User object</p> |
| <p>Finally, add this service in the spring configuration file to complete all service development work</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:#586e75">&lt;!-- Expose the service on port 8080 using the rest protocol --&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:protocol</span> name=<span style="color:#2aa198">&#34;rest&#34;</span> port=<span style="color:#2aa198">&#34;8080&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#586e75">&lt;!-- Declare the service interface that needs to be exposed --&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:service</span> interface=<span style="color:#2aa198">&#34;xxx.UserService&#34;</span> ref=<span style="color:#2aa198">&#34;userService&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#586e75">&lt;!-- Implement services like local beans --&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;bean</span> id=<span style="color:#2aa198">&#34;userService&#34;</span> class=<span style="color:#2aa198">&#34;xxx.UserServiceImpl&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><h3 id="detailed-explanation-of-rest-service-provider">Detailed explanation of REST service provider</h3> |
| <p>Next, we expand the UserService in the &ldquo;Quick Start&rdquo; to further demonstrate the development points of the REST service provider in dubbo.</p> |
| <h3 id="implementation-of-http-postget">Implementation of HTTP POST/GET</h3> |
| <p>In the REST service, although it is recommended to use the four standard methods POST, DELETE, PUT, and GET in the HTTP protocol to implement common &ldquo;addition, deletion, modification and query&rdquo; respectively, in practice, we generally use POST directly to implement &ldquo;addition and modification&rdquo;, and GET to implement Just implement &ldquo;delete check&rdquo; (DELETE and PUT will even be blocked by some firewalls).</p> |
| <p>The implementation of POST has been briefly demonstrated before. Here, we add a function of obtaining registered user information to UserService to demonstrate the implementation of GET.</p> |
| <p>This function is to enable the client to obtain user profiles with different IDs by accessing the following URLs</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>http://localhost:8080/users/1001 |
| </span></span><span style="display:flex;"><span>http://localhost:8080/users/1002 |
| </span></span><span style="display:flex;"><span>http://localhost:8080/users/1003 |
| </span></span></code></pre></div><p>Of course, user profiles with different IDs can also be accessed through other forms of URLs, for example</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-gdscript3" data-lang="gdscript3"><span style="display:flex;"><span>http:<span style="color:#719e07">//</span>localhost:<span style="color:#2aa198">8080</span><span style="color:#719e07">/</span>users<span style="color:#719e07">/</span><span style="color:#b58900">load</span>?id<span style="color:#719e07">=</span><span style="color:#2aa198">1001</span> |
| </span></span></code></pre></div><p>JAX-RS natively supports all of these forms. But the above form of including query parameters in the URL path (http://localhost:8080/users/1001) is more in line with the general habits of REST, so it is recommended for everyone to use. Next, we will add a getUser() method to UserService to achieve this form of URL access</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">@GET</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">@Path</span>(<span style="color:#2aa198">&#34;{id : \\d+}&#34;</span>) |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">@Produces</span>({MediaType. APPLICATION_JSON}) |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">public</span> User <span style="color:#268bd2">getUser</span>(<span style="color:#268bd2">@PathParam</span>(<span style="color:#2aa198">&#34;id&#34;</span>) Long id) { |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">//...</span> |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>@GET: Specifies to use the HTTP GET method to access</p> |
| <p>@Path(&quot;{id : \d+}&quot;): According to the functional requirements above, the URL to access getUser() should be &ldquo;http://localhost:8080/users/ + any number&rdquo;, and this number should be made Pass the getUser() method as a parameter. In the annotation configuration here, {id: xxx} in the middle of @Path specifies that the URL relative path contains a parameter named id, and its value will be automatically passed to the method parameter modified with @PathParam(&ldquo;id&rdquo;) below id. {id: followed by \d+ is a regular expression, specifying that the id parameter must be a number.</p> |
| <p>@Produces({MediaType.APPLICATION_JSON}): Specify getUser() to output data in JSON format. The framework will automatically serialize the User object into JSON data.</p> |
| <h3 id="annotation-is-placed-in-the-interface-class-or-the-implementation-class">Annotation is placed in the interface class or the implementation class</h3> |
| <p>The development of REST services in Dubbo is mainly configured through JAX-RS annotations. In the above examples, we put the annotations in the service implementation class. But in fact, we can also put the annotation on the interface of the service. The two methods are completely equivalent, for example:</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">@Path</span>(<span style="color:#2aa198">&#34;users&#34;</span>) |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">interface</span> <span style="color:#268bd2">UserService</span> { |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@GET</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@Path</span>(<span style="color:#2aa198">&#34;{id : \\d+}&#34;</span>) |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@Produces</span>({MediaType. APPLICATION_JSON}) |
| </span></span><span style="display:flex;"><span> User <span style="color:#268bd2">getUser</span>(<span style="color:#268bd2">@PathParam</span>(<span style="color:#2aa198">&#34;id&#34;</span>) Long id); |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>In general applications, we recommend placing the annotation in the service implementation class, so that the location of the annotation and the java implementation code are closer, making it easier to develop and maintain. In addition, more importantly, we generally tend to avoid pollution of the interface, and maintain the purity and wide applicability of the interface.</p> |
| <p>However, as mentioned later, if we want to use the consumer directly developed by dubbo to access this service, the annotation must be placed on the interface.</p> |
| <p>If annotations are added to both the interface and the implementation class, the annotation configuration of the implementation class will take effect, and the annotation on the interface will be ignored directly.</p> |
| <h3 id="support-for-multiple-data-formats-such-as-json-and-xml">Support for multiple data formats such as JSON and XML</h3> |
| <p>The REST service developed in dubbo can support the transmission of data in multiple formats at the same time to provide clients with maximum flexibility. Among them we currently have added extra functionality especially for the most commonly used formats JSON and XML.</p> |
| <p>For example, if we want the getUser() method in the above example to support returning data in JSON and XML formats, we only need to include both formats in the 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">@Produces</span>({MediaType. APPLICATION_JSON, MediaType. TEXT_XML}) |
| </span></span><span style="display:flex;"><span>User <span style="color:#268bd2">getUser</span>(<span style="color:#268bd2">@PathParam</span>(<span style="color:#2aa198">&#34;id&#34;</span>) Long id); |
| </span></span></code></pre></div><p>Or you can directly use strings (wildcards are also supported) to represent MediaType</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">@Produces</span>({<span style="color:#2aa198">&#34;application/json&#34;</span>, <span style="color:#2aa198">&#34;text/xml&#34;</span>}) |
| </span></span><span style="display:flex;"><span>User <span style="color:#268bd2">getUser</span>(<span style="color:#268bd2">@PathParam</span>(<span style="color:#2aa198">&#34;id&#34;</span>) Long id); |
| </span></span></code></pre></div><p>If all methods support the same type of input and output data format, we don&rsquo;t need to configure each method, just add annotation to the service class</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">@Path</span>(<span style="color:#2aa198">&#34;users&#34;</span>) |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">@Consumes</span>({MediaType. APPLICATION_JSON, MediaType. TEXT_XML}) |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">@Produces</span>({MediaType. APPLICATION_JSON, MediaType. TEXT_XML}) |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">class</span> <span style="color:#268bd2">UserServiceImpl</span> <span style="color:#268bd2">implements</span> UserService { |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">//...</span> |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>In the case that a REST service supports multiple data formats at the same time, according to the JAX-RS standard, the MIME header (content-type and accept) in HTTP is generally used to specify which format data is currently wanted.</p> |
| <p>But in dubbo, we also automatically support the method commonly used in the industry at present, that is, use a URL suffix (.json and .xml) to specify the desired data format. For example, after adding the above annotation, direct access to http://localhost:8888/users/1001.json means to use json format, and direct access to http://localhost:8888/users/1002.xml means to use xml format, Simpler and more intuitive than using HTTP Header. The REST APIs of Twitter, Weibo, etc. all use this method. |
| If you add neither HTTP header nor suffix, dubbo&rsquo;s REST will give priority to the data format that ranks first in the above annotation definition.</p> |
| <blockquote> |
| <p>Note: To support XML format data here, you can use MediaType.TEXT_XML or MediaType.APPLICATION_XML in annotation, but TEXT_XML is more commonly used, and if you want to use the above URL suffix method to specify the data format, you can only use Only when it is configured as TEXT_XML can it take effect.</p> |
| </blockquote> |
| <h3 id="chinese-character-support">Chinese character support</h3> |
| <p>In order to output Chinese characters normally in dubbo REST, like usual Java web applications, we need to set the contentType of the HTTP response to UTF-8 encoding.</p> |
| <p>Based on the standard usage of JAX-RS, we only need to do the following annotation configuration:</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">@Produces</span>({<span style="color:#2aa198">&#34;application/json; charset=UTF-8&#34;</span>, <span style="color:#2aa198">&#34;text/xml; charset=UTF-8&#34;</span>}) |
| </span></span><span style="display:flex;"><span>User <span style="color:#268bd2">getUser</span>(<span style="color:#268bd2">@PathParam</span>(<span style="color:#2aa198">&#34;id&#34;</span>) Long id); |
| </span></span></code></pre></div><p>For the convenience of users, we directly added a support class in dubbo REST to define the above constants, which can be used directly to reduce the possibility of errors.</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">@Produces</span>({ContentType. APPLICATION_JSON_UTF_8, ContentType. TEXT_XML_UTF_8}) |
| </span></span><span style="display:flex;"><span>User <span style="color:#268bd2">getUser</span>(<span style="color:#268bd2">@PathParam</span>(<span style="color:#2aa198">&#34;id&#34;</span>) Long id); |
| </span></span></code></pre></div><h3 id="additional-requirements-for-xml-data-format">Additional requirements for XML data format</h3> |
| <p>Since the implementation of JAX-RS generally uses the standard JAXB (Java API for XML Binding) to serialize and deserialize XML format data, we need to add a class-level JAXB annotation for each object to be transmitted in XML, Otherwise serialization will report an error. For example, add the following to the User returned in getUser()</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">@XmlRootElement</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">class</span> <span style="color:#268bd2">User</span> <span style="color:#268bd2">implements</span> Serializable { |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">//...</span> |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>In addition, if the return values in the service method are Java primitive types (such as int, long, float, double, etc.), it is best to add a layer of wrapper objects for them, because JAXB cannot directly serialize primitive types.</p> |
| <p>For example, we want the aforementioned registerUser() method to return the ID number generated by the server for the user:</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:#dc322f">long</span> <span style="color:#268bd2">registerUser</span>(User user); |
| </span></span></code></pre></div><p>Since primitive types are not supported by JAXB serialization, add a wrapper object:</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">@XmlRootElement</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">class</span> <span style="color:#268bd2">RegistrationResult</span> <span style="color:#268bd2">implements</span> Serializable { |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">private</span> Long id; |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">public</span> <span style="color:#268bd2">RegistrationResult</span>() { |
| </span></span><span style="display:flex;"><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">RegistrationResult</span>(Long id) { |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">this</span>.id <span style="color:#719e07">=</span> id; |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">public</span> Long <span style="color:#268bd2">getId</span>() { |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">return</span> id; |
| </span></span><span style="display:flex;"><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">setId</span>(Long id) { |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">this</span>.id <span style="color:#719e07">=</span> id; |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>And modify the service method:</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>RegistrationResult <span style="color:#268bd2">registerUser</span>(User user); |
| </span></span></code></pre></div><p>This not only solves the problem of XML serialization, but also makes the returned data conform to the specifications of XML and JSON. For example, in JSON, the return would be of the form</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-javascript" data-lang="javascript"><span style="display:flex;"><span>{<span style="color:#2aa198">&#34;id&#34;</span><span style="color:#719e07">:</span> <span style="color:#2aa198">1001</span>} |
| </span></span></code></pre></div><p>If no wrapper is added, the JSON return value will be directly</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>1001 |
| </span></span></code></pre></div><p>In XML, the return value after adding wrapper will be:</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;registrationResult&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;id&gt;</span>1002<span style="color:#268bd2">&lt;/id&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;/registrationResult&gt;</span> |
| </span></span></code></pre></div><p>This kind of wrapper object actually uses the so-called Data Transfer Object (DTO) pattern, and using DTO can also do more useful customizations for the transferred data.</p> |
| <h3 id="custom-serialization">Custom serialization</h3> |
| <p>As mentioned above, the underlying implementation of REST will automatically serialize/deserialize between service objects and JSON/XML data formats. However, in some scenarios, if you feel that this automatic conversion does not meet the requirements, you can customize it.</p> |
| <p>The REST implementation in Dubbo uses JAXB for XML serialization and Jackson for JSON serialization, so you can customize the mapping by adding JAXB or Jackson annotations to objects.</p> |
| <p>For example, custom object properties map to XML element names:</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">@XmlRootElement</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">@XmlAccessorType</span>(XmlAccessType.FIELD) |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">class</span> <span style="color:#268bd2">User</span> <span style="color:#268bd2">implements</span> Serializable { |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@XmlElement</span>(name<span style="color:#719e07">=</span><span style="color:#2aa198">&#34;username&#34;</span>) |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">private</span> String name; |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>Map custom object properties to JSON field names:</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">User</span> <span style="color:#268bd2">implements</span> Serializable { |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@JsonProperty</span>(<span style="color:#2aa198">&#34;username&#34;</span>) |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">private</span> String name; |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>For more information, please refer to the official documentation of JAXB and Jackson, or google yourself.</p> |
| <h3 id="configure-the-implementation-of-rest-server">Configure the implementation of REST Server</h3> |
| <p>Currently in dubbo, we support the implementation of 5 embedded rest servers, and at the same time support the implementation of the rest server using an external application server. The rest server can be implemented through the following configuration:</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;rest&#34;</span> server=<span style="color:#2aa198">&#34;jetty&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>The above configuration uses the embedded jetty as the rest server. At the same time, if the server attribute is not configured, the rest protocol also uses jetty by default. jetty is a very mature java servlet container, and has been well integrated with dubbo (currently, among the five embedded servers, only jetty and tomcat and tjws described later have seamlessly integrated with dubbo monitoring system), Therefore, if your dubbo system is a separate startup process, you can directly use jetty by default.</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;rest&#34;</span> server=<span style="color:#2aa198">&#34;tomcat&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>The above configuration uses the embedded tomcat as the rest server. On the embedded tomcat, the performance of REST is much better than that on jetty (see the benchmark test later), it is recommended to use tomcat in the scenario that requires high performance.</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;rest&#34;</span> server=<span style="color:#2aa198">&#34;netty&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>The above configuration uses embedded netty as the rest server. (TODO more contents to add)</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;rest&#34;</span> server=<span style="color:#2aa198">&#34;tjws&#34;</span><span style="color:#268bd2">/&gt;</span> (tjws is now deprecated) |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:protocol</span> name=<span style="color:#2aa198">&#34;rest&#34;</span> server=<span style="color:#2aa198">&#34;sunhttp&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>The above configuration uses the embedded tjws or Sun HTTP server as the rest server. These two server implementations are very lightweight, very convenient for quick start-up in integration tests, and of course they can also be used in production environments with low load. Note: tjws is currently deprecated because it doesn&rsquo;t work well with the servlet 3.1 API.</p> |
| <p>If your dubbo system is not a separate startup process, but is deployed in a Java application server, it is recommended that you use the following configuration</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;rest&#34;</span> server=<span style="color:#2aa198">&#34;servlet&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>By setting the server as a servlet, dubbo will use the servlet container of the external application server as the rest server. At the same time, add the following configuration to the web.xml of the dubbo system</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;web-app&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;context-param&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;param-name&gt;</span>contextConfigLocation<span style="color:#268bd2">&lt;/param-name&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;param-value&gt;</span>/WEB-INF/classes/META-INF/spring/dubbo-demo-provider.xml<span style="color:#268bd2">&lt;/param-value&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;/context-param&gt;</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;listener&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;listener-class&gt;</span>org.apache.dubbo.remoting.http.servlet.BootstrapListener<span style="color:#268bd2">&lt;/listener-class&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;/listener&gt;</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;listener&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;listener-class&gt;</span>org.springframework.web.context.ContextLoaderListener<span style="color:#268bd2">&lt;/listener-class&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;/listener&gt;</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;servlet&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;servlet-name&gt;</span>dispatcher<span style="color:#268bd2">&lt;/servlet-name&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;servlet-class&gt;</span>org.apache.dubbo.remoting.http.servlet.DispatcherServlet<span style="color:#268bd2">&lt;/servlet-class&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;load-on-startup&gt;</span>1<span style="color:#268bd2">&lt;/load-on-startup&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;/servlet&gt;</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;servlet-mapping&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;servlet-name&gt;</span>dispatcher<span style="color:#268bd2">&lt;/servlet-name&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;url-pattern&gt;</span>/*<span style="color:#268bd2">&lt;/url-pattern&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;/servlet-mapping&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;/web-app&gt;</span> |
| </span></span></code></pre></div><p>That is, dubbo&rsquo;s BootstrapListener and DispatherServlet must be added to web.xml to complete the integration of dubbo&rsquo;s REST function with the external servlet container.</p> |
| <blockquote> |
| <p>Note: If you use spring&rsquo;s ContextLoaderListener to load spring, you must ensure that BootstrapListener is configured before ContextLoaderListener, otherwise dubbo initialization will fail.</p> |
| </blockquote> |
| <p>In fact, you can still use the embedded server in this scenario, but the servlet container of the external application server is often more powerful than the embedded server (especially if you are deploying to a more robust and scalable WebLogic, WebSphere, etc.), and Sometimes it is also convenient for unified management, monitoring, etc. on the application server.</p> |
| <h3 id="get-context-information">Get context information</h3> |
| <p>In the remote call, there may be many kinds of context information worth obtaining. Here, the client IP is taken as an example.</p> |
| <p>In dubbo&rsquo;s REST, we have two ways to get client IP.</p> |
| <p>The first way, using JAX-RS standard @Context 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">public</span> User <span style="color:#268bd2">getUser</span>(<span style="color:#268bd2">@PathParam</span>(<span style="color:#2aa198">&#34;id&#34;</span>) Long id, <span style="color:#268bd2">@Context</span> HttpServletRequest request) { |
| </span></span><span style="display:flex;"><span> System.out.println(<span style="color:#2aa198">&#34;Client address is &#34;</span> <span style="color:#719e07">+</span> request.getRemoteAddr()); |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>After modifying a method parameter of getUser() with Context, you can inject the current HttpServletRequest into it, and then directly call the servlet api to obtain the IP.</p> |
| <blockquote> |
| <p>Note: This method can only work when the server is set to tjws, tomcat, jetty or servlet, because only these server implementations provide a servlet container. In addition, the standard JAX-RS also supports using @Context to modify an instance field of the service class to obtain HttpServletRequest, but we do not support this in dubbo.</p> |
| </blockquote> |
| <p>The second way, use RpcContext commonly used in dubbo</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> User <span style="color:#268bd2">getUser</span>(<span style="color:#268bd2">@PathParam</span>(<span style="color:#2aa198">&#34;id&#34;</span>) Long id) { |
| </span></span><span style="display:flex;"><span> System.out.println(<span style="color:#2aa198">&#34;Client address is &#34;</span> <span style="color:#719e07">+</span> RpcContext.getContext().getRemoteAddressString()); |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><blockquote> |
| <p>Note: This method can only work when setting server=&ldquo;jetty&rdquo; or server=&ldquo;tomcat&rdquo; or server=&ldquo;servlet&rdquo; or server=&ldquo;tjws&rdquo;. In addition, currently dubbo&rsquo;s RpcContext is a relatively intrusive usage, and we are likely to refactor it in the future.</p> |
| </blockquote> |
| <p>If you want to keep your project compatible with JAX-RS and run without dubbo in the future, please choose the first method. If you want a more elegant service interface definition, please choose the second way.</p> |
| <p>In addition, in the latest dubbo rest, it is also supported to obtain HttpServletRequest and HttpServletResponse through RpcContext to provide greater flexibility for users to implement some complex functions, such as accessing HTTP Header in dubbo standard filter. An example of usage is as follows</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">if</span> (RpcContext.getContext().getRequest() <span style="color:#719e07">!=</span> <span style="color:#cb4b16">null</span> <span style="color:#719e07">&amp;&amp;</span> RpcContext.getContext().getRequest() <span style="color:#719e07">instanceof</span> HttpServletRequest) { |
| </span></span><span style="display:flex;"><span> System.out.println(<span style="color:#2aa198">&#34;Client address is &#34;</span> <span style="color:#719e07">+</span> ((HttpServletRequest) RpcContext.getContext().getRequest()).getRemoteAddr()); |
| </span></span><span style="display:flex;"><span>} |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">if</span> (RpcContext.getContext().getResponse() <span style="color:#719e07">!=</span> <span style="color:#cb4b16">null</span> <span style="color:#719e07">&amp;&amp;</span> RpcContext.getContext().getResponse() <span style="color:#719e07">instanceof</span> HttpServletResponse) { |
| </span></span><span style="display:flex;"><span> System.out.println(<span style="color:#2aa198">&#34;Response object from RpcContext: &#34;</span> <span style="color:#719e07">+</span> RpcContext.getContext().getResponse()); |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><blockquote> |
| <p>Note: In order to maintain the neutrality of the protocol, RpcContext.getRequest() and RpcContext.getResponse() return only an Object class, and may be null. So, you have to do null and type checking yourself.</p> |
| </blockquote> |
| <blockquote> |
| <p>Note: Only when server=&ldquo;jetty&rdquo; or server=&ldquo;tomcat&rdquo; or server=&ldquo;servlet&rdquo; is set, can you get HttpServletRequest and HttpServletResponse correctly through the above method, because only these servers implement the servlet container.</p> |
| </blockquote> |
| <p>In order to simplify programming, you can also use generics to directly obtain specific types of request/response:</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">if</span> (RpcContext. <span style="color:#268bd2">getContext</span>(). getRequest(HttpServletRequest. <span style="color:#268bd2">class</span>) != <span style="color:#268bd2">null</span>) { |
| </span></span><span style="display:flex;"><span> System.out.println(<span style="color:#2aa198">&#34;Client address is &#34;</span> <span style="color:#719e07">+</span> RpcContext.getContext().getRequest(HttpServletRequest.class).getRemoteAddr()); |
| </span></span><span style="display:flex;"><span>} |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">if</span> (RpcContext. <span style="color:#268bd2">getContext</span>(). getResponse(HttpServletResponse. <span style="color:#268bd2">class</span>) != <span style="color:#268bd2">null</span>) { |
| </span></span><span style="display:flex;"><span> System.out.println(<span style="color:#2aa198">&#34;Response object from RpcContext: &#34;</span> <span style="color:#719e07">+</span> RpcContext.getContext().getResponse(HttpServletResponse.class)); |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>If the request/response does not conform to the specified type, null will also be returned here.</p> |
| <h3 id="configure-port-number-and-context-path">Configure port number and Context Path</h3> |
| <p>The rest protocol in dubbo will use port 80 by default. If you want to modify the port, configure it directly:</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;rest&#34;</span> port=<span style="color:#2aa198">&#34;8888&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>In addition, as mentioned earlier, we can use @Path to configure the URL relative path of a single rest service. But in fact, we can also set a basic relative path that is applicable to all rest services, that is, the context path that is often said in java web applications.</p> |
| <p>Just add the following contextpath attribute:</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;rest&#34;</span> port=<span style="color:#2aa198">&#34;8888&#34;</span> contextpath=<span style="color:#2aa198">&#34;services&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>Take the previous code as an example:</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">@Path</span>(<span style="color:#2aa198">&#34;users&#34;</span>) |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">class</span> <span style="color:#268bd2">UserServiceImpl</span> <span style="color:#268bd2">implements</span> UserService { |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@POST</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@Path</span>(<span style="color:#2aa198">&#34;register&#34;</span>) |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@Consumes</span>({MediaType. APPLICATION_JSON}) |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">public</span> <span style="color:#dc322f">void</span> <span style="color:#268bd2">registerUser</span>(User user) { |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">// save the user...</span> |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>Now the full access path of registerUser()</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>http://localhost:8888/services/users/register |
| </span></span></code></pre></div><p>Note: If you choose an external application server as the rest server, that is, configure</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;rest&#34;</span> port=<span style="color:#2aa198">&#34;8888&#34;</span> contextpath=<span style="color:#2aa198">&#34;services&#34;</span> server=<span style="color:#2aa198">&#34;servlet&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>You must ensure that the port and contextpath set here are consistent with the port of the external application server and the context path of DispatcherServlet (that is, webapp path plus servlet url pattern). For example, for an application deployed as the tomcat ROOT path, the contextpath here must be exactly the same as <code>&lt;url-pattern/&gt;</code> of DispacherServlet in web.xml:</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;servlet-mapping&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;servlet-name&gt;</span>dispatcher<span style="color:#268bd2">&lt;/servlet-name&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;url-pattern&gt;</span>/services/*<span style="color:#268bd2">&lt;/url-pattern&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;/servlet-mapping&gt;</span> |
| </span></span></code></pre></div><h3 id="configure-the-number-of-threads-and-io-threads">Configure the number of threads and IO threads</h3> |
| <p>Thread pool size can be configured for rest services</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;rest&#34;</span> threads=<span style="color:#2aa198">&#34;500&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><blockquote> |
| <p>Note: The current thread pool settings only take effect when server=&ldquo;netty&rdquo; or server=&ldquo;jetty&rdquo; or server=&ldquo;tomcat&rdquo;. In addition, if server=&ldquo;servlet&rdquo;, since the external application server is enabled as the rest server at this time, it is not controlled by dubbo, so the thread pool setting here is also invalid.</p> |
| </blockquote> |
| <p>If you choose netty server, you can also configure the number of IO worker threads of Netty</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;rest&#34;</span> iothreads=<span style="color:#2aa198">&#34;5&#34;</span> threads=<span style="color:#2aa198">&#34;100&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><h3 id="configure-long-connection">Configure long connection</h3> |
| <p>The rest service in Dubbo is accessed by http long connection by default, if you want to switch to short connection, configure it directly</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;rest&#34;</span> keepalive=<span style="color:#2aa198">&#34;false&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><blockquote> |
| <p>Note: This configuration is currently only valid for server=&ldquo;netty&rdquo; and server=&ldquo;tomcat&rdquo;.</p> |
| </blockquote> |
| <h3 id="configure-the-maximum-number-of-http-connections">Configure the maximum number of HTTP connections</h3> |
| <p>The maximum number of HTTP connections that the server provider can receive at the same time can be configured to prevent the REST server from being overwhelmed by too many connections, as a basic self-protection mechanism</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;rest&#34;</span> accepts=<span style="color:#2aa198">&#34;500&#34;</span> server=<span style="color:#2aa198">&#34;tomcat/</span><span style="color:#268bd2">&gt;</span> |
| </span></span></code></pre></div><blockquote> |
| <p>Note: This configuration is currently only valid for server=&ldquo;tomcat&rdquo;.</p> |
| </blockquote> |
| <h3 id="configure-the-timeout-period-and-the-number-of-http-connections-for-each-consumer">Configure the timeout period and the number of HTTP connections for each consumer</h3> |
| <p>If the consumer of the rest service is also a dubbo system, you can configure the maximum timeout period for the consumer to call this rest service and the maximum number of HTTP connections each consumer can initiate like other dubbo RPC mechanisms.</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:service</span> interface=<span style="color:#2aa198">&#34;xxx&#34;</span> ref=<span style="color:#2aa198">&#34;xxx&#34;</span> protocol=<span style="color:#2aa198">&#34;rest&#34;</span> timeout=<span style="color:#2aa198">&#34;2000&#34;</span> connections=<span style="color:#2aa198">&#34;10&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>Of course, since this configuration is effective for the consumer side, it can also be configured on the consumer side</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:reference</span> id=<span style="color:#2aa198">&#34;xxx&#34;</span> interface=<span style="color:#2aa198">&#34;xxx&#34;</span> timeout=<span style="color:#2aa198">&#34;2000&#34;</span> connections=<span style="color:#2aa198">&#34;10&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>However, in general we recommend configuration to provide such configuration on the service provider side. According to dubbo&rsquo;s official documentation: &ldquo;Providers should be configured with as many properties as possible on the Consumer side, so that Provider implementers can think about Provider service characteristics and service quality issues from the very beginning.&rdquo;</p> |
| <blockquote> |
| <p>Note: If dubbo&rsquo;s REST service is published to non-dubbo clients, the configuration on <code>&lt;dubbo:service/&gt;</code> here is completely invalid, because such clients are not controlled by dubbo.</p> |
| </blockquote> |
| <h3 id="replace-part-of-spring-xml-configuration-with-annotation">Replace part of Spring XML configuration with Annotation</h3> |
| <p>All the above discussions are based on the xml configuration of dubbo in spring. However, dubbo/spring itself also supports the use of annotations for configuration, so we can also follow the steps in dubbo&rsquo;s official documentation to add related annotations to the implementation of REST services to replace some xml configurations, for example</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">@Service</span>(protocol <span style="color:#719e07">=</span> <span style="color:#2aa198">&#34;rest&#34;</span>) |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">@Path</span>(<span style="color:#2aa198">&#34;users&#34;</span>) |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">public</span> <span style="color:#268bd2">class</span> <span style="color:#268bd2">UserServiceImpl</span> <span style="color:#268bd2">implements</span> UserService { |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@Autowired</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">private</span> UserRepository userRepository; |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@POST</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@Path</span>(<span style="color:#2aa198">&#34;register&#34;</span>) |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@Consumes</span>({MediaType. APPLICATION_JSON}) |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">public</span> <span style="color:#dc322f">void</span> <span style="color:#268bd2">registerUser</span>(User user) { |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">// save the user</span> |
| </span></span><span style="display:flex;"><span> userRepository. <span style="color:#268bd2">save</span>(user); |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>The configuration of annotation is simpler and more precise, and it is usually easier to maintain (of course, modern IDEs can support such as class name refactoring in xml, so in terms of specific use cases here, xml is also very maintainable). And xml is less intrusive to the code, especially conducive to dynamic modification of configuration, especially if you want to configure connection timeout, maximum number of connections per client, cluster strategy, weight, etc. for a single service. In addition, especially for complex applications or modules, xml provides a central point to cover all components and configurations, which is more clear at a glance and generally more convenient for long-term project maintenance.</p> |
| <p>Of course, there is no absolute advantage or disadvantage in choosing which configuration method to choose, and it has nothing to do with personal preference.</p> |
| <h3 id="add-custom-filter-interceptor-etc">Add custom Filter, Interceptor, etc.</h3> |
| <p>Dubbo&rsquo;s REST also supports JAX-RS standard Filter and Interceptor to facilitate customized interception of REST request and response processes.</p> |
| <p>Among them, Filter is mainly used to access and set HTTP request and response parameters, URI, etc. For example, to set the cache header of an HTTP response:</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">CacheControlFilter</span> <span style="color:#268bd2">implements</span> ContainerResponseFilter { |
| </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">filter</span>(ContainerRequestContext req, ContainerResponseContext res) { |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">if</span> (req. <span style="color:#268bd2">getMethod</span>(). equals(<span style="color:#2aa198">&#34;GET&#34;</span>)) { |
| </span></span><span style="display:flex;"><span> res.getHeaders().add(<span style="color:#2aa198">&#34;Cache-Control&#34;</span>, <span style="color:#2aa198">&#34;someValue&#34;</span>); |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>Interceptor is mainly used to access and modify input and output byte streams, for example, manually add GZIP compression</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">GZIPWriterInterceptor</span> <span style="color:#268bd2">implements</span> WriterInterceptor { |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">@Override</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">public</span> <span style="color:#dc322f">void</span> <span style="color:#268bd2">aroundWriteTo</span>(WriterInterceptorContext context) |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">throws</span> IOException, WebApplicationException { |
| </span></span><span style="display:flex;"><span> OutputStream outputStream <span style="color:#719e07">=</span> context. <span style="color:#268bd2">getOutputStream</span>(); |
| </span></span><span style="display:flex;"><span> context.setOutputStream(<span style="color:#719e07">new</span> GZIPOutputStream(outputStream)); |
| </span></span><span style="display:flex;"><span> context. <span style="color:#268bd2">proceed</span>(); |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>In standard JAX-RS applications, we generally add @Provider annotations for Filter and Interceptor, and then JAX-RS runtime will automatically discover and enable them. In dubbo, we register Filter and Interceptor by adding XML configuration:</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;rest&#34;</span> port=<span style="color:#2aa198">&#34;8888&#34;</span> extension=<span style="color:#2aa198">&#34;xxx.TraceInterceptor, xxx.TraceFilter&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>Here, we can add all three types of objects, Filter, Interceptor and DynamicFeature, to the <code>extension</code> attribute, and separate them with commas. (DynamicFeature is another interface, which can facilitate us to enable Filter and Interceptor more dynamically. If you are interested, please google yourself.)</p> |
| <p>Of course, dubbo itself also supports the concept of Filter, but the Filter and Interceptor we discuss here are closer to the bottom layer of the protocol implementation. Compared with Dubbo&rsquo;s filter, it can be customized at a lower level.</p> |
| <blockquote> |
| <p>Note: The XML attribute here is called extension, not interceptor or filter, because in addition to Interceptor and Filter, we will add more extension types in the future.</p> |
| </blockquote> |
| <p>If the consumer side of REST is also a dubbo system (see the discussion below), you can also configure Interceptor and Filter for the consumer side in a similar way. But note that the consumer-side Filter and the provider-side Filter in JAX-RS are two different interfaces. For example, in the previous example, the server is the ContainerResponseFilter interface, while the consumer corresponds to the ClientResponseFilter:</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">LoggingFilter</span> <span style="color:#268bd2">implements</span> ClientResponseFilter { |
| </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">filter</span>(ClientRequestContext reqCtx, ClientResponseContext resCtx) <span style="color:#268bd2">throws</span> IOException { |
| </span></span><span style="display:flex;"><span> System.out.println(<span style="color:#2aa198">&#34;status: &#34;</span> <span style="color:#719e07">+</span> resCtx.getStatus()); |
| </span></span><span style="display:flex;"><span>System.out.println(<span style="color:#2aa198">&#34;date: &#34;</span> <span style="color:#719e07">+</span> resCtx.getDate()); |
| </span></span><span style="display:flex;"><span>System.out.println(<span style="color:#2aa198">&#34;last-modified: &#34;</span> <span style="color:#719e07">+</span> resCtx.getLastModified()); |
| </span></span><span style="display:flex;"><span>System.out.println(<span style="color:#2aa198">&#34;location: &#34;</span> <span style="color:#719e07">+</span> resCtx.getLocation()); |
| </span></span><span style="display:flex;"><span>System.out.println(<span style="color:#2aa198">&#34;headers:&#34;</span>); |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">for</span> (Entry<span style="color:#719e07">&lt;</span>String, List<span style="color:#719e07">&lt;</span>String<span style="color:#719e07">&gt;&gt;</span> header : resCtx. <span style="color:#268bd2">getHeaders</span>(). entrySet()) { |
| </span></span><span style="display:flex;"><span> System.out.print(<span style="color:#2aa198">&#34;\t&#34;</span> <span style="color:#719e07">+</span> header.getKey() <span style="color:#719e07">+</span> <span style="color:#2aa198">&#34; :&#34;</span>); |
| </span></span><span style="display:flex;"><span><span style="color:#719e07">for</span> (String value : header. <span style="color:#268bd2">getValue</span>()) { |
| </span></span><span style="display:flex;"><span>System.out.print(value <span style="color:#719e07">+</span> <span style="color:#2aa198">&#34;, &#34;</span>); |
| </span></span><span style="display:flex;"><span>} |
| </span></span><span style="display:flex;"><span>System.out.print(<span style="color:#2aa198">&#34;\n&#34;</span>); |
| </span></span><span style="display:flex;"><span>} |
| </span></span><span style="display:flex;"><span>System.out.println(<span style="color:#2aa198">&#34;media-type: &#34;</span> <span style="color:#719e07">+</span> resCtx.getMediaType().getType()); |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><h3 id="add-custom-exception-handling">Add custom Exception handling</h3> |
| <p>Dubbo&rsquo;s REST also supports JAX-RS standard ExceptionMapper, which can be used to customize the HTTP response that should be returned after a specific exception occurs.</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">CustomExceptionMapper</span> <span style="color:#268bd2">implements</span> ExceptionMapper<span style="color:#719e07">&lt;</span>NotFoundException<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> Response <span style="color:#268bd2">toResponse</span>(NotFoundException e) { |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">return</span> Response.status(Response.Status.NOT_FOUND).entity(<span style="color:#2aa198">&#34;Oops! the requested resource is not found!&#34;</span>).type(<span style="color:#2aa198">&#34;text/plain&#34;</span>).build(); |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>Similar to Interceptor and Filter, it can be enabled by adding it to the XML configuration 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-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:protocol</span> name=<span style="color:#2aa198">&#34;rest&#34;</span> port=<span style="color:#2aa198">&#34;8888&#34;</span> extension=<span style="color:#2aa198">&#34;xxx.CustomExceptionMapper&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><h3 id="configure-http-log-output">Configure HTTP log output</h3> |
| <p>Dubbo rest supports outputting header fields and body message bodies in all HTTP requests/responses.</p> |
| <p>Add the following built-in REST filter in the XML configuration:</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;rest&#34;</span> port=<span style="color:#2aa198">&#34;8888&#34;</span> extension=<span style="color:#2aa198">&#34;org.apache.dubbo.rpc.protocol.rest.support.LoggingFilter&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>Then configure to turn on INFO level log output for at least org.apache.dubbo.rpc.protocol.rest.support in the logging configuration, for example, configure in log4j.xml</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;logger</span> name=<span style="color:#2aa198">&#34;org.apache.dubbo.rpc.protocol.rest.support&#34;</span><span style="color:#268bd2">&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;level</span> value=<span style="color:#2aa198">&#34;INFO&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;appender-ref</span> ref=<span style="color:#2aa198">&#34;CONSOLE&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;/logger&gt;</span> |
| </span></span></code></pre></div><p>Of course, you can also directly open INFO level log output in ROOT logger</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;root&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;level</span> value=<span style="color:#2aa198">&#34;INFO&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;appender-ref</span> ref=<span style="color:#2aa198">&#34;CONSOLE&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;/root&gt;</span> |
| </span></span></code></pre></div><p>Then something similar to the following will be output in the log</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>The HTTP headers are: |
| </span></span><span style="display:flex;"><span>accept: application/json;charset=UTF-8 |
| </span></span><span style="display:flex;"><span>accept-encoding: gzip, deflate |
| </span></span><span style="display:flex;"><span>connection: Keep-Alive |
| </span></span><span style="display:flex;"><span>content-length: 22 |
| </span></span><span style="display:flex;"><span>content-type: application/json |
| </span></span><span style="display:flex;"><span>host: 192.168.1.100:8888 |
| </span></span><span style="display:flex;"><span>user-agent: Apache-HttpClient/4.2.1 (java 1.5) |
| </span></span></code></pre></div><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>The contents of request body are: |
| </span></span><span style="display:flex;"><span>{&#34;id&#34;:1,&#34;name&#34;:&#34;dang&#34;} |
| </span></span></code></pre></div><p>After HTTP log output is enabled, in addition to the performance overhead of normal log output, additional overhead will be generated when parsing HTTP requests, for example, because additional memory buffers need to be established to prepare data for log output.</p> |
| <h3 id="validation-of-input-parameters">Validation of input parameters</h3> |
| <p>Dubbo&rsquo;s rest supports Java standard bean validation annotation (JSR 303) for input validation <a href="http://beanvalidation.org/">http://beanvalidation.org/</a></p> |
| <p>In order to be consistent with other dubbo remote call protocols, the annotation for verification in rest must be placed on the service interface, for example</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">UserService</span> { |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> User <span style="color:#268bd2">getUser</span>(<span style="color:#268bd2">@Min</span>(value<span style="color:#719e07">=</span>1L, message<span style="color:#719e07">=</span><span style="color:#2aa198">&#34;User ID must be greater than 1&#34;</span>) Long id); |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>Of course, in many other bean validation application scenarios, the annotation is placed on the implementation class instead of the interface. At least one advantage of putting the annotation on the interface is that dubbo clients can share the information of this interface, and dubbo can complete the input verification locally without even making remote calls.</p> |
| <p>Then open the validation in the XML configuration according to dubbo&rsquo;s standard way:</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:service</span> interface=<span style="color:#2aa198">xxx.UserService&#34;</span> ref=<span style="color:#2aa198">&#34;userService&#34;</span> protocol=<span style="color:#2aa198">&#34;rest&#34;</span> validation=<span style="color:#2aa198">&#34;true&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>In many other remote call protocols of dubbo, if the input verification fails, <code>RpcException</code> is directly thrown to the client, but in rest, since the client is often a non-dubbo or even non-java system, it is inconvenient to directly throw a Java exception . Therefore, currently we return validation errors as XML</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;violationReport&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;constraint</span> Violations<span style="color:#268bd2">&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;path&gt;</span>getUserArgument0<span style="color:#268bd2">&lt;/path&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;message&gt;</span>User ID must be greater than 1<span style="color:#268bd2">&lt;/message&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;value&gt;</span>0<span style="color:#268bd2">&lt;/value&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;/constraintViolations&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;/violationReport&gt;</span> |
| </span></span></code></pre></div><p>Return values in other data formats will be supported later. As for how to internationalize the validation error message, just refer to the relevant documents of bean validation.</p> |
| <p>If you think that the default validation error return format does not meet your requirements, you can add a custom ExceptionMapper to freely customize the error return format as described in the above section. It should be noted that this ExceptionMapper must use a generic declaration to catch dubbo&rsquo;s RpcException, in order to successfully override the default exception handling strategy of dubbo rest. In order to simplify the operation, in fact, the easiest way here is to directly inherit the RpcExceptionMapper of dubbo rest, and override the method of handling verification exceptions</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">MyValidationExceptionMapper</span> <span style="color:#268bd2">extends</span> RpcExceptionMapper { |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">protected</span> Response <span style="color:#268bd2">handleConstraintViolationException</span>(ConstraintViolationException cve) { |
| </span></span><span style="display:flex;"><span> ViolationReport report <span style="color:#719e07">=</span> <span style="color:#719e07">new</span> ViolationReport(); |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">for</span> (ConstraintViolation cv : cve. <span style="color:#268bd2">getConstraintViolations</span>()) { |
| </span></span><span style="display:flex;"><span> report.addConstraintViolation(<span style="color:#719e07">new</span> RestConstraintViolation( |
| </span></span><span style="display:flex;"><span> cv.getPropertyPath().toString(), |
| </span></span><span style="display:flex;"><span> cv. <span style="color:#268bd2">getMessage</span>(), |
| </span></span><span style="display:flex;"><span> cv.getInvalidValue() <span style="color:#719e07">==</span> <span style="color:#cb4b16">null</span> <span style="color:#719e07">?</span> <span style="color:#2aa198">&#34;null&#34;</span> : cv.getInvalidValue().toString())); |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span> <span style="color:#586e75">// Use json output instead of xml output</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#719e07">return</span> Response.status(Response.Status.INTERNAL_SERVER_ERROR).entity(report).type(ContentType.APPLICATION_JSON_UTF_8).build(); |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span>} |
| </span></span></code></pre></div><p>Then add this ExceptionMapper to the XML configuration:</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;rest&#34;</span> port=<span style="color:#2aa198">&#34;8888&#34;</span> extension=<span style="color:#2aa198">&#34;xxx.MyValidationExceptionMapper&#34;</span><span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div></description></item><item><title>Docs3-V2: gRPC Protocol</title><link>https://dubbo.apache.org/en/docs3-v2/java-sdk/reference-manual/protocol/grpc/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/en/docs3-v2/java-sdk/reference-manual/protocol/grpc/</guid><description> |
| <h2 id="feature-description">Feature description</h2> |
| <p>Dubbo has supported the gRPC protocol since version 2.7.5. For developers who plan to use HTTP/2 communication, or want to take advantage of the capabilities of Stream, backpressure, and Reactive programming brought by gRPC, |
| You can consider enabling the gRPC protocol.</p> |
| <h4 id="benefits-of-supporting-grpc">Benefits of supporting gRPC</h4> |
| <ul> |
| <li>Bring service governance capabilities to users who expect to use the gRPC protocol, and facilitate access to the Dubbo system</li> |
| <li>Users can use Dubbo-style, interface-based programming style to define and use remote services</li> |
| </ul> |
| <h2 id="scenes-to-be-used">scenes to be used</h2> |
| <ul> |
| <li>Synchronous backend microservice-to-microservice communication that requires an immediate response to continue processing.</li> |
| <li>Requires a Polyglot environment that supports mixed programming platforms.</li> |
| <li>Low latency and high throughput communications where performance is critical.</li> |
| <li>Peer-to-peer real-time communication - gRPC pushes messages in real time without polling and has excellent support for bidirectional streaming.</li> |
| <li>Network Constrained Environments - Binary gRPC messages are always smaller than equivalent text-based JSON messages.</li> |
| </ul> |
| <h2 id="how-to-use">How to use</h2> |
| <h3 id="using-grpc-in-dubbo">Using gRPC in Dubbo</h3> |
| <p><a href="https://github.com/apache/dubbo-samples/tree/master/99-integration/dubbo-samples-grpc">Example</a></p> |
| <h3 id="steps">steps</h3> |
| <ol> |
| <li>Define a service using IDL</li> |
| <li>Configure the compiler plug-in, precompile locally</li> |
| <li>Configure to expose/reference Dubbo service</li> |
| </ol> |
| <blockquote> |
| <p>In addition to the native StreamObserver interface type, Dubbo also supports <a href="https://github.com/apache/dubbo-samples/tree/master/99-integration/dubbo-samples-grpc/dubbo-samples-rxjava">RxJava</a>, <a href="https://github.com/apache/dubbo-samples/tree/master/99-integration/dubbo-samples-grpc/dubbo-samples-reactor">Reactor</a> programming style API.</p> |
| </blockquote></description></item><item><title>Docs3-V2: HTTP protocol</title><link>https://dubbo.apache.org/en/docs3-v2/java-sdk/reference-manual/protocol/http/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/en/docs3-v2/java-sdk/reference-manual/protocol/http/</guid><description> |
| <h2 id="feature-description">Feature description</h2> |
| <p>HTTP form-based remote invocation protocol, implemented by Spring&rsquo;s HttpInvoker, supported by versions above <code>2.3.0</code>.</p> |
| <ul> |
| <li>Number of connections: multiple connections</li> |
| <li>Connection method: short connection</li> |
| <li>Transmission protocol: HTTP</li> |
| <li>Transmission method: synchronous transmission</li> |
| <li>Serialization: form serialization</li> |
| <li>Scope of application: The size of incoming and outgoing parameter data packets is mixed, the number of providers is more than that of consumers, it can be viewed with a browser, and parameters can be passed in by form or URL, and file transfer is not supported for now.</li> |
| <li>Applicable scenarios: services that need to be used by both application and browser JS.</li> |
| </ul> |
| <h4 id="constraints">Constraints</h4> |
| <ul> |
| <li>Parameters and return values must conform to the Bean specification</li> |
| </ul> |
| <h2 id="scenes-to-be-used">scenes to be used</h2> |
| <p>HTTP short connection, standardized and easy-to-read protocol, easy to connect to external systems, suitable for upper-level business modules.</p> |
| <h2 id="how-to-use">How to use</h2> |
| <p>Starting from Dubbo 3, the Http protocol is no longer embedded in Dubbo, and an independent <a href="https://dubbo.apache.org/zh-cn/download/spi-extensions/#dubbo-rpc">module</a> needs to be introduced separately.</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;dependency&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;groupId&gt;</span>org.apache.dubbo.extensions<span style="color:#268bd2">&lt;/groupId&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;artifactId&gt;</span>dubbo-rpc-http<span style="color:#268bd2">&lt;/artifactId&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;version&gt;</span>1.0.0<span style="color:#268bd2">&lt;/version&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;/dependency&gt;</span> |
| </span></span></code></pre></div><h3 id="configuration-protocol">Configuration protocol</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-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:protocol</span> name=<span style="color:#2aa198">&#34;http&#34;</span> port=<span style="color:#2aa198">&#34;8080&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><h3 id="configure-jetty-server-default">Configure Jetty Server (default)</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-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:protocol</span> ... server=<span style="color:#2aa198">&#34;jetty&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><h3 id="configure-servlet-bridge-server-recommended">Configure Servlet Bridge Server (recommended)</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-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:protocol</span> ... server=<span style="color:#2aa198">&#34;servlet&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><h3 id="configure-dispatcherservlet">Configure DispatcherServlet</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-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;servlet&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;servlet-name&gt;</span>dubbo<span style="color:#268bd2">&lt;/servlet-name&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;servlet-class&gt;</span>org.apache.dubbo.remoting.http.servlet.DispatcherServlet<span style="color:#268bd2">&lt;/servlet-class&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;load-on-startup&gt;</span>1<span style="color:#268bd2">&lt;/load-on-startup&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;/servlet&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;servlet-mapping&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;servlet-name&gt;</span>dubbo<span style="color:#268bd2">&lt;/servlet-name&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;url-pattern&gt;</span>/*<span style="color:#268bd2">&lt;/url-pattern&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;/servlet-mapping&gt;</span> |
| </span></span></code></pre></div><blockquote> |
| <p>If a servlet is used to dispatch the request</p> |
| <ul> |
| <li>The protocol port <code>&lt;dubbo:protocol port=&quot;8080&quot; /&gt;</code> must be the same as the port of the servlet container,</li> |
| <li>The context path of the protocol <code>&lt;dubbo:protocol contextpath=&quot;foo&quot; /&gt;</code> must be the same as the context path of the servlet application.</li> |
| </ul> |
| </blockquote></description></item><item><title>Docs3-V2: Thrift protocol</title><link>https://dubbo.apache.org/en/docs3-v2/java-sdk/reference-manual/protocol/thrift/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/en/docs3-v2/java-sdk/reference-manual/protocol/thrift/</guid><description> |
| <h2 id="feature-description">Feature description</h2> |
| <p>The thrift protocol currently supported by dubbo is an extension of the thrift native protocol, adding some additional header information on the basis of the native protocol, such as service name, magic number, etc. <code>2.3.0</code> and above are supported.</p> |
| <p><a href="http://thrift.apache.org">Thrift</a> is an RPC framework donated by Facebook to Apache.</p> |
| <p>Using the dubbo thrift protocol also needs to use thrift&rsquo;s idl compiler to compile and generate the corresponding java code, and some enhancements will be made in this regard in subsequent versions.</p> |
| <h2 id="scenes-to-be-used">scenes to be used</h2> |
| <p>For SOA standard RPC framework.</p> |
| <h2 id="how-to-use">How to use</h2> |
| <h3 id="dependencies">Dependencies</h3> |
| <p>Starting from Dubbo 3, the Thrift protocol is no longer embedded in Dubbo, and an independent <a href="https://dubbo.apache.org/zh-cn/download/spi-extensions/#dubbo-rpc">module</a> needs to be introduced separately.</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;dependency&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;groupId&gt;</span>org.apache.dubbo.extensions<span style="color:#268bd2">&lt;/groupId&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;artifactId&gt;</span>dubbo-rpc-native-thrift<span style="color:#268bd2">&lt;/artifactId&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;version&gt;</span>1.0.0<span style="color:#268bd2">&lt;/version&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;/dependency&gt;</span> |
| </span></span></code></pre></div><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;dependency&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;groupId&gt;</span>org.apache.thrift<span style="color:#268bd2">&lt;/groupId&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;artifactId&gt;</span>libthrift<span style="color:#268bd2">&lt;/artifactId&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;version&gt;</span>0.8.0<span style="color:#268bd2">&lt;/version&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;/dependency&gt;</span> |
| </span></span></code></pre></div><h3 id="all-services-share-one-port">All services share one port</h3> |
| <p>Incompatible with native Thrift</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;thrift&#34;</span> port=<span style="color:#2aa198">&#34;3030&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>[Example code in dubbo project](<a href="https://github.com/apache/dubbo/tree/master/dubbo-rpc/dubbo-rpc-thrift/src/test/java/org/apache/dubbo/rpc/protocol">https://github.com/apache/dubbo/tree/master/dubbo-rpc/dubbo-rpc-thrift/src/test/java/org/apache/dubbo/rpc/protocol</a> /thrift)</p> |
| <blockquote> |
| <p>Thrift does not support null values, ie: you cannot pass null values in the protocol</p> |
| </blockquote></description></item><item><title>Docs3-V2: Rmi agreement</title><link>https://dubbo.apache.org/en/docs3-v2/java-sdk/reference-manual/protocol/rmi/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/en/docs3-v2/java-sdk/reference-manual/protocol/rmi/</guid><description> |
| <h2 id="feature-description">Feature description</h2> |
| <p>The RMI protocol is implemented using the JDK standard <code>java.rmi.*</code>, using blocking short connections and JDK standard serialization.</p> |
| <ul> |
| <li>Number of connections: multiple connections</li> |
| <li>Connection method: short connection</li> |
| <li>Transport protocol: TCP</li> |
| <li>Transmission method: synchronous transmission</li> |
| <li>Serialization: Java standard binary serialization</li> |
| <li>Scope of application: Incoming and outgoing parameter packets are mixed in size, the number of consumers and providers is similar, and files can be transferred.</li> |
| <li>Applicable scenarios: regular remote service method calls, interoperability with native RMI services</li> |
| </ul> |
| <h4 id="constraints">Constraints</h4> |
| <ul> |
| <li>Parameters and return values need to implement <code>Serializable</code> interface</li> |
| <li>The timeout in dubbo configuration is invalid for RMI, you need to use the java startup parameter setting: <code>-Dsun.rmi.transport.tcp.responseTimeout=3000</code>, see the following RMI configuration</li> |
| </ul> |
| <h2 id="scenes-to-be-used">scenes to be used</h2> |
| <p>It is a set of Java APIs that supports the development of distributed applications, and realizes the method calling of programs between different operating systems.</p> |
| <h2 id="how-to-use">How to use</h2> |
| <h3 id="import-dependencies">Import dependencies</h3> |
| <p>Starting from Dubbo 3, the RMI protocol is no longer embedded in Dubbo, and an independent <a href="https://dubbo.apache.org/zh-cn/download/spi-extensions/#dubbo-rpc">module</a> needs to be introduced separately.</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;dependency&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;groupId&gt;</span>org.apache.dubbo.extensions<span style="color:#268bd2">&lt;/groupId&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;artifactId&gt;</span>dubbo-rpc-rmi<span style="color:#268bd2">&lt;/artifactId&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;version&gt;</span>1.0.0<span style="color:#268bd2">&lt;/version&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;/dependency&gt;</span> |
| </span></span></code></pre></div><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>java -Dsun.rmi.transport.tcp.responseTimeout<span style="color:#719e07">=</span><span style="color:#2aa198">3000</span> |
| </span></span></code></pre></div><p>For more RMI optimization parameters, please see <a href="https://docs.oracle.com/javase/6/docs/technotes/guides/rmi/sunrmiproperties.html">JDK Documentation</a></p> |
| <h3 id="interface-description">Interface Description</h3> |
| <p>If the service interface inherits the <code>java.rmi.Remote</code> interface, it can interoperate with native RMI, namely:</p> |
| <ul> |
| <li>The provider uses Dubbo&rsquo;s RMI protocol to expose the service, and the consumer directly uses the standard RMI interface to call,</li> |
| <li>Or the provider uses standard RMI to expose the service, and the consumer uses Dubbo&rsquo;s RMI protocol to call.</li> |
| </ul> |
| <p>If the service interface does not extend the <code>java.rmi.Remote</code> interface:</p> |
| <ul> |
| <li>By default, Dubbo will automatically generate a <code>com.xxx.XxxService$Remote</code> interface, inherit the <code>java.rmi.Remote</code> interface, and expose the service through this interface,</li> |
| <li>But if <code>&lt;dubbo:protocol name=&quot;rmi&quot; codec=&quot;spring&quot; /&gt;</code> is set, the <code>$Remote</code> interface will not be generated, and the service will be exposed using Spring’s <code>RmiInvocationHandler</code> interface, which is compatible with Spring.</li> |
| </ul> |
| <p><strong>Define the RMI protocol</strong></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;rmi&#34;</span> port=<span style="color:#2aa198">&#34;1099&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p><strong>SET DEFAULT PROTOCOL</strong></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:provider</span> protocol=<span style="color:#2aa198">&#34;rmi&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p><strong>Set the protocol of a service</strong></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:service</span> interface=<span style="color:#2aa198">&#34;...&#34;</span> protocol=<span style="color:#2aa198">&#34;rmi&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p><strong>Multiple ports</strong></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> id=<span style="color:#2aa198">&#34;rmi1&#34;</span> name=<span style="color:#2aa198">&#34;rmi&#34;</span> port=<span style="color:#2aa198">&#34;1099&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:protocol</span> id=<span style="color:#2aa198">&#34;rmi2&#34;</span> name=<span style="color:#2aa198">&#34;rmi&#34;</span> port=<span style="color:#2aa198">&#34;2099&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:service</span> interface=<span style="color:#2aa198">&#34;...&#34;</span> protocol=<span style="color:#2aa198">&#34;rmi1&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p><strong>Spring Compatibility</strong></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;rmi&#34;</span> codec=<span style="color:#2aa198">&#34;spring&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><blockquote> |
| <ul> |
| <li><strong>If you are using RMI to provide services for external access,</strong> there should be no risk of attack in the company&rsquo;s intranet environment.</li> |
| </ul> |
| </blockquote> |
| <blockquote> |
| <ul> |
| <li><strong>At the same time, if the application relies on the old common-collections package,</strong> dubbo will not depend on this package. Please check whether your application has used it.</li> |
| </ul> |
| </blockquote> |
| <blockquote> |
| <ul> |
| <li>** There is a deserialization security risk. ** Please check the application: Please upgrade commons-collections3 to <a href="https://commons.apache.org/proper/commons-collections/release_3_2_2.html">3.2.2</a>; Please upgrade commons-collections4 to <a href="https://commons.apache.org/proper/commons-collections/release_4_1.html">4.1</a>. The new version of commons-collections solves this problem.</li> |
| </ul> |
| </blockquote></description></item><item><title>Docs3-V2: Redis protocol</title><link>https://dubbo.apache.org/en/docs3-v2/java-sdk/reference-manual/protocol/redis/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/en/docs3-v2/java-sdk/reference-manual/protocol/redis/</guid><description> |
| <h2 id="feature-description">Feature description</h2> |
| <p>RPC protocol implemented based on Redis. <code>2.3.0</code> and above are supported.</p> |
| <p><a href="http://redis.io">Redis</a> is an efficient KV storage server.</p> |
| <h2 id="scenes-to-be-used">scenes to be used</h2> |
| <p>Caching, current limiting, distributed locks, etc.</p> |
| <h2 id="how-to-use">How to use</h2> |
| <h3 id="import-dependencies">Import dependencies</h3> |
| <p>Starting from Dubbo 3, the Redis protocol is no longer embedded in Dubbo, and an independent <a href="https://dubbo.apache.org/zh-cn/download/spi-extensions/#dubbo-rpc">module</a> needs to be introduced separately.</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;dependency&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;groupId&gt;</span>org.apache.dubbo.extensions<span style="color:#268bd2">&lt;/groupId&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;artifactId&gt;</span>dubbo-rpc-redis<span style="color:#268bd2">&lt;/artifactId&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;version&gt;</span>1.0.0<span style="color:#268bd2">&lt;/version&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;/dependency&gt;</span> |
| </span></span></code></pre></div><h3 id="register-the-address-of-the-redis-service">Register the address of the redis service</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-java" data-lang="java"><span style="display:flex;"><span>RegistryFactory registryFactory <span style="color:#719e07">=</span> ExtensionLoader.getExtensionLoader(RegistryFactory.class).getAdaptiveExtension(); |
| </span></span><span style="display:flex;"><span>Registry registry <span style="color:#719e07">=</span> registryFactory.getRegistry(URL.valueOf(<span style="color:#2aa198">&#34;zookeeper://10.20.153.10:2181&#34;</span>)); |
| </span></span><span style="display:flex;"><span>registry.register(URL.valueOf(<span style="color:#2aa198">&#34;redis://10.20.153.11/com.foo.BarService?category=providers&amp;dynamic=false&amp;application=foo&amp;group=member&amp;loadbalance=consistenthash&#34;</span>)); |
| </span></span></code></pre></div><h3 id="referenced-on-the-client-side">Referenced on the client side</h3> |
| <p>Does not need to be aware of Redis addresses</p> |
| <p>On the client side use:</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:reference</span> id=<span style="color:#2aa198">&#34;store&#34;</span> interface=<span style="color:#2aa198">&#34;java.util.Map&#34;</span> group=<span style="color:#2aa198">&#34;member&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>Or point-to-point direct connection:</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:reference</span> id=<span style="color:#2aa198">&#34;store&#34;</span> interface=<span style="color:#2aa198">&#34;java.util.Map&#34;</span> url=<span style="color:#2aa198">&#34;redis://10.20.153.10:6379&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>It is also possible to use a custom interface:</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:reference</span> id=<span style="color:#2aa198">&#34;store&#34;</span> interface=<span style="color:#2aa198">&#34;com.foo.StoreService&#34;</span> url=<span style="color:#2aa198">&#34;redis://10.20.153.10:6379&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>Where &ldquo;p:xxx&rdquo; is the standard p tag of spring</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:reference</span> id=<span style="color:#2aa198">&#34;cache&#34;</span> interface=<span style="color:#2aa198">&#34;com.foo.CacheService&#34;</span> url=<span style="color:#2aa198">&#34;redis://10.20.153.10:6379&#34;</span> p:set=<span style="color:#2aa198">&#34;putFoo&#34;</span> p:get=<span style="color:#2aa198">&#34;getFoo&#34;</span> p:delete=<span style="color:#2aa198">&#34; removeFoo&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>The method name is suggested to be the same as the standard method name of redis, namely: get(key), set(key, value), delete(key).</p> |
| <p>If the method name is different from the standard method name of redis, you need to configure the mapping relationship:</p></description></item><item><title>Docs3-V2: Hessian Agreement</title><link>https://dubbo.apache.org/en/docs3-v2/java-sdk/reference-manual/protocol/hessian/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/en/docs3-v2/java-sdk/reference-manual/protocol/hessian/</guid><description> |
| <h2 id="feature-description">Feature description</h2> |
| <p>The Hessian protocol is used to integrate Hessian&rsquo;s services. The bottom layer of Hessian uses Http communication and Servlet to expose services. Dubbo&rsquo;s default embedded Jetty is implemented as a server.</p> |
| <p><a href="http://hessian.caucho.com">Hessian</a> is an open source RPC framework of Caucho, whose communication efficiency is higher than the serialization that comes with WebService and Java.</p> |
| <ul> |
| <li>Number of connections: multiple connections</li> |
| <li>Connection method: short connection</li> |
| <li>Transmission protocol: HTTP</li> |
| <li>Transmission method: synchronous transmission</li> |
| <li>Serialization: Hessian binary serialization</li> |
| <li>Scope of application: The incoming and outgoing parameter data packets are large, the number of providers is larger than that of consumers, the pressure on providers is high, and files can be transferred.</li> |
| <li>Applicable scenarios: page transfer, file transfer, or interoperability with native Hessian services.</li> |
| </ul> |
| <p>Dubbo&rsquo;s Hessian protocol can interoperate with native Hessian services, namely:</p> |
| <ul> |
| <li>The provider uses Dubbo&rsquo;s Hessian protocol to expose the service, and the consumer directly uses the standard Hessian interface to call,</li> |
| <li>Or the provider uses the standard Hessian to expose the service, and the consumer uses Dubbo&rsquo;s Hessian protocol to call.</li> |
| </ul> |
| <h4 id="constraints">Constraints</h4> |
| <ul> |
| <li>Parameters and return values need to implement <code>Serializable</code> interface.</li> |
| <li>Parameters and return values cannot be customized to implement <code>List</code>, <code>Map</code>, <code>Number</code>, <code>Date</code>, <code>Calendar</code> and other interfaces, only the implementations that come with JDK can be used, because hessian will do special processing and customize the implementation All attribute values in the class are lost.</li> |
| </ul> |
| <h2 id="scenes-to-be-used">scenes to be used</h2> |
| <p>Hessian is a lightweight RPC service implemented based on the Binary-RPC protocol, serializing and deserializing instances.</p> |
| <h2 id="how-to-use">How to use</h2> |
| <h3 id="dependencies">Dependencies</h3> |
| <p>Starting from Dubbo 3, the Hessian protocol is no longer embedded in Dubbo, and an independent <a href="https://dubbo.apache.org/zh-cn/download/spi-extensions/#dubbo-rpc">module</a> needs to be introduced separately.</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;dependency&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;groupId&gt;</span>org.apache.dubbo.extensions<span style="color:#268bd2">&lt;/groupId&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;artifactId&gt;</span>dubbo-rpc-hessian<span style="color:#268bd2">&lt;/artifactId&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;version&gt;</span>1.0.0<span style="color:#268bd2">&lt;/version&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;/dependency&gt;</span> |
| </span></span></code></pre></div><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;dependency&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;groupId&gt;</span>com.caucho<span style="color:#268bd2">&lt;/groupId&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;artifactId&gt;</span>hessian<span style="color:#268bd2">&lt;/artifactId&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;version&gt;</span>4.0.7<span style="color:#268bd2">&lt;/version&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;/dependency&gt;</span> |
| </span></span></code></pre></div><h3 id="define-the-hessian-protocol">Define the hessian protocol</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-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:protocol</span> name=<span style="color:#2aa198">&#34;hessian&#34;</span> port=<span style="color:#2aa198">&#34;8080&#34;</span> server=<span style="color:#2aa198">&#34;jetty&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><h3 id="set-the-default-protocol">Set the default protocol</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-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:provider</span> protocol=<span style="color:#2aa198">&#34;hessian&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><h3 id="set-service-protocol">Set service protocol</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-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:service</span> protocol=<span style="color:#2aa198">&#34;hessian&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><h3 id="multiport">Multiport</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-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:protocol</span> id=<span style="color:#2aa198">&#34;hessian1&#34;</span> name=<span style="color:#2aa198">&#34;hessian&#34;</span> port=<span style="color:#2aa198">&#34;8080&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:protocol</span> id=<span style="color:#2aa198">&#34;hessian2&#34;</span> name=<span style="color:#2aa198">&#34;hessian&#34;</span> port=<span style="color:#2aa198">&#34;8081&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><h3 id="direct-connection">direct connection</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-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:reference</span> id=<span style="color:#2aa198">&#34;helloService&#34;</span> interface=<span style="color:#2aa198">&#34;HelloWorld&#34;</span> url=<span style="color:#2aa198">&#34;hessian://10.20.153.10:8080/helloWorld&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div></description></item><item><title>Docs3-V2: Webservice protocol</title><link>https://dubbo.apache.org/en/docs3-v2/java-sdk/reference-manual/protocol/webservice/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/en/docs3-v2/java-sdk/reference-manual/protocol/webservice/</guid><description> |
| <h2 id="feature-description">Feature description</h2> |
| <p>WebService-based remote invocation protocol, implemented based on <code>frontend-simple</code> and <code>transports-http</code> of <a href="http://cxf.apache.org">Apache CXF</a>. <code>2.3.0</code> and above are supported.</p> |
| <p>CXF is an open source RPC framework of Apache, which is merged from Xfire and Celtix.</p> |
| <ul> |
| <li>Number of connections: multiple connections</li> |
| <li>Connection method: short connection</li> |
| <li>Transmission protocol: HTTP</li> |
| <li>Transmission method: synchronous transmission</li> |
| <li>Serialization: SOAP text serialization</li> |
| <li>Applicable scenarios: system integration, cross-language call</li> |
| </ul> |
| <p>It can interoperate with native WebService services, namely:</p> |
| <ul> |
| <li>The provider uses Dubbo&rsquo;s WebService protocol to expose the service, and the consumer directly uses the standard WebService interface to call,</li> |
| <li>Or the provider uses the standard WebService to expose the service, and the consumer uses Dubbo&rsquo;s WebService protocol to call.</li> |
| </ul> |
| <h4 id="constraints">Constraints</h4> |
| <ul> |
| <li>Parameters and return values need to implement <code>Serializable</code> interface</li> |
| <li>Parameters try to use basic types and POJO</li> |
| </ul> |
| <h2 id="scenes-to-be-used">scenes to be used</h2> |
| <p>To publish a service (internal/external), regardless of client type or performance, it is recommended to use webservice. The server has determined to use webservice, the client cannot choose, and must use webservice.</p> |
| <h2 id="how-to-use">How to use</h2> |
| <h3 id="dependencies">Dependencies</h3> |
| <p>Starting from Dubbo 3, the Webservice protocol is no longer embedded in Dubbo, and an independent <a href="https://dubbo.apache.org/zh-cn/download/spi-extensions/#dubbo-rpc">module</a> needs to be introduced separately.</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;dependency&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;groupId&gt;</span>org.apache.dubbo.extensions<span style="color:#268bd2">&lt;/groupId&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;artifactId&gt;</span>dubbo-rpc-webservice<span style="color:#268bd2">&lt;/artifactId&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;version&gt;</span>1.0.0<span style="color:#268bd2">&lt;/version&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;/dependency&gt;</span> |
| </span></span></code></pre></div><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;dependency&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;groupId&gt;</span>org.apache.cxf<span style="color:#268bd2">&lt;/groupId&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;artifactId&gt;</span>cxf-rt-frontend-simple<span style="color:#268bd2">&lt;/artifactId&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;version&gt;</span>2.6.1<span style="color:#268bd2">&lt;/version&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;/dependency&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;dependency&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;groupId&gt;</span>org.apache.cxf<span style="color:#268bd2">&lt;/groupId&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;artifactId&gt;</span>cxf-rt-transports-http<span style="color:#268bd2">&lt;/artifactId&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;version&gt;</span>2.6.1<span style="color:#268bd2">&lt;/version&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;/dependency&gt;</span> |
| </span></span></code></pre></div><h3 id="configuration-protocol">Configuration protocol</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-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:protocol</span> name=<span style="color:#2aa198">&#34;webservice&#34;</span> port=<span style="color:#2aa198">&#34;8080&#34;</span> server=<span style="color:#2aa198">&#34;jetty&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><h3 id="configure-the-default-protocol">Configure the default protocol</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-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:provider</span> protocol=<span style="color:#2aa198">&#34;webservice&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><h3 id="configure-service-protocol">Configure service protocol</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-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:service</span> protocol=<span style="color:#2aa198">&#34;webservice&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><h3 id="multiport">Multiport</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-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:protocol</span> id=<span style="color:#2aa198">&#34;webservice1&#34;</span> name=<span style="color:#2aa198">&#34;webservice&#34;</span> port=<span style="color:#2aa198">&#34;8080&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:protocol</span> id=<span style="color:#2aa198">&#34;webservice2&#34;</span> name=<span style="color:#2aa198">&#34;webservice&#34;</span> port=<span style="color:#2aa198">&#34;8081&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><h3 id="direct-connection">direct connection</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-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:reference</span> id=<span style="color:#2aa198">&#34;helloService&#34;</span> interface=<span style="color:#2aa198">&#34;HelloWorld&#34;</span> url=<span style="color:#2aa198">&#34;webservice://10.20.153.10:8080/com.foo.HelloWorld&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>###WSDL</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>http://10.20.153.10:8080/com.foo.HelloWorld?wsdl |
| </span></span></code></pre></div><h3 id="jetty-server-default">Jetty Server (default)</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-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:protocol</span> ... server=<span style="color:#2aa198">&#34;jetty&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><h3 id="servlet-bridge-server-recommended">Servlet Bridge Server (recommended)</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-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;dubbo:protocol</span> ... server=<span style="color:#2aa198">&#34;servlet&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><h3 id="configure-dispatcherservlet">Configure DispatcherServlet</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-xml" data-lang="xml"><span style="display:flex;"><span><span style="color:#268bd2">&lt;servlet&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;servlet-name&gt;</span>dubbo<span style="color:#268bd2">&lt;/servlet-name&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;servlet-class&gt;</span>org.apache.dubbo.remoting.http.servlet.DispatcherServlet<span style="color:#268bd2">&lt;/servlet-class&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;load-on-startup&gt;</span>1<span style="color:#268bd2">&lt;/load-on-startup&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;/servlet&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;servlet-mapping&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;servlet-name&gt;</span>dubbo<span style="color:#268bd2">&lt;/servlet-name&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;url-pattern&gt;</span>/*<span style="color:#268bd2">&lt;/url-pattern&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;/servlet-mapping&gt;</span> |
| </span></span></code></pre></div><blockquote> |
| <p>If a servlet is used to dispatch the request</p> |
| <ul> |
| <li>The protocol port <code>&lt;dubbo:protocol port=&quot;8080&quot; /&gt;</code> must be the same as the port of the servlet container.</li> |
| <li>The context path of the protocol <code>&lt;dubbo:protocol contextpath=&quot;foo&quot; /&gt;</code> must be the same as the context path of the servlet application.</li> |
| </ul> |
| </blockquote></description></item><item><title>Docs3-V2: Memcached protocol</title><link>https://dubbo.apache.org/en/docs3-v2/java-sdk/reference-manual/protocol/memcached/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://dubbo.apache.org/en/docs3-v2/java-sdk/reference-manual/protocol/memcached/</guid><description> |
| <h2 id="feature-description">Feature description</h2> |
| <p>RPC protocol implemented based on memcached. <code>2.3.0</code> and above are supported.</p> |
| <p><a href="http://memcached.org/">Memcached</a> is an efficient KV cache server.</p> |
| <h2 id="scenes-to-be-used">scenes to be used</h2> |
| <p>Relieve database pressure, improve interaction speed, etc.</p> |
| <h2 id="how-to-use">How to use</h2> |
| <h3 id="import-dependencies">Import dependencies</h3> |
| <p>Starting from Dubbo 3, the Memcached protocol is no longer embedded in Dubbo, and an independent <a href="https://dubbo.apache.org/zh-cn/download/spi-extensions/#dubbo-rpc">module</a> needs to be introduced separately.</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;dependency&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;groupId&gt;</span>org.apache.dubbo.extensions<span style="color:#268bd2">&lt;/groupId&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;artifactId&gt;</span>dubbo-rpc-memcached<span style="color:#268bd2">&lt;/artifactId&gt;</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#268bd2">&lt;version&gt;</span>1.0.0<span style="color:#268bd2">&lt;/version&gt;</span> |
| </span></span><span style="display:flex;"><span><span style="color:#268bd2">&lt;/dependency&gt;</span> |
| </span></span></code></pre></div><h3 id="register-the-address-of-memcached-service">Register the address of memcached service</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-java" data-lang="java"><span style="display:flex;"><span>RegistryFactory registryFactory <span style="color:#719e07">=</span> ExtensionLoader.getExtensionLoader(RegistryFactory.class).getAdaptiveExtension(); |
| </span></span><span style="display:flex;"><span>Registry registry <span style="color:#719e07">=</span> registryFactory.getRegistry(URL.valueOf(<span style="color:#2aa198">&#34;zookeeper://10.20.153.10:2181&#34;</span>)); |
| </span></span><span style="display:flex;"><span>registry.register(URL.valueOf(<span style="color:#2aa198">&#34;memcached://10.20.153.11/com.foo.BarService?category=providers&amp;dynamic=false&amp;application=foo&amp;group=member&amp;loadbalance=consistenthash&#34;</span>)); |
| </span></span></code></pre></div><h3 id="referenced-on-the-client-side">Referenced on the client side</h3> |
| <p><strong>Do not need to be aware of the address of Memcached</strong></p> |
| <p>use on client side</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:reference</span> id=<span style="color:#2aa198">&#34;cache&#34;</span> interface=<span style="color:#2aa198">&#34;java.util.Map&#34;</span> group=<span style="color:#2aa198">&#34;member&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>Or point-to-point direct connection</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:reference</span> id=<span style="color:#2aa198">&#34;cache&#34;</span> interface=<span style="color:#2aa198">&#34;java.util.Map&#34;</span> url=<span style="color:#2aa198">&#34;memcached://10.20.153.10:11211&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>You can also use a custom interface</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:reference</span> id=<span style="color:#2aa198">&#34;cache&#34;</span> interface=<span style="color:#2aa198">&#34;com.foo.CacheService&#34;</span> url=<span style="color:#2aa198">&#34;memcached://10.20.153.10:11211&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>Where &ldquo;p:xxx&rdquo; is the standard p tag of spring</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:reference</span> id=<span style="color:#2aa198">&#34;cache&#34;</span> interface=<span style="color:#2aa198">&#34;com.foo.CacheService&#34;</span> url=<span style="color:#2aa198">&#34;memcached://10.20.153.10:11211&#34;</span> p:set=<span style="color:#2aa198">&#34;putFoo&#34;</span> p:get=<span style="color:#2aa198">&#34;getFoo&#34;</span> p:delete=<span style="color:#2aa198">&#34; removeFoo&#34;</span> <span style="color:#268bd2">/&gt;</span> |
| </span></span></code></pre></div><p>If the method name is different from the standard method name of memcached, you need to configure the mapping relationship;</p> |
| <p>The method name is recommended to be the same as the standard method name of memcached, namely: get(key), set(key, value), delete(key).</p></description></item></channel></rss> |
