Subversion Repositories Integrator Subversion

Rev

Details | Last modification | View Log | RSS feed

Rev Author Line No. Line
771 blopes 1 
<!DOCTYPE html SYSTEM "about:legacy-compat">
2 
<html lang="en"><head><META http-equiv="Content-Type" content="text/html; charset=UTF-8"><link href="../images/docs-stylesheet.css" rel="stylesheet" type="text/css"><title>Apache Tribes - The Tomcat Cluster Communication Module (9.0.112) - Apache Tribes - Introduction</title></head><body><div id="wrapper"><header><div id="header"><div><div><div class="logo noPrint"><a href="https://tomcat.apache.org/"><img alt="Tomcat Home" src="../images/tomcat.png"></a></div><div style="height: 1px;"></div><div class="asfLogo noPrint"><a href="https://www.apache.org/" target="_blank"><img src="../images/asf-logo.svg" alt="The Apache Software Foundation" style="width: 266px; height: 83px;"></a></div><h1>Apache Tribes - The Tomcat Cluster Communication Module</h1><div class="versionInfo">
3 
            Version 9.0.112,
4 
            <time datetime="2025-11-06">Nov 6 2025</time></div><div style="height: 1px;"></div><div style="clear: left;"></div></div></div></div></header><div id="middle"><div><div id="mainLeft" class="noprint"><div><nav><div><h2>Links</h2><ul><li><a href="../index.html">Docs Home</a></li><li><a href="introduction.html">Tribes Docs Home</a></li><li><a href="https://cwiki.apache.org/confluence/display/TOMCAT/FAQ">FAQ</a></li><li><a href="#comments_section">User Comments</a></li></ul></div><div><h2>User Guide</h2><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></div><div><h2>Reference</h2><ul><li><a href="../api/org/apache/catalina/tribes/package-summary.html">JavaDoc</a></li></ul></div><div><h2>Apache Tribes Development</h2><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></div></nav></div></div><div id="mainRight"><div id="content"><h2>Apache Tribes - Introduction</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
5 
<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>
6 
</div><h3 id="Quick_Start">Quick Start</h3><div class="text">
7 
 
8 
  <p>Apache Tribes is a group or peer-to-peer communication framework that enables you to easily connect
9 
     your remote objects to communicate with each other.
10 
  </p>
11 
  <ul>
12 
    <li>Import: <code>org.apache.catalina.tribes.Channel</code></li>
13 
    <li>Import: <code>org.apache.catalina.tribes.Member</code></li>
14 
    <li>Import: <code>org.apache.catalina.tribes.MembershipListener</code></li>
15 
    <li>Import: <code>org.apache.catalina.tribes.ChannelListener</code></li>
16 
    <li>Import: <code>org.apache.catalina.tribes.group.GroupChannel</code></li>
17 
    <li>Create a class that implements: <code>org.apache.catalina.tribes.ChannelListener</code></li>
18 
    <li>Create a class that implements: <code>org.apache.catalina.tribes.MembershipListener</code></li>
19 
    <li>Simple class to demonstrate how to send a message:
20 
      <div class="codeBox"><pre><code>//create a channel
21 
Channel myChannel = new GroupChannel();
22 
 
23 
//create my listeners
24 
ChannelListener msgListener = new MyMessageListener();
25 
MembershipListener mbrListener = new MyMemberListener();
26 
 
27 
//attach the listeners to the channel
28 
myChannel.addMembershipListener(mbrListener);
29 
myChannel.addChannelListener(msgListener);
30 
 
31 
//start the channel
32 
myChannel.start(Channel.DEFAULT);
33 
 
34 
//create a message to be sent, message must implement java.io.Serializable
35 
//for performance reasons you probably want them to implement java.io.Externalizable
36 
Serializable myMsg = new MyMessage();
37 
 
38 
//retrieve my current members
39 
Member[] group = myChannel.getMembers();
40 
 
41 
//send the message
42 
myChannel.send(group,myMsg,Channel.SEND_OPTIONS_DEFAULT);</code></pre></div>
43 
    </li>
