| <?xml version="1.0" encoding="UTF-8"?> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| <!DOCTYPE document [ |
| <!ENTITY project SYSTEM "project.xml"> |
| ]> |
| <document url="cluster-interceptor.html"> |
| |
| &project; |
| |
| <properties> |
| <title>The Channel Interceptor object</title> |
| </properties> |
| |
| <body> |
| |
| <section name="Table of Contents"> |
| <toc/> |
| </section> |
| |
| <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 useful feature add-ons. |
| </p> |
| </section> |
| |
| <section name="Available Interceptors"> |
| <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.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.SimpleCoordinator</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> |
| <li><code>org.apache.catalina.tribes.group.interceptors.TcpPingInterceptor</code></li> |
| <li><code>org.apache.catalina.tribes.group.interceptors.EncryptInterceptor</code></li> |
| </ul> |
| </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> |
| after 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.</p> |
| <source><![CDATA[ <Interceptor className="org.apache.catalina.tribes.group.interceptors.StaticMembershipInterceptor"> |
| <LocalMember className="org.apache.catalina.tribes.membership.StaticMember" |
| domain="staging-cluster" |
| uniqueId="{1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,1}"/> |
| <Member className="org.apache.catalina.tribes.membership.StaticMember" |
| port="5678" |
| securePort="-1" |
| host="tomcat01.mydomain.com" |
| domain="staging-cluster" |
| uniqueId="{0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}"/> |
| </Interceptor>]]></source> |
| </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.DomainFilterInterceptor Attributes"> |
| <attributes> |
| <attribute name="domain" required="true"> |
| The logical cluster domain that this Interceptor accepts. |
| Two different type of values are possible:<br/> |
| 1. Regular string values like "staging-domain" or "tomcat-cluster" will be converted into bytes |
| using ISO-8859-1 encoding.<br/> |
| 2. byte array in string form, for example {216,123,12,3}<br/> |
| </attribute> |
| <attribute name="logInterval" required="false"> |
| This value indicates the interval for logging for messages from different domains. |
| The default is 100, which means that to log per 100 messages. |
| </attribute> |
| </attributes> |
| </subsection> |
| <subsection name="org.apache.catalina.tribes.group.interceptors.FragmentationInterceptor Attributes"> |
| <attributes> |
| <attribute name="expire" required="false"> |
| How long do we keep the fragments in memory and wait for the rest to arrive. |
| The default is 60000 ms. |
| </attribute> |
| <attribute name="maxSize" required="false"> |
| The maximum message size in bytes. If the message size exceeds this value, this interceptor fragments the message and sends them. |
| If it is less than this value, this interceptor does not fragment the message and sent in as one message. The default is 1024*100. |
| </attribute> |
| </attributes> |
| </subsection> |
| <subsection name="org.apache.catalina.tribes.group.interceptors.MessageDispatchInterceptor Attributes"> |
| <attributes> |
| <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> |
| <attribute name="alwaysSend" required="false"> |
| What behavior should be executed when the dispatch queue is full. If <code>true</code> (default), then the message is |
| is sent synchronously, if <code>false</code> an error is thrown. |
| </attribute> |
| <attribute name="maxQueueSize" required="false"> |
| Size in bytes of the dispatch queue, the default value is <code> 1024*1024*64 (64 MiB)</code> sets the maximum queue size for the dispatch queue |
| if the queue fills up, one can trigger the behavior, if <code>alwaysSend</code> is set to true, the message will be sent synchronously |
| if the flag is false, an error is thrown |
| </attribute> |
| <attribute name="maxThreads" required="false"> |
| The maximum number of threads in this pool, default is 10. |
| </attribute> |
| <attribute name="maxSpareThreads" required="false"> |
| The number of threads to keep in the pool, default is 2. |
| </attribute> |
| <attribute name="keepAliveTime" required="false"> |
| Maximum number of milliseconds of until Idle thread terminates. Default value is 5000(5 seconds). |
| </attribute> |
| </attributes> |
| </subsection> |
| <subsection name="org.apache.catalina.tribes.group.interceptors.TcpFailureDetector Attributes"> |
| <attributes> |
| <attribute name="connectTimeout" required="false"> |
| Specifies the timeout, in milliseconds, to use when attempting a TCP connection |
| to the suspect node. Default is 1000. |
| </attribute> |
| <attribute name="performSendTest" required="false"> |
| If true is set, send a test message to the suspect node. Default is true. |
| </attribute> |
| <attribute name="performReadTest" required="false"> |
| If true is set, read the response of the test message that sent. Default is false. |
| <strong>Note:</strong> if <code>performSendTest</code> is false, this attribute will have no effect. |
| </attribute> |
| <attribute name="readTestTimeout" required="false"> |
| Specifies the timeout, in milliseconds, to use when performing a read test |
| to the suspicious node. Default is 5000. |
| </attribute> |
| <attribute name="removeSuspectsTimeout" required="false"> |
| The maximum time(in seconds) for remove from removeSuspects. Member of |
| removeSuspects will be automatically removed after removeSuspectsTimeout. |
| If a negative value specified, the removeSuspects members never be |
| removed until disappeared really. If the attribute is not provided, |
| a default of 300 seconds (5 minutes) is used. |
| </attribute> |
| </attributes> |
| </subsection> |
| <subsection name="org.apache.catalina.tribes.group.interceptors.TcpPingInterceptor Attributes"> |
| <attributes> |
| <attribute name="interval" required="false"> |
| If useThread == true, defines the interval of sending a ping message. |
| default is 1000 ms. |
| </attribute> |
| <attribute name="useThread" required="false"> |
| Flag of whether to start a thread for sending a ping message. |
| If set to true, this interceptor will start a local thread for sending a ping message. |
| if set to false, channel heartbeat will send a ping message. |
| default is false. |
| </attribute> |
| </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="org.apache.catalina.tribes.group.interceptors.EncryptInterceptor Attributes"> |
| <p> |
| The EncryptInterceptor adds encryption to the channel messages carrying |
| session data between nodes. |
| </p> |
| <p> |
| If using the <code>TcpFailureDetector</code>, the <code>EncryptInterceptor</code> |
| <i>must</i> be inserted into the interceptor chain <i>before</i> the |
| <code>TcpFailureDetector</code>. This is because when validating cluster |
| members, <code>TcpFailureDetector</code> writes channel data directly |
| to the other members without using the remainder of the interceptor chain, |
| but on the receiving side, the message still goes through the chain (in reverse). |
| Because of this asymmetry, the <code>EncryptInterceptor</code> must execute |
| <i>before</i> the <code>TcpFailureDetector</code> on the sender and <i>after</i> |
| it on the receiver, otherwise message corruption will occur. |
| </p> |
| <attributes> |
| <attribute name="encryptionAlgorithm" required="false"> |
| The encryption algorithm to be used, including the mode and padding. Please see |
| <a href="https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html">https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html</a> |
| for the standard JCA names that can be used. |
| |
| EncryptInterceptor currently supports the following |
| <a href="https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation">block-cipher modes</a>: |
| CBC, OFB, CFB, and GCM. |
| |
| The length of the key will specify the flavor of the encryption algorithm |
| to be used, if applicable (e.g. AES-128 versus AES-256). |
| |
| The default algorithm is <code>AES/CBC/PKCS5Padding</code>. |
| </attribute> |
| <attribute name="encryptionKey" required="true"> |
| The key to be used with the encryption algorithm. |
| |
| The key should be specified as hex-encoded bytes of the appropriate |
| length for the algorithm (e.g. 16 bytes / 32 characters / 128 bits for |
| AES-128, 32 bytes / 64 characters / 256 bits for AES-256, etc.). |
| </attribute> |
| </attributes> |
| </subsection> |
| </section> |
| |
| <section name="Nested Components"> |
| |
| <subsection name="StaticMember Attributes"> |
| <p><b>LocalMember:</b> <br/> |
| Static member that is the local member of the static cluster group. |
| </p> |
| <attributes> |
| <attribute name="className" required="true"> |
| Only one implementation available:<code>org.apache.catalina.tribes.membership.StaticMember</code> |
| </attribute> |
| <attribute name="port" required="false"> |
| There is no need to set. |
| The value of this attribute inherits from the cluster receiver setting. |
| </attribute> |
| <attribute name="securePort" required="false"> |
| There is no need to set. |
| The value of this attribute inherits from the cluster receiver setting. |
| </attribute> |
| <attribute name="host" required="false"> |
| There is no need to set. |
| The value of this attribute inherits from the cluster receiver setting. |
| </attribute> |
| <attribute name="domain" required="false"> |
| The logical cluster domain for that this static member listens for cluster messages. |
| Two different type of values are possible:<br/> |
| 1. Regular string values like "staging-domain" or "tomcat-cluster" 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> |
| |
| <p><b>Member:</b> <br/> |
| Static member that add to the static cluster group. |
| </p> |
| <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 "216.123.1.23"<br/> |
| 2. Hostnames like "tomcat01.mydomain.com" or "tomcat01" 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="false"> |
| The logical cluster domain for that this static member listens for cluster messages. |
| Two different type of values are possible:<br/> |
| 1. Regular string values like "staging-domain" or "tomcat-cluster" will be converted into bytes |
| using ISO-8859-1 encoding.<br/> |
| 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> |
