Introducing JBoss Remoting

Recently, JBoss introduced a new open source remoting framework called JBoss Remoting. It serves as the core framework for the next generation (v5.0) JBoss Application Server (AS) to provide remote services--things like remoting JMX MBeans, remoting EJBs, and so on. JBoss Remoting can also be used as a standalone framework to build network-aware services independent of the JBoss AS.

Considering the plethora of remoting frameworks that already exist (RMI, EJB, web services, et al.), the first question you might ask is, "Why introduce another remoting framework?" The competitive advantage of JBoss Remoting is that it is very lightweight, agnostic to network transport, and easy to extend. It supports a versatile invocation model that is far beyond today's RMI or web services. There is no need to generate and compile a client-side agent for each service. As a result, JBoss Remoting provides the basis for more complex and heavyweight remoting frameworks. For instance, the next generation JBoss web services stack, JBossWS, is based on JBoss Remoting with a custom SOAP data marshaller. Another example is the JBoss AOP Remoting project, which provides clustering features such as request load balancing and failover for remote calls using annotations. JBoss AOP Remoting also supports asynchronous invocation and propagation of both the transaction and security context over the network.

From the user's point of view, JBoss Remoting enables you to very easily design, implement, and deploy services that can be remotely invoked by clients using several different transport mechanisms transparently. It also provides you an efficient way to access existing services in JBoss AS. In this article, we will show you how to get started with JBoss Remoting.

Server-Side API

One of the first things to consider when building your JBoss Remoting service is what your endpoint reference is. In other words, how do clients identify your service in order to connect to it? JBoss Remoting defines the org.jboss.remoting.InvokerLocator class for this. For all intents and purposes, it is a URL (with some restrictions). Simple yet efficient, the InvokerLocator will not only identify the endpoint name of your specific service, but also define what transport protocol to use when sending the data (as any URL does). The format of the InvokerLocator URL is technically:

transport://host:port/parameter1=value1¶meterN=valueN

This isn't a true URL (aside from providing parameter values, there is no identification data beyond the protocol, hostname, and port number), but that is an easy way to think of it. A server will create its InvokerLocator by passing in the locator URL as a String:

InvokerLocator myLocator = 
    new InvokerLocator("socket://mybox:8084");

Note that by doing this, I am indicating that my service will be hosted on the computer mybox and will be network-aware via a simple TCP/IP socket transport layer listening on port 8084.

The InvokerLocator merely indicates where and how clients can connect to the server. The server must create a Connector and start it in order to actually be live on the network. It does this by creating an org.jboss.remoting.transport.Connector, associating that Connector with our InvokerLocator URL, and then starting the Connector:

Connector connector = new Connector();
connector.setInvokerLocator(myLocator.getLocatorURI());
connector.start();

Once started, the Connector becomes live and ready to accept connections from clients. The Connector object is actually a valid JMX MBean, so it can be deployed in JBossAS using the configuration shown below. Note that while some of this XML performs the same function as the Java code above, it also provides additional functionality by defining the configuration of the invocation handler--see the next section for more details on this.

  xmbean-dd="org/jboss/remoting/transport/Connector.xml"
  name="jboss.remoting:service=Connector,transport=Socket">
  
    socket://mybox:8084
  
  
    
      
        com.abc.MyHandler
       
    
  
The question now becomes: what to do with the request when one comes in?  That's where invocation handlers come in. When a Connector
accepts an incoming request, it hands off that request to one of its
invocation handlers. You plug your service-specific code into the JBoss
/** handler to simply echo incoming
    parameter's toString value */
public class MyHandler
    implements ServerInvocationHandler {
  public Object invoke(InvocationRequest invocation) {
    return "Echo:" + invocation.getParameter();
  }
}
Remoting framework by implementing org.jboss.remoting.ServerInvocationHandler and installing that handler into your Connector. The important method that you need to implement is ServerInvocationHandler.invoke(InvocationRequest). Within the invoke method, you perform the work your service actually needs to perform.  The InvocationRequest encapsulates the data sent from the client--the invocation handler obtains the client data via InvocationRequest.getParameter():