44 
  </ul>
45 
  <p>
46 
      Simple yeah? There is a lot more to Tribes than we have shown, hopefully the docs will be able
47 
      to explain more to you. Remember, that we are always interested in suggestions, improvements, bug fixes
48 
      and anything that you think would help this project.
49 
  </p>
50 
</div><h3 id="What_is_Tribes">What is Tribes</h3><div class="text">
51 
  <p>
52 
    Tribes is a messaging framework with group communication abilities. Tribes allows you to send and receive
53 
    messages over a network, it also allows for dynamic discovery of other nodes in the network.<br>
54 
    And that is the short story, it really is as simple as that. What makes Tribes useful and unique will be
55 
    described in the section below.<br>
56 
  </p>
57 
  <p>
58 
    The Tribes module was started early 2006 and a small part of the code base comes from the clustering module
59 
    that has been existing since 2003 or 2004.
60 
    The current cluster implementation has several short comings and many workarounds were created due
61 
    to the complexity in group communication. Long story short, what should have been two modules a long time
62 
    ago, will be now. Tribes takes out the complexity of messaging from the replication module and becomes
63 
    a fully independent and highly flexible group communication module.<br>
64 
  </p>
65 
  <p>
66 
    In Tomcat the old <code>modules/cluster</code> has now become <code>modules/groupcom</code>(Tribes) and
67 
    <code>modules/ha</code> (replication). This will allow development to proceed and let the developers
68 
    focus on the issues they are actually working on rather than getting boggled down in details of a module
69 
    they are not interested in. The understanding is that both communication and replication are complex enough,
70 
    and when trying to develop them in the same module, well you know, it becomes a cluster :)<br>
71 
  </p>
72 
  <p>
73 
    Tribes allows for guaranteed messaging, and can be customized in many ways. Why is this important?<br>
74 
    Well, you as a developer want to know that the messages you are sending are reaching their destination.
75 
    More than that, if a message doesn't reach its destination, the application on top of Tribes will be notified
76 
    that the message was never sent, and what node it failed.
77 
  </p>
78 
 
79 
</div><h3 id="Why_another_messaging_framework">Why another messaging framework</h3><div class="text">
80 
  <p>
81 
    I am a big fan of reusing code and would never dream of developing something if someone else has already
82 
    done it and it was available to me and the community I try to serve.<br>
83 
    When I did my research to improve the clustering module I was constantly faced with a few obstacles:<br>
84 
    1. The framework wasn't flexible enough<br>
85 
    2. The framework was licensed in a way that neither I nor the community could use it<br>
86 
    3. Several features that I needed were missing<br>
87 
    4. Messaging was guaranteed, but no feedback was reported to me<br>
88 
    5. The semantics of my message delivery had to be configured before runtime<br>
89 
    And the list continues...
90 
  </p>
91 
  <p>
92 
    So I came up with Tribes, to address these issues and other issues that came along.
93 
    When designing Tribes I wanted to make sure I didn't lose any of the flexibility and
94 
    delivery semantics that the existing frameworks already delivered. The goal was to create a framework
95 
    that could do everything that the others already did, but to provide more flexibility for the application
96 
    developer. In the next section will give you the high level overview of what features tribes offers or will offer.
97 
  </p>
98 
</div><h3 id="Feature_Overview">Feature Overview</h3><div class="text">
99 
  <p>
100 
    To give you an idea of the feature set I will list it out here.
101 
    Some of the features are not yet completed, if that is the case they are marked accordingly.
102 
  </p>
103 
  <p>
104 
    <b>Pluggable modules</b><br>
105 
    Tribes is built using interfaces. Any of the modules or components that are part of Tribes can be swapped out
106 
    to customize your own Tribes implementation.
107 
  </p>
108 
  <p>
109 
    <b>Guaranteed Messaging</b><br>
110 
    In the default implementation of Tribes uses TCP or UDP for messaging. TCP already has guaranteed message delivery
111 
    and flow control built in. I believe that the performance of Java TCP, will outperform an implementation of
