blob: a1d0fdd1b38a297e8cdef0f5c89b24e811d60545 [file] [log] [blame]
刘洪青6266f992017-05-15 21:21:03 +08001<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tribes - The Tomcat Cluster Communication Module (7.0.77) - Apache Tribes - Introduction</title><meta name="author" content="Filip Hanik"><style type="text/css" media="print">
2 .noPrint {display: none;}
3 td#mainBody {width: 100%;}
4</style><style type="text/css">
5code {background-color:rgb(224,255,255);padding:0 0.1em;}
6code.attributeName, code.propertyName {background-color:transparent;}
7
8
9table {
10 border-collapse: collapse;
11 text-align: left;
12}
13table *:not(table) {
14 /* Prevent border-collapsing for table child elements like <div> */
15 border-collapse: separate;
16}
17
18th {
19 text-align: left;
20}
21
22
23div.codeBox pre code, code.attributeName, code.propertyName, code.noHighlight, .noHighlight code {
24 background-color: transparent;
25}
26div.codeBox {
27 overflow: auto;
28 margin: 1em 0;
29}
30div.codeBox pre {
31 margin: 0;
32 padding: 4px;
33 border: 1px solid #999;
34 border-radius: 5px;
35 background-color: #eff8ff;
36 display: table; /* To prevent <pre>s from taking the complete available width. */
37 /*
38 When it is officially supported, use the following CSS instead of display: table
39 to prevent big <pre>s from exceeding the browser window:
40 max-width: available;
41 width: min-content;
42 */
43}
44
45div.codeBox pre.wrap {
46 white-space: pre-wrap;
47}
48
49
50table.defaultTable tr, table.detail-table tr {
51 border: 1px solid #CCC;
52}
53
54table.defaultTable tr:nth-child(even), table.detail-table tr:nth-child(even) {
55 background-color: #FAFBFF;
56}
57
58table.defaultTable tr:nth-child(odd), table.detail-table tr:nth-child(odd) {
59 background-color: #EEEFFF;
60}
61
62table.defaultTable th, table.detail-table th {
63 background-color: #88b;
64 color: #fff;
65}
66
67table.defaultTable th, table.defaultTable td, table.detail-table th, table.detail-table td {
68 padding: 5px 8px;
69}
70
71
72p.notice {
73 border: 1px solid rgb(255, 0, 0);
74 background-color: rgb(238, 238, 238);
75 color: rgb(0, 51, 102);
76 padding: 0.5em;
77 margin: 1em 2em 1em 1em;
78}
79</style></head><body bgcolor="#ffffff" text="#000000" link="#525D76" alink="#525D76" vlink="#525D76"><table border="0" width="100%" cellspacing="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img src="../images/tomcat.gif" align="right" alt="Apache Tomcat" border="0"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 7</font></h1><font face="arial,helvetica,sanserif">Version 7.0.77, Mar 28 2017</font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="../images/asf-logo.svg" align="right" alt="Apache Logo" border="0" style="width: 266px;height: 83px;"></a></td></tr></table><table border="0" width="100%" cellspacing="4"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><tr><!--LEFT SIDE NAVIGATION--><td width="20%" valign="top" nowrap class="noPrint"><p><strong>Links</strong></p><ul><li><a href="../index.html">Docs Home</a></li><li><a href="introduction.html">Tribes Docs Home</a></li><li><a href="http://wiki.apache.org/tomcat/FAQ">FAQ</a></li><li><a href="#comments_section">User Comments</a></li></ul><p><strong>User Guide</strong></p><ul><li><a href="introduction.html">1) Introduction</a></li><li><a href="setup.html">2) Setup</a></li><li><a href="faq.html">3) FAQ</a></li></ul><p><strong>Reference</strong></p><ul><li><a href="../api/org/apache/catalina/tribes/package-summary.html">JavaDoc</a></li></ul><p><strong>Apache Tribes Development</strong></p><ul><li><a href="membership.html">Membership</a></li><li><a href="transport.html">Transport</a></li><li><a href="interceptors.html">Interceptors</a></li><li><a href="status.html">Status</a></li><li><a href="developers.html">Developers</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left" id="mainBody"><h1>Apache Tribes - Introduction</h1><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Table of Contents"><!--()--></a><a name="Table_of_Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote>
Hongqing Liufd5ee812014-05-10 16:32:51 +080080<ul><li><a href="#Quick_Start">Quick Start</a></li><li><a href="#What_is_Tribes">What is Tribes</a></li><li><a href="#Why_another_messaging_framework">Why another messaging framework</a></li><li><a href="#Feature_Overview">Feature Overview</a></li><li><a href="#Where_can_I_get_Tribes">Where can I get Tribes</a></li></ul>
81</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Quick Start"><!--()--></a><a name="Quick_Start"><strong>Quick Start</strong></a></font></td></tr><tr><td><blockquote>
82
83 <p>Apache Tribes is a group or peer-to-peer communication framework that enables you to easily connect
84 your remote objects to communicate with each other.
85 </p>
86 <ul>
87 <li>Import: <code>org.apache.catalina.tribes.Channel</code></li>
88 <li>Import: <code>org.apache.catalina.tribes.Member</code></li>
89 <li>Import: <code>org.apache.catalina.tribes.MembershipListener</code></li>
90 <li>Import: <code>org.apache.catalina.tribes.ChannelListener</code></li>
91 <li>Import: <code>org.apache.catalina.tribes.group.GroupChannel</code></li>
92 <li>Create a class that implements: <code>org.apache.catalina.tribes.ChannelListener</code></li>
93 <li>Create a class that implements: <code>org.apache.catalina.tribes.MembershipListener</code></li>
94 <li>Simple class to demonstrate how to send a message:
刘洪青6266f992017-05-15 21:21:03 +080095 <div class="codeBox"><pre><code>
Hongqing Liufd5ee812014-05-10 16:32:51 +080096 //create a channel
97 Channel myChannel = new GroupChannel();
98
99 //create my listeners
100 ChannelListener msgListener = new MyMessageListener();
101 MembershipListener mbrListener = new MyMemberListener();
102
103 //attach the listeners to the channel
104 myChannel.addMembershipListener(mbrListener);
105 myChannel.addChannelListener(msgListener);
106
107 //start the channel
108 myChannel.start(Channel.DEFAULT);
109
110 //create a message to be sent, message must implement java.io.Serializable
111 //for performance reasons you probably want them to implement java.io.Externalizable
112 Serializable myMsg = new MyMessage();
113
114 //retrieve my current members
115 Member[] group = myChannel.getMembers();
116
117 //send the message
刘洪青6266f992017-05-15 21:21:03 +0800118 myChannel.send(group,myMsg,Channel.SEND_OPTIONS_DEFAULT);
119 </code></pre></div>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800120 </li>
121 </ul>
122 <p>
123 Simple yeah? There is a lot more to Tribes than we have shown, hopefully the docs will be able
124 to explain more to you. Remember, that we are always interested in suggestions, improvements, bug fixes
125 and anything that you think would help this project.
126 </p>
127 <p>
128 Note: Tribes is currently built for JDK1.5, you can run on JDK1.4 by a small modifications to locks used from the <code>java.util.concurrent</code> package.
129 </p>
130</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="What is Tribes"><!--()--></a><a name="What_is_Tribes"><strong>What is Tribes</strong></a></font></td></tr><tr><td><blockquote>
131 <p>
132 Tribes is a messaging framework with group communication abilities. Tribes allows you to send and receive
133 messages over a network, it also allows for dynamic discovery of other nodes in the network.<br>
134 And that is the short story, it really is as simple as that. What makes Tribes useful and unique will be
135 described in the section below.<br>
136 </p>
137 <p>
138 The Tribes module was started early 2006 and a small part of the code base comes from the clustering module
139 that has been existing since 2003 or 2004.
140 The current cluster implementation has several short comings and many workarounds were created due
141 to the complexity in group communication. Long story short, what should have been two modules a long time
142 ago, will be now. Tribes takes out the complexity of messaging from the replication module and becomes
143 a fully independent and highly flexible group communication module.<br>
144 </p>
145 <p>
146 In Tomcat the old <code>modules/cluster</code> has now become <code>modules/groupcom</code>(Tribes) and
147 <code>modules/ha</code> (replication). This will allow development to proceed and let the developers
148 focus on the issues they are actually working on rather than getting boggled down in details of a module
149 they are not interested in. The understanding is that both communication and replication are complex enough,
150 and when trying to develop them in the same module, well you know, it becomes a cluster :)<br>
151 </p>
152 <p>
153 Tribes allows for guaranteed messaging, and can be customized in many ways. Why is this important?<br>
154 Well, you as a developer want to know that the messages you are sending are reaching their destination.
155 More than that, if a message doesn't reach its destination, the application on top of Tribes will be notified
156 that the message was never sent, and what node it failed.
157 </p>
158
159</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Why another messaging framework"><!--()--></a><a name="Why_another_messaging_framework"><strong>Why another messaging framework</strong></a></font></td></tr><tr><td><blockquote>
160 <p>
161 I am a big fan of reusing code and would never dream of developing something if someone else has already
162 done it and it was available to me and the community I try to serve.<br>
163 When I did my research to improve the clustering module I was constantly faced with a few obstacles:<br>
164 1. The framework wasn't flexible enough<br>
165 2. The framework was licensed in a way that neither I nor the community could use it<br>
166 3. Several features that I needed were missing<br>
167 4. Messaging was guaranteed, but no feedback was reported to me<br>
168 5. The semantics of my message delivery had to be configured before runtime<br>
169 And the list continues...
170 </p>
171 <p>
172 So I came up with Tribes, to address these issues and other issues that came along.
173 When designing Tribes I wanted to make sure I didn't lose any of the flexibility and
174 delivery semantics that the existing frameworks already delivered. The goal was to create a framework
175 that could do everything that the others already did, but to provide more flexibility for the application
176 developer. In the next section will give you the high level overview of what features tribes offers or will offer.
177 </p>
178</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Feature Overview"><!--()--></a><a name="Feature_Overview"><strong>Feature Overview</strong></a></font></td></tr><tr><td><blockquote>
179 <p>
180 To give you an idea of the feature set I will list it out here.
181 Some of the features are not yet completed, if that is the case they are marked accordingly.
182 </p>
183 <p>
184 <b>Pluggable modules</b><br>
185 Tribes is built using interfaces. Any of the modules or components that are part of Tribes can be swapped out
186 to customize your own Tribes implementation.
187 </p>
188 <p>
189 <b>Guaranteed Messaging</b><br>
刘洪青6266f992017-05-15 21:21:03 +0800190 In the default implementation of Tribes uses TCP or UDP for messaging. TCP already has guaranteed message delivery
Hongqing Liufd5ee812014-05-10 16:32:51 +0800191 and flow control built in. I believe that the performance of Java TCP, will outperform an implementation of
刘洪青6266f992017-05-15 21:21:03 +0800192 Java/UDP/flow-control/message guarantee since the logic happens further down the stack. UDP messaging has been added in for
193 sending messages over UDP instead of TCP when desired. The same guarantee scenarios as described below are still available
194 over UDP, however, when a UDP message is lost, it's considered failed.<br>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800195 Tribes supports both non-blocking and blocking IO operations. The recommended setting is to use non blocking
196 as it promotes better parallelism when sending and receiving messages. The blocking implementation is available
197 for those platforms where NIO is still a trouble child.
198 </p>
199 <p>
200 <b>Different Guarantee Levels</b><br>
201 There are three different levels of delivery guarantee when a message is sent.<br>
202 <ol>
203 <li>IO Based send guarantee. - fastest, least reliable<br>
204 This means that Tribes considers the message transfer to be successful
205 if the message was sent to the socket send buffer and accepted.<br>
206 On blocking IO, this would be <code>socket.getOutputStream().write(msg)</code><br>
207 On non blocking IO, this would be <code>socketChannel.write()</code>, and the buffer byte buffer gets emptied
208 followed by a <code>socketChannel.read()</code> to ensure the channel still open.
209 The <code>read()</code> has been added since <code>write()</code> will succeed if the connection has been "closed"
210 when using NIO.
211 </li>
212 <li>ACK based. - recommended, guaranteed delivery<br>
213 When the message has been received on a remote node, an ACK is sent back to the sender,
214 indicating that the message was received successfully.
215 </li>
216 <li>SYNC_ACK based. - guaranteed delivery, guaranteed processed, slowest<br>
217 When the message has been received on a remote node, the node will process
218 the message and if the message was processed successfully, an ACK is sent back to the sender
219 indicating that the message was received and processed successfully.
220 If the message was received, but processing it failed, an ACK_FAIL will be sent back
221 to the sender. This is a unique feature that adds an incredible amount value to the application
222 developer. Most frameworks here will tell you that the message was delivered, and the application
223 developer has to build in logic on whether the message was actually processed properly by the application
224 on the remote node. If configured, Tribes will throw an exception when it receives an ACK_FAIL
225 and associate that exception with the member that didn't process the message.
226 </li>
227 </ol>
228 You can of course write even more sophisticated guarantee levels, and some of them will be mentioned later on
229 in the documentation. One mentionable level would be a 2-Phase-Commit, where the remote applications don't receive
230 the message until all nodes have received the message. Sort of like a all-or-nothing protocol.
231 </p>
232 <p>
233 <b>Per Message Delivery Attributes</b><br>
234 Perhaps the feature that makes Tribes stand out from the crowd of group communication frameworks.
235 Tribes enables you to send to decide what delivery semantics a message transfer should have on a per
236 message basis. Meaning, that your messages are not delivered based on some static configuration
237 that remains fixed after the message framework has been started.<br>
238 To give you an example of how powerful this feature is, I'll try to illustrate it with a simple example.
刘洪青6266f992017-05-15 21:21:03 +0800239 Imagine you need to send 10 different messages, you could send them the following way:
240 <div class="codeBox"><pre><code>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800241 Message_1 - asynchronous and fast, no guarantee required, fire and forget
242 Message_2 - all-or-nothing, either all receivers get it, or none.
243 Message_3 - encrypted and SYNC_ACK based
244 Message_4 - asynchronous, SYNC_ACK and call back when the message is processed on the remote nodes
245 Message_5 - totally ordered, this message should be received in the same order on all nodes that have been
246 send totally ordered
247 Message_6 - asynchronous and totally ordered
248 Message_7 - RPC message, send a message, wait for all remote nodes to reply before returning
249 Message_8 - RPC message, wait for the first reply
250 Message_9 - RPC message, asynchronous, don't wait for a reply, collect them via a callback
251 Message_10- sent to a member that is not part of this group
刘洪青6266f992017-05-15 21:21:03 +0800252 </code></pre></div>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800253 As you can imagine by now, these are just examples. The number of different semantics you can apply on a
254 per-message-basis is almost limitless. Tribes allows you to set up to 28 different on a message
255 and then configure Tribes to what flag results in what action on the message.<br>
256 Imagine a shared transactional cache, probably &gt;90% are reads, and the dirty reads should be completely
257 unordered and delivered as fast as possible. But transactional writes on the other hand, have to
258 be ordered so that no cache gets corrupted. With tribes you would send the write messages totally ordered,
259 while the read messages you simple fire to achieve highest throughput.<br>
260 There are probably better examples on how this powerful feature can be used, so use your imagination and
261 your experience to think of how this could benefit you in your application.
262 </p>
263 <p>
264 <b>Interceptor based message processing</b><br>
265 Tribes uses a customizable interceptor stack to process messages that are sent and received.<br>
266 <i>So what, all frameworks have this!</i><br>
267 Yes, but in Tribes interceptors can react to a message based on the per-message-attributes
268 that are sent runtime. Meaning, that if you add a encryption interceptor that encrypts message
269 you can decide if this interceptor will encrypt all messages, or only certain messages that are decided
270 by the applications running on top of Tribes.<br>
271 This is how Tribes is able to send some messages totally ordered and others fire and forget style
272 like the example above.<br>
273 The number of interceptors that are available will keep growing, and we would appreciate any contributions
274 that you might have.
275 </p>
276 <p>
277 <b>Threadless Interceptor stack</b>
278 The interceptor don't require any separate threads to perform their message manipulation.<br>
279 Messages that are sent will piggy back on the thread that is sending them all the way through transmission.
280 The exception is the <code>MessageDispatchInterceptor</code> that will queue up the message
281 and send it on a separate thread for asynchronous message delivery.
282 Messages received are controlled by a thread pool in the <code>receiver</code> component.<br>
283 The channel object can send a <code>heartbeat()</code> through the interceptor stack to allow
284 for timeouts, cleanup and other events.<br>
285 The <code>MessageDispatchInterceptor</code> is the only interceptor that is configured by default.
286 </p>
287 <p>
288 <b>Parallel Delivery</b><br>
289 Tribes support parallel delivery of messages. Meaning that node_A could send three messages to node_B in
290 parallel. This feature becomes useful when sending messages with different delivery semantics.
291 Otherwise if Message_1 was sent totally ordered, Message_2 would have to wait for that message to complete.<br>
292 Through NIO, Tribes is also able to send a message to several receivers at the same time on the same thread.
293 </p>
294 <p>
295 <b>Silent Member Messaging</b><br>
296 With Tribes you are able to send messages to members that are not in your group.
297 So by default, you can already send messages over a wide area network, even though the dynamic discover
298 module today is limited to local area networks by using multicast for dynamic node discovery.
299 Of course, the membership component will be expanded to support WAN memberships in the future.
300 But this is very useful, when you want to hide members from the rest of the group and only communicate with them
301 </p>
302</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Where can I get Tribes"><!--()--></a><a name="Where_can_I_get_Tribes"><strong>Where can I get Tribes</strong></a></font></td></tr><tr><td><blockquote>
303 <p>
刘洪青6266f992017-05-15 21:21:03 +0800304 Tribes ships as a module with Tomcat, and is released as part of the Apache Tomcat release.
Hongqing Liufd5ee812014-05-10 16:32:51 +0800305 </p>
306
307
刘洪青6266f992017-05-15 21:21:03 +0800308</blockquote></td></tr></table></td></tr><tr class="noPrint"><td width="20%" valign="top" nowrap class="noPrint"></td><td width="80%" valign="top" align="left"><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="comments_section" id="comments_section"><strong>Comments</strong></a></font></td></tr><tr><td><blockquote><p class="notice"><strong>Notice: </strong>This comments section collects your suggestions
309 on improving documentation for Apache Tomcat.<br><br>
310 If you have trouble and need help, read
311 <a href="http://tomcat.apache.org/findhelp.html">Find Help</a> page
312 and ask your question on the tomcat-users
313 <a href="http://tomcat.apache.org/lists.html">mailing list</a>.
314 Do not ask such questions here. This is not a Q&amp;A section.<br><br>
315 The Apache Comments System is explained <a href="../comments.html">here</a>.
316 Comments may be removed by our moderators if they are either
317 implemented or considered invalid/off-topic.</p><script type="text/javascript"><!--//--><![CDATA[//><!--
318 var comments_shortname = 'tomcat';
319 var comments_identifier = 'http://tomcat.apache.org/tomcat-7.0-doc/tribes/introduction.html';
320 (function(w, d) {
321 if (w.location.hostname.toLowerCase() == "tomcat.apache.org") {
322 d.write('<div id="comments_thread"><\/div>');
323 var s = d.createElement('script');
324 s.type = 'text/javascript';
325 s.async = true;
326 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
327 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
328 }
329 else {
330 d.write('<div id="comments_thread"><strong>Comments are disabled for this page at the moment.<\/strong><\/div>');
331 }
332 })(window, document);
333 //--><!]]></script></blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
334 Copyright &copy; 1999-2017, Apache Software Foundation
Hongqing Liufd5ee812014-05-10 16:32:51 +0800335 </em></font></div></td></tr></table></body></html>