Lightweight Remote Object Access – RESTful Java

Posted by

Really thin
Source code (simple text transfer)
Source code (object data transfer)
Client code
Servlet code
Advantages and disadvantages
ORBs and firewalls
URLConnection and firewall tunnelling/proxy server usage


The Java platform (VM, language, etc.) supports loading classes from any stream. This source for this stream can be a URL, a database connection, or a file. The ability to load a class at runtime from just about any source, over the network, creates many strange and interesting deployment scenarios for a Java based application. Applets are severely limited in what they can due, due to security restrictions placed on them by the VM, and are not conducive to deployment. Applications on the other hand, are a totally different ball game.

Unfortunately, client side deployment and application partitioning depend greatly on the requirements of the project. This makes it more of an art to do such things, rather than a precise science, because there are no right answers, only better or worse ones.

With web services, SOAP and XML RPC and session-less RESTful protocols becoming popular over the last few years, this tutorial will take you through the steps of crafting a very lightweight RPC mechanism that uses Java’s object serialization and HTTP (URLConnection and Servlets). It’s like using a RESTful API, except that the parameters passed are Java objects, and only HTTP POST is used for communication between the client and servlet.


Client side Java applications can justify their existence in situations where platform independence and heavy network dependence are top on the requirements list for the applications. In these situations, Java can be used in interesting ways to partition what is the “client” side from the “server” side.

For example, traditional “heavy” clients have a lot of resource requirements, and require a lot of classes to exist on the local VM in which they run. These classes could be heavy Oracle JDBC drivers, Weblogic JMS client classes, etc. In deploying a heavy client, there are advantages and disadvantages. The major advantage is:

  • development is usually easier, simply because all the required classes on the client side can just be bundled with the app. There is no need to come up with nifty proxy services to offload some of the processing to the “server”.

The disadvantages are:

  • the client side classes have to be updated for any changes made on the server that require bundled classes to change. For example, if Weblogic comes up with a different implementation of JMS, then the “new” classes have to be used by the client app. Client apps have to be dynamically upgradeable.
  • If there are bandwidth restrictions (modem connection to the internet), then it becomes cumbersome to make major updates to a client apps codebase. This depends on the size of the codebase that needs to be updated, of course.
  • Heavy clients are usually more resource intensive. Since they “do more things” on the client VM, they also take more resources to get these “things” done. This could be allocation of more threads, or acquiring more socket connections (for example, doing remote object lookups, and using stubs).

Now, if there is a restriction on the bandwidth and resources that a client app can acquire, then it might be a better idea to go with a thin client.


There is another very important reason for creating a thin client, even when none of the requirements listed above apply – firewalls. If the client app has to work even when it is behind a corporate firewall, then there is a compelling reason to create the client app as a thin client, and have it tunnel through HTTP. Why HTTP? Simply because most corporations have proxy servers that allow employees to connect to sites on the web. So, by piggy backing data over HTTP (that connects to a server that is not a web server), it is possible to “tunnel” through the firewall. Now, the firewall tunneling requirement necessitates the use of HTTP, otherwise we could choose any protocol that gets the job done.


A thin client changes the partitioning of the application space so that more objects and tasks are performed in the server realm. This has the following disadvantages:

  • it takes more time to architect this solution, simply because more layers of abstraction need to be added, which invariably leads to more coding.
  • it is more resource intensive on the server side. By using thin clients, more objects get pushed into the server, with more layers, which takes up more resources on the server side.

It does have its advantages:

  • speed. Thin clients are usually always faster. Why? Because the servers (with powerful machines and fast network connections) can usually do things faster than the client host (with slower machines and less bandwidth). However, more server resources are taken up as a result.
  • scalability. It is easier to add hosts to a server farm, due to better manageability on the server side. In order to improve performance (if the application is done correctly), you simply have to add more hosts to offload processing, and get faster LAN connections. It is easier to do this, than to deal with many copies of the client app, on a variety of different client hosts, perhaps running a wide variety of OSes.


