JBoss Remoting Guide

The simplest way to configure a Connector is to pass an InvokerLocator to a Connector constructor. For example, the code fragment

String locatorURI = "socket://test.somedomain.com:8084";
String params = "/?clientLeasePeriod=10000&timeout=120000";
locatorURI += params;
InvokerLocator locator = new InvokerLocator(locatorURI);
Connector connector = new Connector(locator);
connector.create();
SampleInvocationHandler invocationHandler = new SampleInvocationHandler();
connector.addInvocationHandler("sample", invocationHandler);
connector.start();

creates a server invoker based on the socket transport, directs it to listen for invocations on port 8084 of host test.somedomain.com, and passes two configuration parameters, "clientLeasePeriod" and "timeout". It also supplies the server invoker with an invocation handler.

One limitation of the InvokerLocator is that it can only represent string values. An alternative that overcomes this limitation is to pass some or all of the parameters to the Connector by way of a configuration map. The following code fragment accomplishes all that the previous fragment does, but it passes one parameter by way of the InvokerLocator and passes the other by way of a configuration map. It also passes in a non-string object, a ServerSocketFactory:

String locatorURI = "socket://test.somedomain.com:8084";
String params = "/?clientLeasePeriod=10000";
locatorURI += params;
InvokerLocator locator = new InvokerLocator(locatorURI);
HashMap config = new HashMap();
config.put(ServerInvoker.TIMEOUT, 120000);
config.put(ServerInvoker.SERVER_SOCKET_FACTORY, new MyServerSocketFactory());
Connector connector = new Connector(locator, config);
connector.create();
SampleInvocationHandler invocationHandler = new SampleInvocationHandler();
connector.addInvocationHandler("sample", invocationHandler);
connector.start();

Note that the value of ServerInvoker.TIMEOUT is "timeout", and the value of ServerInvoker.SERVER_SOCKET_FACTORY is "serverSocketFactory". These configuration map keys are discussed throughout the chapter and accumulated in section Configuration by properties. Also, server socket factory configuration is covered in Socket factories and server socket factories.

A third programmatic option is available for those configuration properties which happen to be server invoker MBean properties. In the following fragment, the server invoker is obtained from the Connector and a ServerSocketFactory is passed to it by way of a setter method:

String locatorURI = "socket://test.somedomain.com:8084";
String params = "/?clientLeasePeriod=10000";
locatorURI += params;
InvokerLocator locator = new InvokerLocator(locatorURI);
HashMap config = new HashMap();
config.put(ServerInvoker.TIMEOUT, 120000);
Connector connector = new Connector(locator, config);
connector.create();
ServerInvoker serverInvoker = connector.getServerInvoker();
ServerSocketFactory ssf = new MyServerSocketFactory();
serverInvoker.setServerSocketFactory(ssf);
SampleInvocationHandler invocationHandler = new SampleInvocationHandler();
connector.addInvocationHandler("sample", invocationHandler);
connector.start();

Note. The Connector creates the server invoker during the call to Connector.create(), so this option only works after that method has been called. Also, depending on the parameter and the transport, this option may or may not be effective after the call to Connector.start(), which calls start() on the server invoker.

A fourth option, which exists primarily to support the declarative mode of configuration presented below, is to pass an XML document to the Connector. The following fragment duplicates the behavior of the first and second examples above.

HashMap config = new HashMap();
config.put(ServerInvoker.TIMEOUT, 120000);
Connector connector = new Connector(config);

// Set xml configuration element.
StringBuffer buf = new StringBuffer();
buf.append("<?xml version=\"1.0\"?>\n");
buf.append("<config>");
buf.append("   <invoker transport=\"socket\">");
buf.append("      <attribute name=\"serverBindAddress\">test.somedomain.com</attribute>");
buf.append("      <attribute name=\"serverBindPort\">8084</attribute>");
buf.append("      <attribute name=\"clientLeasePeriod\">10000</attribute>");
buf.append("   </invoker>");
buf.append("   <handlers>");
buf.append("      <handler subsystem=\"mock\">");
buf.append("         org.jboss.remoting.transport.mock.SampleInvocationHandler");
buf.append("      </handler>");
buf.append("   </handlers>");
buf.append("</config>");