112 
    Java/UDP/flow-control/message guarantee since the logic happens further down the stack. UDP messaging has been added in for
113 
    sending messages over UDP instead of TCP when desired. The same guarantee scenarios as described below are still available
114 
    over UDP, however, when a UDP message is lost, it's considered failed.<br>
115 
    Tribes supports both non-blocking and blocking IO operations. The recommended setting is to use non blocking
116 
    as it promotes better parallelism when sending and receiving messages. The blocking implementation is available
117 
    for those platforms where NIO is still a trouble child.
118 
  </p>
119 
  <p>
120 
    <b>Different Guarantee Levels</b><br>
121 
    There are three different levels of delivery guarantee when a message is sent.
122 
  </p>
123 
    <ol>
124 
      <li>IO Based send guarantee. - fastest, least reliable<br>
125 
          This means that Tribes considers the message transfer to be successful
126 
          if the message was sent to the socket send buffer and accepted.<br>
127 
          On blocking IO, this would be <code>socket.getOutputStream().write(msg)</code><br>
128 
          On non blocking IO, this would be <code>socketChannel.write()</code>, and the buffer byte buffer gets emptied
129 
          followed by a <code>socketChannel.read()</code> to ensure the channel still open.
130 
          The <code>read()</code> has been added since <code>write()</code> will succeed if the connection has been "closed"
131 
          when using NIO.
132 
      </li>
133 
      <li>ACK based. - recommended, guaranteed delivery<br>
134 
          When the message has been received on a remote node, an ACK is sent back to the sender,
135 
          indicating that the message was received successfully.
136 
      </li>
137 
      <li>SYNC_ACK based. - guaranteed delivery, guaranteed processed, slowest<br>
138 
          When the message has been received on a remote node, the node will process
139 
          the message and if the message was processed successfully, an ACK is sent back to the sender
140 
          indicating that the message was received and processed successfully.
141 
          If the message was received, but processing it failed, an ACK_FAIL will be sent back
142 
          to the sender. This is a unique feature that adds an incredible amount value to the application
143 
          developer. Most frameworks here will tell you that the message was delivered, and the application
144 
          developer has to build in logic on whether the message was actually processed properly by the application
145 
          on the remote node. If configured, Tribes will throw an exception when it receives an ACK_FAIL
146 
          and associate that exception with the member that didn't process the message.
147 
      </li>
148 
    </ol>
149 
  <p>
150 
    You can of course write even more sophisticated guarantee levels, and some of them will be mentioned later on
151 
    in the documentation. One mentionable level would be a 2-Phase-Commit, where the remote applications don't receive
152 
    the message until all nodes have received the message. Sort of like a all-or-nothing protocol.
153 
  </p>
154 
  <p>
155 
    <b>Per Message Delivery Attributes</b><br>
156 
    Perhaps the feature that makes Tribes stand out from the crowd of group communication frameworks.
157 
    Tribes enables you to send to decide what delivery semantics a message transfer should have on a per
158 
    message basis. Meaning, that your messages are not delivered based on some static configuration
159 
    that remains fixed after the message framework has been started.<br>
160 
    To give you an example of how powerful this feature is, I'll try to illustrate it with a simple example.
161 
    Imagine you need to send 10 different messages, you could send them the following way:
162 
  </p>
163 
    <div class="codeBox"><pre><code>Message_1 - asynchronous and fast, no guarantee required, fire and forget
164 
Message_2 - all-or-nothing, either all receivers get it, or none.
165 
Message_3 - encrypted and SYNC_ACK based
166 
Message_4 - asynchronous, SYNC_ACK and call back when the message is processed on the remote nodes
167 
Message_5 - totally ordered, this message should be received in the same order on all nodes that have been
168 
            send totally ordered
169 
Message_6 - asynchronous and totally ordered
170 
Message_7 - RPC message, send a message, wait for all remote nodes to reply before returning
171 
Message_8 - RPC message, wait for the first reply
172 
Message_9 - RPC message, asynchronous, don't wait for a reply, collect them via a callback
173 
Message_10- sent to a member that is not part of this group</code></pre></div>
174 
  <p>
