This is an automated email from the ASF dual-hosted git repository.
markt pushed a commit to branch 10.1.x
in repository https://gitbox.apache.org/repos/asf/tomcat.git
The following commit(s) were added to refs/heads/10.1.x by this push:
new ebed13b349 Fix BZ 62814 - user human-readable names for
[channel|map]SendOptions
ebed13b349 is described below
commit ebed13b349c2085a426af5269bcc3e2b7b87cdf5
Author: Mark Thomas <[email protected]>
AuthorDate: Wed Jan 7 17:05:44 2026 +0000
Fix BZ 62814 - user human-readable names for [channel|map]SendOptions
Documents the human-readable versions of the options. Also notes which
ones are NO-OPs.
https://bz.apache.org/bugzilla/show_bug.cgi?id=62814
Based on PR #929 by archan0621
---
webapps/docs/changelog.xml | 10 ++++
webapps/docs/cluster-howto.xml | 10 ++--
webapps/docs/config/cluster-manager.xml | 47 ++++++++++++++--
webapps/docs/config/cluster-valve.xml | 46 ++++++++++++++--
webapps/docs/config/cluster.xml | 97 +++++++++++++--------------------
5 files changed, 136 insertions(+), 74 deletions(-)
diff --git a/webapps/docs/changelog.xml b/webapps/docs/changelog.xml
index cc62561dcd..aaad510fc2 100644
--- a/webapps/docs/changelog.xml
+++ b/webapps/docs/changelog.xml
@@ -145,6 +145,16 @@
</fix>
</changelog>
</subsection>
+ <subsection name="Cluster">
+ <changelog>
+ <add>
+ <bug>62814</bug>: Document that human-readable names maybe used for
+ <code>mapSendOptions</code> and align documentation with
+ <code>channelSendOptions</code>. Based on pull request <pr>929</pr> by
+ archan0621. (markt)
+ </add>
+ </changelog>
+ </subsection>
<subsection name="Other">
<changelog>
<update>
diff --git a/webapps/docs/cluster-howto.xml b/webapps/docs/cluster-howto.xml
index cc753422e1..441dbf6cc0 100644
--- a/webapps/docs/cluster-howto.xml
+++ b/webapps/docs/cluster-howto.xml
@@ -72,7 +72,7 @@
The following is the default cluster configuration:
</p>
<source><![CDATA[ <Cluster
className="org.apache.catalina.ha.tcp.SimpleTcpCluster"
- channelSendOptions="8">
+ channelSendOptions="async">
<Manager className="org.apache.catalina.ha.session.DeltaManager"
expireSessionsOnShutdown="false"
@@ -275,12 +275,12 @@ should be completed:</p>
<section name="Configuration Example">
<source><![CDATA[ <Cluster
className="org.apache.catalina.ha.tcp.SimpleTcpCluster"
- channelSendOptions="6">
+ channelSendOptions="use_ack,sync">
<Manager className="org.apache.catalina.ha.session.BackupManager"
expireSessionsOnShutdown="false"
notifyListenersOnReplication="true"
- mapSendOptions="6"/>
+ mapSendOptions="use_ack,sync"/>
<!--
<Manager className="org.apache.catalina.ha.session.DeltaManager"
expireSessionsOnShutdown="false"
@@ -321,7 +321,7 @@ should be completed:</p>
Break it down!!
</p>
<source><![CDATA[ <Cluster
className="org.apache.catalina.ha.tcp.SimpleTcpCluster"
- channelSendOptions="6">]]></source>
+ channelSendOptions="use_ack,sync">]]></source>
<p>
The main element, inside this element all cluster details can be
configured.
The <code>channelSendOptions</code> is the flag that is attached to each
message sent by the
@@ -335,7 +335,7 @@ should be completed:</p>
<source><![CDATA[ <Manager
className="org.apache.catalina.ha.session.BackupManager"
expireSessionsOnShutdown="false"
notifyListenersOnReplication="true"
- mapSendOptions="6"/>
+ mapSendOptions="use_ack,sync"/>
<!--
<Manager className="org.apache.catalina.ha.session.DeltaManager"
expireSessionsOnShutdown="false"
diff --git a/webapps/docs/config/cluster-manager.xml
b/webapps/docs/config/cluster-manager.xml
index 1a801737fb..1125ac7ad6 100644
--- a/webapps/docs/config/cluster-manager.xml
+++ b/webapps/docs/config/cluster-manager.xml
@@ -212,12 +212,47 @@
<subsection name="org.apache.catalina.ha.session.BackupManager Attributes">
<attributes>
<attribute name="mapSendOptions" required="false">
- The backup manager uses a replicated map, this map is sending and
- receiving messages. You can setup the flag for how this map is sending
- messages, the default value is <code>6</code>(synchronous).<br/>
- Note that if you use asynchronous messaging it is possible for update
- messages for a session to be processed by the receiving node in a
- different order to the order in which they were sent.
+ <p>The backup manager uses a replicated map. This map sends and
receives
+ messages internally. You can configure the flag that controls how this
+ map sends messages.</p>
+ <p>The value may be specified either as an integer (add values to use
+ multiple flags) or using a comma-separate list of the human-readable
+ option names. Human-readable names are translated to their integer
+ values on startup.</p>
+ <p>The different values offer a tradeoff between throughput on the
+ sending node and the reliability of replication should the sending or
+ receiving node(s) fail.</p>
+ <p>The supported values are:</p>
+ <dl>
+ <dt><code>byte_message</code>, <code>byte</code> or
+ <code>1</code></dt>
+ <dd>The message is a pure byte message and no marshaling or
+ unmarshalling will be performed</dd>
+ <dt><code>use_ack</code> or <code>2</code></dt>
+ <dd>The message is sent and an ACK is received when the message has
+ been received by the recipient. If no ack is received, the
message
+ is not considered successful.</dd>
+ <dt><code>synchronized_ack</code>, <code>sync</code> or
+ <code>4</code></dt>
+ <dd>Has no effect unless <code>use_ack</code> is set. The message is
+ sent and an ACK is received when the message has been received
and
+ processed by the recipient. If no ack is received, the message is
+ not considered successful.</dd>
+ <dt><code>asynchronous</code>, <code>async</code> or
+ <code>8</code></dt>
+ <dd>The message will be placed on a queue and sent by a separate
+ thread. It is possible for update messages for a session to be
+ processed by the receiving node in a different order to the order
+ in which they were sent.</dd>
+ <dt><code>secure</code> or <code>16</code></dt>
+ <dd>Not implemented. Has no effect if used.</dd>
+ <dt><code>udp</code> or <code>32</code></dt>
+ <dd>The message will be sent using UDP instead of TCP.</dd>
+ <dt><code>multicast</code> or <code>64</code></dt>
+ <dd>Not implemented. Messages will not be sent if used.</dd>
+ </dl>
+ <p>The default value is <code>6</code> (<code>use_ack</code> with
+ <code>sync</code>).</p>
</attribute>
<attribute name="maxActiveSessions" required="false">
The maximum number of active sessions that will be created by this
diff --git a/webapps/docs/config/cluster-valve.xml
b/webapps/docs/config/cluster-valve.xml
index c353053afb..7ab3612b27 100644
--- a/webapps/docs/config/cluster-valve.xml
+++ b/webapps/docs/config/cluster-valve.xml
@@ -127,11 +127,47 @@
<p>Sets the host domain to be used for sso cookies.</p>
</attribute>
<attribute name="mapSendOptions" required="false">
- <p>The Valve uses a replicated map. You can setup the flag for how this
- map sends messages. The default value is <code>6</code> (synchronous).
- Note that if you use asynchronous messaging it is possible for update
- messages to be processed by the receiving node in a different order to
- the order in which they were sent.</p>
+ <p>The valve uses a replicated map. This map sends and receives
messages
+ internally. You can configure the flag that controls how this map sends
+ messages.</p>
+ <p>The value may be specified either as an integer (add values to use
+ multiple flags) or using a comma-separate list of the human-readable
+ option names. Human-readable names are translated to their integer
+ values on startup.</p>
+ <p>The different values offer a tradeoff between throughput on the
+ sending node and the reliability of replication should the sending or
+ receiving node(s) fail.</p>
+ <p>The supported values are:</p>
+ <dl>
+ <dt><code>byte_message</code>, <code>byte</code> or
+ <code>1</code></dt>
+ <dd>The message is a pure byte message and no marshaling or
+ unmarshalling will be performed</dd>
+ <dt><code>use_ack</code> or <code>2</code></dt>
+ <dd>The message is sent and an ACK is received when the message has
+ been received by the recipient. If no ack is received, the
message
+ is not considered successful.</dd>
+ <dt><code>synchronized_ack</code>, <code>sync</code> or
+ <code>4</code></dt>
+ <dd>Has no effect unless <code>use_ack</code> is set. The message is
+ sent and an ACK is received when the message has been received
and
+ processed by the recipient. If no ack is received, the message is
+ not considered successful.</dd>
+ <dt><code>asynchronous</code>, <code>async</code> or
+ <code>8</code></dt>
+ <dd>The message will be placed on a queue and sent by a separate
+ thread. It is possible for update messages for a session to be
+ processed by the receiving node in a different order to the order
+ in which they were sent.</dd>
+ <dt><code>secure</code> or <code>16</code></dt>
+ <dd>Not implemented. Has no effect if used.</dd>
+ <dt><code>udp</code> or <code>32</code></dt>
+ <dd>The message will be sent using UDP instead of TCP.</dd>
+ <dt><code>multicast</code> or <code>64</code></dt>
+ <dd>Not implemented. Messages will not be sent if used.</dd>
+ </dl>
+ <p>The default value is <code>6</code> (<code>use_ack</code> with
+ <code>sync</code>).</p>
</attribute>
<attribute name="requireReauthentication" required="false">
<p>Default false. Flag to determine whether each request needs to be
diff --git a/webapps/docs/config/cluster.xml b/webapps/docs/config/cluster.xml
index 95f49f05fb..29337d792f 100644
--- a/webapps/docs/config/cluster.xml
+++ b/webapps/docs/config/cluster.xml
@@ -121,64 +121,45 @@ network, particularly DoS attacks.</p>
</p>
</attribute>
<attribute name="channelSendOptions" required="true">
- <p>The Tribes channel send options, default is <code>8</code>.<br/>
- This option is used to set the flag that all messages sent through the
- SimpleTcpCluster uses. The flag decides how the messages are sent,
and is a simple logical OR.</p>
-
- <source>int options = Channel.SEND_OPTIONS_ASYNCHRONOUS |
- Channel.SEND_OPTIONS_SYNCHRONIZED_ACK |
- Channel.SEND_OPTIONS_USE_ACK;</source>
- <p>Some of the values are:<br/>
- <code>Channel.SEND_OPTIONS_SYNCHRONIZED_ACK = 0x0004</code><br/>
- <code>Channel.SEND_OPTIONS_ASYNCHRONOUS = 0x0008</code><br/>
- <code>Channel.SEND_OPTIONS_USE_ACK = 0x0002</code><br/>
- So to use ACK and ASYNC messaging, the flag would be <code>10</code>
(8+2)
- <br/>
- Note that if you use ASYNC messaging it is possible for update messages
- for a session to be processed by the receiving nodes in a different order
- to the order in which they were sent.
- </p>
- <p>
- The various <code>channelSendOptions</code> values offer a tradeoff
- between throughput on the sending node and the reliability of
- replication should the sending or receiving node(s) fail. Here are
- some common options. "Message" could be any message sent between nodes,
- but only session-change messages are considered, here.
- </p>
- <p>
- <code>channelSendOptions="8"</code> /
<code>channelSendOptions="async"</code>
- As far as the sender is concerned, the message is "sent"
- as soon as it has been placed in the queue on the sender for
- transmission to the other nodes. The message may not reach any or all
- of the recipient nodes and may not be successfully processed on any
- nodes that it does reach. This option offers the highest throughput on
- the sender but the least reliability, as the triggering request will
- complete without any knowledge of the success/failure of the session
- replication.
- </p>
- <p>
- <code>channelSendOptions="2"</code> /
<code>channelSendOptions="use_ack"</code>
- The sender will block the completion of the current request until all
- of the receiving nodes have acknowledged that they have received the
- message, but have not necessarily processed that message. This option
- will result in lower throughput on the sending node, because the
message
- must be transmitted and the acknowledgement received, but the
- reliability is greater than the asynchronous model.
- </p>
- <p>
- <code>channelSendOptions="6"</code> /
<code>channelSendOptions="sync,use_ack"</code>
- The sender will block the completion of the current request until
- all of the receiving nodes have acknowledged that they have received
- <u>and</u> processed the message. This option will have the lowest
- throughput (of these three) but the greatest reliability.
- </p>
- <p>
- You may also set these options as a comma separated string, e.g. "async,
multicast", which
- will be translated into <code>Channel.SEND_OPTIONS_ASYNCHRONOUS |
Channel.SEND_OPTIONS_MULTICAST</code>
- <br/>
- The valid option names are "asynchronous" (alias "async"),
"byte_message" (alias "byte")
- , "multicast", "secure", "synchronized_ack" (alias "sync"), "udp",
"use_ack"
- </p>
+ <p>The Tribes channel send options. This option is used for all
messages
+ sent through the SimpleTcpCluster.</p>
+ <p>The value may be specified either as an integer (add values to use
+ multiple flags) or using a comma-separate list of the human-readable
+ option names. Human-readable names are translated to their integer
+ values on startup.</p>
+ <p>The different values offer a tradeoff between throughput on the
+ sending node and the reliability of replication should the sending or
+ receiving node(s) fail.</p>
+ <p>The supported values are:</p>
+ <dl>
+ <dt><code>byte_message</code>, <code>byte</code> or
+ <code>1</code></dt>
+ <dd>The message is a pure byte message and no marshaling or
+ unmarshalling will be performed</dd>
+ <dt><code>use_ack</code> or <code>2</code></dt>
+ <dd>The message is sent and an ACK is received when the message has
+ been received by the recipient. If no ack is received, the
message
+ is not considered successful.</dd>
+ <dt><code>synchronized_ack</code>, <code>sync</code> or
+ <code>4</code></dt>
+ <dd>Has no effect unless <code>use_ack</code> is set. The message is
+ sent and an ACK is received when the message has been received
and
+ processed by the recipient. If no ack is received, the message is
+ not considered successful.</dd>
+ <dt><code>asynchronous</code>, <code>async</code> or
+ <code>8</code></dt>
+ <dd>The message will be placed on a queue and sent by a separate
+ thread. It is possible for update messages for a session to be
+ processed by the receiving node in a different order to the order
+ in which they were sent.</dd>
+ <dt><code>secure</code> or <code>16</code></dt>
+ <dd>Not implemented. Has no effect if used.</dd>
+ <dt><code>udp</code> or <code>32</code></dt>
+ <dd>The message will be sent using UDP instead of TCP.</dd>
+ <dt><code>multicast</code> or <code>64</code></dt>
+ <dd>Not implemented. Messages will not be sent if used.</dd>
+ </dl>
+ <p>The default value is <code>8</code> (<code>async</code>).</p>
</attribute>
<attribute name="channelStartOptions" required="false">
<p>Sets the start and stop flags for the <Channel> object used by
the cluster.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
