182 lines
9.3 KiB
XML
182 lines
9.3 KiB
XML
<?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-sender.html">
|
|
|
|
&project;
|
|
|
|
<properties>
|
|
<author email="fhanik@apache.org">Filip Hanik</author>
|
|
<title>The Cluster Sender object</title>
|
|
</properties>
|
|
|
|
<body>
|
|
|
|
<section name="Table of Contents">
|
|
<toc/>
|
|
</section>
|
|
|
|
<section name="Introduction">
|
|
<p>
|
|
The channel sender component is responsible for delivering outgoing cluster messages over the network.
|
|
In the default implementation, <code>org.apache.catalina.tribes.transport.ReplicationTransmitter</code>,
|
|
the sender is a fairly empty shell with not much logic around a fairly complex <code><Transport></code>
|
|
component the implements the actual delivery mechanism.
|
|
</p>
|
|
</section>
|
|
|
|
<section name="Concurrent Parallel Delivery">
|
|
<p>
|
|
In the default <code>transport</code> implementation, <code>org.apache.catalina.tribes.transport.nio.PooledParallelSender</code>,
|
|
Apache Tribes implements what we like to call "Concurrent Parallel Delivery".
|
|
This means that we can send a message to more than one destination at the same time(parallel), and
|
|
deliver two messages to the same destination at the same time(concurrent). Combine these two and we have
|
|
"Concurrent Parallel Delivery".
|
|
</p>
|
|
<p>
|
|
When is this useful? The simplest example we can think of is when part of your code is sending a 10MB message,
|
|
like a war file being deployed, and you need to push through a small 10KB message, say a session being replicated,
|
|
you don't have to wait for the 10MB message to finish, as a separate thread will push in the small message
|
|
transmission at the same time. Currently there is no interrupt, pause or priority mechanism available, but check back soon.
|
|
</p>
|
|
</section>
|
|
|
|
<section name="Nested Elements">
|
|
<p>
|
|
The nested element <code><Transport></code> is not required, but encouraged, as this is where
|
|
you would set all the socket options for the outgoing messages. Please see its attributes below.
|
|
There are two implementations, in a similar manner to the <a href="cluster-receiver.html">receiver</a>, one is non-blocking
|
|
based and the other is built using blocking IO. <br/>
|
|
<code>org.apache.catalina.tribes.transport.bio.PooledMultiSender</code> is the blocking implementation and
|
|
<code>org.apache.catalina.tribes.transport.nio.PooledParallelSender</code>.
|
|
Parallel delivery is not available for the blocking implementation due to the fact that it is blocking a thread on sending data.
|
|
</p>
|
|
</section>
|
|
|
|
<section name="Attributes">
|
|
<subsection name="Common Sender Attributes">
|
|
<attributes>
|
|
<attribute name="className" required="true">
|
|
Required, only available implementation is <code>org.apache.catalina.tribes.transport.ReplicationTransmitter</code>
|
|
</attribute>
|
|
</attributes>
|
|
</subsection>
|
|
<subsection name="Common Transport Attributes">
|
|
<attributes>
|
|
<attribute name="className" required="true">
|
|
Required, an implementation of the <code>org.apache.catalina.tribes.transport.MultiPointSender</code>.<br/>
|
|
Non-blocking implementation is <code>org.apache.catalina.tribes.transport.nio.PooledParallelSender</code><br/>
|
|
Blocking implementation is <code>org.apache.catalina.tribes.transport.bio.PooledMultiSender</code>
|
|
</attribute>
|
|
<attribute name="rxBufSize" required="false">
|
|
The receive buffer size on the socket.
|
|
Default value is <code>25188</code> bytes.
|
|
</attribute>
|
|
<attribute name="txBufSize" required="false">
|
|
The send buffer size on the socket.
|
|
Default value is <code>43800</code> bytes.
|
|
</attribute>
|
|
<attribute name="udpRxBufSize" required="false">
|
|
The receive buffer size on the datagram socket.
|
|
Default value is <code>25188</code> bytes.
|
|
</attribute>
|
|
<attribute name="udpTxBufSize" required="false">
|
|
The send buffer size on the datagram socket.
|
|
Default value is <code>43800</code> bytes.
|
|
</attribute>
|
|
<attribute name="directBuffer" required="false">
|
|
Possible values are <code>true</code> or <code>false</code>.
|
|
Set to true if you want the receiver to use direct bytebuffers when writing data
|
|
to the sockets. Default value is <code>false</code>
|
|
</attribute>
|
|
<attribute name="keepAliveCount" required="false">
|
|
The number of requests that can go through the socket before the socket is closed, and reopened
|
|
for the next request. The default value is <code>-1</code>, which is unlimited.
|
|
</attribute>
|
|
<attribute name="keepAliveTime" required="false">
|
|
The number of milliseconds a connection is kept open after its been opened.
|
|
The default value is <code>-1</code>, which is unlimited.
|
|
</attribute>
|
|
<attribute name="timeout" required="false">
|
|
Sets the SO_TIMEOUT option on the socket. The value is in milliseconds and the default value is <code>3000</code>
|
|
milliseconds.(3 seconds) This timeout starts when a message send attempt is starting, until the transfer has been completed.
|
|
For the NIO sockets, this will mean, that the caller can guarantee that we will not attempt sending the message
|
|
longer than this timeout value. For the blocking IO implementation, this translated directly to the soTimeout.<br/>
|
|
A timeout will not spawn a retry attempt, in order to guarantee the return of the application thread.
|
|
</attribute>
|
|
<attribute name="maxRetryAttempts" required="false">
|
|
How many times do we retry a failed message, that received a IOException at the socket level.
|
|
The default value is <code>1</code>, meaning we will retry a message that has failed once.
|
|
In other words, we will attempt a message send no more than twice. One is the original send, and one is the
|
|
<code>maxRetryAttempts</code>.
|
|
</attribute>
|
|
<attribute name="ooBInline" required="false">
|
|
Boolean value for the socket OOBINLINE option. Possible values are <code>true</code> or <code>false</code>.
|
|
</attribute>
|
|
<attribute name="soKeepAlive" required="false">
|
|
Boolean value for the socket SO_KEEPALIVE option. Possible values are <code>true</code> or <code>false</code>.
|
|
</attribute>
|
|
<attribute name="soLingerOn" required="false">
|
|
Boolean value to determine whether to use the SO_LINGER socket option.
|
|
Possible values are <code>true</code> or <code>false</code>. Default value is <code>true</code>.
|
|
</attribute>
|
|
<attribute name="soLingerTime" required="false">
|
|
Sets the SO_LINGER socket option time value. The value is in seconds.
|
|
The default value is <code>3</code> seconds.
|
|
</attribute>
|
|
<attribute name="soReuseAddress" required="false">
|
|
Boolean value for the socket SO_REUSEADDR option. Possible values are <code>true</code> or <code>false</code>.
|
|
</attribute>
|
|
<attribute name="soTrafficClass" required="false">
|
|
Sets the traffic class level for the socket, the value is between 0 and 255.
|
|
Default value is <code>int soTrafficClass = 0x04 | 0x08 | 0x010;</code>
|
|
Different values are defined in <a href="http://docs.oracle.com/javase/7/docs/api/java/net/Socket.html#setTrafficClass(int)">
|
|
java.net.Socket#setTrafficClass(int)</a>.
|
|
</attribute>
|
|
<attribute name="tcpNoDelay" required="false">
|
|
Boolean value for the socket TCP_NODELAY option. Possible values are <code>true</code> or <code>false</code>.
|
|
The default value is <code>true</code>
|
|
</attribute>
|
|
<attribute name="throwOnFailedAck" required="false">
|
|
Boolean value, default value is <code>true</code>.
|
|
If set to true, the sender will throw a <code>org.apache.catalina.tribes.RemoteProcessException</code>
|
|
when we receive a negative ack from the remote member.
|
|
Set to false, and Tribes will treat a positive ack the same way as a negative ack, that the message was received.
|
|
</attribute>
|
|
</attributes>
|
|
</subsection>
|
|
<subsection name="Common PooledSender Attributes">
|
|
<attributes>
|
|
<attribute name="poolSize" required="false">
|
|
The maximum number of concurrent connections from A to B.
|
|
The value is based on a per-destination count.
|
|
The default value is <code>25</code>
|
|
</attribute>
|
|
<attribute name="maxWait" required="false">
|
|
The maximum number of milliseconds that the senderPool will wait when
|
|
there are no available senders. The default value is <code>3000</code>
|
|
milliseconds.(3 seconds).
|
|
</attribute>
|
|
</attributes>
|
|
</subsection>
|
|
</section>
|
|
</body>
|
|
</document>
|