The proxy pattern is the most important thing to use in creating a thin client. By adding a level of indirection, or abstraction, between the client objects, and the actual server objects, you too can create thin(ner) clients. The “way” of doing things is quite consistent, move heavy objects from the client app, to the server side, while allowing access to the interfaces exposed by the server side objects. Now, access to the server side objects can be streamlined by using a lightweight protocol (like HTTP or raw sockets), instead of using ORBs. However, there is a delicate balance to doing this. You have to create layers that do low level protocol translation (to “object-speak”) in the client code. This is replication functionality that you can get from ORBs. However, ORBs were meant for a slightly different application than thin clients.

Again, you would only want to undertake these tasks if performance, and client app size and resource usage were key requirements in the design of your app. If they are not, then it is easier to go with heavy clients.

ORBs support location transparency for object references, which allows you to use remote references to access server side objects. However, the ORB uses its own protocol and sockets at the lowest level to “pull this off”. Now, the implementation strategies used by commercially available ORBs might not be condusive to deploying thin clients, because the ORBs might have been designed to do other things in different environments (like exist on the server side, with plenty of memory and processor power, and plentiful bandwidth).

There are 3rd party implementations of these lightweight protocol layers that allow you to create proxies for objects, but the project requirements might not warrant their use.

Figure 1 illustrates this pattern.

The Servlet API, for example, chooses to have Servlets implement the Runnable interface rather than extending the Thread class. The end result of this is that there is one instance of the each Servlet class, and the Servlet container creates a new thread for each HTTP request that comes in (for that Servlet) and attaches it to the same Servlet object. This is the Singleton pattern, where only the same (single) instance of a class is used anywhere that an object of that class is required. Now, you can override this default behaviour of Servlets, by having your Servlet extend SingleThreadedModel. This starts to emulate the behavior that you would get by extending Thread. When you extend SingleThreadedModel, a new Servlet object is created for every thread that is created to service each HTTP request. This behavior is illustrated in Figure 2. Please refer to the source code example below on the details of implementing Runnable.

The behavior of RMI objects is very similar to this. When a client looks up a remote reference, they get a stub to the skeleton of the remote object. Now, there is only one remote object, per remote reference. However, a multitude of clients can connect to this singular remote object and invoke methods on it. Sounds like the SIngleton pattern at work again. The skeleton creates a new Thread that runs through the singular remote object (in addition to managing all the protocol translation between it and the stub). This is very similar to the Servlet mechanism. This kind of design strategy exists in most server frameworks, from Servlets, to RMI, to CORBA ORBs.

However, in EJB, the model is a little different. When your client code gets a reference to the home interface implementation, you usually call the craete() method, which gives you a remote reference to a bean. Now, you get a new bean for each remote interface, rather than sharing one bean. This is not the Singleton pattern. However, the Home interface does use the typical ORB model, where you get a stub to a skeleton that points to the object that implements the Home interface. This Home object (or factory) is responsible for returning remote references that point to unique beans (or server side objects).

For a more complete tutorial on threads, please read these tutorials: threads and advanced threads.

Really thin

You can use traditional distributed computing layers (like RMI, or CORBA, or Weblogic’s RMI/T3) to create thin layers. However, the client code will need access to the ORB classes (which are required for the stub and skeleton communication). This is sufficient for most projects.

However, instead of using normal stubs on the client application, it is possible to add another layer between the stub and the actual client. Also a lightweight protocol (like HTTP) can be used to talk between the thin client and the stub (which now exists on the server side as well). Now, the stub can exist on any host in the server environment, everything doesnt have to be one one machine. Figure 2 illustrates this.

In Figure 2, you can see that the remote object (that implements your remote interface) could exist in the Servlet container itself, or it can be a remote reference itself, that uses RMI (or someother ORB technology) to connect to some object on another host. So the Servlet gateway serves as a thin proxy that allows access to the heavier remote objects that actually live on the server side.

This partitioning is simply taking the ORB concept to another level, but providing a light protocol to access the actual remote reference from the actual client. I will have code examples on how to do this later, but the key classes on the client side is, and the key class on the server side is javax.servlet.HttpServlet.

Source code (simple text transfer)

