<?xml version="1.0"?>
<!DOCTYPE document [
  <!ENTITY project SYSTEM "project.xml">
]>
<document url="cluster-interceptor.html">

  &project;

  <properties>
    <author email="fhanik@apache.org">Filip Hanik</author>
    <title>The Channel Interceptor object</title>
  </properties>

<body>


<section name="Introduction">
  <p>
  Apache Tribes supports an interceptor architecture to intercept both messages and membership notifications.
  This architecture allows decoupling of logic and opens the way for some very kewl feature add ons.
  </p>
</section>

<section name="Available Interceptors">
 <p>
   <ul>
    <li><code>org.apache.catalina.tribes.group.interceptors.TcpFailureDetector</code></li>
    <li><code>org.apache.catalina.tribes.group.interceptors.ThroughputInterceptor</code></li>
    <li><code>org.apache.catalina.tribes.group.interceptors.MessageDispatch15Interceptor</code></li>
    <li><code>org.apache.catalina.tribes.group.interceptors.MessageDispatchInterceptor</code></li>
    <li><code>org.apache.catalina.tribes.group.interceptors.NonBlockingCoordinator</code></li>
    <li><code>org.apache.catalina.tribes.group.interceptors.OrderInterceptor</code></li>
    <li><code>org.apache.catalina.tribes.group.interceptors.StaticMembershipInterceptor</code></li>
    <li><code>org.apache.catalina.tribes.group.interceptors.TwoPhaseCommitInterceptor</code></li>
    <li><code>org.apache.catalina.tribes.group.interceptors.DomainFilterInterceptor</code></li>
    <li><code>org.apache.catalina.tribes.group.interceptors.FragmentationInterceptor</code></li>
    <li><code>org.apache.catalina.tribes.group.interceptors.GzipInterceptor</code></li>
   </ul>
 </p>
</section>

<section name="Static Membership">
  <p>
   In addition to dynamic discovery, Apache Tribes also supports static membership, with membership verification.
   To achieve this add the <code>org.apache.catalina.tribes.group.interceptors.StaticMembershipInterceptor</code>
   underneath the <code>org.apache.catalina.tribes.group.interceptors.TcpFailureDetector</code> interceptor.
   Inside the <code>StaticMembershipInterceptor</code> you can add the static members you wish to have.
   The <code>TcpFailureDetector</code> will do a health check on the static members,and also monitor them for crashes
   so they will have the same level of notification mechanism as the members that are automatically discovered.
   <source>
     &lt;Interceptor className=&quot;org.apache.catalina.tribes.group.interceptors.StaticMembershipInterceptor&quot;&gt;
       &lt;Member className=&quot;org.apache.catalina.tribes.membership.StaticMember&quot;
                  port=&quot;5678&quot;
                  securePort=&quot;-1&quot;
                  host=&quot;tomcat01.mydomain.com&quot;
                  domain=&quot;staging-cluster&quot;
                  uniqueId=&quot;{0,1,2,3,4,5,6,7,8,9}&quot;/&gt;
     &lt;/Interceptor&gt;
   
   </source>
  </p>
</section>

<section name="Attributes">

  <subsection name="Common Attributes">
   <attributes>
     <attribute name="className" required="true">
       Required, as there is no default 
     </attribute>
     <attribute name="optionFlag" required="false">
       If you want the interceptor to trigger on certain message depending on the message's option flag,
       you can setup the interceptors flag here.
       The default value is <code>0</code>, meaning this interceptor will trigger on all messages.
     </attribute>
   </attributes>
  </subsection>

  <subsection name="org.apache.catalina.tribes.group.interceptors.MessageDispatch15Interceptor Attributes">
   <attributes>
     <attribute name="className" required="true">
       Required, This dispatcher uses JDK 1.5 java.util.concurrent package 
     </attribute>
     <attribute name="optionFlag" required="false">
       The default and hard coded value is <code>8 (org.apache.catalina.tribes.Channel.SEND_OPTIONS_ASYNCHRONOUS)</code>.
       The dispatcher will trigger on this value only, as it is predefined by Tribes.
     </attribute>
   </attributes>
  </subsection>
  <subsection name="org.apache.catalina.tribes.group.interceptors.MessageDispatchInterceptor Attributes">
   <attributes>
     <attribute name="className" required="true">
       Required, Same implementation as <code>MessageDispatch15Interceptor</code>, but with JDK 1.4 compliance.
     </attribute>
     <attribute name="optionFlag" required="false">
       The default and hard coded value is <code>8 (org.apache.catalina.tribes.Channel.SEND_OPTIONS_ASYNCHRONOUS)</code>.
       The dispatcher will trigger on this value only, as it is predefined by Tribes.
     </attribute>
   </attributes>
  </subsection>
  <subsection name="org.apache.catalina.tribes.group.interceptors.TcpFailureDetector Attributes">
   <attributes>
   </attributes>
  </subsection>
  <subsection name="org.apache.catalina.tribes.group.interceptors.ThroughputInterceptor Attributes">
   <attributes>
     <attribute name="interval" required="false">
       Defines the interval in number of messages when we are to report the throughput statistics.
       The report is logged to the <code>org.apache.juli.logging.LogFactory.getLog(ThroughputInterceptor.class)</code>
       logger under the <code>INFO</code> level.
       Default value is to report every <code>10000</code> messages.
     </attribute>
   </attributes>
  </subsection>
  
  <subsection name="Nested element StaticMember Attributes">
   <attributes>
     <attribute name="className" required="true">
       Only one implementation available:<code>org.apache.catalina.tribes.membership.StaticMember</code>
     </attribute>
     <attribute name="port" required="true">
       The port that this static member listens to for cluster messages
     </attribute>
     <attribute name="securePort" required="false">
       The secure port this static member listens to for encrypted cluster messages
       default value is <code>-1</code>, this value means the member is not listening on a secure port
     </attribute>
     <attribute name="host" required="true">
       The host (or network interface) that this static member listens for cluster messages.
       Three different type of values are possible:<br/>
       1. IP address in the form of &quot;216.123.1.23&quot;<br/>
       2. Hostnames like &quot;tomcat01.mydomain.com&quot; or &quot;tomcat01&quot; as long as they resolve correctly<br/>
       3. byte array in string form, for example {216,123,12,3}<br/>
     </attribute>
     <attribute name="domain" required="true">
       The logical cluster domain for this this static member listens for cluster messages.
       Two different type of values are possible:<br/>
       1. Regular string values like &quot;staging-domain&quot; or &quot;tomcat-cluster&quot; will be converted into bytes 
       using ISO-8859-1 encoding.
       2. byte array in string form, for example {216,123,12,3}<br/>
     </attribute>
     <attribute name="uniqueId" required="true">
       A universally uniqueId for this static member.
       The values must be 16 bytes in the following form:<br/>
       1. byte array in string form, for example {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}<br/>
     </attribute>
   </attributes>
  </subsection>
  <!--TODO Document all the interceptors-->
  
</section>


</body>

</document>