175 
    As you can imagine by now, these are just examples. The number of different semantics you can apply on a
176 
    per-message-basis is almost limitless. Tribes allows you to set up to 28 different on a message
177 
    and then configure Tribes to what flag results in what action on the message.<br>
178 
    Imagine a shared transactional cache, probably &gt;90% are reads, and the dirty reads should be completely
179 
    unordered and delivered as fast as possible. But transactional writes on the other hand, have to
180 
    be ordered so that no cache gets corrupted. With tribes you would send the write messages totally ordered,
181 
    while the read messages you simple fire to achieve highest throughput.<br>
182 
    There are probably better examples on how this powerful feature can be used, so use your imagination and
183 
    your experience to think of how this could benefit you in your application.
184 
  </p>
185 
  <p>
186 
    <b>Interceptor based message processing</b><br>
187 
    Tribes uses a customizable interceptor stack to process messages that are sent and received.<br>
188 
    <i>So what, all frameworks have this!</i><br>
189 
    Yes, but in Tribes interceptors can react to a message based on the per-message-attributes
190 
    that are sent runtime. Meaning, that if you add a encryption interceptor that encrypts message
191 
    you can decide if this interceptor will encrypt all messages, or only certain messages that are decided
192 
    by the applications running on top of Tribes.<br>
193 
    This is how Tribes is able to send some messages totally ordered and others fire and forget style
194 
    like the example above.<br>
195 
    The number of interceptors that are available will keep growing, and we would appreciate any contributions
196 
    that you might have.
197 
  </p>
198 
  <p>
199 
    <b>Threadless Interceptor stack</b>
200 
    The interceptor don't require any separate threads to perform their message manipulation.<br>
201 
    Messages that are sent will piggy back on the thread that is sending them all the way through transmission.
202 
    The exception is the <code>MessageDispatchInterceptor</code> that will queue up the message
203 
    and send it on a separate thread for asynchronous message delivery.
204 
    Messages received are controlled by a thread pool in the <code>receiver</code> component.<br>
205 
    The channel object can send a <code>heartbeat()</code> through the interceptor stack to allow
206 
    for timeouts, cleanup and other events.<br>
207 
    The <code>MessageDispatchInterceptor</code> is the only interceptor that is configured by default.
208 
  </p>
209 
  <p>
210 
    <b>Parallel Delivery</b><br>
211 
    Tribes support parallel delivery of messages. Meaning that node_A could send three messages to node_B in
212 
    parallel. This feature becomes useful when sending messages with different delivery semantics.
213 
    Otherwise if Message_1 was sent totally ordered, Message_2 would have to wait for that message to complete.<br>
214 
    Through NIO, Tribes is also able to send a message to several receivers at the same time on the same thread.
215 
  </p>
216 
  <p>
217 
    <b>Silent Member Messaging</b><br>
218 
    With Tribes you are able to send messages to members that are not in your group.
219 
    So by default, you can already send messages over a wide area network, even though the dynamic discover
220 
    module today is limited to local area networks by using multicast for dynamic node discovery.
221 
    Of course, the membership component will be expanded to support WAN memberships in the future.
222 
    But this is very useful, when you want to hide members from the rest of the group and only communicate with them
223 
  </p>
224 
</div><h3 id="Where_can_I_get_Tribes">Where can I get Tribes</h3><div class="text">
225 
  <p>
226 
    Tribes ships as a module with Tomcat, and is released as part of the Apache Tomcat release.
227 
  </p>
228 
 
229 
 
230 
</div></div></div></div></div><footer><div id="footer">
231 
    Copyright &copy; 1999-2025, The Apache Software Foundation
232 
    <br>
233 
    Apache Tomcat, Tomcat, Apache, the Apache Tomcat logo and the Apache logo
234 
    are either registered trademarks or trademarks of the Apache Software
235 
    Foundation.
236 
    </div></footer></div></body></html>