Listed below is some source code that shows how to use on the thin client, and a Servlet on the server side to tunnel.
Here is the code for the Servlet:

 1: import*;
 2: import javax.servlet.*;
 3: import javax.servlet.http.*;
 5: /**
 6:  My servlet gateway
 7: */
 8: public class MyServlet extends HttpServlet{
 9:     //INIT METHOD
 10:     public void init( ServletConfig config ) throws ServletException
 11:     {
 12:         super.init(config);
 13:     }
 15:     //doPost Method
 16:     public void doPost(
 17:         HttpServletRequest req , HttpServletResponse res )
 18:         throws IOException , ServletException
 19:     {
 20:         //handle client request
 21:         ServletInputStream sis = req.getInputStream();
 22:         DataInputStream dis = new DataInputStream( sis );
 24:         String line = dis.readLine();
 26:         //send a response to the client
 27:         res.setStatus( HttpServletResponse.SC_OK);
 28:         ServletOutputStream sos = res.getOutputStream();
 29:         PrintStream ps = new PrintStream( sos );
 30:         ps.println("SERVLET:"+line);
 32:     }
 35: }//end class

Here is the code for the client (written as an Applet):

 1: import java.awt.*;
 2: import java.applet.*;
 3: import*;
 4: import*;
 6: /**
 7:  Applet to talk to a servlet via HTTP by using URLConnection
 8: */
 10: public class MyApplet extends Applet implements Runnable{
 12:     //data
 13:     TextArea ta = new TextArea();
 14:     Thread t = new Thread(this);
 17:     //methods
 18:     public void init(){
 19:         setLayout( new CardLayout() );
 20:         add( "card" , ta );
 21:         display("ready.");
 22:         t.start();
 23:         ta.setFont(new Font("Helvetica",Font.PLAIN,12));
 24:     }
 26:     public void display(String text){
 27:         ta.appendText( text + "n" );
 28:         }
 30:     public void run(){
 31:     try{
 32:         String hostname = getCodeBase().getHost();
 33:         String servletAddress = "http://"+hostname+"/servlets/MyServlet";
 35:         display("hostname:"+hostname);
 36:         URL servletURL = new URL(servletAddress);
 38:         //create a URLConnection to the URL
 39:         display("opening connection to Servlet URL:"+servletAddress);
 40:         URLConnection uc = servletURL.openConnection();
 42:         //change URLConnection settings
 43:         display("setting URLConnection properties");
 44:         uc.setDoInput(true);
 45:         uc.setDoOutput(true);
 46:         uc.setUseCaches(false);
 47:         uc.setRequestProperty("Content-Type","application/x-www-form-urlencoded");
 50:  //get InputStream from the servlet
 51:  display("getting InputStream to servlet");
 52:  DataInputStream dis = new DataInputStream(
 53:  uc.getInputStream());
 55:  String line;
 56:  while( (line=dis.readLine())!=null ){
 57:  display( "FROM SERVLET:"+line );
 58:  }
 59:  dis.close();
 60:  display("closing InputStream");
 61: */
 63:         /////////////////////////////
 64:         //PERFORM A POST OPERATION //
 65:         /////////////////////////////
 66:         //get OutputStream to servlet
 67:         display("getting OutputStream to servlet");
 68:         PrintStream ps = new PrintStream(
 69:             uc.getOutputStream());
 70:         String msg = "HI SUN!!!";
 71:         display("sending this message to the servlet:"+msg);
 72:         ps.println(msg);
 73:         ps.close();
 74:         display("closing OutputStream");
 76:         //get Response from the servlet
 77:         DataInputStream dis2 = new DataInputStream( uc.getInputStream() );
 78:         String line2 = dis2.readLine();
 79:         display("got this response from servlet:"+line2);
 80:         dis2.close();
 82:     }catch(Exception e){
 83:         display(e+"n");
 84:         e.printStackTrace();
 85:         }
 86:     }
 87: }

Source code (object data transfer)

The only difference between transferring text (Strings) and objects (or byte arrays) are:

  • object streams have to be used to write and read to/from the URLConnection and Servlet
  • byte arrays get transmitted from the client to the servlet, rather than plain text, and so the mime type for the URLConnection (on the client) has to be different.