ByteArrayInputStream bais = new ByteArrayInputStream(buf.toString().getBytes());
Document xml = DocumentBuilderFactory.newInstance().newDocumentBuilder().parse(bais);
connector.setConfiguration(xml.getDocumentElement());

connector.create();
connector.start();

Note that there is no InvokerLocator in this example. If the Connector gets an InvokerLocator, it ignores the presence of the xml document. Note also that this method only supports the use of string values, so it is necessary to include the fully qualified name of the invocation handler, from which the handler is created by calling the default constructor.

An example of this option in use can be found in org.jboss.test.remoting.configuration.SocketClientConfigurationTestCase.

A fifth option, which exists primarily to support the injection of POJOs in the presence of the JBoss Microcontainer, is to pass an org.jboss.remoting.ServerConfiguration object to the Connector.setServerConfiguration() method. The following fragment duplicates the behavior of the first and second examples above.

HashMap config = new HashMap();
config.put(ServerInvoker.TIMEOUT, 120000);
Connector connector = new Connector(config);

// Create ServerConfiguration object for socket transport
ServerConfiguration serverConfig = new ServerConfiguration("socket");

// Add invokerLocatorParameters (applicable to client and server)
Map locatorConfig = new HashMap();
locatorConfig.put("serverBindAddress", "test.somedomain.com");
locatorConfig.put("serverBindPort", "8084");
serverConfig.setInvokerLocatorParameters(locatorConfig);

// Add serverParameters (applicable to server)
Map serverParameters = new HashMap();
locatorConfig.put("clientLeasePeriod", "10000");
serverConfig.setServerParameters(serverParameters);

// Add invocation handlers
Map handlers = new HashMap();
handlers.put("mock", "org.jboss.remoting.transport.mock.SampleInvocationHandler");
serverConfig.setInvocationHandlers(handlers);

connector.setServerConfiguration(serverConfig);
connector.create();
connector.start();

For more information about ServerConfiguration, see the section "Declarative configuration: POJOs".

One configuration option discussed in Section Programmatic configuration, passing an XML document to the Connector, works in conjunction with the service archive deployer (SARDeployer) inside the JBoss Application Server to allow declarative configuration on the server side. In particular, the SARDeployer reads XMl documents containing MBean descriptors from files whose name has the form "*-service.xml". When it sees a descriptor for a Connector MBean, it passes the descriptor's <config> element to a newly created Connector.

There are two ways in which to specify the server invoker configuration via a service xml file. The first is to specify just the InvokerLocator attribute as a sub-element of the Connector MBean. For example, a possible configuration for a Connector using a socket invoker that is listening on port 8084 on the test.somedomain.com address would be:

