5.11. Configuring the Remoting Connector

JBoss Messaging uses JBoss Remoting for all communication between the client and the server.
For more information about JBoss Remoting configuration and capabilities, refer to the Remoting chapter in the Administration and Configuration Guide.
The default configuration includes one remoting connector, which is used by the single default connection factory. Each connection factory can be configured to use a different connector.
The default connector is configured to use the remoting bisocket transport, a TCP socket-based transport that listens and accepts connections only on the server side. That is, connections are always initiated from the client side. This connector is ideal for typical firewall scenarios, where only inbound connections are allowed on the server, or where only outbound connections are allowed from the client.
The bisocket transport can be configured to use SSL when a higher level of security is required.
The other supported transport is the HTTP transport, which uses the Hypertext Transfer Protocol to communicate between client and server. The client periodically polls the server for messages to receive data. This transport is ideal when a firewall between server and client allows only incoming HTTP traffic on the server. Because of its polling behavior and the limitations of HTTP, this transport does not perform as well as the bisocket transport. It is not designed to handle high-load situations.
No other remoting transports are currently supported by JBoss Messaging.
Remoting configuration details can be seen in $JBOSS_HOME/server/$SERVER/deploy/messaging/remoting-bisocket-service.xml. The following code is an example of a bisocket remoting configuration:

Example 5.2. Bisocket Remoting Configuration

<?xml version="1.0" encoding="UTF-8"?>

<!-- Standard bisocket-based Remoting service deployment descriptor. $Id: 
 remoting-bisocket-service.xml 3981 2008-03-28 18:00:41Z timfox $ -->

<server>
 <!-- Standard bisocket connector - the bisocket transport only opens connection 
  from client->server so can be used with firewalls where only outgoing connections 
  are allowed. For examples of HTTP and SSL transports see docs/examples -->
 <mbean code="org.jboss.remoting.transport.Connector"
  name="jboss.messaging:service=Connector,transport=bisocket"
  display-name="Bisocket Transport Connector">
  <attribute name="Configuration">
   <config>
    <invoker transport="bisocket">

     <!-- There should be no reason to change these parameters - warning! 
      Changing them may stop JBoss Messaging working correctly -->
     <attribute name="marshaller" isParam="true">org.jboss.jms.wireformat.JMSWireFormat
     </attribute>
     <attribute name="unmarshaller" isParam="true">org.jboss.jms.wireformat.JMSWireFormat
     </attribute>
     <attribute name="dataType" isParam="true">jms</attribute>
     <attribute name="socket.check_connection" isParam="true">false</attribute>
     <attribute name="serverBindAddress">${jboss.bind.address}</attribute>
     <attribute name="serverBindPort">${jboss.messaging.connector.bisocket.port:4457}
     </attribute>
     <attribute name="clientSocketClass" isParam="true">
     org.jboss.jms.client.remoting.ClientSocketWrapper
     </attribute>
     <attribute name="serverSocketClass">org.jboss.jms.server.remoting.ServerSocketWrapper
     </attribute>
     <attribute name="onewayThreadPool">org.jboss.jms.server.remoting.DirectThreadPool
     </attribute>

     <!-- the following parameters are useful when there is a firewall between 
      client and server. Uncomment them if so. -->
     <!-- <attribute name="numberOfCallRetries" isParam="true">1</attribute> 
      <attribute name="pingFrequency" isParam="true">214748364</attribute> 
      <attribute name="pingWindowFactor" isParam="true">10</attribute> 
      <attribute name="generalizeSocketException" isParam="true">true</attribute> -->

     <!-- Now remoting supports socket write timeout configuration. Uncomment 
      this if you need it. -->
     <!-- <attribute name="writeTimeout" isParam="true">30000</attribute> -->

     <!-- End immutable parameters -->

     <attribute name="stopLeaseOnFailure" isParam="true">true</attribute>

     <!-- Periodicity of client pings. Server window by default is twice 
      this figure -->
     <attribute name="clientLeasePeriod" isParam="true">10000</attribute>
     <attribute name="validatorPingPeriod" isParam="true">10000</attribute>
     <attribute name="validatorPingTimeout" isParam="true">5000</attribute>

     <attribute name="failureDisconnectTimeout" isParam="true">0</attribute>
     <attribute name="callbackErrorsAllowed">1</attribute>
     <attribute name="registerCallbackListener">false</attribute>
     <attribute name="useClientConnectionIdentity" isParam="true">true</attribute>

     <attribute name="timeout" isParam="true">0</attribute>

     <!-- Max Number of connections in client pool. This should be significantly 
      higher than the max number of sessions/consumers you expect -->
     <attribute name="JBM_clientMaxPoolSize" isParam="true">200</attribute>

     <!-- The maximum time to wait before timing out on trying to write a 
      message to socket for delivery -->
     <attribute name="callbackTimeout">10000</attribute>

     <!-- Use these parameters to specify values for binding and connecting 
      control connections to work with your firewall/NAT configuration 
      <attribute name="secondaryBindPort">xyz</attribute> 
      <attribute name="secondaryConnectPort">abc</attribute> -->

    </invoker>
    <handlers>
     <handler subsystem="JMS">org.jboss.jms.server.remoting.JMSServerInvocationHandler
     </handler>
    </handlers>
   </config>
  </attribute>
 </mbean>
</server>
There are restricted attributes that should not be changed unless you are absolutely confident you understand the impact of the changes. The following attributes are safe to change and configure to the requirements of your project:
clientLeasePeriod
Clients periodically return heartbeats to the server to confirm that they are still active. If the server does not receive a heartbeat after a certain period of time, it will close down the connection and remove all resources that correspond to the client's session. The clientLeasePeriod determines the period of time between heartbeats, in milliseconds. The default value is 10000.
By default, the server closes a client if it does not receive a heartbeat within double the clientLeasePeriod. In reality, the period is automatically resized according to system load.
numberOfRetries
The number of seconds JBoss Remoting blocks on the client pool while waiting for a connection to become available. If you have a very large number of sessions concurrently accessing the server from a client and cannot obtain connections from the pool, you may want to increase this value.
clientMaxPoolSize
JBoss Remoting maintains a client-side pool of TCP connections on which to service requests. If you have a large number of sessions concurrently accessing the server from a client and cannot obtain connections from the pool, you may want to increase this value.
secondaryBindPort
The bisocket transport uses control connections to pass control messages between server and client. This attribute defines the address to which the secondary ServerSocket is bound. Its value is random by default. To work behind a firewall, you need to set it to a particular value and create a rule for it in the firewall configuration. The recommended value is 4458 because the primary port is 4457.
secondaryConnectPort
The port that the client uses to connect. Specify this to let your client work with NAT routers.
maxPoolSize
The number of threads used on the server side to service requests.
By default, JBoss Messaging binds to ${jboss.bind.address}, which can be defined by running the ./run.sh -c [yourconfig] -b [yourIP] command.
If necessary, you can change remoting-bisocket-service.xml to use a different communication port.

Warning

Do not change values in the connector configuration other than those listed above. Changing other values can cause JBoss Messaging to stop functioning correctly.