| <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"> | |
| .noPrint {display: none;} | |
| td#mainBody {width: 100%;} | |
| </style><style type="text/css"> | |
| code {background-color:rgb(224,255,255);padding:0 0.1em;} | |
| code.attributeName, code.propertyName {background-color:transparent;} | |
| table { | |
| border-collapse: collapse; | |
| text-align: left; | |
| } | |
| table *:not(table) { | |
| /* Prevent border-collapsing for table child elements like <div> */ | |
| border-collapse: separate; | |
| } | |
| th { | |
| text-align: left; | |
| } | |
| div.codeBox pre code, code.attributeName, code.propertyName, code.noHighlight, .noHighlight code { | |
| background-color: transparent; | |
| } | |
| div.codeBox { | |
| overflow: auto; | |
| margin: 1em 0; | |
| } | |
| div.codeBox pre { | |
| margin: 0; | |
| padding: 4px; | |
| border: 1px solid #999; | |
| border-radius: 5px; | |
| background-color: #eff8ff; | |
| display: table; /* To prevent <pre>s from taking the complete available width. */ | |
| /* | |
| When it is officially supported, use the following CSS instead of display: table | |
| to prevent big <pre>s from exceeding the browser window: | |
| max-width: available; | |
| width: min-content; | |
| */ | |
| } | |
| div.codeBox pre.wrap { | |
| white-space: pre-wrap; | |
| } | |
| table.defaultTable tr, table.detail-table tr { | |
| border: 1px solid #CCC; | |
| } | |
| table.defaultTable tr:nth-child(even), table.detail-table tr:nth-child(even) { | |
| background-color: #FAFBFF; | |
| } | |
| table.defaultTable tr:nth-child(odd), table.detail-table tr:nth-child(odd) { | |
| background-color: #EEEFFF; | |
| } | |
| table.defaultTable th, table.detail-table th { | |
| background-color: #88b; | |
| color: #fff; | |
| } | |
| table.defaultTable th, table.defaultTable td, table.detail-table th, table.detail-table td { | |
| padding: 5px 8px; | |
| } | |
| p.notice { | |
| border: 1px solid rgb(255, 0, 0); | |
| background-color: rgb(238, 238, 238); | |
| color: rgb(0, 51, 102); | |
| padding: 0.5em; | |
| margin: 1em 2em 1em 1em; | |
| } | |
| </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> | |
| <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> | |
| </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> | |
| <p>Apache Tribes is a group or peer-to-peer communication framework that enables you to easily connect | |
| your remote objects to communicate with each other. | |
| </p> | |
| <ul> | |
| <li>Import: <code>org.apache.catalina.tribes.Channel</code></li> | |
| <li>Import: <code>org.apache.catalina.tribes.Member</code></li> | |
| <li>Import: <code>org.apache.catalina.tribes.MembershipListener</code></li> | |
| <li>Import: <code>org.apache.catalina.tribes.ChannelListener</code></li> | |
| <li>Import: <code>org.apache.catalina.tribes.group.GroupChannel</code></li> | |
| <li>Create a class that implements: <code>org.apache.catalina.tribes.ChannelListener</code></li> | |
| <li>Create a class that implements: <code>org.apache.catalina.tribes.MembershipListener</code></li> | |
| <li>Simple class to demonstrate how to send a message: | |
| <div class="codeBox"><pre><code> | |
| //create a channel | |
| Channel myChannel = new GroupChannel(); | |
| //create my listeners | |
| ChannelListener msgListener = new MyMessageListener(); | |
| MembershipListener mbrListener = new MyMemberListener(); | |
| //attach the listeners to the channel | |
| myChannel.addMembershipListener(mbrListener); | |
| myChannel.addChannelListener(msgListener); | |
| //start the channel | |
| myChannel.start(Channel.DEFAULT); | |
| //create a message to be sent, message must implement java.io.Serializable | |
| //for performance reasons you probably want them to implement java.io.Externalizable | |
| Serializable myMsg = new MyMessage(); | |
| //retrieve my current members | |
| Member[] group = myChannel.getMembers(); | |
| //send the message | |
| myChannel.send(group,myMsg,Channel.SEND_OPTIONS_DEFAULT); | |
| </code></pre></div> | |
| </li> | |
| </ul> | |
| <p> | |
| Simple yeah? There is a lot more to Tribes than we have shown, hopefully the docs will be able | |
| to explain more to you. Remember, that we are always interested in suggestions, improvements, bug fixes | |
| and anything that you think would help this project. | |
| </p> | |
| <p> | |
| 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. | |
| </p> | |
| </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> | |
| <p> | |
| Tribes is a messaging framework with group communication abilities. Tribes allows you to send and receive | |
| messages over a network, it also allows for dynamic discovery of other nodes in the network.<br> | |
| And that is the short story, it really is as simple as that. What makes Tribes useful and unique will be | |
| described in the section below.<br> | |
| </p> | |
| <p> | |
| The Tribes module was started early 2006 and a small part of the code base comes from the clustering module | |
| that has been existing since 2003 or 2004. | |
| The current cluster implementation has several short comings and many workarounds were created due | |
| to the complexity in group communication. Long story short, what should have been two modules a long time | |
| ago, will be now. Tribes takes out the complexity of messaging from the replication module and becomes | |
| a fully independent and highly flexible group communication module.<br> | |
| </p> | |
| <p> | |
| In Tomcat the old <code>modules/cluster</code> has now become <code>modules/groupcom</code>(Tribes) and | |
| <code>modules/ha</code> (replication). This will allow development to proceed and let the developers | |
| focus on the issues they are actually working on rather than getting boggled down in details of a module | |
| they are not interested in. The understanding is that both communication and replication are complex enough, | |
| and when trying to develop them in the same module, well you know, it becomes a cluster :)<br> | |
| </p> | |
| <p> | |
| Tribes allows for guaranteed messaging, and can be customized in many ways. Why is this important?<br> | |
| Well, you as a developer want to know that the messages you are sending are reaching their destination. | |
| More than that, if a message doesn't reach its destination, the application on top of Tribes will be notified | |
| that the message was never sent, and what node it failed. | |
| </p> | |
| </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> | |
| <p> | |
| I am a big fan of reusing code and would never dream of developing something if someone else has already | |
| done it and it was available to me and the community I try to serve.<br> | |
| When I did my research to improve the clustering module I was constantly faced with a few obstacles:<br> | |
| 1. The framework wasn't flexible enough<br> | |
| 2. The framework was licensed in a way that neither I nor the community could use it<br> | |
| 3. Several features that I needed were missing<br> | |
| 4. Messaging was guaranteed, but no feedback was reported to me<br> | |
| 5. The semantics of my message delivery had to be configured before runtime<br> | |
| And the list continues... | |
| </p> | |
| <p> | |
| So I came up with Tribes, to address these issues and other issues that came along. | |
| When designing Tribes I wanted to make sure I didn't lose any of the flexibility and | |
| delivery semantics that the existing frameworks already delivered. The goal was to create a framework | |
| that could do everything that the others already did, but to provide more flexibility for the application | |
| developer. In the next section will give you the high level overview of what features tribes offers or will offer. | |
| </p> | |
| </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> | |
| <p> | |
| To give you an idea of the feature set I will list it out here. | |
| Some of the features are not yet completed, if that is the case they are marked accordingly. | |
| </p> | |
| <p> | |
| <b>Pluggable modules</b><br> | |
| Tribes is built using interfaces. Any of the modules or components that are part of Tribes can be swapped out | |
| to customize your own Tribes implementation. | |
| </p> | |
| <p> | |
| <b>Guaranteed Messaging</b><br> | |
| In the default implementation of Tribes uses TCP or UDP for messaging. TCP already has guaranteed message delivery | |
| and flow control built in. I believe that the performance of Java TCP, will outperform an implementation of | |
| Java/UDP/flow-control/message guarantee since the logic happens further down the stack. UDP messaging has been added in for | |
| sending messages over UDP instead of TCP when desired. The same guarantee scenarios as described below are still available | |
| over UDP, however, when a UDP message is lost, it's considered failed.<br> | |
| Tribes supports both non-blocking and blocking IO operations. The recommended setting is to use non blocking | |
| as it promotes better parallelism when sending and receiving messages. The blocking implementation is available | |
| for those platforms where NIO is still a trouble child. | |
| </p> | |
| <p> | |
| <b>Different Guarantee Levels</b><br> | |
| There are three different levels of delivery guarantee when a message is sent.<br> | |
| <ol> | |
| <li>IO Based send guarantee. - fastest, least reliable<br> | |
| This means that Tribes considers the message transfer to be successful | |
| if the message was sent to the socket send buffer and accepted.<br> | |
| On blocking IO, this would be <code>socket.getOutputStream().write(msg)</code><br> | |
| On non blocking IO, this would be <code>socketChannel.write()</code>, and the buffer byte buffer gets emptied | |
| followed by a <code>socketChannel.read()</code> to ensure the channel still open. | |
| The <code>read()</code> has been added since <code>write()</code> will succeed if the connection has been "closed" | |
| when using NIO. | |
| </li> | |
| <li>ACK based. - recommended, guaranteed delivery<br> | |
| When the message has been received on a remote node, an ACK is sent back to the sender, | |
| indicating that the message was received successfully. | |
| </li> | |
| <li>SYNC_ACK based. - guaranteed delivery, guaranteed processed, slowest<br> | |
| When the message has been received on a remote node, the node will process | |
| the message and if the message was processed successfully, an ACK is sent back to the sender | |
| indicating that the message was received and processed successfully. | |
| If the message was received, but processing it failed, an ACK_FAIL will be sent back | |
| to the sender. This is a unique feature that adds an incredible amount value to the application | |
| developer. Most frameworks here will tell you that the message was delivered, and the application | |
| developer has to build in logic on whether the message was actually processed properly by the application | |
| on the remote node. If configured, Tribes will throw an exception when it receives an ACK_FAIL | |
| and associate that exception with the member that didn't process the message. | |
| </li> | |
| </ol> | |
| You can of course write even more sophisticated guarantee levels, and some of them will be mentioned later on | |
| in the documentation. One mentionable level would be a 2-Phase-Commit, where the remote applications don't receive | |
| the message until all nodes have received the message. Sort of like a all-or-nothing protocol. | |
| </p> | |
| <p> | |
| <b>Per Message Delivery Attributes</b><br> | |
| Perhaps the feature that makes Tribes stand out from the crowd of group communication frameworks. | |
| Tribes enables you to send to decide what delivery semantics a message transfer should have on a per | |
| message basis. Meaning, that your messages are not delivered based on some static configuration | |
| that remains fixed after the message framework has been started.<br> | |
| To give you an example of how powerful this feature is, I'll try to illustrate it with a simple example. | |
| Imagine you need to send 10 different messages, you could send them the following way: | |
| <div class="codeBox"><pre><code> | |
| Message_1 - asynchronous and fast, no guarantee required, fire and forget | |
| Message_2 - all-or-nothing, either all receivers get it, or none. | |
| Message_3 - encrypted and SYNC_ACK based | |
| Message_4 - asynchronous, SYNC_ACK and call back when the message is processed on the remote nodes | |
| Message_5 - totally ordered, this message should be received in the same order on all nodes that have been | |
| send totally ordered | |
| Message_6 - asynchronous and totally ordered | |
| Message_7 - RPC message, send a message, wait for all remote nodes to reply before returning | |
| Message_8 - RPC message, wait for the first reply | |
| Message_9 - RPC message, asynchronous, don't wait for a reply, collect them via a callback | |
| Message_10- sent to a member that is not part of this group | |
| </code></pre></div> | |
| As you can imagine by now, these are just examples. The number of different semantics you can apply on a | |
| per-message-basis is almost limitless. Tribes allows you to set up to 28 different on a message | |
| and then configure Tribes to what flag results in what action on the message.<br> | |
| Imagine a shared transactional cache, probably >90% are reads, and the dirty reads should be completely | |
| unordered and delivered as fast as possible. But transactional writes on the other hand, have to | |
| be ordered so that no cache gets corrupted. With tribes you would send the write messages totally ordered, | |
| while the read messages you simple fire to achieve highest throughput.<br> | |
| There are probably better examples on how this powerful feature can be used, so use your imagination and | |
| your experience to think of how this could benefit you in your application. | |
| </p> | |
| <p> | |
| <b>Interceptor based message processing</b><br> | |
| Tribes uses a customizable interceptor stack to process messages that are sent and received.<br> | |
| <i>So what, all frameworks have this!</i><br> | |
| Yes, but in Tribes interceptors can react to a message based on the per-message-attributes | |
| that are sent runtime. Meaning, that if you add a encryption interceptor that encrypts message | |
| you can decide if this interceptor will encrypt all messages, or only certain messages that are decided | |
| by the applications running on top of Tribes.<br> | |
| This is how Tribes is able to send some messages totally ordered and others fire and forget style | |
| like the example above.<br> | |
| The number of interceptors that are available will keep growing, and we would appreciate any contributions | |
| that you might have. | |
| </p> | |
| <p> | |
| <b>Threadless Interceptor stack</b> | |
| The interceptor don't require any separate threads to perform their message manipulation.<br> | |
| Messages that are sent will piggy back on the thread that is sending them all the way through transmission. | |
| The exception is the <code>MessageDispatchInterceptor</code> that will queue up the message | |
| and send it on a separate thread for asynchronous message delivery. | |
| Messages received are controlled by a thread pool in the <code>receiver</code> component.<br> | |
| The channel object can send a <code>heartbeat()</code> through the interceptor stack to allow | |
| for timeouts, cleanup and other events.<br> | |
| The <code>MessageDispatchInterceptor</code> is the only interceptor that is configured by default. | |
| </p> | |
| <p> | |
| <b>Parallel Delivery</b><br> | |
| Tribes support parallel delivery of messages. Meaning that node_A could send three messages to node_B in | |
| parallel. This feature becomes useful when sending messages with different delivery semantics. | |
| Otherwise if Message_1 was sent totally ordered, Message_2 would have to wait for that message to complete.<br> | |
| Through NIO, Tribes is also able to send a message to several receivers at the same time on the same thread. | |
| </p> | |
| <p> | |
| <b>Silent Member Messaging</b><br> | |
| With Tribes you are able to send messages to members that are not in your group. | |
| So by default, you can already send messages over a wide area network, even though the dynamic discover | |
| module today is limited to local area networks by using multicast for dynamic node discovery. | |
| Of course, the membership component will be expanded to support WAN memberships in the future. | |
| But this is very useful, when you want to hide members from the rest of the group and only communicate with them | |
| </p> | |
| </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> | |
| <p> | |
| Tribes ships as a module with Tomcat, and is released as part of the Apache Tomcat release. | |
| </p> | |
| </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 | |
| on improving documentation for Apache Tomcat.<br><br> | |
| If you have trouble and need help, read | |
| <a href="http://tomcat.apache.org/findhelp.html">Find Help</a> page | |
| and ask your question on the tomcat-users | |
| <a href="http://tomcat.apache.org/lists.html">mailing list</a>. | |
| Do not ask such questions here. This is not a Q&A section.<br><br> | |
| The Apache Comments System is explained <a href="../comments.html">here</a>. | |
| Comments may be removed by our moderators if they are either | |
| implemented or considered invalid/off-topic.</p><script type="text/javascript"><!--//--><![CDATA[//><!-- | |
| var comments_shortname = 'tomcat'; | |
| var comments_identifier = 'http://tomcat.apache.org/tomcat-7.0-doc/tribes/introduction.html'; | |
| (function(w, d) { | |
| if (w.location.hostname.toLowerCase() == "tomcat.apache.org") { | |
| d.write('<div id="comments_thread"><\/div>'); | |
| var s = d.createElement('script'); | |
| s.type = 'text/javascript'; | |
| s.async = true; | |
| s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier; | |
| (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s); | |
| } | |
| else { | |
| d.write('<div id="comments_thread"><strong>Comments are disabled for this page at the moment.<\/strong><\/div>'); | |
| } | |
| })(window, document); | |
| //--><!]]></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> | |
| Copyright © 1999-2017, Apache Software Foundation | |
| </em></font></div></td></tr></table></body></html> |