A Remoting transport is represented by a matching pair of classes derived from RemoteClientInvoker and SocketInvoker (see the Central concepts chapter). They are matched in the sense that they share a wire protocol. In the socket transport, the classes are org.jboss.remoting.transport.socket.SocketClientInvoker and org.jboss.remoting.transport.socket.SocketServerInvoker. SocketClientInvoker is, in fact, further subclassed by the actual client invoker class, org.jboss.remoting.transport.socket.MicroSocketClientInvoker.
The socket transport is a relatively low level transport in the sense that it interacts directly with Java sockets and server sockets. SocketServerInvoker is a classic old i/o style server, in which it listens to a server socket and, for each new socket created, it either creates a new worker thread, represented by org.jboss.remoting.transport.socket.ServerThread or reuses an idle ServerThread obtained from a pool. A ServerThread manages a single socket, waiting for an invocation to come in on the wire, passing the invocation to the ServerInvoker which passes it to the appropriate ServerInvokerHandler, and then writing the response to the wire.
On the client side, MicroSocketClientInvoker takes an invocation passed in by a Client, either creates a new connection that wraps a Java socket or reuses an idle connection from a pool, writes the invocation to the socket, and reads and returns the result. An important consideration is the determination of the viability of a pooled connection. A slow but reliable method is to write a byte to the socket and wait for the byte to come back. This method is turned off by default. Another method is for the server side to write a couple of bytes when the connection is closed, and for the client side to check for available bytes. This method is always turned on, but it is less reliable since the server side may be unable to write the bytes, or they may not have arrived yet when the test is made. A palliative for these possibilities is to configure MicroSocketClientInvoker to retry a failed invocation in the event of a java.net.SocketException or certain variants of a java.io.IOException.
A number of parameters may be configured on each side, including, for example, timeout times, pool sizes, and number of retry attempts. Note that most of these are given their default values by JBoss Messaging, EJB2, and EJB3, and, in general, the configured values of the others should not be changed without a good reason.
acceptThreadPriorityIncrement - can be used to increment the priority of the accept thread, which manages the ServerSocket. The value is added to java.lang.Thread.NORM_PRIORITY, and the resulting value must be no more than java.lang.Thread.MAX_PRIORITY. This parameter might be useful on a heavily loaded machine if the accept thread is getting starved. Introduced in release 2.5.4.SP2.
backlog - the preferred number of unaccepted incoming connections allowed at a given time. The actual number may be greater than the specified backlog. When the queue is full, further connection requests are rejected. The default value is 200.
continueAfterTimeout - indicates what a ServerThread should do after experiencing a java.net.SocketTimeoutException. If set to true, or if JBoss Serialization is being used (which is never the case, by default, which is why JBoss Serialization is not discussed in this guide), the server thread will continue to wait for the next invocation; otherwise, it will return itself to the thread pool. For Java serialization, the default value is false.
evictabilityTimeout - indicates the number of milliseconds during which a ServerThread waiting for the next invocation will not be interruptible. The default value is 10000 milliseconds.
idleTimeout - indicates the number of seconds a pooled ServerThread can be idle, that is, waiting on the next invocation, before it should be removed from the thread pool. The value for this property must be greater than zero in order to enable idle timeouts. The default value is -1.
immediateShutdown - indicates, when set to "true", that, when Connector.stop() is called and it calls SocketServerInvoker.stop(), all ServerThreads are shut down immediately, even if they are processing an invocation. The default value is false.
maxPoolSize - the maximum number of ServerThreads that can exist at any given time. The default value is 300.
numAcceptThreads - the number of threads listening on the ServerSocket. The default value is 1.
serverSocketClass - specifies the fully qualified class name for a custom SocketWrapper implementation to use on the server. By default, org.jboss.remoting.transport.socket.ServerSocketWrapper is used. JBoss Messaging uses a custom wrapper.
socket.check_connection - indicates if a client side pooled connection should be checked by sending a single byte from the client to the server and then back to the client. This parameter needs to be set on both client and server to work. It is false by default.
timeout - the socket timeout value passed to the Socket.setSoTimeout() method. The default on the server side is 60000 milliseconds.
writeTimeout - a timeout value imposed on socket write operations. This feature is enabled by setting writeTimeout to a value, in milliseconds, greater than zero. By default, the feature is not enabled.
The following socket parameters, in addition to SO_TIMEOUT, can be configured on the server side: SO_KEEPALIVE, OOBINLINE, SO_RCVBUF, SO_REUSEADDR, SO_SNDBUF, SO_LINGER, and "traffic class". They are configured by passing the following parameter keys to SocketServerInvoker:
keepAlive - sets socket parameter SO_KEEPALIVE
oOBInline - sets socket parameter OOBINLINE
receiveBufferSize - sets socket parameter SO_RCVBUF
reuseAddress - sets socket parameter SO_REUSEADDR
sendBufferSize - sets socket parameter SO_SNDBUF
soLinger - sets socket parameter SO_LINGER
soLingerDuration - when socket parameter SO_LINGER is set to "true", sets linger duration
trafficClass - sets socket traffic class
clientMaxPoolSize - the maximum number of socket connections that can exist at any given time. The default value is 50.
clientSocketClass - specifies the fully qualified class name for a custom SocketWrapper implementation to use on the client. By default, org.jboss.remoting.transport.socket.ClientSocketWrapper is used. JBoss Messaging uses a custom wrapper.
generalizeSocketException - If set to false, a failed invocation will be retried in the case of SocketExceptions. If set to true, a failed invocation will be retried in the case of SocketExceptions and also any IOException whose message matches the regular expression ^.*(?:connection.*reset|connection.*closed|connection.*abort|broken.*pipe|connection.*shutdown).*$. See also the "numberOfCallRetries" parameter, below. The default value is false.
numberOfCallRetries - the number of times a failed invocation will be retried. For example, it is possible that the server side of a socket connection could time out, leaving the connection invalid. In that case, the socket will be discarded and another, possibly new, socket will be used. After numberOfCallRetries attempts, an InvocationFailureException, whose cause is the original exception, will be thrown. The default value is 3. See also the "generalizeSocketException" parameter, above.
socket.check_connection - indicates if a client side pooled connection should be checked by sending a single byte from the client to the server and then back to the client. This parameter needs to be set on both client and server to work. It is false by default.
timeout - The socket timeout value passed to the Socket.setSoTimeout() method. The default on the client side is 1800000 milliseconds (30 minutes).
useOnewayConnectionTimeout - indicates if, during a client side oneway invocation, MicroSocketClientInvoker should wait for a version byte from the server, which prevents the anomalous behavior described in JBREM-706 "In socket transport, prevent client side oneway invocations from artificially reducing concurrency". The default value is true.
writeTimeout - a timeout value imposed on socket write operations. This feature is enabled by setting writeTimeout to a value, in milliseconds, greater than zero. By default, the feature is not enabled.
The following socket parameters, in addition to SO_TIMEOUT, can be configured on the client side: TCP_NODELAY, SO_KEEPALIVE, OOBINLINE, SO_RCVBUF, SO_REUSEADDR, SO_SNDBUF, SO_LINGER, and "traffic class". They are configured by passing the following parameter keys to MicroSocketClientInvoker:
enableTcpNoDelay - sets socket parameter TCP_NODELAY. The default value is false.
keepAlive - sets socket parameter SO_KEEPALIVE
oOBInline - sets socket parameter OOBINLINE
receiveBufferSize - sets socket parameter SO_RCVBUF
reuseAddress - sets socket parameter SO_REUSEADDR. The default value is true.
sendBufferSize - sets socket parameter SO_SNDBUF
soLinger - sets socket parameter SO_LINGER
soLingerDuration - when socket parameter SO_LINGER is set to "true", sets linger duration
trafficClass - sets socket traffic class