Red Hat Training

A Red Hat training course is available for JBoss Enterprise Application Platform Common Criteria Certification

5.9. Configuring the Remoting Connector

JBoss Messaging uses JBoss Remoting for all communication between the client and the server.
For further information about JBoss Remoting configuration and capabilities, see the [Remoting] chapter in the JBoss 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 $


   <!-- 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"
          display-name="Bisocket Transport Connector">
      <attribute name="Configuration">
            <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>               
               <handler subsystem="JMS">org.jboss.jms.server.remoting.JMSServerInvocationHandler</handler>

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:
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.
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.
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.
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. To work behind a firewall, you may need to specify a particular value for your firewall configuration.
The port that the client uses to connect. Specify this to let your client work with NAT routers.
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 ./ -c [yourconfig] -b [yourIP] command.
If necessary, you can change remoting-bisocket-service.xml to use a different communication port.


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