The Apache Tomcat Servlet/JSP Container

Apache Tomcat 7

Version 7.0.42, Jul 2 2013
Apache Logo

Links

Top Level Elements

Executors

Connectors

Containers

Nested Components

Cluster Elements

Other

The Cluster Receiver object

Table of Contents
Introduction

The receiver component is responsible for receiving cluster messages. As you might notice through the configuration, is that the receiving of messages and sending of messages are two different components, this is different from many other frameworks, but there is a good reason for it, to decouple the logic for how messages are sent from how messages are received.
The receiver is very much like the Tomcat Connector, its the base of the thread pool for incoming cluster messages. The receiver is straight forward, but all the socket settings for incoming traffic are managed here.

Blocking vs Non-Blocking Receiver

The receiver supports both a non blocking, org.apache.catalina.tribes.transport.nio.NioReceiver, and a blocking, org.apache.catalina.tribes.transport.bio.BioReceiver. It is preferred to use the non blocking receiver to be able to grow your cluster without running into thread starvation.
Using the non blocking receiver allows you to with a very limited thread count to serve a large number of messages. Usually the rule is to use 1 thread per node in the cluster for small clusters, and then depending on your message frequency and your hardware, you'll find an optimal number of threads peak out at a certain number.

Attributes
Common Attributes
AttributeDescription
className The implementation of the receiver component. Two implementations available, org.apache.catalina.tribes.transport.nio.NioReceiver and org.apache.catalina.tribes.transport.bio.BioReceiver.
The org.apache.catalina.tribes.transport.nio.NioReceiver is the preferred implementation
address The address (network interface) to listen for incoming traffic. Same as the bind address. The default value is auto and translates to java.net.InetAddress.getLocalHost().getHostAddress().
direct Possible values are true or false. Set to true if you want the receiver to use direct bytebuffers when reading data from the sockets.
port The listen port for incoming data. The default value is 4000. To avoid port conflicts the receiver will automatically bind to a free port within the range of port <= bindPort < port+autoBind So for example, if port is 4000, and autoBind is set to 10, then the receiver will open up a server socket on the first available port in the range 4000-4009.
autoBind Default value is 100. Use this value if you wish to automatically avoid port conflicts the cluster receiver will try to open a server socket on the port attribute port, and then work up autoBind number of times.
securePort The secure listen port. This port is SSL enabled. If this attribute is omitted no SSL port is opened up. There default value is unset, meaning there is no SSL socket available.
udpPort The UDP listen port. If this attribute is omitted no UDP port is opened up. There default value is unset, meaning there is no UDP listener available.
selectorTimeout The value in milliseconds for the polling timeout in the NioReceiver. On older versions of the JDK there have been bugs, that should all now be cleared out where the selector never woke up. The default value is a very high 5000 milliseconds.
maxThreads The maximum number of threads in the receiver thread pool. The default value is 6 Adjust this value relative to the number of nodes in the cluster, the number of messages being exchanged and the hardware you are running on. A higher value doesn't mean more efficiency, tune this value according to your own test results.
minThreads Minimum number of threads to be created when the receiver is started up. Default value is 6
ooBInline Boolean value for the socket OOBINLINE option. Possible values are true or false.
rxBufSize The receiver buffer size on the receiving sockets. Value is in bytes, the default value is 43800 bytes.
txBufSize The sending buffer size on the receiving sockets. Value is in bytes, the default value is 25188 bytes.
udpRxBufSize The receive buffer size on the datagram socket. Default value is 25188 bytes.
udpTxBufSize The send buffer size on the datagram socket. Default value is 43800 bytes.
soKeepAlive Boolean value for the socket SO_KEEPALIVE option. Possible values are true or false.
soLingerOn Boolean value to determine whether to use the SO_LINGER socket option. Possible values are true or false. Default value is true.
soLingerTime Sets the SO_LINGER socket option time value. The value is in seconds. The default value is 3 seconds.
soReuseAddress Boolean value for the socket SO_REUSEADDR option. Possible values are true or false.
tcpNoDelay Boolean value for the socket TCP_NODELAY option. Possible values are true or false. The default value is true
timeout Sets the SO_TIMEOUT option on the socket. The value is in milliseconds and the default value is 3000 milliseconds.
useBufferPool Boolean value whether to use a shared buffer pool of cached org.apache.catalina.tribes.io.XByteBuffer objects. If set to true, the XByteBuffer that is used to pass a message up the channel, will be recycled at the end of the requests. This means that interceptors in the channel must not maintain a reference to the object after the org.apache.catalina.tribes.ChannelInterceptor#messageReceived method has exited.
NioReceiver
BioReceiver
Comments

Notice: This comments section collects your suggestions on improving documentation for Apache Tomcat.

If you have trouble and need help, read Find Help page and ask your question on the tomcat-users mailing list. Do not ask such questions here. This is not a Q&A section.

The Apache Comments System is explained here. Comments may be removed by our moderators if they are either implemented or considered invalid/off-topic.


Copyright © 1999-2013, Apache Software Foundation