-- JohnCatherino - 23 Jun 2006

This extension of the previous example will demonstrate how to use the TransparentItemProxy from the cajo project to obtain remote objects by value.

Unlike conventional Java, which only allows object passing by reference, now we can also pass objects by value.

Let's go back to our shared interface:

Duck.java

public interface Duck {
   boolean looks();
   boolean walks();
   boolean talks();
   Duck getDuck();
}

Note the new method getDuck() this is how we will get a local instance, or bitwise copy, of a Duck object.

Next let's modify the simple server POJO, to implement this interface:

DuckServer.java

import java.io.Serializable;
import gnu.cajo.invoke.Remote;
import gnu.cajo.utils.ItemServer;
import gnu.cajo.utils.CodebaseServer;

public class DuckServer implements Duck, Serializable {
   public boolean looks()  {
      System.out.println("hi there!");
      return true;
   }
   public boolean walks()  {
      System.out.println("waddle waddle");
      return true;
   }
   public boolean talks() {
      System.out.println("quack quack!");
      return true;
   }
   public Duck getDuck() { return new DuckServer(); }
   public static void main(String args[]) throws Exception { // simple unit test
      Remote.config(null, 1198, null, 0); // use cajo port 1198
      new CodebaseServer(null, 0);
      ItemServer.bind(new DuckServer(), "Donald");
      System.out.println("duck server running");
   }
}

Note the addition of a CodebaseServer object, this allows class files to be passed from the server, to the client. The getDuck() method returns a new instance, if this object had some state that would be important to the client, it would be implemented as: return this;. Either way works, but each implies slightly, but very importantly, different semantics. Also note that the object must now implement java.io.Serializable, this allows its bitwise instance to be sent over the network.

Now let's create a test server directory; and in it place the common interface Duck, the server object DuckServer, and of course, the tiny 40 kB cajo.jar library.

Like last time the server files can be compiled as follows:

javac -classpath cajo.jar;. DuckServer.java

Now let's start up the server, it will require a command line input like the following:

java -classpath cajo.jar;. DuckServer

OK. Now let's update the simple client unit test; to use the duck server object by value:

DuckClient.java

import gnu.cajo.invoke.NoSecurityManager;
import gnu.cajo.utils.extra.TransparentItemProxy;

public class DuckClient { // try out DuckServer
   public static void main(String args[]) throws Exception {
      System.setSecurityManager(new NoSecurityManager());
      Duck duck = (Duck)TransparentItemProxy.getItem(
         "//serverHost:1198/Donald",
         new Class[] { Duck.class }
      );
      duck = duck.getDuck(); // by value
      System.out.println("looks like = " + duck.looks());
      System.out.println("walks like = " + duck.walks());
      System.out.println("talks like = " + duck.talks());
   }
}

Note: The serverHost portion of the string in the getItem call, must be replaced, with the acutal host name, or IP address of the server.

Note the addition of the NoSecurityManager, this allows the client to run without a security policy file, and provides the loaded objects with full permissions on the host machine. If you do not want this; use a security policy.

Now let's create a test client directory; on either the same, or a different physical machine, and in it place the common interface Duck, the client object DuckClient, and likewise, the cajo library.

Similarly, compile the client files:

javac -classpath cajo.jar;. DuckClient.java

Now let's start up the client, it will require a command line input like the following:

java -classpath cajo.jar;. DuckClient

This will result in the following client console output:

hi there!
looks like = true
waddle waddle
walks like = true
quack quack!
talks like = true

Note that this time all of the output is at the client, and none is at the server; the duck is executing entirely inside the client!

Also note, if the client did not call getDuck(); this version would execute by reference, exactly like the previous example. The decision to execute on a remote object by reference, or by value, can actually be made dynamically.

A final thought, a gift for those who made it this far: A method can of course return a remote reference to an object as a result. This reference can also be used with local syntax, via an alternate getItem method of the TransparentItemProxy class.

Enjoy!