Client code

Here is some code that does the object data transfer on the client side, using URLConnection:

 1: public void communicateWithServlet(){
 2:     try{
 3:         String hostname = getCodeBase().getHost();
 4:         String servletAddress = "http://"+hostname+"/servlets/MyServlet";
 6:         display("hostname:"+hostname);
 7:         URL servletURL = new URL(servletAddress);
 9:         //perhaps use proxy server to get out of firewall
 10:         System.getProperties().put("proxySet", "true");
 11:         System.getProperties().put("proxyHost", proxyServer);
 12:         System.getProperties().put("proxyPort", proxyPort);
 13:         //explanation of this proxy stuff given below.
 15:         //create a URLConnection to the URL
 16:         display("opening connection to Servlet URL:"+servletAddress);
 17:         URLConnection con = servletURL.openConnection();
 19:         //change URLConnection settings
 20:         display("setting URLConnection properties");
 21:         con.setDoInput(true);
 22:         con.setDoOutput(true);
 23:         con.setUseCaches(false);
 24:         con.setRequestProperty("Content-Type","application/x-www-form-urlencoded");
 26:       /////////////////////////////
 27:         //PERFORM A POST OPERATION //
 28:         /////////////////////////////
 29:         //send data (contained in someObject) in the request
 30:         byte[] buf = getBytesFromObject( someObject );
 33:         //get the size of the compressed MBParamter object in
 34:         //its byte[] representation
 35:         int bufSize = buf.length;
 38:         //set the headers to notify servlet of what is coming
 39:         con.setRequestProperty( "Content-type" ,
 40:                                 "application/octet-stream" );
 41:         con.setRequestProperty( "Content-length",
 42:                                 Integer.toString( bufSize ) );
 45:         //make the actual request, send the parameter to the servlet
 46:         DataOutputStream dos = new DataOutputStream(
 47:             con.getOutputStream() );
 48:         dos.write( buf );
 49:         dos.flush();
 50:         dos.close();
 52:         //get response from the servlet
 53:         ObjectInputStream ins = new ObjectInputStream(
 54:             con.getInputStream());
 55:         Object returnValue = ins.readObject();
 56:       process( returnValue );
 57:         ins.close();
 59:     }catch(Exception e){
 60:         display(e+"n");
 61:         e.printStackTrace();
 62:         }
 63:     }
 64: }

A sample getBytesFromObject(Object) implementation is shown below:

 1: byte[] getBytesFromObject( Object param ){
 3:     ByteArrayOutputStream baos = new ByteArrayOutputStream();
 4:     ObjectOutputStream oos = new ObjectOutputStream( baos );
 6:     oos.writeObject( param) );
 7:     oos.flush();
 9:     oos.close();
 10:     baos.close();
 12:     return baos.toByteArray();
 14: }


The process( Object o ) method should be used to do something the object that was received from the Servlet.

Servlet code

In order to do non-textual data transfer to a Servlet, you have to use the service() method in your Servlet, not the doPost() method, like it was done above. Here is a new Servlet that deals in data objects, rather than just plain text:

 1: import*;
 2: import javax.servlet.*;
 3: import javax.servlet.http.*;
 5: /**
 6:  My servlet gateway
 7: */
 8: public class MyServlet extends HttpServlet{
 10: public void init( ServletConfig config ) throws ServletException
 11: {
 12:     super.init(config);
 13: }
 15: //service method
 16: public void service( HttpServletRequest req ,
 17:                      HttpServletResponse res )
 18: throws ServletException, IOException{
 19:     try{
 20:         ObjectInputStream ois = new ObjectInputStream(
 21:             req.getInputStream() );
 23:         //read object from the client
 24:         Object param = ois.readObject();
 26:         //process this param and return another object
 27:         Object retVal = process( param );
 29:         //turn the return value to a byte[]
 30:         byte[] buf = getBytesFromObject( retVal );
 31:         res.setContentType( "application/octet-stream" );
 32:         res.setContentLength( buf.length );
 34:         //send the byte array to the client
 35:         ServletOutputStream sos = res.getOutputStream();
 36:         sos.write( buf );
 37:         sos.flush();
 38:         sos.close();
 40:     }
 41:     catch(Exception e){
 42:         System.out.println( e );
 43:         e.printStackTrace();
 44:     }
 45: }
 48: }//end class

