JBoss remoting tutorial

JBossRemoting is a standalone project,which enables you to very easily design, implement, and deploy services that can be remotely invoked by clients using several different transport mechanisms transparently. As a matter of fact, JBoss Remoting provides the basis for more complex and heavyweight remoting frameworks. For instance, JBoss web services stack, JBossWS, is based on JBoss Remoting with a custom SOAP data marshaller, also JBoss ESB relies on JBoss remoting as transport and data marshaller.


Until now, when you had to connect to a remote server your only option was to use the necessary interfaces which speak the same protocol as the server: for example a Socket would require a Socket client, a Web resource needed an URLConnection and so on…

With JBoss remoting all you have to provide is the endpoint reference:

for example if you had to connect to a socket server you could use the following transport protocol

while if you are an http client all you have to do is switching to :



The class which wraps the transport protocol is the InvokerLocator:

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

The remoting framework will then take the information embedded within the InvokerLocator and construct the underlying remoting components needed and build the full stack required for either making or receiving remote invocations.

Installing JBoss remoting

Before building a working sample download the JBoss remoting API from JBoss site:

Now unzip the JBoss remoting zip file and add the following libraries to your favourite development IDE:

JBoss remoting core libs:

  • jboss-remoting.jar
  • jboss-remoting-core.jar

Apache libs:

  • log4j.jar

JBoss libs:

  • jboss-logging-log4j.jar
  • jboss-logging-spi.jar
  • jboss-serialization.jar
  • jnpserver.jar
  • jboss/jboss-common-core.jar

Third part libs (oswego libs):

  • concurrent.jar


A JBoss Remoting Server:

package test;

import org.jboss.remoting.InvokerLocator;
import org.jboss.remoting.transport.*;


public class Server {


 public Server() throws Exception {


  InvokerLocator myLocator = new InvokerLocator("socket://");
  Connector connector = new Connector();

  connector.addInvocationHandler("MYSYS",new MyInvocationHandler());


  public static void main(String[] args) throws Exception {
    new Server();



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.

Ok but how to deal with incoming requests? That’s where invocation handlers come in. You plug your service-specific code into the JBoss Remoting framework by implementing org.jboss.remoting.ServerInvocationHandler and installing that handler into your Connector :


package test;

import javax.management.MBeanServer;
import javax.management.ObjectName;

import org.jboss.remoting.InvocationRequest;
import org.jboss.remoting.ServerInvocationHandler;
import org.jboss.remoting.ServerInvoker;
import org.jboss.remoting.callback.InvokerCallbackHandler;

public class MyInvocationHandler implements ServerInvocationHandler {
  public Object invoke(InvocationRequest invocation) {
    System.out.println("New Message incoming!");
    return "Received:" + invocation.getParameter();

   public void addListener(InvokerCallbackHandler arg0) {

   public void removeListener(InvokerCallbackHandler arg0) {

   public void setInvoker(ServerInvoker arg0) {

   public void setMBeanServer(MBeanServer arg0) {


As you can see, you need to implement several methods, but we are going to use only the invoke method for our sample: that’s the method which receives notification when a new connection kicks and perform the work your service actually needs.

A JBoss Remoting Client:

package test;
import org.jboss.remoting.Client;
import org.jboss.remoting.InvokerLocator;


public class TestClient {


 TestClient() throws Throwable {
   InvokerLocator myLocator = new InvokerLocator("socket://");
   Client myClient = new Client(myLocator, "MYSYS");
   System.out.println(myClient.invoke("Message for you!"));

  public static void main(String args[]) throws Throwable{
   new TestClient();

As you can see, you only need to use a generic Client interface with your InvokerLocator URL. Now you can remotely invoke our service and obtain its results via the Client.invoke().

How it works:

Ok the code is quite easy to understand but how it happens to work ? let’s see in detail the process of a request:

When a user calls on the Client to make an invocation, it will pass this invocation request to the appropriate client Invoker, based on the transport specified by the locator url.
The client invoker will then use the Marshaller to convert the invocation request object to the proper data format to send over the network.

jboss remoting tutorial

On the server side, an Unmarshaller will receive this data from the network and convert it back into a standard invocation request object and send it on to the Server Invoker.
The server invoker will then pass this invocation request on to the user’s implementation of the Invocation handler.

jboss remoting
The response from the invocation handler will pass back through the Server invoker and on to the Marshaller, which will then convert the invocation response object to the proper data format and send back to the client. The Unmarshaller on the client will convert the invocation response from wire data format into standard invocation response object, which will be passed back up through the client invoker and Client to the original caller.