JBoss Remoting Guide

Release 2.2.2.GA includes a number of bug fixes, greater configurability, and a couple of new features, including

The following changes affect configurability:

For the JIRA items related to release 2.2.2.GA, see Release Notes.

The heart of the server side is the Connector, and it is through the Connector that the server side of a transport is configured. The central goals of configuration on the server side are to establish a server invoker and supply it with a set of invocation handlers. Only one invoker can be declared per Connector. Although declaring an invocation handler is not required, it should only be omitted in the case of declaring a callback server that will not receive direct invocations, but only callback messages. Otherwise client invocations can not be processed. The invocation handler is the only interface that is required by the remoting framework for a user to implement and will be what the remoting framework calls upon when receiving invocations.

There are two general approaches to server side configuration: programmatic and declarative. A variety of programmatic techniques work in any environment, including the JBoss Application Server (JBossAS). Moreover, JBossAS adds the option of declarative configuration. In particular, the SARDeployer (see The JBoss 4 Application Server Guide on the labs.jboss.org web site) can read information from a *-service.xml file and use it to configure MBeans such as Connectors.

             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();
           

             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();
          

             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();
          

             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();
          

            <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>
         

 
            <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>
         

            <attribute name="InvokerLocator"><![CDATA[socket://test.somedomain.com:8084/foo/bar]]></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>
                    ...
         

Invoker configuration on the client side parallels configuration on the server side, with the exception that (1) it operates in a simpler environment (in particular, it does not assume the presence of an MBeanServer) and (2) it does not support a declarative option. However, it does support versions of the first three server side programmatic options, with the Client class playing the central role played by the Connector class on the server side.

Again, the most straightforward form of configuration is to put the configuration parameters on the InvokerLocator. For example, the fragment

          String locatorURI = "socket://test.somedomain.com:8084";
          String params = "/?clientMaxPoolSize=10&timeout=360000";
          locatorURI += params;
          InvokerLocator locator = new InvokerLocator(locatorURI);
          Client client = new Client(locator);
          client.connect();
       

creates a Client using the socket transport to connect to a server on host test.somedomain.com, listening on port 8084. It also passes in two parameters, "clientMaxPoolSize" and "timeout", that will be used by the client invoker.

It is also possible to use configuration maps on the client side. 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 SocketFactory:

          String locatorURI = "socket://test.somedomain.com:8084";
          String params = "/?clientMaxPoolSize=10";
          locatorURI += params;
          InvokerLocator locator = new InvokerLocator(locatorURI);
          HashMap config = new HashMap();
          config.put(ServerInvoker.TIMEOUT, 360000);
          config.put(Remoting.CUSTOM_SOCKET_FACTORY, new MySocketFactory());
          Client client = new Client(locator, config);
          client.connect();
       

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

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

          String locatorURI = "socket://test.somedomain.com:8084";
          String params = "/?clientMaxPoolSize=10";
          locatorURI += params;
          InvokerLocator locator = new InvokerLocator(locatorURI);
          HashMap config = new HashMap();
          config.put(ServerInvoker.TIMEOUT, 360000);
          Client client = new Client(locator, config);
          client.connect();
          SocketFactory sf = new MySocketFactory();
          ClientInvoker clientInvoker = client.getInvoker();
          clientInvoker.setSocketFactory(sf);
       

Note. The Client creates the client invoker during the call to Client.connect(), so this option only works after that method has been called.

Subsequent to the release of Remoting 2.2.0.GA, some transport independent features have been introduced.

            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
         

The following configuration properties are common to all the current server invokers.

serverBindAddress - The address on which the server binds to listen for requests. The default is an empty value which indicates the server should be bound to the host provided by the locator url, or if this value is null, the local host as provided by InetAddress.getLocalHost() .

serverBindPort - The port to listen for requests on. A value of 0 or less indicates that a free anonymous port should be chosen.

maxNumThreadsOneway - specifies the maximum number of threads to be used within the thread pool for accepting one way invocations on the server side. This property will only be used in the case that the default thread pool is used. If a custom thread pool is set, this property will have no meaning. This property can also be retrieved or set programmatically via the MaxNumberOfOnewayThreads property.

onewayThreadPool - specifies either the fully qualified class name for a class that implements the org.jboss.util.threadpool.ThreadPool interface or the JMX ObjectName for an MBean that implements the org.jboss.util.threadpool.ThreadPool interface. This will replace the default org.jboss.util.threadpool.BasicThreadPool used by the server invoker.

Note that this value will NOT be retrieved until the first one-way (server side) invocation is made. So if the configuration is invalid, will not be detected until this first call is made. The thread pool can also be accessed or set via the OnewayThreadPool property programmatically.

Important to note that the default thread pool used for the one-way invocations on the server side will block the calling thread if all the threads in the pool are in use until one is released.

There are some configurations which will impact the invoker client. These will be communicated to the client invoker via parameters in the Locator URI. These configurations can not be changed during runtime, so can only be set up upon initial configuration of the server invoker on the server side. The following is a list of these and their effects.

clientConnectPort - the port the client will use to connect to the remoting server. This would be needed in the case that the client will be going through a router that forwards requests made externally to a different port internally.

clientConnectAddress - the ip or hostname the client will use to connect to the remoting server. This would be needed in the case that the client will be going through a router that forwards requests made externally to a different ip or host internally.

If no client connect address or server bind address specified, will use the local host's address (via InetAddress.getLocalHost().getHostAddress() ).

Note The role played by "clientConnectAddress" and "clientConnectPort" deserves some further elaboration. When a server is set up, it is either given an InvokerLocator explicitly, or it is given enough information in an MBean XML file from which to construct an InvokerLocator, and a client uses the host field and port field in the InvokerLocator to determine how to connect to the server. It follows that if an explicit InvokerLocator is passed to the server, then the host and port fields are either given explicitly or are generated, so there is no need for "clientConnectAddress" or "clientConnectPort" fields. However, if the server is configured by way of an MBean XML file, and no explicit InvokerLocator is specified, then the "clientConnectAddress" and "clientConnectPort" parameters can be used to specify the host and port fields in the InvokerLocator. If they are omitted, then the host and port fields will be derived from the values of the "serverBindAddress" and "serverBindPort" parameters (or generated, if those fields are omitted). Therefore, there is a role for the "clientConnectAddress" and "clientConnectPort" parameters only if clients are meant to connect to a host and port different than the bind host and bind port. Such a situation might occur in the presence of a translating firewall between the client and the server.

If the serverBindAddress property is set, the server invoker will bind to that address. Otherwise, it will, with one exception, use the address in the InvokerLocator (if there is one). The exception is the case in which the clientConnectAddress property is set, which indicates that the adddess in the InvokerLocator is not the real address of the server's host. In that case, and in the case that there is no address in the InvokerLocator, the server will bind to the address of the local host, as determined by the call

         InetAddress.getLocalHost().getHostAddress();
      

In other words, the logic is

         if (serverBindAddress is set)
            use it
         else if (the host is present in the InvokerLocator and clientConnectAddress is not set)
            use host from InvokerLocator
         else
            use local host address	
      

If the serverBindPort property is set, it will be used. If this value is 0 or a negative number, then the next available port will be found and used. If the serverBindPort property is not set, but the clientConnectPort property is set, then the next available port will be found and used. If neither the serverBindPort nor the clientConnectPort is set, then the port specified in the original InvokerLocator will be used. If this is 0 or a negative number, then the next available port will be found and used. In the case that the next available port is used because either the serverBindPort or the original InvokerLocator port value was either 0 or negative, the InvokerLocator will be updated to reflect the new port value.

Note. In the case that a bind port isn't specified, the utility class org.jboss.remoting.transport.PortUtil is used to supply an available port. By default, it will look for a port in the range 1024 to 65535, inclusively. As of release 2.2.3.SP1, PortUtil can be configured to search a smaller range by setting the values PortUtil.MIN_PORT (actual value "minPort") and / or PortUtil.MAX_PORT (actual value "maxPort") in the InvokerLocator, a configuration map, an MBean XML file. The range is static; that is, whenever "minPort" or "maxPort" are set, they affect all subsequent calls in the JVM. Note that PortUtil will apply a new "minPort" value only if it is greater than the current value, and it will apply a new "maxPort" value only if it is less than the current value. And it will never apply a new value when the result would be such that the value of "maxPort" would be less than the value of "minPort".

The following configuration properties can be set at any time, but will not take effect until the socket invoker, on the server side, is stopped and restarted.

timeout - The socket timeout value passed to the Socket.setSoTimeout() method. The default on the server side is 60000 (one minute). If the timeout parameter is set, its value will also be passed to the client side (see below).

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. Must be a positive value greater than 0. If the value passed if equal or less than 0, then the default value will be assumed. The default value is 200.

numAcceptThreads - The number of threads that exist for accepting client connections. The default is 1.

maxPoolSize - The number of server threads for processing client. The default is 300.

serverSocketClass - specifies the fully qualified class name for the custom SocketWrapper implementation to use on the server.

socket.check_connection - indicates if the invoker should try to check the connection before re-using it by sending a single byte ping from the client to the server and then back from the server. This config needs to be set on both client and server to work. This if false by default.

idleTimeout - indicates the number of seconds a pooled server thread can be idle (meaning time since last invocations request processed) before it should be cleaned up and removed from the thread pool. The value for this property must be greater than zero in order to enable idle timeouts on pooled server threads (otherwise they will not be checked). Setting to value less than zero will disable idle timeout checks on pooled server threads, in the case was previously enabled. The default value for this property is -1.

continueAfterTimeout - indicates what a server thread should do after experiencing a java.net.SocketTimeoutException. If set to "true", or if JBossSerialization is being used, the server thread will continue to wait for an invocation; otherwise, it will return itself to the thread pool.

Configurations affecting the Socket invoker client

There are some configurations which will impact the socket invoker client. These will be communicated to the client invoker via parameters in the Locator URI. These configurations can not be changed during runtime, so can only be set up upon initial configuration of the socket invoker on the server side. The following is a list of these and their effects.

enableTcpNoDelay - can be either true or false and will indicate if client socket should have TCP_NODELAY turned on or off. TCP_NODELAY is for a specific purpose; to disable the Nagle buffering algorithm. It should only be set for applications that send frequent small bursts of information without getting an immediate response; where timely delivery of data is required (the canonical example is mouse movements). The default is false.

timeout - The socket timeout value passed to the Socket.setSoTimeout() method. The default on the client side is 1800000 (or 30 minutes).

clientMaxPoolSize - the client side maximum number of active socket connections. This basically equates to the maximum number of concurrent client calls that can be made from the socket client invoker. The default is 50.

numberOfCallRetries - number of retries for making invocation. It is possible that an existing socket connection timed out while waiting within the pool. Since not doing a connection check by default, will throw away the connection and try to get a new one. Will do this for whatever the numberOfCallRetries (which defaults to 3) is. However, when reaches numberOfCallsRetries - 2, will flush the entire connection pool under the assumption that all connections in the pool have timed out and are invalid and will start over by creating a new connection. If still fails, will throw MarshalException with the cause being the original SocketException.

clientSocketClass - specifies the fully qualified class name for the custom SocketWrapper implementation to use on the client. Note, will need to make sure this is marked as a client parameter (using the 'isParam' attribute). Making this change will not affect the marshaller/unmarshaller that is used, which may also be a requirement.

socket.check_connection - indicates if the invoker should try to check the connection before re-using it by sending a single byte ping from the client to the server and then back from the server. This config needs to be set on both client and server to work. This if false by default.

An example of locator uri for a socket invoker that has TCP_NODELAY set to false and the client's max pool size of 30 would be:

socket://test.somedomain.com:8084/?enableTcpNoDelay=false&maxPoolSize=30

To reiterate, these client configurations can only be set within the server side configuration and will not change during runtime.

        Client client = new Client(locator);
        ...
        InvocationResponse response = (InvocationResponse) client.invoke("$GET_CLIENT_LOCAL_ADDRESS$");
        InetAddress address = (InetAddress) response.getResult();
        

Supports all the configuration attributes as the Socket Invoker. The main difference is that the SSL Socket Invoker uses an SSLServerSocket by default, created by an SSLServerSocketFactory. See section Socket factories and server socket factories for more information.

registryPort - the port on which to create the RMI registry. The default is 3455. This also needs to have the isParam attribute set to true.

Note. The RMI server invoker creates a socket factory and passes it to a client invoker along with the RMI stub, so the socket factory must be serializable. Therefore, if a socket factory is passed in to the server invoker by one of the methods discussed in section Socket factories and server socket factories, then the user is responsible for supplying a serializable socket factory.

This is essentially identical to the RMI invoker, except that it creates SSL socket and server socket factories by default.

Note. The SSL RMI server invoker creates a socket factory and passes it to a client invoker along with the RMI stub, so the socket factory must be serializable. If the SSL RMI server invoker is allowed to create an SSLSocketFactory from SSL parameters, as discussed in section Socket factories and server socket factories, it will take care to create a serializable socket factory. However, if a socket factory is passed in to the server invoker (also discussed in section Socket factories and server socket factories), then the user is responsible for supplying a serializable socket factory. See sslrmi below for more information.

The HTTP server invoker implementation is based on the Apache Tomcat connector components which support GET, POST, HEAD, OPTIONS, and HEAD method types and keep-alive. Therefore, most any configuration allowed for Tomcat can be configured for the remoting HTTP server invoker. For more information on the configuration attributes available for the Tomcat connectors, please refer to http://tomcat.apache.org/tomcat-5.5-doc/config/http.html. http://tomcat.apache.org/tomcat-5.5-doc/config/http.html So for example, if wanted to set the maximum number of threads to be used to accept incoming http requests, would use the 'maxThreads' attribute. The only exception when should use remoting configuration over the Tomcat configuration is for attribute 'address' (use serverBindAddress instead) and attribute 'port' (use serverBindPort instead).

Note: The http invoker no longer has the configuration attributes 'maxNumThreadsHTTP' or 'HTTPThreadPool' as thread pooling is now handled within the Tomcat connectors, which does not expose external API for setting these.

Since the remoting HTTP server invoker implementation is using Tomcat connectors, is possible to swap out the Tomcat protocol implementations being used. By default, the protocol being used is org.apache.coyote.http11.Http11Protocol. However, it is possible to switch to use the org.apache.coyote.http11.Http11AprProtocol protocol, which is based on the Apache Portable Runtime (see http://tomcat.apache.org/tomcat-5.5-doc/apr.html and http://apr.apache.org/ for more details). If want to use the APR implementation, simply put the tcnative-1.dll (or tcnative-1.so) on the system path so can be loaded. The APR native binaries can be found at http://tomcat.heanet.ie.

Note: There is a bug with release 1.1.1 of APR where get an error upon shutting down (see JBREM-277 for more information). This does not impact anything while running, but is still an issue when shutting down (as upon starting up again, can get major problems). This should be fixed in a later release of APR so can just replace the 1.1.1 version of tcnative-1.dll with the new one.

Client request headers

The HTTP Invoker allows for some of the properties to be passed as request headers from client caller. The following are possible http headers and what they mean:

sessionId - is the remoting session id to identify the client caller. If this is not passed, the HTTP server invoker will try to create a session id based on information that is passed. Note, this means if the sessionId is not passed as part of the header, there is no guarantee that the sessionId supplied to the invocation handler will always indicate the request from the same client.

subsystem - the subsystem to call upon (which invoker handler to call upon). If there is more than one handler per Connector, this will need to be set (otherwise will just use the only one available).

These request headers are set automatically when using a remoting client, but if using another client to send request to the HTTP server invoker, may want to add these headers.

Response headers

If a request on the HTTP transport is made with the org.jboss.remoting.Client method

public Object invoke(Object param, Map metadata) throws Throwable

then org.jboss.remoting.transport.http.HTTPClientInvoker returns the HTTP response headers in a map in metadata, associated with the key org.jboss.remoting.transport.http.HTTPMetadataConstants.RESPONSE_HEADERS (actual value "ResponseHeaders"). For example, the response header "Date" can be retrieved as follows:

Object payload = ... ;
HashMap metadata = new HashMap();
client.invoke(payload, metadata);
Map responseHeaders = (Map) metadata.get(HTTPMetadataConstants.RESPONSE_HEADERS);
String date = (String) responseHeaders.get("Date");

CR/LF in HTTP transport

By default, the HTTP transport uses org.jboss.remoting.marshal.http.HTTPMarshaller and org.jboss.remoting.marshal.http.HTTPUnMarshaller to marshal and unmarshal invocations and responses. Prior to Remoting version 2.2.3, HTTPUnMarshaller stripped CR/LF characters. As of version 2.2.3, the default behavior remains the same, but it is possible to change the behavior, on the client and the server, by setting the parameter HTTPUnMarshaller.PRESERVE_LINES (actual value "preserveLines") to "true".

Supports all the configuration attributes as the HTTP Invoker, plus the following:

SSLImplementation - Sets the Tomcat SSLImplementation to use. This should always be org.jboss.remoting.transport.coyote.ssl.RemotingSSLImplementation.

The main difference with the HTTP invoker is that the HTTPS Invoker uses an SSLServerSocket by default, created by an SSLServerSocketFactory. See section Socket factories and server socket factories for more information.

This section covers configuration specific to the HTTP Client Invoker only and is NOT related to HTTP(S) invoker configuration on the server side (via service xml).

proxy

There are a few ways in which to enable http proxy using the HTTP client invoker. The first is simply to add the following properties to the metadata Map passed on the Client's invoke() method: http.proxyHost and http.proxyPort.

An example would be:

               Map metadata = new HashMap();
               ...

               // proxy info
               metadata.put("http.proxyHost", "ginger");
               metadata.put("http.proxyPort", "80");

               ...

               response = client.invoke(payload, metadata);
            

The http.proxyPort property is not required and if not present, will use default of 80. Note: setting the proxy config in this way can ONLY be done if using JDK 1.5 or higher.

The other way to enable use of an http proxy server from the HTTP client invoker is to set the following system properties (either via System.setProperty() method call or via JVM arguments): http.proxyHost, http.proxyPort, and proxySet.

An example would be setting the following JVM arguments:

-Dhttp.proxyHost=ginger -Dhttp.proxyPort=80 -DproxySet=true

Note: when testing with Apache 2.0.48 (mod_proxy and mod_proxy_http), all of the properties above were required.

Setting the system properties can be used for JDK 1.4 and higher. However, will not be able to specify proxy server per remoting client if use system properties..

Basic authentication - direct and via proxy

The HTTP client invoker also has support for BASIC authentication for both proxied and non-proxied invocations. For proxied invocations, the following properties need to be set: http.proxy.username and http.proxy.password.

For non-proxied invocations, the following properties need to be set: http.basic.username and http.basic.password.

For setting either proxied or non-proxied properties, can be done via the metadata map or system properties (see setting proxy properties above for how to). However, for authentication properties, values set in the metadata Map will take precedence over those set within the system properties.

Note: Only the proxy authentication has been tested using Apache 2.0.48; non-proxied authentication has not.

Since there are many different ways to do proxies and authentication in this great world of web, not all possible configurations have been tested (or even supported). If you find a particular problem or see that a particular implementation is not supported, please enter an issue in Jira (http://jira.jboss.com) under the JBossRemoting project, as this is where bugs and feature requests belong. If after reading the documentation have unanswered questions about how to use these features, please post them to the remoting forum ( http://www.jboss.org/index.html?module=bb&op=viewforum&f=222 ).

Host name verification

During the SSL handshake when making client calls using https transport, if the URL's hostname and the server's identification hostname mismatch, a javax.net.ssl.HostnameVerifier implementation will be called to determine if this connection should be allowed. The default implementation will not allow this, but it is possible to override the default behavior

One option is to use the key HTTPSClientInvoker.HOSTNAME_VERIFIER (actual value "hostnameVerifier") to supply the name of a class that implements the javax.net.ssl.HostnameVerifier interface, passing it either in the metadata map supplied with an invocation or in the configuration map supplied when the HTTPSClientInvoker was created. If the key appears in both maps, the value in the metadata map takes precedence.

In the absence of an explicitly declared HostnameVerifier, another way to configure the hostname verification behavior is to declare that all host names are acceptable, which can be accomplished by setting the HTTPSClientInvoker.IGNORE_HTTPS_HOST property (actual value "org.jboss.security.ignoreHttpsHost") to true. In order of increasing precedence, the property may be set (1) as a system property, (2) in the configuration map supplied when the HTTPSClientInvoker was created, or in the metadata map supplied with an invocation.

Finally, in the absence of both an explicitly declared HostnameVerifier and an explicit directive to ignore host names, an HTTPSClientInvoker will check to see if its SocketFactory is an instance of org.jboss.remoting.security.CustomSSLSocketFactory and, if so, if authentication has been turned off. If that is the case, host names will be ignored. See Section Socket factories and server socket factories for more information about SocketFactory configuration.

The servlet invoker is a server invoker implementation that uses a servlet running within a web container to accept initial client invocation requests. The servlet request is then passed on to the servlet invoker for processing.

The deployment for this particular server invoker is a little different than the other server invokers since a web deployment is also required. To start, the servlet invoker will need to be configured and deployed. This can be done by adding the Connector MBean service to an existing service xml or creating a new one. The following is an example of how to declare a Connector that uses the servlet invoker:

           <mbean code="org.jboss.remoting.transport.Connector"
                  name="jboss.remoting:service=Connector,transport=Servlet"
                  display-name="Servlet transport Connector">

              <attribute name="InvokerLocator">
                 servlet://localhost:8080/servlet-invoker/ServerInvokerServlet
              </attribute>

              <attribute name="Configuration">
                 <config>
                    <handlers>
                       <handler subsystem="test">
                          org.jboss.test.remoting.transport.web.WebInvocationHandler
                       </handler>
                    </handlers>
                 </config>
              </attribute>
           </mbean>
        

An important point of configuration to note is that the value for the InvokerLocator attribute is the exact url used to access the servlet for the servlet invoker (more on how to define this below), with the exception of the protocol being servlet instead of http. This is important if using automatic discovery, as this is the locator url that will be discovered and used by clients to connect to this server invoker.

The next step is to configure and deploy the servlet that fronts the servlet invoker. The pre-built deployment file for this servlet is the servlet-invoker.war file (which can be found in lib directory of the release distribution or under the output/lib/ directory if doing a source build). By default, it is actually an exploded war, so the servlet-invoker.war is actually a directory so that can be more easily configured (feel free to zip up into an actual war file if prefer). In the WEB-INF directory is located the web.xml file. This is a standard web configuration file and should look like:

 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE web-app PUBLIC
    "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
    "http://java.sun.com/dtd/web-app_2_3.dtd">

 <web-app>
     <servlet>
         <servlet-name>ServerInvokerServlet</servlet-name>
         <description>The ServerInvokerServlet receives requests via HTTP
            protocol from within a web container and passes it onto the
            ServletServerInvoker for processing.
         </description>
         <servlet-class>org.jboss.remoting.transport.servlet.web.ServerInvokerServlet</servlet-class>
         <init-param>
             <param-name>invokerName</param-name>
             <param-value>jboss.remoting:service=invoker,transport=servlet</param-value>
             <description>The servlet server invoker</description>
            <!--
             <param-name>locatorUrl</param-name>
             <param-value>servlet://localhost:8080/servlet-invoker/ServerInvokerServlet</param-value>
             <description>The servlet server invoker locator url</description>
            -->
         </init-param>
         <load-on-startup>1</load-on-startup>
     </servlet>
     <servlet-mapping>
         <servlet-name>ServerInvokerServlet</servlet-name>
         <url-pattern>/ServerInvokerServlet/*</url-pattern>
     </servlet-mapping>
 </web-app>

There are two ways in which the servlet can obtain a reference to the servlet server invoker it needs to pass its request onto. The first is by using the param 'invokerName', as is shown above. The value for this should be the JMX ObjectName for the servlet server invoker that was deployed as a service mbean (see service xml above). The other way is to provide a param 'locatorUrl' with a value that matches the locator url of the servlet server invoker to use. In this case, will use the InvokerRegistry to find the server invoker instead of using JMX, which is useful if not deploying server invoker as a mbean service or if want to run in web container other than the JBoss application server. Note, one or the other param is required. If both are provided, the 'locatorUrl' param take precedence.

This file can be changed to meet any web requirements you might have, such as adding security (see sslservlet) or changing the actual url context that the servlet maps to. If the url that the servlet maps to is changed, will need to change the value for the InvokerLocator in the Connector configuration mentioned above.

Note. Prior to Remoting version 2.2.3, org.jboss.remoting.transport.servlet.ServletServerInvoker generated a single MBean ObjectName for representing ServletServerInvokers as MBeans, which meant that an MBeanServer could be aware of only a single ServletServerInvoker MBean. As of version 2.2.3, that restriction can be eliminated by setting the parameter org.jboss.remoting.transport.servlet.ServletServerInvoker.CREATE_UNIQUE_OBJECT_NAME (actual value "createUniqueObjectName") to "true".

Issues

One of the issues of using Servlet invoker is that the invocation handlers (those that implement ServerInvocationHandler) can not return very much detail in regards to a web context. For example, the content type used for the response is the same as that of the request.

The SSL Servlet Invoker is exactly the same as its parent, Servlet Invoker, with the exception that it uses the protocol of 'sslservlet'. On the server side it is deployed exactly the same as a servlet invoker would be but requires setting up ssl within the web container (i.e. enabling the ssl connector within Tomcat's server.xml). This will usually require specifing a different port as well.

An example of the mbean service xml for deploying the ssl servlet server invoker would be:

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

 <server>
   <mbean code="org.jboss.remoting.transport.Connector"
          name="jboss.remoting:service=Connector,transport=SSLServlet"
          display-name="SSL Servlet transport Connector">

              <attribute name="InvokerLocator">
                 sslservlet://localhost:8443/servlet-invoker/ServerInvokerServlet
              </attribute>
              <attribute name="Configuration">
                 <config>
                    <handlers>
                       <handler subsystem="test">org.jboss.test.remoting.transport.web.WebInvocationHandler</handler>
                    </handlers>
                 </config>
              </attribute>
   </mbean>
 </server> 

An example of servlet-invoker.war/WEB-INF/web.xml for the ssl server invoker servlet would be:

 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE web-app PUBLIC
    "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
    "http://java.sun.com/dtd/web-app_2_3.dtd">

 <web-app>
     <servlet>
         <servlet-name>ServerInvokerServlet</servlet-name>
         <description>The ServerInvokerServlet receives requests via HTTP
            protocol from within a web container and passes it onto the
            ServletServerInvoker for processing.
         </description>
         <servlet-class>org.jboss.remoting.transport.servlet.web.ServerInvokerServlet</servlet-class>
         <init-param>
             <param-name>locatorUrl</param-name>
             <param-value>sslservlet://localhost:8443/servlet-invoker/ServerInvokerServlet</param-value>
             <description>The servlet server invoker locator url</description>
         </init-param>
         <load-on-startup>1</load-on-startup>
     </servlet>
    <servlet-mapping>
         <servlet-name>ServerInvokerServlet</servlet-name>
         <url-pattern>/ServerInvokerServlet/*</url-pattern>
     </servlet-mapping>
 </web-app> 

Web based clients, meaning remoting clients that call on web based remoting servers (i.e. http, https, servlet, and sslservlet) have special needs when it comes to handling exceptions that come from the servers they are calling on. The main reason for this is that depending on what type of server they are calling on, they might receive the error in different formats.

By default, web based clients will throw an exception when the response code from the server is greater than 400. The exact exception type thrown will depend on the type of web server the client is interacting with. If it is a JBoss Remoting server (http or https server invoker), the exception thrown will be the one originally generated on the server side. If the server is not a JBoss Remoting server (e.g. JBossAS, Tomcat, Apache Web Server, etc.), the exception throw will be org.jboss.test.remoting.transport.http.WebServerError. The WebServerError's message will be the error html returned by the web server. To turn off the throwing of an exception when the web server responds with an error, can add config to the configuration map passed to the Client.invoke() method where they key is HTTPMetadataConstants.NO_THROW_ON_ERROR (actual text value 'NoThrowOnError') and a value of of type java.lang.String set to 'true'. This will cause the http client invoker to not throw an exception, but instead return the data from the web server error stream. In the case that the data returned from this error stream is of type java.lang.String (i.e. is error html), it will be wrapped in a WebServerError and returned as this type. The raw data from the web server can the be retrieved by getting the WebServerError's message.

Note. Prior to Remoting release 2.2.2.SP2, the servlet transport returned a simple error message in the event of an error on the server side. As of release 2.2.2.SP2, the exception handling behavior described above can be requested for the the servlet and sslservlet transports as well by configuring the server with the parameter org.jboss.remoting.transport.http.HTTPMetadataConstants.RETURN_EXCEPTION (actual value "return-exception") set to "true".

The multiplex invoker is intended to replicate the functionality of the socket invoker with the added feature that it supports multiple streams of communication over a single pair of sockets. Multiplexing may be motivated by, for example, a desire to conserve socket resources or by firewall restrictions on port availability. This additional service is made possible by the Multiplex subproject, which provides "virtual" sockets and "virtual" server sockets. Please refer to the Multiplex documentation at

for further details.

In a typical multiplexed scenario a Client on a client host, through a MultiplexClientInvoker C, could make synchronous method invocations to a MultiplexServerInvoker on a server host, and at the same time (and over the same TCP connection) asynchronous push callbacks could be made to a MultiplexServerInvoker S on the client host. In this, the Prime Scenario, which motivated the creation of the multiplex invoker, C and S use two different virtual sockets but share the same port and same actual socket. We say that C and S belong to the same invoker group.

One of the primary design goals of the Multiplex subsystem is for virtual sockets and virtual server sockets to demonstrate behavior as close as possible to their real counterparts, and, indeed, they implement complete socket and server socket APIs. However, they are necessarily different in some respects, and it follows that the multiplex invoker is somewhat different than the socket invoker. In particular, there are three areas specific to the multiplex invoker that must be understood in order to use it effectively:

This transport is essentially identical to the Multiplex transport, except that it will create SSL socket factories and server socket factories by default.

The twist to be found with the multiplex transport is that virtual MultiplexServerInvokers use a VirtualServerSocket, which is based on a client rather than a server socket, and consequently they act like a client in some ways. In particular, a virtual MultiplexServerInvoker will, in some cases, attempt to connect to a remote master MultiplexServerInvoker, for which it will need an actual client socket. All of the rules for configuring socket factories apply to the MultiplexServerInvoker, which calls the same method that client invokers use to get a socket factory. Moreover, if necessary, it will look for a ServerSocketFactoryMBean to get SSL information when configuring a socket factory. See section Socket factories and server socket factories for more information.

The bisocket transport, like the multiplex transport, is a bidirectional transport that can function in the presence of restrictions that would prevent a unidirectional transport like socket or http from creating a server to client push callback connection. (See Section Callbacks for more information about callbacks and bidirectional and unidirectional transports.) For example, security restrictions could prevent the application from opening a ServerSocket on the client, or firewall restrictions could prevent the server from contacting a ServerSocket even if it were possible to create one.

5.4.17.2. Details

Using the bisocket transport certainly does not require understanding its implementation details, but some further information is presented in this section for those who might be interested.

In the following discussion, the client side client invoker and the server side server invoker will be referred to simply as "client invoker" and "server invoker." The callback client invoker and callback server invoker will be explicitly identified as such.

The following sequence of events occurs in the course of creating a control connection. For simplicity it is assumed that the Client and Connector have already been created, and that the callback server is created implicitly by the Client. These events are illustrated in Figure 5.1.

1. The application calls Client.addListener().
2. The Client creates a callback Connector and the callback server invoker registers itself in a static map.
3. The Client sends an "addListener" message to the server invoker by way of the client invoker.
4. The client invoker intercepts the "addListener" message, which tells it that a callback server is being created. It retrieves the callback server invoker from the static map and tells it to create a control connection for the callback connection that is being constructed.
5. The callback server invoker sends an internal message to the server invoker requesting the address and port of the secondary ServerSocket
6. The callback server invoker connects to the secondary ServerSocket to create a Socket for the control connection. If it has not already done so, the callback server invoker creates a TimerTask which will monitor the state of all of its control connections. (Note that if the callback Connector is created explicitly, it could have multiple InvokerCallbackHandlers registered with it.)
7. On the server side, the Socket just created by the secondary ServerSocket is stored in a static map, awaiting the creation of the callback client invoker.
8. The client invoker transmits the "addListener" message to the server invoker.
9. The server invoker creates a callback client invoker.
10. The callback client invoker retrieves the waiting socket and uses it for the control connection.
11. The callback client invoker begins pinging on the control connection.

Figure 5.1. Creating a control connection.

The following sequence of events occurs in the course of creating a connection for the callback client invoker to use for sending callbacks. It is illustrated in Figure 5.2.

1. The ServerInvocationHandler calls InvokerCallbackHandler.handleCallback().
2. The InvocationCallbackHandler calls invoke() on the callback Client.
3. The Client calls invoke() on the callback client invoker.
4. If there are no connections in its connection pool, the callback client invoker sends a message on the control connection asking the callback server invoker to connect to the server side secondary ServerSocket. It then waits for the Socket to appear in a static map.
5. The callback server invoker receives the request and calls upon either a Socket constructor or a SocketFactory to create a new Socket. It passes the new Socket to a worker thread to process subsequent callback invocations.
6. The secondary ServerSocket creates a new Socket, which is placed in a static map.
7. The callback client invoker retrieves the new Socket
8. The callback client uses the new Socket to transmit a callback, and adds the new connection to its connection pool for later use.

Figure 5.2. Creating a callback connection.

The following sequence of events occurs when a control connection fails. It is illustrated in Figure 5.3.

1. The callback server invoker notices that a ping has not been received during the control connection's current window.
2. The callback server invoker reacquires the host and port of the secondary ServerSocket, just in case it has changed.
3. The callback server invoker calls on a Socket constructor or SocketFactory to create a new Socket.
4. The callback server invoker sends an internal message on the new connection directing the server to replace the current control connection with the new connection.
5. After the secondary ServerSocket creates a new Socket, the Socket is passed directly to the client invoker in a method that replaces the old control connection with a new one.

Figure 5.3. Replacing a failed control connection.

The SSL bisocket transport has the same relation to the bisocket transport as the SSL socket transport has to the socket transport. That is, it uses an SSLServerSocket and creates SSLSockets by default. See Section Socket factories and server socket factories for more information.

SSL bisocket transport supports all the configuration attributes supported by the bisocket transport.

Although this section covers callback configuration, it will be useful to begin with a little general information about callbacks within Remoting. In addition to the ordinary remote method invocation model, in which invocation results are returned synchronously, Remoting also supports an invocation model in which the server asynchronously generates information to be returned to the client.

There are two models for callbacks, push callbacks and pull callbacks. In the push model, the client registers a client side callback server with the target server. When the target server has a callback to deliver, it will call on the callback server directly and send the callback message. The other model, pull callbacks, allows the client to call on the target server to collect the callback messages waiting for it.

          public void addListener(InvokerCallbackHandler callbackHandler);
        

          public void handleCallback(Callback callback) throws HandleCallbackException;
        

          public void handleCallbackOneway(Callback callback) throws HandleCallbackException;
  
          public void handleCallbackOneway(Callback callback, boolean serverSide)) throws HandleCallbackException;
        

           public void invokeOneway(final Object param, final Map sendPayload, boolean clientSide) throws Throwable;
        

        public interface CallbackListener
        {
           /**
            * @param callbackHandler InvokerCallbackHandler that handled this callback
            * @param callbackId id of callback being acknowledged
            * @param response either (1) response sent with acknowledgement or (2) null
            */
           void acknowledgeCallback(InvokerCallbackHandler callbackHandler, Object callbackId, Object response);
        }
        

           public int acknowledgeCallback(InvokerCallbackHandler callbackHandler, Callback callback) throws Throwable;
           
           public int acknowledgeCallback(InvokerCallbackHandler callbackHandler, Callback callback, Object response) throws Throwable;
           
           public int acknowledgeCallbacks(InvokerCallbackHandler callbackHandler, List callbacks) throws Throwable;
           
           public int acknowledgeCallbacks(InvokerCallbackHandler callbackHandler, List callbacks, List responses) throws Throwable;
        

There are several ways in which callback handlers can be configured. The main distinction in type of callback setup is whether the callbacks will be push (asynchronous) or pull (synchronous) callbacks.

          public void addListener(InvokerCallbackHandler) throws Throwable;
          
          public void addListener(InvokerCallbackHandler callbackHandler, InvokerLocator clientLocator) throws Throwable;
          
          public void addListener(InvokerCallbackHandler callbackHandler,  InvokerLocator clientLocator, Object callbackHandlerObject) throws Throwable;
        

          public List getCallbacks(InvokerCallbackHandler callbackHandler) throws Throwable
        

          public List getCallbacks(InvokerCallbackHandler callbackHandler, Map metadata) throws Throwable;
        

          public void addListener(InvokerCallbackHandler callbackHandler, InvokerLocator clientLocator) throws Throwable;
          
          public void addListener(InvokerCallbackHandler callbackHandler,InvokerLocator clientLocator, Object callbackHandlerObject) throws Throwable;
        

          public void addListener(InvokerCallbackHandler callbackhandler, Map metadata) throws Throwable;
          
          public void addListener(InvokerCallbackHandler callbackhandler, Map metadata, Object callbackHandlerObject) throws Throwable;
          
          public void addListener(InvokerCallbackHandler callbackhandler, Map metadata, Object callbackHandlerObject, boolean serverToClient) throws Throwable;
        

        InvokerCallbackHandler callbackHandler = new SampleCallbackHandler();
        client.addListener(callbackHandler, new HashMap(), null, true);
        client.addListener(callbackHandler, new HashMap(), null, true);
        

        public Set getCallbackConnectors(InvokerCallbackHandler callbackHandler);
        

        InvokerCallbackHandler callbackHandler1 = new SampleCallbackHandler();
        client.addListener(callbackHandler1, new HashMap(), null, true);
        Set callbackConnectors = client.getCallbackConnectors(callbackHandler1);
        Connector callbackConnector = (Connector) callbackConnectors.iterator().next();
        InvokerCallbackHandler callbackHandler2 = new SampleCallbackHandler();
        client.addListener(callbackHandler2, callbackConnector.getLocator());
        

        InvokerCallbackHandler callbackHandler1 = new SampleCallbackHandler();
        client.addListener(callbackHandler1, new HashMap(), null, true);
        Set callbackConnectors = client.getCallbackConnectors(callbackHandler1);
        Connector callbackConnector = (Connector) callbackConnectors.iterator().next();
        client.addListener(callbackHandler1, callbackConnector.getLocator());
        

Callback connections are torn down through a call to the method

        public void removeListener(InvokerCallbackHandler callbackHandler) throws Throwable;
      

in the org.jboss.remoting.Client class. A Client can unregister only those InvokerCallbackHandlers that it originally registered.

It is good practice to eliminate callback connections when they are no longer needed. For example, callback Connectors can, depending on the transport, occupy TCP ports, and CallbackPollers will continue to poll as long as a connection exists.

All callback store configuration will need to be defined within the server invoker configuration, since the server invoker is the parent that creates the callback stores as needed (when client registers for pull callbacks). Example service xml files are included below.

The following general callback store parameters may be configured. They are defined as constants in the org.jboss.callback.ServerInvokerCallbackHandler class.

CALLBACK_MEM_CEILING (actual value is "callbackMemCeiling"): the percentage of free memory available before callbacks will be persisted. If the memory heap allocated has reached its maximum value and the percent of free memory available is less than the callbackMemCeiling, this will trigger persisting of the callback message. The default value is 20.

Note: The calculations for this is not always accurate. The reason is that total memory used is usually less than the max allowed. Thus, the amount of free memory is relative to the total amount allocated at that point in time. It is not until the total amount of memory allocated is equal to the max it will be allowed to allocate. At this point, the amount of free memory becomes relevant. Therefore, if the memory percentage ceiling is high, it might not trigger until after free memory percentage is well below the ceiling.

CALLBACK_STORE_KEY (actual value is "callbackStore"): specifies the callback store to be used. The value can be either an MBean ObjectName or a fully qualified class name. If using class name, the callback store implementation must have a void constructor. The default is to use the NullCallbackStore.

The following parameters specific to CallbackStore can be configured via the invoker configuration as well. They are defined as constants in the CallbackStore class.

FILE_PATH_KEY (actual value is "StoreFilePath"): indicates to which directory to write the callback objects. The default value is the property value of 'jboss.server.data.dir' and if this is not set, then will be 'data'. Will then append 'remoting' and the callback client's session id. An example would be 'data\remoting\5c4o05l-9jijyx-e5b6xyph-1-e5b6xyph-2'.

FILE_SUFFIX_KEY (actual value is "StoreFileSuffix"): indicates the file suffix to use for the callback objects written to disk. The default value is 'ser'.

Sample service configuration

Socket transport with callback store specified by class name and memory ceiling set to 30%:

           <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="callbackStore">org.jboss.remoting.callback.CallbackStore</attribute>
                       <attribute name="callbackMemCeiling">30</attribute>
                    </invoker>
                    <handlers>
                       <handler subsystem="test">
                          org.jboss.remoting.callback.pull.memory.CallbackInvocationHandler
                       </handler>
                    </handlers>
                 </config>
              </attribute>
           </mbean>
        

Socket transport with callback store specified by MBean ObjectName and declaration of CallbackStore as service:

           <mbean code="org.jboss.remoting.callback.CallbackStore"
                 name="jboss.remoting:service=CallbackStore,type=Serializable"
                 display-name="Persisted Callback Store">

              <!-- the directory to store the persisted callbacks into -->
              <attribute name="StoreFilePath">callback_store</attribute>
              <!-- the file suffix to use for each callback persisted to disk -->
              <attribute name="StoreFileSuffix">cbk</attribute>
           </mbean>

           <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="callbackStore">
                          jboss.remoting:service=CallbackStore,type=Serializable
                       </attribute>
                    </invoker>
                    <handlers>
                       <handler subsystem="test">
                          org.jboss.remoting.callback.pull.memory.CallbackInvocationHandler
                       </handler>
                    </handlers>
                 </config>
              </attribute>
           </mbean>
        

Socket transport with callback store specified by class name and the callback store's file path and file suffix defined:

           <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="callbackStore">org.jboss.remoting.callback.CallbackStore</attribute>
                       <attribute name="StoreFilePath">callback</attribute>
                       <attribute name="StoreFileSuffix">cst</attribute>
                    </invoker>
                    <handlers>
                       <handler subsystem="test">
                          org.jboss.remoting.callback.pull.memory.CallbackInvocationHandler
                       </handler>
                    </handlers>
                 </config>
              </attribute>
           </mbean>
        

Since performing callbacks can sometimes fail, due to network errors or errors produced by the client callback handler, there needs to be a mechanism for managing exceptions when delivering callbacks. This is handled via use of the org.jboss.remoting.callback.CallbackErrorHandler interface. Implementations of this interface can be registered with the Connector to control the behavior when callback exceptions occur.

The implementation of the CallbackErrorHandler interface can be specified by setting the 'callbackErrorHandler' attribute to either the ObjectName of an MBean instance of the CallbackErrorHandler which is already running and registered with the MBeanServer, or can just specify the fully qualified class name of the CallbackErrorHandler implementation (which will be constructed on the fly and must have a void parameter constructor). The full server invoker configuration will be passed along to the CallbackErrorHandler, so if want to add extra configuration information in the invoker's configuration for the callback error handler, it will be available. If no callback error handler is specified via configuration, org.jboss.remoting.callback.DefaultCallbackErrorHandler will be used by default. This implementation will allow up to 5 exceptions to occur when trying to deliver a callback message from the server to the registered callback listener client (regardless of what the cause of the exception is, so could be because could not connect or could be because the client actually threw a valid exception). After the DefaultCallbackErrorHandler receives its fifth exception, it will remove the callback listener from the server invoker handler and shut down the callback listener proxy on the server side. The number of exceptions the DefaultCallbackErrorHandler will allow before removing the listener can by configured by the 'callbackErrorsAllowed' attribute.

Note. As of Remoting release 2.2.2.SP4, an org.jboss.remoting.callback.ServerInvokerCallbackHandler, which manages both push and pull callbacks on the server side, can register to be informed of a failure on the connection to the client that it is servicing. In particular, if there is a lease registered for the connection for that particular client, then the ServerInvokerCallbackHandler can be registered as a org.jboss.remoting.ConnectionListener for that lease. The default behavior is to do the registration, but the parameter org.jboss.remoting.ServerInvoker.REGISTER_CALLBACK_LISTENER (actual value "registerCallbackListener") may be set to "false" to prevent registration. If leasing is enabled and registration is turned on, a ServerInvokerCallbackHandler will shut itself down upon being informed of a connection failure. For more information about leasing, see Network Connection Monitoring.

All server invokers use server sockets, and it makes sense, therefore, to be able to configure server invokers with server socket factories. It is also true, though less obvious. that server invokers create sockets (other than by way of server sockets). When a server invoker makes a push callback to a client, it creates a client invoker, which creates a socket. Moreover, some server invokers, e.g., the RMI server invoker, have their own idiosyncratic uses for socket factories. Remoting offers a number of ways of configuring socket factories and server socket factories, and these apply to all transports (except for the servlet invokers).

On the client side it is possible to configure socket factories for client invokers and to configure server socket factories for callback server invokers. Configuration on the client side is largely the same as configuration on the server side, with the exception that no MBeanServer is assumed to be present, and the Client has no facilities for parsing xml documents.

Everything in the previous two sections applies to configuring socket and server socket factories in any environment, including inside the JBoss Application Server (JBossAS), but JBossAS adds some new options. In particular, the SARDeployer (see The JBoss 4 Application Server Guide on the labs.jboss.org web site) can read information from a *-service.xml file, as discussed above in the section "General Connector and Invoker configuration," and use it to configure MBeans such as Connectors.

An example of a service xml that covers all the different transport and service configurations can be found within the example-service.xml file under the etc directory of the JBoss Remoting distribution.

The server socket factory to be used by a server invoker can be set via configuration within the service xml. To do this, the serverSocketFactory attribute will need to be set as a sub-element of the invoker element (this cannot be done if just specifying the invoker configuration using the InvokerLocator attribute). The attribute value must be either

An example of the first case would be:

            <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="sslsocket">
                        <attribute name="serverSocketFactory">
                           jboss.remoting:service=ServerSocketFactory,type=SSL
                        </attribute>
                        <attribute name="numAcceptThreads">1</attribute>
         

The serverSocketFactory attribute is processed as follows:

The JBossRemoting project provides an implementation of the ServerSocketFactoryMBean that can be used and should provide most of the customization features that would be needed. More on this implementation later.

Note that these two options correspond exactly to options 4 and 5 in section Server socket factories (on the server side), which is how these two new options are implemented.

Timing considerations. If a Connector is accessed by way of the MBeanServer, then most of the options for configuring the server socket factory discussed in Server socket factories are irrelevant since ConnectorMBean does not expose methods for using them. However, when a Connector that is registered with an MBeanServer creates a server invoker during a call to Connector.create(), it also registers the server invoker with the same MBeanServer, which means that the server invoker is accessible by way of its ObjectName, which has the form

            jboss.remoting:service=invoker,transport=socket,host=www.jboss.com,port=8765
         

for example, followed by additional parameter=value pairs. (See the jmx-console for a running instance of JBossAS at http://localhost:8080/jmx-console/ to see examples of server invoker ObjectNames.) Now, if another MBean is configured in a *-service.xml file to be dependent on the server invoker MBean, e.g.

            <mbean code="org.jboss.BlueMonkey" name="jboss.remoting:bluemonkey,name=diamond">
               <depends optional-attribute-name="serverInvoker">
                   jboss.remoting:service=invoker,transport=socket,host=www.jboss.com,port=8765
               </depends>
            </mbean>
         

then org.jboss.BlueMonkey.create() will have access to the designated server invoker after the invoker has been created but before it has been started, which means that ServerInvoker.setServerSocketFactory() will be effective. (See the The JBoss 4 Application Server Guide, Chapter 2, for more information about the life cycle of JBoss MBeans.)

As described in section Declarative configuration the declarative xml files used by the Application Server can be used to configure the client by way of the parameters included in the InvokerLocator. However, a peculiarity in the way socket factories are created on the client restricts the parameters taken into consideration to those passed in the configuration map passed to the org.jboss.remoting.Client constructor. The following two parameters, introduced in releases 2.2.2.SP9 and 2.2.3, respectively, eliminate that restriction.

org.jboss.remoting.Remoting.SOCKET_FACTORY_NAME (actual value is 'socketFactory') - key for giving the name of the socket factory class to be used by clients.

org.jboss.remoting.Remoting.USE_ALL_SOCKET_FACTORY_PARAMS (actual value is 'useAllSocketFactoryParams') - key for indicating that all socket factory parameters in the InvokerLocator should be used by clients.

Every Remoting transport uses Sockets, but the creation and management of the Sockets is generally inaccessible from the application code. Remoting has a hook that can provide access to Sockets, in the form of a listener interface in the org.jboss.remoting.socketfactory package:

      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 registered to be informed every time a socket is created by a SocketFactory or ServerSocket. The mechanisms for registering listeners are the usual ones, e.g., by putting them in configuration maps passed to client and server invokers. (See Section General transport configuration for a general discussion of parameter configuration in Remoting.) In any case they should be associated with one of the following keys from org.jboss.remoting.Remoting:

      /**
       * Key for the configuration map passed to a Client or Connector to indicate
       * a socket creation listener for sockets created by a SocketFactory.
       */
      public static final String SOCKET_CREATION_CLIENT_LISTENER = "socketCreationClientListener";
      
      /**
       * Key for the configuration map passed to a Client or Connector to indicate
       * a socket creation listener for sockets created by a ServerSocket.
       */
      public static final String SOCKET_CREATION_SERVER_LISTENER = "socketCreationServerListener";
      

The value associated with either of these keys can be an actual object, or, to facilitate configuration by InvokerLocator or xml, it can be the name of a class that implements SocketCreationListener and has a default constructor

Note that client and server invokers always use the respective keys SOCKET_CREATION_CLIENT_LISTENER and SOCKET_CREATION_SERVER_LISTENER, whether they are on the client side or server side. For example, a callback client invoker would be configured by putting a listener with the key SOCKET_CREATION_CLIENT_LISTENER in the configuration map passed to the server side Connector, which will find its way to the callback client invoker when a callback handler is registered.

The creation listener facility currently is supported by the following transports: bisocket, sslbisocket, https, multiplex, sslmultiplex, rmi, sslrmi, socket, and sslsocket. It is not supported by http because HttpURLConnection does not expose its socket factory (though HttpsURLConnection does). It is not supported by the servlet transport because invocations with the servlet transport go through a servlet container, which is outside the scope of Remoting.

There are now four transports that support SSL: https, sslmultiplex, sslrmi, and sslsocket (plus sslservlet, which is not relevant here). All of the preceding discussion applies to each of these, and, moreover, they are all extensions of their non-ssl counterparts, so only some ssl specific information will be added here.

https

Configuration of the https transport is a bit different from that of the other transports since the implementation is based off the Tomcat connectors. One difference is that, in order to use SSL connections, the SSLImplementation attribute must be set and must always have the value org.jboss.remoting.transport.coyote.ssl.RemotingSSLImplementation. The SSLImplementation is used by the Tomcat connector to create ServerSocketFactorys, and RemotingSSLImplementation presents Tomcat with the ServerSocketFactory configured according to the options described above.

An example of setting up https via service.xml configuration would be:

     <mbean code="org.jboss.remoting.transport.Connector"
         name="jboss.remoting:service=Connector,transport=HTTPS"
         display-name="HTTPS transport Connector">

         <attribute name="Configuration">
            <config>
               <invoker transport="https">
                  <attribute name="serverSocketFactory">jboss.remoting:service=ServerSocketFactory,type=SSL</attribute>
                  <attribute name="SSLImplementation">org.jboss.remoting.transport.coyote.ssl.RemotingSSLImplementation</attribute>
                  <attribute name="serverBindAddress">${jboss.bind.address}</attribute>
                  <attribute name="serverBindPort">6669</attribute>
               </invoker>
               <handlers>
                  <handler subsystem="mock">org.jboss.test.remoting.transport.mock.MockServerInvocationHandler</handler>
               </handlers>
            </config>
         </attribute>
         <!-- This depends is included because need to make sure this mbean is running before configure invoker. -->
         <depends>jboss.remoting:service=ServerSocketFactory,type=SSL</depends>
      </mbean>
   

See section SSLServerSocketFactoryService below for a discussion of the "jboss.remoting:service=ServerSocketFactory,type=SSL" MBean that appears in this configuration element.

Note that the configuration for SSL support only works when using the java based http processor and not with the APR based transport. See section HTTP Invoker for more information on using the APR based transport.

sslmultiplex

The sslmultiplex server invoker inherits from the socket server invoker a method with signature

            public void setNewServerSocketFactory(ServerSocketFactory serverSocketFactory)
         

which supports dynamic replacement of server socket factories. The principal motivation for this facility is to be able to swap in a new SSLServerSocketFactory configured with an updated keystore.

sslrmi

The extra twist in the sslrmi invoker is that the server invoker creates the (client) socket factory and packages it with its own stub, from which it follows that the socket factory must be serializable. If the sslrmi server invoker is allowed to create an SSLSocketFactory from SSL parameters, it will take care to create a serializable socket factory. In particular, the server invoker creates a copy of org.jboss.remoting.transport.rmi.ssl.SerializableSSLClientSocketFactory, which is essentially just a holder for the configuration map passed to the server invoker, with any parameters removed which concern trust store and key store configuration. On the client side, when an sslrmi client invoker is created, it stores its own configuration map in a static variable which the transferred SerializableSSLClientSocketFactory can retrieve and merge with the configuration information it brought with it from the server. In particular, if a socket factory is explicitly passed to the client invoker, then SerializableSSLClientSocketFactory will use it. If not, then SerializableSSLClientSocketFactory will use any key store and trust store information passed to the client to create and configure a socket factory.

Note. If instead of using SerializableSSLClientSocketFactory, a socket factory is passed in to the server invoker by one of the methods discussed above, then the user is responsible for supplying a serializable socket factory.

sslsocket

In addition to the various configuration options discussed above, the sslsocket transport exposes the

public void setServerSocketFactory(ServerSocketFactory serverSocketFactory)

method as a JMX operation.

Also, the sslsocket server invoker inherits from the socket server invoker a method with signature

            public void setNewServerSocketFactory(ServerSocketFactory serverSocketFactory)
         

which supports dynamic replacement of server socket factories. The principal motivation for this facility is to be able to swap in a new SSLServerSocketFactory configured with an updated keystore.

Throughout this section reference has been made to SSL socket factory and server socket factory configuration parameters. This subsection will introduce these parameters in the context of configuring org.jboss.remoting.security.SSLSocketBuilder, Remoting's flexible, highly customizable master factory for creating socket and server socket factories. It can be used programmatically on both the client and server side, and it is also a service MBean, so it can be configured and started from within a service xml in a JBossAS environment.

Once a SSLSocketBuilder has been constructed and configured, a call to its method createSSLServerSocketFactory() will return a custom instance of a SSLServerSocketFactory, and a call to createSSLSocketFactory() will return a custom instance of SSLSocketFactory.

There are two modes in which the SSLSocketBuilder can be run. The first is the default mode where all that is needed is to declare the SSLSocketBuilder and set the system properties javax.net.ssl.keyStore and javax.net.ssl.keyStorePassword. This will use the JVM vendor's default configuration for creating the SSL server socket factory.

In order to customize any of the SSL properties, the first requirement is that the default mode is turned off. This is IMPORTANT because otherwise, if the default mode is not explicitly turned off, all other settings will be IGNORED, even if they are explicitly set. To turn off the default mode via service xml configuration, set the UseSSLServerSocketFactory attribute to false. This can also be done programmatically by calling the setUseSSLServerSocketFactory() and passing false as the parameter value.

There are two ways to configure a SSLSocketBuilder

The configuration properties for SSLSocketBuilderare as follows. Note that in the "key name" column, the name in capital letters (e.g., REMOTING_CLIENT_AUTH_MODE) is a handy constant in the SSLSocketBuilder class with the value given in parentheses (e.g. "org.jboss.remoting.clientAuthMode"). It is the latter that should be used for declarative configuration in, for example, MBean descriptors.

Note. If any of the attributes KeyStoreURL, KeyStorePassword, KeyStoreType, TrustStoreURL, TrustStorePassword, or TrustStoreType are left unconfigured, SSLSocketBuilder will also examine the corresponding standard SSL system properties "javax.net.ssl.keyStore", "javax.net.ssl.keyStorePassword", "javax.net.ssl.keyStoreType", "javax.net.ssl.trustStore", "javax.net.ssl.trustStorePassword", "javax.net.ssl.trustStoreType". In the cases of KeyStoreType and TrustStoreType, SSLSocketBuilder will then go on to use default values after checking the system properties.

The following is an example of configuring a SSLSocketBuilder and using it to create a custom SSLSocketFactory:

         protected SSLSocketFactory getSocketFactory() throws Exception
         {
            HashMap config = new HashMap();
            config.put(SSLSocketBuilder.REMOTING_KEY_STORE_TYPE, "JKS");
            String keyStoreFilePath = getKeystoreFilePath();
            config.put(SSLSocketBuilder.REMOTING_KEY_STORE_FILE_PATH, keyStoreFilePath);
            config.put(SSLSocketBuilder.REMOTING_KEY_STORE_PASSWORD, "unit-tests-server");
            config.put(SSLSocketBuilder.REMOTING_SSL_PROTOCOL, "SSL");
            SSLSocketBuilder builder = new SSLSocketBuilder(config);
            builder.setUseSSLSocketFactory(false);
            return builder.createSSLSocketFactory();
         }
         

More examples of configuring SSLSocketBuilder can be found in the class FactoryConfigSSLSample in the package org.jboss.remoting.samples.config.factories.

The following is an example of configuring SSLSocketBuilder in a *-service.xml file:

            <!-- This service is used to build the SSL Server socket factory -->
            <!-- This will be where all the store/trust information will be set. -->
            <!-- If do not need to make any custom configurations, no extra attributes -->
            <!-- need to be set for the SSLSocketBuilder and just need to set the -->
            <!-- javax.net.ssl.keyStore and javax.net.ssl.keyStorePassword system properties. -->
            <!-- This can be done by just adding something like the following to the run -->
            <!-- script for JBoss -->
            <!-- (this one is for run.bat): -->
            <!-- set JAVA_OPTS=-Djavax.net.ssl.keyStore=.keystore -->
            <!-- -Djavax.net.ssl.keyStorePassword=opensource %JAVA_OPTS% -->
            <!-- Otherwise, if want to customize the attributes for SSLSocketBuilder, -->
            <!-- will need to uncomment them below. -->
            <mbean code="org.jboss.remoting.security.SSLSocketBuilder"
                  name="jboss.remoting:service=SocketBuilder,type=SSL"
                  display-name="SSL Server Socket Factory Builder">
               <!-- IMPORTANT - If making ANY customizations, this MUST be set to false. -->
               <!-- Otherwise, will used default settings and the following attributes will be ignored. -->
               <attribute name="UseSSLServerSocketFactory">false</attribute>
               <!-- This is the url string to the key store to use -->
               <attribute name="KeyStoreURL">.keystore</attribute>
               <!-- The password for the key store -->
               <attribute name="KeyStorePassword">opensource</attribute>
               <!-- The password for the keys (will use KeystorePassword if this is not set explicitly. -->
               <attribute name="KeyPassword">opensource</attribute>
               <!-- The protocol for the SSLContext. Default is TLS. -->
               <attribute name="SecureSocketProtocol">TLS</attribute>
               <!-- The algorithm for the key manager factory. Default is SunX509. -->
               <attribute name="KeyManagementAlgorithm">SunX509</attribute>
               <!-- The type to be used for the key store. -->
               <!-- Defaults to JKS. Some acceptable values are JKS (Java Keystore - Sun's keystore format), -->
               <!-- JCEKS (Java Cryptography Extension keystore - More secure version of JKS), and -->
               <!-- PKCS12 (Public-Key Cryptography Standards #12 keystore - RSA's Personal Information Exchange Syntax Standard). -->
               <!-- These are not case sensitive. -->
               <attribute name="KeyStoreType">JKS</attribute>
            </mbean>
         

It is also possible to set the default socket factory to be used when not using customized settings (meaning UseSSLSocketFactory property value is true, which is the default). This can be done by setting system property of org.jboss.remoting.defaultSocketFactory to the fully qualified class name of the javax.net.SocketFactory implementation to use. Will then call the getDefault() method on that implementation to get the SocketFactory instance to use.

Although any server socket factory can be set for the various transports, there is a customizable server socket factory service provided within JBossRemoting that supports SSL. This is the org.jboss.remoting.security.SSLServerSocketFactoryService class. The SSLServerSocketFactoryService class extends the javax.net.ServerSocketFactory class and also implements the SSLServerSocketFactoryServiceMBean interface (so that it can be set using the socketServerFactory attribute described previously). Other than providing the proper interfaces, this class is a simple wrapper around the org.jboss.remoting.security.SSLSocketBuilder class.

The following is an example of configuring SSLServerSocketFactoryService in a *-service.xml file. Note that it depends on the SSLSocketBuilder MBean defined in the xml fragment above:

         <!-- This service provides the exact same API as the ServerSocketFactory, so -->
         <!-- can be set as an attribute of that type on any MBean requiring an ServerSocketFactory. -->
         <mbean code="org.jboss.remoting.security.SSLServerSocketFactoryService"
               name="jboss.remoting:service=ServerSocketFactory,type=SSL"
               display-name="SSL Server Socket Factory">
            <depends optional-attribute-name="SSLSocketBuilder"
               proxy-type="attribute">jboss.remoting:service=SocketBuilder,type=SSL</depends>
         </mbean>
      

Since we are talking about keystores and truststores, this section will quickly go over how to quickly generate a test keystore and truststore for testing. This is not intended to be a full security overview, just an example of how I originally created mine for testing.

To get started, will need to create key store and trust store.

Generating key entry into keystore:

               C:\tmp\ssl>keytool -genkey -alias remoting -keyalg RSA
               Enter keystore password: opensource
               What is your first and last name?
               [Unknown]: Tom Elrod
               What is the name of your organizational unit?
               [Unknown]: Development
               What is the name of your organization?
               [Unknown]: JBoss Inc
               What is the name of your City or Locality?
               [Unknown]: Atlanta
               What is the name of your State or Province?
               [Unknown]: GA
               What is the two-letter country code for this unit?
               [Unknown]: US
               Is CN=Tom Elrod, OU=Development, O=JBoss Inc, L=Atlanta, ST=GA, C=US correct?
               [no]: yes

               Enter key password for <remoting>
               (RETURN if same as keystore password):
            

Since did not specify the -keystore filename parameter, created the keystore in $HOME/.keystore (or C:\Documents and Settings\Tom\.keystore).

Export the RSA certificate (without the private key)

               C:\tmp\ssl>keytool -export -alias remoting -file remoting.cer
               Enter keystore password: opensource
               Certificate stored in file <remoting.cer>
            

Import the RSE certificate into a new truststore file.

               C:\tmp\ssl>keytool -import -alias remoting -keystore .truststore -file remoting.cer
               Enter keystore password: opensource
               Owner: CN=Tom Elrod, OU=Development, O=JBoss Inc, L=Atlanta, ST=GA, C=US
               Issuer: CN=Tom Elrod, OU=Development, O=JBoss Inc, L=Atlanta, ST=GA, C=US
               Serial number: 426f1ee3
               Valid from: Wed Apr 27 01:10:59 EDT 2005 until: Tue Jul 26 01:10:59 EDT 2005
               Certificate fingerprints:
               MD5: CF:D0:A8:7D:20:49:30:67:44:03:98:5F:8E:01:4A:6A
               SHA1: C6:76:3B:6C:79:3B:8D:FD:FB:4F:33:3B:25:C9:01:9D:50:BF:9F:8A
               Trust this certificate? [no]: yes
               Certificate was added to keystore
            

Now have two files, .keystore for the server and .truststore for the client.

Common errors when using server socket factory:

javax.net.ssl.SSLException: No available certificate corresponds to the SSL cipher suites which are enabled.

The 'javax.net.ssl.keyStore' system property has not been set and are using the default SSLServerSocketFactory.

java.net.SocketException: Default SSL context init failed: Cannot recover key

The 'javax.net.ssl.keyStorePassword' system property has not been set and are using the default SSLServerSocketFactory.

java.io.IOException: Can not create SSL Server Socket Factory due to the url to the key store not being set.

The default SSLServerSocketFactory is NOT being used (so custom configuration for the server socket factory) and the key store url has not been set.

java.lang.IllegalArgumentException: password can't be null

The default SSLServerSocketFactory is NOT being used (so custom configuration for the server socket factory) and the key store password has not been set.

As with all configuration parameters, there are several avenues for specifying parameter values. See Section General transport configuration for a general discussion of parameter configuration in Remoting. The transport independent key for setting timeouts is "timeout", also available as org.jboss.remoting.ServerInvoker.TIMEOUT. All server invokers also have the getter/setter methods

      public int getTimeout();
                 
      public void setTimeout(int timeout);
      

where the values are given in milliseconds. The default timeout value is 60000 for server invokers.

Beginning with release 2.2.0, some Remoting transports offer a per invocation transport facility, which allows a timeout value to be set for a particular invocation, overriding the client invoker's previously configured timeout value. The per invocation timeout is set by passing the String representation of the timeout value in the invocation's metadata map, using the key "timeout". For example,

        HashMap metadata = new HashMap();
        metadata.put("timeout", "2000");
        client.invoke("testInvocation", metadata);
      

will allow approximately 2 seconds for this particular invocation, after which the timeout value will be reset to its previously configured value.

Each transport that supports per invocation timeouts handles them a little differently. More details are given below.

There are many ways in which to expose a remote interface to a java object. Some require a complex framework API based on a standard specification and some require new technologies like annotations and AOP. Each of these have their own benefits. JBoss Remoting transporters provide the same behavior via a simple API without the need for any of the newer technologies.

When boiled down, transporters take a plain old java object (POJO) and expose a remote proxy to it via JBoss Remoting. Dynamic proxies and reflection are used to make the typed method calls on that target POJO. Since JBoss Remoting is used, can select from a number of different network transports (i.e. rmi, http, socket, multiplex, etc.), including support for SSL. Even clustering features can be included.

How it works

In this section will discuss how remoting transporters can be used, some requirments for usage, and a little detail on the implementation. For greater breath on usage, please review the transporter samples as most use cases are covered there.

To start, will need to have a plain old java object that implements one or more interfaces that want to expose for remote method invocation. Then will need to create a org.jboss.remoting.transporter.TransporterServer to wrap around it, so that can be exposed remotely. This can be done in one of two basic ways. The first is to use a static createTransporterServer() method of the TransporterServer class. There are many of these create methods, but all basically do that same thing in that they take a remoting locator and target pojo and will return a TransporterServer instance that has been started and ready to receive remote invocations (see javadoc for TransporterServer for all the different static createTransporterServer() methods). The other way to create a TransporterServer for the target pojo is to construct an instance of it. This provides a little more flexibility as are able to control more aspects of the TransporterServer, such as when it will be started.

When a TransporterServer is created, it will create a remoting Connector using the locator provided. It will generate a server invocation handler that wraps the target pojo provided and use reflection to make the calls on it based on the invocations it receives from clients. By default, the subsystem underwhich the server invocation handler is registered is the interface class name for which the target pojo is exposing. If the target implements multiple interfaces, and a specific one to use is not specified, all the interfaces will be registered as subsystems for the same server invocation handler. Whenever no long want the target pojo to receive remote method invocations, will need to call the stop() method on the TransporterServer for the target pojo (this is very important, as otherwise will never be released from memory and will continue to consume network and memory resources).

On the client side, in order to be able to call on the target pojo remotely, will need to use the org.jboss.remoting.transporter.TransporterClient. Unlike the TransporterServer, can only use the static create methods of the TransporterClient (this is because the return to the static create method is a typed dynamic proxy). The static method to call on the TransportClient is createTransporterClient(), where will pass the locator to find the target pojo (same as one used when creating the TransporterServer) and the interface for the target pojo that want to make remote method invocations on. The return from this create call will be a dynamic proxy which you can cast to to same interface type supplied. At that point, can make typed method invocations on the returned object, which will then make the remote invocations under the covers. Note that can have multiple transporter clients to the same target pojo, each using different interface types for making calls.

When no longer need to make invocations on the target pojo, the resources associated with the remoting client will need to be cleaned up. This is done by calling the destroyTransporterClient() method of the TransporterClient. This is important to remember to do, as will otherwise leave network resources active even though not in use.

One of the features of using remoting transporters is location transparency. By this mean that client proxies returned by the TransporterClient can be passed over the network. For example, can have a target pojo that returns from a method call a client proxy (that it created using the TransporterClient) in which the client can call on directly as well. See the transporter proxy sample code to see how this can be done.

Another nice feature when using transporters is the ability to cluster. To be more specific, can create multiple target pojos using the TransporterServer in clustered mode and then use the TransporterClient in clustered mode to create a client proxy that will discover the location of the target pojos are wanting to call on. Will also provide automatic, seemless failover of remote method invocations in the case that a particular target pojo instance fails. However, note that only provide invocation failover and does not take into account state transfer between target pojos (would need addition of JBoss Cache or some other state synchronization tool).

The simple transporter example (found in org.jboss.remoting.samples.transporter.simple package) demonstrates a very simple example of how to use the transporters to expose a plain old java object for remote method invocations.

In this simple transporter example, will be taking a class that formats a java.util.Date into a simple String representation and exposing it so can call on the remotely. The target object in this case, org.jboss.remoting.samples.transporter.simple.DateProcessorImpl, implements the org.jboss.remoting.samples.transporter.simple.DateProcessor interfaces (as shown below):

public interface DateProcessor
{
   public String formatDate(Date dateToConvert);
}


public class DateProcessorImpl implements DateProcessor
{
   public String formatDate(Date dateToConvert)
   {
      DateFormat dateFormat = DateFormat.getDateInstance(DateFormat.MEDIUM);
      return dateFormat.format(dateToConvert);
   }
}

This is then exposed using the TransporterServer by the org.jboss.remoting.samples.transporter.simple.Server class.

public class Server
{
   public static void main(String[] args) throws Exception
   {
      TransporterServer server = TransporterServer.createTransporterServer("socket://localhost:5400", new DateProcessorImpl(), DateProcessor.class.getName());
      Thread.sleep(10000);
      server.stop();
   }
}

The Server class simply creates a TransporterServer by indicating the locator url would like to use for the remoting server, a newly created instance of DataProcessorImpl, and the interface type would like to expose remotely. The TransporterServer returned from the createTransporterServer call is live and ready to receive incoming method invocation requests. Will then wait 10 seconds for a request, then stop the server.

Next need to have client to make the remote invocation. This can be found within org.jboss.remoting.samples.transporter.simple.Client.

public class Client
{
   public static void main(String[] args) throws Exception
   {
      DateProcessor dateProcessor = (DateProcessor) TransporterClient.createTransporterClient("socket://localhost:5400", DateProcessor.class);
      String formattedDate = dateProcessor.formatDate(new Date());
      System.out.println("Current date: " + formattedDate);
   }
}

In the Client class, create a TransporterClient which can be cast to the desired type, which is DataProcessor in this case. In calling the createTransporterClient, need to specify the locator ulr (same as was used for the TransporterServer), and the interface type will be calling on for the target pojo. Once have the DateProcessor variable, will make the call to formatDate() and pass a newly created Date object. The return will be a formated String of the date passed.

To run this example, can run the Server and then the Client. Or can go to the examples directory and run the ant target 'run-transporter-simple-server' and then in another window run the ant target 'run-transporter-simple-client'. For example:

ant run-transporter-simple-server

and then:

ant run-transporter-simple-client

The output from the client window should look similar to:

Current date: Jul 31, 2006

The basic transporter example (found in org.jboss.remoting.samples.transporter.basic package) illustrates how to build a simple transporter for making remote invocations on plain old java objects.

In this basic transporter example, will be using a few domain objects; Customer and Address, which are just data objects.

public class Customer implements Serializable
{
   private String firstName = null;
   private String lastName = null;
   private Address addr = null;
   private int customerId = -1;

   public String getFirstName()
   {
      return firstName;
   }

   public void setFirstName(String firstName)
   {
      this.firstName = firstName;
   }

   public String getLastName()
   {
      return lastName;
   }

   public void setLastName(String lastName)
   {
      this.lastName = lastName;
   }

   public Address getAddr()
   {
      return addr;
   }

   public void setAddr(Address addr)
   {
      this.addr = addr;
   }

   public int getCustomerId()
   {
      return customerId;
   }

   public void setCustomerId(int customerId)
   {
      this.customerId = customerId;
   }

   public String toString()
   {
      StringBuffer buffer = new StringBuffer();
      buffer.append("\nCustomer:\n");
      buffer.append("customer id: " + customerId + "\n");
      buffer.append("first name: " + firstName + "\n");
      buffer.append("last name: " + lastName + "\n");
      buffer.append("street: " + addr.getStreet() + "\n");
      buffer.append("city: " + addr.getCity() + "\n");
      buffer.append("state: " + addr.getState() + "\n");
      buffer.append("zip: " + addr.getZip() + "\n");

      return buffer.toString();
   }
}

public class Address implements Serializable
{
   private String street = null;
   private String city = null;
   private String state = null;
   private int zip = -1;

   public String getStreet()
   {
      return street;
   }

   public void setStreet(String street)
   {
      this.street = street;
   }

   public String getCity()
   {
      return city;
   }

   public void setCity(String city)
   {
      this.city = city;
   }

   public String getState()
   {
      return state;
   }

   public void setState(String state)
   {
      this.state = state;
   }

   public int getZip()
   {
      return zip;
   }

   public void setZip(int zip)
   {
      this.zip = zip;
   }
}

Next comes the POJO that we want to expose a remote proxy for, which is CustomerProcessorImpl class. This implementation has one method to process a Customer object. It also implements the CustomerProcessor interface.

public class CustomerProcessorImpl implements CustomerProcessor
{
   /**
    * Takes the customer passed, and if not null and customer id
    * is less than 0, will create a new random id and set it.
    * The customer object returned will be the modified customer
    * object passed.
    *
    * @param customer
    * @return
    */
   public Customer processCustomer(Customer customer)
   {
      if(customer != null && customer.getCustomerId() < 0)
      {
         customer.setCustomerId(new Random().nextInt(1000));
      }
      System.out.println("processed customer with new id of " + customer.getCustomerId());
      return customer;
   }
}

public interface CustomerProcessor
{
   /**
    * Process a customer object.  Implementors
    * should ensure that the customer object
    * passed as parameter should have its internal
    * state changed somehow and returned.
    *
    * @param customer
    * @return
    */
   public Customer processCustomer(Customer customer);
}

So far, nothing special, just plain old java objects. Next need to create the server component that will listen for remote request to invoke on the target POJO. This is where the transporter comes in.

public class Server
{
   private String locatorURI = "socket://localhost:5400";
   private TransporterServer server = null;

   public void start() throws Exception
   {
      server = TransporterServer.createTransporterServer(locatorURI, new CustomerProcessorImpl());
   }

   public void stop()
   {
      if(server != null)
      {
         server.stop();
      }
   }

   public static void main(String[] args)
   {
      Server server = new Server();
      try
      {
         server.start();

         Thread.currentThread().sleep(60000);

      }
      catch(Exception e)
      {
         e.printStackTrace();
      }
      finally
      {
         server.stop();
      }
   }
}

The Server class is a pretty simple one. It calls the TransporterServer factory method to create the server component for the CustomerProcessorImpl instance using the specified remoting locator information.

The TransporterServer returned from the createTransporterServer() call will be a running instance of a remoting server using the socket transport that is bound to localhost and listening for remote requests on port 5400. The requests that come in will be forwarded to the remoting handler which will convert them into direct method calls on the target POJO, CustomerProcessorImpl in this case, using reflection.

The TransporterServer has a start() and stop() method exposed to control when to start and stop the running of the remoting server. The start() method is called automatically within the createTransporterServer() method, so is ready to receive requests upon the return of this method. The stop() method, however, needs to be called explicitly when no longer wish to receive remote calls on the target POJO.

Next up is the client side. This is represented by the Client class.

public class Client
{
   private String locatorURI = "socket://localhost:5400";

   public void makeClientCall() throws Exception
   {
      Customer customer = createCustomer();

      CustomerProcessor customerProcessor = (CustomerProcessor) TransporterClient.createTransporterClient(locatorURI, CustomerProcessor.class);

      System.out.println("Customer to be processed: " + customer);
      Customer processedCustomer = customerProcessor.processCustomer(customer);
      System.out.println("Customer is now: " + processedCustomer);

      TransporterClient.destroyTransporterClient(customerProcessor);
   }

   private Customer createCustomer()
   {
      Customer cust = new Customer();
      cust.setFirstName("Bob");
      cust.setLastName("Smith");
      Address addr = new Address();
      addr.setStreet("101 Oak Street");
      addr.setCity("Atlanata");
      addr.setState("GA");
      addr.setZip(30249);
      cust.setAddr(addr);

      return cust;
   }

   public static void main(String[] args)
   {
      Client client = new Client();
      try
      {
         client.makeClientCall();
      }
      catch(Exception e)
      {
         e.printStackTrace();
      }
   }
}

The Client class is also pretty simple. It creates a new Customer object instance, creates the remote proxy to the CustomerProcessor, and then calls on the CustomerProcessor to process its new Customer instance.

To get the remote proxy for the CustomerProcessor, all that is required is to call the TransporterClient's method createTransporterClient() method and pass the locator uri and the type of the remote proxy (and explicitly cast the return to that type). This will create a dynamic proxy for the specified type, CustomerProcessor in this case, which is backed by a remoting client which in turn makes the calls to the remote POJO's remoting server. Once the call to createTransportClient() has returned, the remoting client has already made its connection to the remoting server and is ready to make calls (will throw an exception if it could not connect to the specified remoting server).

When finished making calls on the remote POJO proxy, will need to explicitly destroy the client by calling destroyTransporterClient() and pass the remote proxy instance. This allows the remoting client to disconnect from the POJO's remoting server and clean up any network resources previously used.

To run this example, can run the Server and then the Client. Or can go to the examples directory and run the ant target 'run-transporter-basic-server' and then in another window run the ant target 'run-transporter-basic-client'. For example:

ant run-transporter-basic-server

and then:

ant run-transporter-basic-client

The output from the Client console should be similar to:

Customer to be processed:
Customer:
customer id: -1
first name: Bob
last name: Smith
street: 101 Oak Street
city: Atlanata
state: GA
zip: 30249

Customer is now:
Customer:
customer id: 204
first name: Bob
last name: Smith
street: 101 Oak Street
city: Atlanata
state: GA
zip: 30249

and the output from the Server class should be similar to:

processed customer with new id of 204

The output shows that the Customer instance created on the client was sent to the server where it was processed (by setting the customer id to 204) and returned to the client (and printed out showing that the customer id was set to 204).

The transporter serialization example (found in org.jboss.remoting.samples.transporter.serialization package) is very similar to the previous basic example, except in this one, the domain objects being sent over the wire will NOT be Serializable. This is accomplished via the use of JBoss Serialization. This can be useful when don't know which domain objects you may be using in remote calls or if adding ability for remote calls on legacy code.

To start, there are a few more domain objects: Order, OrderProcessor, and OrderProcessorImpl. These will use some of the domain objects from the previous example as well, such as Customer.

public class Order
{
   private int orderId = -1;
   private boolean isProcessed = false;
   private Customer customer = null;
   private List items = null;


   public int getOrderId()
   {
      return orderId;
   }

   public void setOrderId(int orderId)
   {
      this.orderId = orderId;
   }

   public boolean isProcessed()
   {
      return isProcessed;
   }

   public void setProcessed(boolean processed)
   {
      isProcessed = processed;
   }

   public Customer getCustomer()
   {
      return customer;
   }

   public void setCustomer(Customer customer)
   {
      this.customer = customer;
   }

   public List getItems()
   {
      return items;
   }

   public void setItems(List items)
   {
      this.items = items;
   }

   public String toString()
   {
      StringBuffer buffer = new StringBuffer();
      buffer.append("\nOrder:\n");
      buffer.append("\nIs processed: " + isProcessed);
      buffer.append("\nOrder id: " + orderId);
      buffer.append(customer.toString());

      buffer.append("\nItems ordered:");
      Iterator itr = items.iterator();
      while(itr.hasNext())
      {
         buffer.append("\n" + itr.next().toString());
      }

      return buffer.toString();
   }
}

public class OrderProcessorImpl implements OrderProcessor
{
   private CustomerProcessor customerProcessor = null;

   public OrderProcessorImpl()
   {
      customerProcessor = new CustomerProcessorImpl();
   }

   public Order processOrder(Order order)
   {
      System.out.println("Incoming order to process from customer.\n" + order.getCustomer());

      // has this customer been processed?
      if(order.getCustomer().getCustomerId() < 0)
      {
         order.setCustomer(customerProcessor.processCustomer(order.getCustomer()));
      }

      List items = order.getItems();
      System.out.println("Items ordered:");
      Iterator itr = items.iterator();
      while(itr.hasNext())
      {
         System.out.println(itr.next());
      }

      order.setOrderId(new Random().nextInt(1000));
      order.setProcessed(true);

      System.out.println("Order processed.  Order id now: " + order.getOrderId());
      return order;
   }
}

public interface OrderProcessor
{
   public Order processOrder(Order order);
}

The OrderProcessorImpl will take orders, via the processOrder() method, check that the customer for the order has been processed, and if not have the customer processor process the new customer. Then will place the order, which means will just set the order id and processed attribute to true.

The most important point to this example is that the Order class does NOT implement java.io.Serializable.

Now onto the Server class. This is just like the previous Server class in the basic example with one main difference: the locatorURI value.

public class Server
{
   private String locatorURI = "socket://localhost:5400/?serializationtype=jboss";
   private TransporterServer server = null;

   public void start() throws Exception
   {
      server = TransporterServer.createTransporterServer(locatorURI, new OrderProcessorImpl());
   }

   public void stop()
   {
      if(server != null)
      {
         server.stop();
      }
   }

   public static void main(String[] args)
   {
      Server server = new Server();
      try
      {
         server.start();

         Thread.currentThread().sleep(60000);

      }
      catch(Exception e)
      {
         e.printStackTrace();
      }
      finally
      {
         server.stop();
      }
   }
}

The addition of serializationtype=jboss tells the remoting framework to use JBoss Serialization in place of the standard java serialization.

On the client side, there is the Client class, just as in the previous basic example.

public class Client
{
   private String locatorURI = "socket://localhost:5400/?serializationtype=jboss";

   public void makeClientCall() throws Exception
   {
      Order order = createOrder();

      OrderProcessor orderProcessor = (OrderProcessor) TransporterClient.createTransporterClient(locatorURI, OrderProcessor.class);

      System.out.println("Order to be processed: " + order);
      Order changedOrder = orderProcessor.processOrder(order);
      System.out.println("Order now processed " + changedOrder);

      TransporterClient.destroyTransporterClient(orderProcessor);

   }

   private Order createOrder()
   {
      Order order = new Order();
      Customer customer = createCustomer();
      order.setCustomer(customer);

      List items = new ArrayList();
      items.add("Xbox 360");
      items.add("Wireless controller");
      items.add("Ghost Recon 3");

      order.setItems(items);

      return order;
   }

   private Customer createCustomer()
   {
      Customer cust = new Customer();
      cust.setFirstName("Bob");
      cust.setLastName("Smith");
      Address addr = new Address();
      addr.setStreet("101 Oak Street");
      addr.setCity("Atlanata");
      addr.setState("GA");
      addr.setZip(30249);
      cust.setAddr(addr);

      return cust;
   }

   public static void main(String[] args)
   {
      Client client = new Client();
      try
      {
         client.makeClientCall();
      }
      catch(Exception e)
      {
         e.printStackTrace();
      }
   }
}

Again, the biggest difference to note is that have added serializationtype=jboss to the locator uri.

Note: Running this example requires JDK 1.5.

To run this example, can run the Server and then the Client. Or can go to the examples directory and run the ant target 'ant run-transporter-serialization-server' and then in another window run the ant target 'ant run-transporter-serialization-client'. For example:

ant run-transporter-serialization-server

and then:

ant run-transporter-serialization-client

When the server and client are run the output for the Client class is:

Order to be processed:
Order:

Is processed: false
Order id: -1
Customer:
customer id: -1
first name: Bob
last name: Smith
street: 101 Oak Street
city: Atlanata
state: GA
zip: 30249

Items ordered:
Xbox 360
Wireless controller
Ghost Recon 3
Order now processed
Order:

Is processed: true
Order id: 221
Customer:
customer id: 861
first name: Bob
last name: Smith
street: 101 Oak Street
city: Atlanata
state: GA
zip: 30249

Items ordered:
Xbox 360
Wireless controller
Ghost Recon 3

The client output shows the printout of the newly created order before calling the OrderProcessor and then the processed order afterwards. Noticed that the processed order has its customer's id set, its order id set and the processed attribute is set to true.

And the output from the Server is:

Incoming order to process from customer.

Customer:
customer id: -1
first name: Bob
last name: Smith
street: 101 Oak Street
city: Atlanata
state: GA
zip: 30249

processed customer with new id of 861
Items ordered:
Xbox 360
Wireless controller
Ghost Recon 3
Order processed.  Order id now: 221

The server output shows the printout of the customer before being processed and then the order while being processed.

In the previous examples, there has been one and only one target POJO to make calls upon. If that target POJO was not available, the client call would fail. In the transporter clustered example (found in org.jboss.remoting.samples.transporter.clustered package), will show how to use the transporter in clustered mode so that if one target POJO becomes unavailable, the client call can be seamlessly failed over to another available target POJO on the network, regardless of network transport type.

This example uses the domain objects from the first, basic example, so only need to cover the client and server code. For this example, there are three different server classes. The first class is the SocketServer class, which is the exact same as the Server class in the basic example, except for the call to the TransportServer's createTransportServer() method.

public class SocketServer
{
   public static String locatorURI = "socket://localhost:5400";
   private TransporterServer server = null;

   public void start() throws Exception
   {
      server = TransporterServer.createTransporterServer(getLocatorURI(), new CustomerProcessorImpl(),
                                                         CustomerProcessor.class.getName(), true);
   }

   protected String getLocatorURI()
   {
      return locatorURI;
   }

   public void stop()
   {
      if(server != null)
      {
         server.stop();
      }
   }

   public static void main(String[] args)
   {
      SocketServer server = new SocketServer();
      try
      {
         server.start();

         Thread.currentThread().sleep(60000);

      }
      catch(Exception e)
      {
         e.printStackTrace();
      }
      finally
      {
         server.stop();
      }
   }
}

Notice that are now calling on the TransportServer to create a server with the locator uri and target POJO (CustomerProcessorImpl) as before, but have also added the interface type of the target POJO (CustomerProcessor) and that want clustering turned on (via the last true parameter).

The interface type of the target POJO is needed because this will be used as the subsystem within the remoting server for the target POJO. The subsystem value will be what the client uses to determine if discovered remoting server is for the target POJO they are looking for.

The second server class is the RMIServer class. The RMIServer class extends the SocketServer class and uses a different locator uri to specify rmi as the transport protocol and a different port (5500).

public class RMIServer extends SocketServer
{
   private String localLocatorURI = "rmi://localhost:5500";

   protected String getLocatorURI()
   {
      return localLocatorURI;
   }

   public static void main(String[] args)
   {
      SocketServer server = new RMIServer();
      try
      {
         server.start();

         Thread.currentThread().sleep(60000);

      }
      catch(Exception e)
      {
         e.printStackTrace();
      }
      finally
      {
         server.stop();
      }
   }
}

The last server class is the HTTPServer class. The HTTPServer class also extends the SocketServer class and specifies http as the transport protocol and 5600 as the port to listen for requests on.

public class HTTPServer extends SocketServer
{
   private String localLocatorURI = "http://localhost:5600";

   protected String getLocatorURI()
   {
      return localLocatorURI;
   }

   public static void main(String[] args)
   {
      SocketServer server = new HTTPServer();
      try
      {
         server.start();

         Thread.currentThread().sleep(60000);

      }
      catch(Exception e)
      {
         e.printStackTrace();
      }
      finally
      {
         server.stop();
      }
   }
}

On the client side, there is only the Client class. This class is very similar to the one from the basic example. The main exceptions are (1) the addition of a TransporterClient call to create a transporter client and (2) the fact that it continually loops, making calls on its customerProcessor variable to process customers. This is done so that when we run the client, we can kill the different servers and see that the client continues to loop making its calls without any exceptions or errors.

public class Client
{
   private String locatorURI = SocketServer.locatorURI;

   private CustomerProcessor customerProcessor = null;

   public void makeClientCall() throws Exception
   {
      Customer customer = createCustomer();

      System.out.println("Customer to be processed: " + customer);
      Customer processedCustomer = customerProcessor.processCustomer(customer);
      System.out.println("Customer is now: " + processedCustomer);

      //TransporterClient.destroyTransporterClient(customerProcessor);
   }

   public void getCustomerProcessor() throws Exception
   {
      customerProcessor = (CustomerProcessor) TransporterClient.createTransporterClient(locatorURI, CustomerProcessor.class, true);
   }

   private Customer createCustomer()
   {
      Customer cust = new Customer();
      cust.setFirstName("Bob");
      cust.setLastName("Smith");
      Address addr = new Address();
      addr.setStreet("101 Oak Street");
      addr.setCity("Atlanata");
      addr.setState("GA");
      addr.setZip(30249);
      cust.setAddr(addr);

      return cust;
   }

   public static void main(String[] args)
   {
      Client client = new Client();
      try
      {
         client.getCustomerProcessor();
         while(true)
         {
            try
            {
               client.makeClientCall();
               Thread.currentThread().sleep(5000);
            }
            catch(Exception e)
            {
               e.printStackTrace();
            }
         }
      }
      catch(Exception e)
      {
         e.printStackTrace();
      }
   }
}

The first item of note is that the locator uri from the SocketServer class is being used. Technically, this is not required as once the clustered TransporterClient is started, it will start to discover the remoting servers that exist on the network. However, this process can take several seconds to occur, so unless it is known that no calls will be made on the remote proxy right away, it is best to bootstrap with a known target server.

Can also see that in the main() method, the first call on the Client instance is to getCustomerProcessor(). This method will call the TransporterClient's createTransporterClient() method and passes the locator uri for the target POJO server, the type of POJO's remote proxy, and that clustering should be enabled.

After getting the customer processor remote proxy, will continually loop making calls using the remote proxy (via the processCustomer() method on the customerProcessor variable).

To run this example, all the servers need to be started (by running the SocketServer, RMIServer, and HTTPServer classes). Then run the Client class. This can be done via ant targets as well. So for example, could open four console windows and enter the ant targets as follows:

ant run-transporter-clustered-socket-server

ant run-transporter-clustered-http-server

ant run-transporter-clustered-rmi-server

ant run-transporter-clustered-client

Once the client starts running, should start to see output logged to the SocketServer, since this is the one used to bootstrap. This output would look like:

processed customer with new id of 378
processed customer with new id of 487
processed customer with new id of 980

Once the SocketServer instance has received a few calls, kill this instance. The next time the client makes a call on its remote proxy, which happens every five seconds, it should fail over to another one of the servers (and will see similar output on that server instance). After that server has received a few calls, kill it and should see it fail over once again to the last server instance that is still running. Then, if kill that server instance, will see a CannotConnectException and stack trace similar to the following:

...
org.jboss.remoting.CannotConnectException: Can not connect http client invoker.
 at org.jboss.remoting.transport.http.HTTPClientInvoker.useHttpURLConnection(HTTPClientInvoker.java:147)
 at org.jboss.remoting.transport.http.HTTPClientInvoker.transport(HTTPClientInvoker.java:56)
 at org.jboss.remoting.RemoteClientInvoker.invoke(RemoteClientInvoker.java:112)
 at org.jboss.remoting.Client.invoke(Client.java:226)
 at org.jboss.remoting.Client.invoke(Client.java:189)
 at org.jboss.remoting.Client.invoke(Client.java:174)
 at org.jboss.remoting.transporter.TransporterClient.invoke(TransporterClient.java:219)
 at $Proxy0.processCustomer(Unknown Source)
 at org.jboss.remoting.samples.transporter3.client.Client.makeClientCall(Client.java:29)
 at org.jboss.remoting.samples.transporter3.client.Client.main(Client.java:64)
 at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
 at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
 at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
 at java.lang.reflect.Method.invoke(Method.java:585)
 at com.intellij.rt.execution.application.AppMain.main(AppMain.java:86)
Caused by: java.net.ConnectException: Connection refused: connect
 at java.net.PlainSocketImpl.socketConnect(Native Method)
 at java.net.PlainSocketImpl.doConnect(PlainSocketImpl.java:333)
 at java.net.PlainSocketImpl.connectToAddress(PlainSocketImpl.java:195)
 at java.net.PlainSocketImpl.connect(PlainSocketImpl.java:182)
 at java.net.Socket.connect(Socket.java:507)
 at java.net.Socket.connect(Socket.java:457)
 at sun.net.NetworkClient.doConnect(NetworkClient.java:157)
 at sun.net.www.http.HttpClient.openServer(HttpClient.java:365)
 at sun.net.www.http.HttpClient.openServer(HttpClient.java:477)
 at sun.net.www.http.HttpClient.<init>(HttpClient.java:214)
 at sun.net.www.http.HttpClient.New(HttpClient.java:287)
 at sun.net.www.http.HttpClient.New(HttpClient.java:299)
 at sun.net.www.protocol.http.HttpURLConnection.getNewHttpClient(HttpURLConnection.java:792)
 at sun.net.www.protocol.http.HttpURLConnection.plainConnect(HttpURLConnection.java:744)
 at sun.net.www.protocol.http.HttpURLConnection.connect(HttpURLConnection.java:669)
 at sun.net.www.protocol.http.HttpURLConnection.getOutputStream(HttpURLConnection.java:836)
 at org.jboss.remoting.transport.http.HTTPClientInvoker.useHttpURLConnection(HTTPClientInvoker.java:117)
 ... 14 more

since there are no target servers left to make calls on. Notice that earlier in the client output there were no errors while was failing over to the different servers as they were being killed.

Because the CannotConnectException is being caught within the while loop, the client will continue to try calling the remote proxy and getting this exception. Now re-run any of the previously killed servers and will see that the client will discover that server instance and begin to successfully call on that server. The output should look something like:

...
 at sun.net.www.protocol.http.HttpURLConnection.connect(HttpURLConnection.java:669)
 at sun.net.www.protocol.http.HttpURLConnection.getOutputStream(HttpURLConnection.java:836)
 at org.jboss.remoting.transport.http.HTTPClientInvoker.useHttpURLConnection(HTTPClientInvoker.java:117)
 ... 14 more

Customer to be processed:
Customer:
customer id: -1
first name: Bob
last name: Smith
street: 101 Oak Stree
city: Atlanata
state: null
zip: 30249

Customer is now:
Customer:
customer id: 633
first name: Bob
last name: Smith
street: 101 Oak Stree
city: Atlanata
state: null
zip: 30249

...

The multiple transporter example (found in org.jboss.remoting.samples.transporter.multiple package) shows how can have a multiple target pojos exposed via the same TransporterServer. In this example, will be two pojos being exposed, CustomerProcessorImpl and AccountProcessorImpl. Since the domain objects for this example is similar to the others discussed in previous examples, will just focus on the server and client code. On the server side, need to create the TransporterServer so that will included both of the target pojos.

public class Server
{
   private String locatorURI = "socket://localhost:5400";
   private TransporterServer server = null;

   public void start() throws Exception
   {
      server = TransporterServer.createTransporterServer(locatorURI, new CustomerProcessorImpl(), CustomerProcessor.class.getName());
      server.addHandler(new AccountProcessorImpl(), AccountProcessor.class.getName());
   }

   public void stop()
   {
      if(server != null)
      {
         server.stop();
      }
   }

   public static void main(String[] args)
   {
      Server server = new Server();
      try
      {
         server.start();

         Thread.currentThread().sleep(60000);

      }
      catch(Exception e)
      {
         e.printStackTrace();
      }
      finally
      {
         server.stop();
      }
   }
}

The TransporterServer is created with the CustomerProcessorImpl as the inital target pojo. Now that have a live TransporterServer, can add other pojos as targets. This is done using the addHandler() method where the target pojo instance is passed and then the interface type to be exposed as.

Next have the Client that makes the call to both pojos.

public class Client
{
   private String locatorURI = "socket://localhost:5400";

   public void makeClientCall() throws Exception
   {
      Customer customer = createCustomer();

      CustomerProcessor customerProcessor = (CustomerProcessor) TransporterClient.createTransporterClient(locatorURI, CustomerProcessor.class);

      System.out.println("Customer to be processed: " + customer);
      Customer processedCustomer = customerProcessor.processCustomer(customer);
      System.out.println("Customer is now: " + processedCustomer);

      AccountProcessor accountProcessor = (AccountProcessor) TransporterClient.createTransporterClient(locatorURI, AccountProcessor.class);

      System.out.println("Asking for a new account to be created for customer.");
      Account account = accountProcessor.createAccount(processedCustomer);
      System.out.println("New account: " + account);

      TransporterClient.destroyTransporterClient(customerProcessor);
      TransporterClient.destroyTransporterClient(accountProcessor);

   }

   private Customer createCustomer()
   {
      Customer cust = new Customer();
      cust.setFirstName("Bob");
      cust.setLastName("Smith");
      Address addr = new Address();
      addr.setStreet("101 Oak Street");
      addr.setCity("Atlanta");
      addr.setState("GA");
      addr.setZip(30249);
      cust.setAddr(addr);

      return cust;
   }

   public static void main(String[] args)
   {
      org.jboss.remoting.samples.transporter.multiple.client.Client client = new org.jboss.remoting.samples.transporter.multiple.client.Client();
      try
      {
         client.makeClientCall();
      }
      catch (Exception e)
      {
         e.printStackTrace();
      }
   }


}

Notice that TransporterClients are created for each target pojo want to call upon, they just happen to share the same locator uri. These are independant instances so need to both be destroyed on their own when finished with them.

To run this example, run the Server class and then the Client class. This can be done via ant targets 'run-transporter-multiple-server' and then 'run-transporter-multiple-client'. For example:

ant run-transporter-multiple-server

and then:

ant run-transporter-multiple-client

The output for the server should look similar to:

processed customer with new id of 980
Created new account with account number: 1 and for customer:

Customer:
customer id: 980
first name: Bob
last name: Smith
street: 101 Oak Street
city: Atlanta
state: GA
zip: 30249

and the output from the client should look similar to:

Customer to be processed: 
Customer:
customer id: -1
first name: Bob
last name: Smith
street: 101 Oak Street
city: Atlanta
state: GA
zip: 30249

Customer is now: 
Customer:
customer id: 980
first name: Bob
last name: Smith
street: 101 Oak Street
city: Atlanta
state: GA
zip: 30249

Asking for a new account to be created for customer.
New account: Account - account number: 1
Customer: 
Customer:
customer id: 980
first name: Bob
last name: Smith
street: 101 Oak Street
city: Atlanta
state: GA
zip: 30249

The proxy transporter example (found in org.jboss.remoting.samples.transporter.proxy package) shows how can have a TransporterClient sent over the network and called upon. In this example, will have a target pojo, CustomerProcessorImpl which itself creates a TransporterClient to another target pojo, Customer, and return it as response to a method invocation.

To start, will look at the initial target pojo, CustomerProcessorImpl.

public class CustomerProcessorImpl implements CustomerProcessor
{
   private String locatorURI = "socket://localhost:5401";

   /**
    * Takes the customer passed, and if not null and customer id
    * is less than 0, will create a new random id and set it.
    * The customer object returned will be the modified customer
    * object passed.
    *
    * @param customer
    * @return
    */
   public ICustomer processCustomer(Customer customer)
   {
      if (customer != null && customer.getCustomerId() < 0)
      {
         customer.setCustomerId(new Random().nextInt(1000));
      }

      ICustomer customerProxy = null;
      try
      {
         TransporterServer server = TransporterServer.createTransporterServer(locatorURI, customer, ICustomer.class.getName());
         customerProxy = (ICustomer) TransporterClient.createTransporterClient(locatorURI, ICustomer.class);
      }
      catch (Exception e)
      {
         e.printStackTrace();
      }

      System.out.println("processed customer with new id of " + customerProxy.getCustomerId());
      return customerProxy;
   }

}

Notice that the processCustomer() method will take a Customer object and set customer id on it. Then it will create a TransporterServer for that customer instance and also create a TransporterClient for the same instance and return that TransporterClient proxy as the return to the processCustomer() method.

Next will look at the Customer class. It is a basic data object in that is really just stores the customer data.

public class Customer implements Serializable, ICustomer
{
   private String firstName = null;
   private String lastName = null;
   private Address addr = null;
   private int customerId = -1;

   public String getFirstName()
   {
      return firstName;
   }

   public void setFirstName(String firstName)
   {
      this.firstName = firstName;
   }

   public String getLastName()
   {
      return lastName;
   }

   public void setLastName(String lastName)
   {
      this.lastName = lastName;
   }

   public Address getAddr()
   {
      return addr;
   }

   public void setAddr(Address addr)
   {
      this.addr = addr;
   }

   public int getCustomerId()
   {
      return customerId;
   }

   public void setCustomerId(int customerId)
   {
      this.customerId = customerId;
   }

   public String toString()
   {
      System.out.println("Customer.toString() being called.");
      StringBuffer buffer = new StringBuffer();
      buffer.append("\nCustomer:\n");
      buffer.append("customer id: " + customerId + "\n");
      buffer.append("first name: " + firstName + "\n");
      buffer.append("last name: " + lastName + "\n");
      buffer.append("street: " + addr.getStreet() + "\n");
      buffer.append("city: " + addr.getCity() + "\n");
      buffer.append("state: " + addr.getState() + "\n");
      buffer.append("zip: " + addr.getZip() + "\n");

      return buffer.toString();
   }


}

Notice the toString() method and how it prints out to the standard out when being called. This will be important when the sample is run later.

Now if look at the Server class, will see is a standard setup like have seen in previous samples.

public class Server
{
   private String locatorURI = "socket://localhost:5400";
   private TransporterServer server = null;

   public void start() throws Exception
   {
      server = TransporterServer.createTransporterServer(locatorURI, new CustomerProcessorImpl(), CustomerProcessor.class.getName());
   }

   public void stop()
   {
      if (server != null)
      {
         server.stop();
      }
   }

   public static void main(String[] args)
   {
      Server server = new Server();
      try
      {
         server.start();

         Thread.currentThread().sleep(60000);

      }
      catch (Exception e)
      {
         e.printStackTrace();
      }
      finally
      {
         server.stop();
      }
   }
}

It is creating a TransporterServer for the CustomerProcessImpl upon being started and will wait 60 seconds for invocations.

Next is the Client class.

public class Client
{
   private String locatorURI = "socket://localhost:5400";

   public void makeClientCall() throws Exception
   {
      Customer customer = createCustomer();

      CustomerProcessor customerProcessor = (CustomerProcessor) TransporterClient.createTransporterClient(locatorURI, CustomerProcessor.class);

      System.out.println("Customer to be processed: " + customer);
      ICustomer processedCustomer = customerProcessor.processCustomer(customer);
      // processedCustomer returned is actually a proxy to the Customer instnace
      // that lives on the server.  So when print it out below, will actually
      // be calling back to the server to get the string (vi toString() call).
      // Notice the output of 'Customer.toString() being called.' on the server side.
      System.out.println("Customer is now: " + processedCustomer);

      TransporterClient.destroyTransporterClient(customerProcessor);


   }

   private Customer createCustomer()
   {
      Customer cust = new Customer();
      cust.setFirstName("Bob");
      cust.setLastName("Smith");
      Address addr = new Address();
      addr.setStreet("101 Oak Street");
      addr.setCity("Atlanta");
      addr.setState("GA");
      addr.setZip(30249);
      cust.setAddr(addr);

      return cust;
   }

   public static void main(String[] args)
   {
      Client client = new Client();
      try
      {
         client.makeClientCall();
      }
      catch (Exception e)
      {
         e.printStackTrace();
      }
   }


}

The client class looks similar to the other example seen in that it creates a TransporterClient for the CustomerProcessor and calls on it to process the customer. Will then call on the ICustomer instance returned from the processCustomer() method call and call toString() on it (in the system out call).

To run this example, run the Server class and then the Client class. This can be done via ant targets 'run-transporter-proxy-server' and then 'run-transporter-proxy-client'. For example:

ant run-transporter-proxy-server

ant then:

ant run-transporter-proxy-client

The output for the client should look similar to:

Customer.toString() being called.
Customer to be processed: 
Customer:
customer id: -1
first name: Bob
last name: Smith
street: 101 Oak Street
city: Atlanta
state: GA
zip: 30249

Customer is now: 
Customer:
customer id: 418
first name: Bob
last name: Smith
street: 101 Oak Street
city: Atlanta
state: GA
zip: 30249

The first line is the print out from calling the Customer's toString() method that was created to be passed to the CustomerProcessor's processCustomer() method. Then the contents of the Customer object before being processed. Then have the print out of the customer after has been processed. Notice that when the ICustomer object instance is printed out the second time, do not see the 'Customer.toString() being called'. This is because that code is no longer being executed in the client vm, but instead is a remote call to the customer instance living on the server (remember, the processCustomer() method returned a TransporterClient proxy to the customer living on the server side).

Now, if look at output from the server will look similar to:

processed customer with new id of 418
Customer.toString() being called.

Notice that the 'Customer.toString() being called.' printed out at the end. This is the result of the client's call to print out the contents of the customer object returned from the processCustomer() method, which actually lives within the server vm.

This example has shown how can pass around TransporterClient proxies to target pojos. However, when doing this, is important to understand where the code is actually being executed as there are consequences to being remote verse local, which need to be understood.

The complex transporter example (found in org.jboss.remoting.samples.transporter.complex package) is based off a test case a user, Milt Grinberg, provided (thanks Milt). The example is similar to the previous examples, except in this case involves matching Doctors and Patients using the ProviderInterface and provides a more complex sample in which to demonstrate how to use transporters.

This example requires JDK 1.5 to run, since is using JBoss Serialization (and non-serialized data objects). To run this example, run the Server class and then the Client class. This can be done via ant targets 'run-transporter-complex-server' and then 'run-transporter-complex-client' as well. For example:

ant run-transporter-complex-server

and then:

ant run-transporter-complex-client

The output for the client should look similar to:

*** Have a new patient that needs a doctor.  The patient is:

Patient:
   Name: Bill Gates
   Ailment - Type: financial, Description: Money coming out the wazoo.

*** Looking for doctor that can help our patient...

*** Found doctor for our patient.  Doctor found is:
Doctor:
   Name: Andy Jones
   Specialty: financial
   Patients:

Patient:
   Name: Larry Ellison
   Ailment - Type: null, Description: null
   Doctor - Name: Andy Jones

Patient:
   Name: Steve Jobs
   Ailment - Type: null, Description: null
   Doctor - Name: Andy Jones

Patient:
   Name: Bill Gates
   Ailment - Type: financial, Description: Money coming out the wazoo.

*** Set doctor as patient's doctor.  Patient info is now:

Patient:
   Name: Bill Gates
   Ailment - Type: financial, Description: Money coming out the wazoo.
   Doctor - Name: Andy Jones

*** Have a new patient that we need to find a doctor for (remember, the previous one retired and there are no others)
*** Could not find doctor for patient.  This is an expected exception when there are not doctors available.
org.jboss.remoting.samples.transporter.complex.NoDoctorAvailableException: No doctor available for ailment 'financial'
 at org.jboss.remoting.RemoteClientInvoker.invoke(RemoteClientInvoker.java:183)
 at org.jboss.remoting.Client.invoke(Client.java:325)
 at org.jboss.remoting.Client.invoke(Client.java:288)
 at org.jboss.remoting.Client.invoke(Client.java:273)
 at org.jboss.remoting.transporter.TransporterClient.invoke(TransporterClient.java:237)
 at $Proxy0.findDoctor(Unknown Source)
 at org.jboss.remoting.samples.transporter.complex.client.Client.makeClientCall(Client.java:72)
 at org.jboss.remoting.samples.transporter.complex.client.Client.main(Client.java:90)
 at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
 at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
 at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
 at java.lang.reflect.Method.invoke(Method.java:585)
 at com.intellij.rt.execution.application.AppMain.main(AppMain.java:86)

From the output see the creation of a new patient, Bill Gates, and the attempt to find a doctor that specializes in his ailment. For Mr. Gates, we were able to find a doctor, Andy Jones, and can see that he has been added to the list of Dr. Jones' patients. Then we have Dr. Jones retire. Then we create a new patient and try to find an available doctor for the same ailment. Since Dr. Jones has retired, and there are no other doctors that specialize in that particular ailment, an exception is thrown. This is as expected.