<mbean code="org.jboss.remoting.transport.Connector"
       name="jboss.remoting:service=Connector,transport=Socket"
       display-name="Socket transport Connector">
   <attribute name="InvokerLocator">
      <![CDATA[socket://test.somedomain.com:8084]]>
   </attribute>
   <attribute name="Configuration">
      <config>
         <handlers>
            <handler subsystem="mock">
               org.jboss.remoting.transport.mock.MockServerInvocationHandler
            </handler>
         </handlers>
      </config>
   </attribute>
</mbean>

Note that all the server side socket invoker configurations will be set to their default values in this case. Also, it is important to add CDATA to any locator uri that contains more than one parameter.

The other way to configure the Connector and its server invoker in greater detail is to provide an invoker sub-element within the config element of the Configuration attribute. The only attribute of invoker element is transport, which will specify which transport type to use (e.g.. socket, rmi, or http). All the sub-elements of the invoker element will be attribute elements with a name attribute specifying the configuration property name and then the value. An isParam attribute can also be added to indicate that the attribute should be added to the locator uri, in the case the attribute needs to be used by the client. An example using this form of configuration is as follows:

<mbean code="org.jboss.remoting.transport.Connector"
       name="jboss.remoting:service=Connector,transport=Socket"
       display-name="Socket transport Connector">
   
   <attribute name="Configuration">
      <config>
          
         <invoker transport="socket">
            <attribute name="numAcceptThreads">1</attribute>
            <attribute name="maxPoolSize">303</attribute>
            <attribute name="clientMaxPoolSize" isParam="true">304</attribute>
            <attribute name="socketTimeout">60000</attribute>
            <attribute name="serverBindAddress">192.168.0.82</attribute>
            <attribute name="serverBindPort">6666</attribute>
            <attribute name="clientConnectAddress">216.23.33.2</attribute>
            <attribute name="clientConnectPort">7777</attribute>
            <attribute name="enableTcpNoDelay" isParam="true">false</attribute>
            <attribute name="backlog">200</attribute>
         </invoker>
         
         <handlers>
            <handler subsystem="mock">
               org.jboss.remoting.transport.mock.MockServerInvocationHandler
            </handler>
         </handlers>
      </config>
   </attribute>
   
</mbean>

Also note that ${jboss.bind.address} can be used for any of the bind address properties, which will be replaced with the bind address specified to JBoss when starting (i.e. via the -b option).

All the attributes set in this configuration could be set directly in the locator uri of the InvokerLocator attribute value, but would be much more difficult to decipher visually and is more prone to editing mistakes.

One of the components of a locator uri that can be expressed within the InvokerLocator attribute is the path. For example, can express a locator uri path of 'foo/bar' via the InvokerLocator attribute as:

<attribute name="InvokerLocator">
   <![CDATA[socket://test.somedomain.com:8084/foo/bar]]>
</attribute>

To include the path using the Configuration attribute, can include a specific 'path' attribute. So the same InvokerLocator can be expressed as follows with the Configuration attribute:

<attribute name="Configuration">
   <config>
      <invoker transport="socket">
         <attribute name="serverBindAddress">test.somedomain.com</attribute>
         <attribute name="serverBindPort">8084</attribute>
         <attribute name="path">foo/bar</attribute>
      </invoker>
      ...

Note: The value for the 'path' attribute should NOT start or end with a / (slash).

The last configuration option discussed in Section Programmatic configuration, passing an org.jboss.remoting.ServerConfiguration object to the Connector.setServerConfiguration() method, works in conjunction with the JBoss Microcontainer, which supports the injection of POJOs. In particular, the Microcontainer reads XML documents containing POJO descriptors from files whose name has the form "*-beans.xml".

A ServerConfiguration object holds four components:

A sample remoting-beans.xml file which duplicates the example in the previous sections is:

<?xml version="1.0" encoding="UTF-8"?>
<deployment xmlns="urn:jboss:bean-deployer:2.0">
            
   <bean name="remoting:invocationHandler"
         class="org.jboss.remoting.transport.mock.SampleInvocationHandler"/>
             
   <bean name="remoting:serverConfiguration"
         class="org.jboss.remoting.ServerConfiguration">
      <constructor>
         <parameter>socket</parameter>
      </constructor>
      <property name="invokerLocatorParameters">
         <map keyClass="java.lang.String" valueClass="java.lang.String">
            <entry>
               <key>serverBindAddress</key>
               <value>test.somedomain.com</value>
            </entry>
            <entry>
               <key>serverBindPort</key>
               <value>8084</value>
            </entry>
         </map>
      </property>
      <property name="serverParameters">
         <map keyClass="java.lang.String" valueClass="java.lang.String">
            <entry>
               <key>clientLeasePeriod</key>
               <value>10000</value>
            </entry>
         </map>
      </property>
      <property name="invocationHandlers">
         <map keyClass="java.lang.String" 
              valueClass="org.jboss.remoting.ServerInvocationHandler">
            <entry>
               <key>mock</key>
               <value><inject bean="remoting:invocationHandler"/></value>
            </entry>
         </map>
      </property>
   </bean>
             
   <bean name="remoting:connector" class="org.jboss.remoting.transport.Connector">
      <property name="serverConfiguration">
         <inject bean="remoting:serverConfiguration"/>
      </property>
   </bean>
             
</deployment>

For more information about using the JBoss Microcontainer, see http://www.jboss.org/jbossmc/.

Remoting supports asynchronous computation and delivery of results through a callback mechanism, as described in Section Callbacks. Callbacks are sent from the server side to the client side on a callback connection which is the reverse of the usual client to server connection. That is, a client invoker on the server side communicates with a server invoker on the client side (in the case of push callbacks - again, see Section Callbacks). When a callback connection is created, all of the configuration information passed to the server side Connector is passed on to the server side callback client invoker. It follows that callback client invokers are configured by way of the server side Connector.

Before version 2.4, a Remoting server could bind to only one specific IP address. In particular, the address 0.0.0.0 was translated to the host returned by java.net.InetAddress.getLocalHost() (or its equivalent IP address). As of version 2.4 [and later releases in the 2.2 series], a server started with the address 0.0.0.0 binds to all available interfaces.

Note. If 0.0.0.0 appears in the InvokerLocator, it needs to be translated to an address that is usable on the client side. If the system property InvokerLocator.BIND_BY_HOST (actual value "remoting.bind_by_host") is set to "true", the InvokerLocator host will be transformed to the value returned by InetAddress.getLocalHost().getHostName(). Otherwise, it will be transformed to the value returned by InetAddress.getLocalHost().getHostAddress().

As of release 2.4, besides binding to all available interfaces, it is also possible to configure a server to bind to a subset of the interfaces available on a given host. Suppose, for example, that a host machine has NICs configured with addresses 10.32.4.2, 192.168.4.2, and 192.168.8.2, and suppose that 192.168.8.2 is on a LAN from which access is meant to be denied. It is now possible to create a single server that binds to 10.32.4.2 and 192.168.4.2.

It would be convenient to be able to create an InvokerLocator that looks something like:

socket://10.32.4.2&192.168.4.2:6500

but, unfortunately, that violates the URI syntax. Instead, a special placeholder, "multihome", is used in the host position, and the actual host addresses are given in the query component, e.g.,

socket://multihome/?homes=10.32.4.2:6500!192.168.4.2:6500

An abbreviated syntax allows factoring out the bind port:

socket://multihome:6500/?homes=10.32.4.2!192.168.4.2

The value in the port position is treated as a default value which can be overriden in the "homes" parameter:

socket://multihome:6500/?homes=10.32.4.2!192.168.4.2:6501

binds to 10.32.4.2:6500 and 192.168.4.2:6501.

In the presence of a NAT router, it may be necessary for the client to connect to addresses different than the bind addresses, and a set of connect addresses may be specified with a "connecthomes" parameter:

socket://multihome/?homes=10.32.4.2:6500!192.168.4.2:6501
       &connecthomes=10.32.42.2:7500!192.168.42.2:7501

specifies a server that binds to 10.32.4.2:6500 and 192.168.4.2:6501, as before, but now a client connects to it using the addresses 10.32.42.2:7500 and 192.168.42.2:7501.

Multihome servers may be configured, also, in *-service.xml MBean files and *-beans.xml POJO files. The following MBean definition is equivalent to the preceding locator:

<mbean code="org.jboss.remoting.transport.Connector"
       name="jboss.remoting:service=Connector,transport=Socket"
       display-name="Socket transport Connector">
    
   <attribute name="Configuration">
      <config>
         <invoker transport="socket">
            
            <attribute name="homes">
               <home>10.32.4.2:6500</home>
               <home>192.168.4.2:6501</home>
            </attribute>
            <attribute name="connecthomes">
               <connecthome>10.32.42.2:7500</connecthome>
               <connecthome>192.168.42.2:7501</connecthome>
            </attribute>
            
         </invoker>
         <handlers>
            ...
         </handlers>
      </config>
   </attribute>
</mbean>

The "serverBindPort" and "clientConnectPort" attributes may be used to give default values for bind ports and connect ports, respectively.

The same server may be configured with the org.jboss.remoting.ServerInvocation object as well. For example,

Connector connector = new Connector();
         
// Create ServerConfiguration object for socket transport
ServerConfiguration serverConfig = new ServerConfiguration("socket");
            
// Add invokerLocatorParameters (applicable to client and server)
Map locatorConfig = new HashMap();

locatorConfig.put("homes", "10.32.4.2:6500!192.168.4.2:6501");
locatorConfig.put("connecthomes", "10.32.42.2:7500!192.168.42.2:7501");

serverConfig.setInvokerLocatorParameters(locatorConfig);
                   
// Add invocation handlers
...
             
connector.setServerConfiguration(serverConfig);
connector.create();
connector.start();

is equivalent to the preceding MBean definition.

Note. The Strings "homes" and "connecthomes" are available as constants in the InvokerLocator class: InvokerLocator.HOMES_KEY and InvokerLocator.CONNECT_HOMES_KEY.

Sometimes it is useful to be able to grab a socket right after it has been created to either apply some additional configuration or retrieve some information. It is possible to configure Remoting with instantions of the interface org.jboss.remoting.socketfactory.SocketCreationListener

public interface SocketCreationListener
{
   /**
    * Called when a socket has been created.
    * 
    * @param socket socket that has been created
    * @param source SocketFactory or ServerSocket that created the socket
    * @throws IOException
    */
   void socketCreated(Socket socket, Object source) throws IOException;
}

Socket creation listeners can be configured through the use of the keys org.jboss.remoting.Remoting.SOCKET_CREATION_CLIENT_LISTENER (actual value "socketCreationClientListener") and org.jboss.remoting.Remoting.SOCKET_CREATION_SERVER_LISTENER (actual value "socketCreationServerListener"), which install listeners for javax.net.SocketFactorys and java.net.ServerSockets, respectively. The value associated with these keys may be (1) an object that implements SocketCreationListener or (2) a string that names a class that implements SocketCreationListener. In the latter case, the default constructor will be used to create an object of the designated class.

All of the transports (bisocket, sslbisocket, http, https, rmi, sslrmi, servlet, sslservlet, socket, and sslsocket) capture the IP address of the client side of a TCP connection from client to server and make it available to application code on both the client side and server side. On the client side, the method org.jboss.remoting.Client.getAddressSeenByServer(), with signature

public InetAddress getAddressSeenByServer() throws Throwable

returns the IP address of the client as seen by the server. On the server side, the same IP address is placed in the request payload map held by the org.jboss.remoting.InvocationRequest. It may be retrieved by the org.jboss.remoting.ServerInvocationHandler as follows:

public Object invoke(InvocationRequest invocation throws Throwable
{
   ...
   InetAddress address = invocation.getRequestPayload().get(Remoting.CLIENT_ADDRESS);
   ...
}

org.jboss.remoting.InvokerLocator will now accept IPv6 IP addresses. For example,

socket://[::1]:3333/?timeout=10000
socket://[::]:4444/?timeout=10000
socket://[::ffff:127.0.0.1]:5555/?timeout=10000
socket://[fe80::205:9aff:fe3c:7800%7]:6666/?timeout=10000
socket://multihome/?homes=[fe80::205:9aff:fe3c:7800%7]:7777![fe80::214:22ff:feef:68bb%4]:8888

Multiple clients may share a single client invoker. For example, in the code

InvokerLocator locator = new InvokerLocator("socket://127.0.0.1:5555");
Client client1 = new Client(locator);
Client client2 = new Client(locator);

client1 and client2 will both communicate with the server through a single org.jboss.remoting.transport.socket.MicroSocketClientInvoker. The number of Clients using a single client invoker is tracked, and the invoker is destroyed when the count goes to zero. It may be useful to delay the destruction of the invoker when it is known that another Client will want to use it in the near future. The delayed destruction of a client invoker may be achieved through the use of the key Client.INVOKER_DESTRUCTION_DELAY (actual value "invokerDestructionDelay"). For example,

InvokerLocator locator =
        new InvokerLocator("socket://127.0.0.1:5555/?invokerDestructionDelay=5000");
Client client = new Client(locator);
client.connect();
...
client.disconnect();

will cause client to delay the destruction of its client invoker (assuming client is the only user), by 5000 milliseconds. Of course, "invokerDestructionDelay" may be passed to the Client by way of a configuration map, as well.

Server

When the socket server invoker is started, it will create one, and only one, instance of java.net.ServerSocket for each configured bind address. Typically there would exactly one ServerSocket, but there would be more than one for a mltihome server with multiple bind addresses. Upon being started, it will also create and start a number of threads to be used for accepting incoming requests from the ServerSocket. These threads are called the accept threads and the number of them created is controlled by the "numAcceptThreads" property. If "numAcceptThreads" is set to "n" (it defaults to 1), there will be "n" accept threads per ServerSocket. When these accept threads are started, they will call accept() on the ServerSocket and block until the ServerSocket receives a request from a client, where it will return a Socket back to the accept thread who called the accept() method. As soon as this happens, the accept thread will try to pass off the Socket to another thread for processing.

The threads that actually process the incoming request, referred to as server threads (org.jboss.remoting.transport.socket.ServerThread), are stored in a pool. The accept thread will try to retrieve the first available server thread from the pool and hand off the Socket for processing. If the pool does not contain any available server threads and the max pool size has not been reached, a new server thread will be created for processing. Otherwise, if the max pool size has been reached, the accept thread will wait for one to become available (will wait until socket timeout has been reached). The size of the server thread pool is defined by the 'maxPoolSize' property. As soon as the accept thread has been able to hand off the Socket to a server thread for processing, it will loop back to ServerSocket and call accept() on it again. This will continue until the socket server invoker is stopped.

The server thread processing the request will be the thread of execution through the unmarshalling of the data, calling on the server invocation handler, and marshalling of response back to the client. After the response has been sent, the server thread will then hold the socket connection and wait for another request to come from this client. It will wait until the socket is closed by the client, a socket timeout occurs, or receives another request from the client in which to process. When the client socket connection session is closed, meaning timeout or client closed socket connection, then the thread will return itself to the pool.

If all the server threads from the pool are in use, meaning have a client connection established, and the pool has reached its maximum value, the accept threads (no matter how many there are) will have to wait until one of the server threads is available for processing. This why having a large number of accept threads does not provide any real benefit. If all the accept threads are blocked waiting for server thread, new client requests will then be queued until it can be accepted. The number of requests that can be queued is controlled by the "backlog" property and can be useful in managing sudden bursts in requests.

If take an example with a socket server invoker that has max pool set to 300, accept threads is 2, and backlog is 200, will be able to make 502 concurrent client calls. The 503rd client request will get an exception immediately. However, this does not mean all 502 requests will be guaranteed to be processed, only the first 300 (as they have server threads available to do the processing). If 202 of the server threads finish processing their requests from their initial client connections and the connection is released before the timeout for the other 202 that are waiting (200 for backlog and 2 for accept thread), then they will be processed (of course this is a request by request determination).

As of JBossRemoting 2.2.0 release, can also add configuration for cleaning up idle server threads using the 'idleTimeout' configuration property. Setting this property to a value of greater than zero will activate idle timeout checking, which is disabled by default. When enabled, the idle timeout checker will periodically iterate through the server threads that are active and inactive and if have not processed a request within the designated idle timeout period, the server thread will be shutdown and removed from corresponding pool. Active server threads are ones that have a socket connection associated with it and are in a blocked read waiting for data from the client. Inactive server threads are ones that have finished processing on a particular socket connection and have been returned to the thread pool for later reuse.

Note. As of Remoting version 2.4, some changes have been made to ServerThread.

Client

When the socket client invoker makes its first invocation, it will check to see if there is an available socket connection in its pool. Since is the first invocation, there will not be and will create a new socket connection and use it for making the invocation. Then when finished making invocation, wi