The process(Object) method should perform some task on the object just received from the client, and it should return a value, that has to be transmitted back to the client.

The getBytesFromObject(Object) uses the same exact implementation that was used in the client code.

Advantages and disadvantages

There are some consequences to doing this super light client:

  • you can’t have call backs from the server object to the client object. Everything is “client pull”, however, you can emulate an event based system using this underlying “pull mechanism”.
  • you can’t pass remote references as return values. You would have to explicitly pass URIs that actually have information it it that will allow the client stub to access another server side object through the gateway.
  • development time might increase simply because there is one more layer between the client and the remote object.

The advantages are:

  • no need to bundle any ORB or app server specific classes with the client code.
  • since the client doesnt have to do lookups and instantiate any stubs (except the really light one), performance is very good, and resource overhead is very low. The burden is simply shifted to the server.
  • no need to update dependency classes (that apply to implementation specifics of the app server), since everything is delegated to the server side proxy object through the gateway.

Nothing is free. In order to get super lightness, there are tradeoffs in development time, and resource overhead when deploying to the server side. Whether you will do this or not, depends entirely on the requirements of the project. There is no right answer, it all depends on what you want to do.

ORBs and firewalls

In order to get through firewalls, many vendors have created ORB implementations that have an HTTP gateway, that allow you to tunnel through HTTP in order to get to the actual server side object. This is a hybrid of traditional ORB technologies and the super light HTTP gateway approach. This middle of the road approach has advantages and disadvantages of both ORBs and the light gateway.

The advantages are:

  • you can tunnel through firewalls, while taking advantage of the simplicity of using a traditional ORB (like RMI over T3, as provided by Weblogic).

The disadvantages are:

  • you will have to bundle app server specific classes, and you will have to updated them on the client (when the app server is upgraded).
  • resource usage is similar to using a normal ORB, because there are heavy stubs on the client side.
  • the protocol is heavier than HTTP, simply because these protocols are ORB protocols, which are designed to do a lot more than act as a simple HTTP gateway for an application.

Here is some information on Weblogic:

The following is an excerpt from

HTTP port-80 access. The WebLogic Server can act as an HTTP server listening on port 80 for serving HTTP servlets. Setting up the WebLogic Server to listen on port 80 means that T3Clients can also communicate with the WebLogic Server across a firewall in standard fashion. This gives all T3Client applications — using WebLogic Events, WebLogic JDBC, and/or WebLogic Beans, etc — port 80 access to WebLogic. The WebLogic Server is designed to serve as a fully-featured webserver for an arbitrary files; in addition, it can proxy to another server.

URLConnection and firewall tunnelling/proxy server usage

The URLConnection class has the ability to use a Proxy server to get out of a firewall. Let’s say the applet or java app that is running on the client host is behind a firewall. In this case, the JVM acutally supports the use of proxy servers in the URLConnection class. By using the following lines of code:

 1: System.getProperties().put("proxySet", "true");
 2: System.getProperties().put("proxyHost", proxyServer);
 3: System.getProperties().put("proxyPort", proxyPort);
 5: URL u = new URL( "http://host/servlet/someServlet" );
 6: URLConnection con = u.openConnection();
 7: //perform operations on con

Where proxyServer is the hostname of your proxy server, and the proxyPort is the port number of your proxy server. This is what allows a client to “tunnel” through a firewall. You don’t have to worry about this if your client host is not behind a firewall.

In order to read more about firewalls and low level network connections, follow this link.


Depending on your project requirements, you will have to define what “thin” means to you. You might be able to get away with normal ORBs (like RMI/IIOP). Or you might have to get fancy and use something like Weblogic’s RMI/T3, that allows you to tunnel through firewalls. Or, you might have to go with the lightweight HTTP gateway.