javac -classpath cajo.jar Test.java

javac -classpath cajo.jar;. Test.java

java -classpath cajo.jar;. Test

Behold the graphical proxy widget, running inside the browser! :-)

Interested to make a Swing version, i.e. JProxyTest? It is a slightly different construction, but fortunately just as easy.

javac -classpath cajo.jar;. ProxyTest.java

java -classpath cajo.jar;. ProxyTest

java -cp cajo.jar gnu.cajo.invoke.Client //hostName:####/

(Note: do not forget the final / as it is required.)

(Note: The two port numbers #### and NNNN are not the same. Typically #### = NNNN + 1)

Behold the graphical widget, running inside the browser! :-)

java -cp cajo.jar;. ProxyTest

I heard that!

There is the graphical widget, running inside the browser! :-)

OK, maybe the example went a little too far, in trying to demonstrate everything at once. Proxies are a very valuable mechanism of the cajo framework; so here is a complete example focusing exclusively on them.

All that is required for this example, is the standard codebase cajo.jar, and the file which will be explained completely below;

ProxyTest.java:

import java.awt.*;
import java.awt.event.*;
import gnu.cajo.invoke.Remote;
import gnu.cajo.utils.ItemServer;
import gnu.cajo.utils.CodebaseServer;

public class ProxyTest {

	public static class TestProxy extends Panel implements ActionListener {
		private Object selfRef, item;
		TestProxy() {
			super(new BorderLayout());
			Label label = new Label("Test Proxy", Label.CENTER);
			add(label, BorderLayout.CENTER);
			Button button = new Button("fun button!");
			button.addActionListener(this);
			add(button, BorderLayout.SOUTH);
		}
		public void setItem(Object item) { this.item = item; }
		public Component init(Object ref) {
			selfRef = ref;
			return this;
		}
		public void actionPerformed(ActionEvent e) {
			try { Remote.invoke(item, "pressed", null); }
			catch(Exception x) { x.printStackTrace(); } // callback failure
		}
		public Dimension getPreferredSize() { return new Dimension(300, 300); }
	}

	private TestProxy proxy = new TestProxy();
	public Component getProxy() { return proxy; }
	public void pressed() { System.out.println("I heard that!"); }
	public static void main(String args[]) {
		try {
			new CodebaseServer(null, 0);
			ProxyTest pt = new ProxyTest();
			ItemServer.bind(pt, "main", pt.proxy);
			System.out.print("Server running on interface ");
			System.out.println(Remote.getServerHost());
			System.out.print("Using TCP port ");
			System.out.println(Remote.getServerPort());
			System.out.print("Codebase server running: ");
			System.out.println(System.getProperty("java.rmi.server.codebase"));
		} catch (Exception x) { x.printStackTrace(); }
	}
}

The ProxyTest represents an item, meaning a remotely callable object furnished by a Virtual Machine. It has a proxy, called TestProxy, which it provides to remote Virtual Machines. TestProxy is a static member class simply to allow this example to consist of a single source file. Many times, proxies exist in separate files. Combining them this way does make their interaction a little clearer, as we will see.

TestProxy is a graphical user interface, provided to remote Virtual Machines, it also interacts with sending object ProxyTest. TestProxy is designed to work seamlessly with the generic cajo graphical Client class, which we will also be using in this example. It has two special methods; setItem, and init. When the ProxyTest binds itself, it uses the three argument method. This tells the ItemServer that this third argument is a proxy to the first. It will automatically invoke the proxy's setItem method, sinc it has one, and provide it with a remote reference to its serving object, on which it may communicate with it when it reaches a remote Virtual Machine host. The second method init, is called by the generic cajo graphical Client class, to signal that it has arrived at its remote Virtual Machine destination, and should perform any local preparation it needs to do, before becoming visible. It also provides a remoted reference to itself, which it may provide to its remote server object, if necessary, making use of the remote reference provided in the init invocation.

The ProxyTest is the server object. It too has two special methods. The first method getProxy is called by the generic cajo graphical Client, to request the proxy widget. The second method, pressed, is called by the remote proxy object, to callback the server object asynchronously, whenever the proxy button is pushed. It also starts up a default CodebaseServer, to provide the necessary resources a remote Virtual Machine would need, in order to instantiate the proxy. In this case it consists solely of the inner class ProxyTest$TestProxy.

Compiling the example:

The file above is compiled using the following command from the console:

javac -classpath cajo.jar ProxyTest.java

java -classpath cajo.jar;. ProxyTest

Server running on interface hostName
Using TCP port ####
Codebase server running: http://hostName:NNNN/

Using the proxy:

Now we go to another machine, though we really could use the same machine too. Again we open up a console window, and launch the generic cajo graphical Client, to request the proxy:

java -cp cajo.jar gnu.cajo.invoke.Client //hostName:####/

Now for the interactive part:

When the client VM user presses the push button in the proxy GUI, the remote server proudly exclaims:

I heard that!

There are two very important things to keep in mind however:

• The client does not have a reference to the proxy, rather it has an exact bitwise copy. Unlike conventional Java, this was an object pass-by-value! Any changes that occur to the remote proxy, none in this particular case; will not be reflected in the original master proxy, held by ProxyTest.

• If many clients request a proxy, they will all receive perfect bitwise copies. This means that the ProxyTest pressed method, can be invoked reentrantly by all of its proxies. Each remote call represents a separate thread of execution, if there are any concurrency issues, none in this particular case, they will have to be properly synchronised.

Extra Fun:

Remember that last line shown when the ProxyTest started:

Codebase server running: http://hostName:NNNN/

Just for fun, you can go to another remote machine, or even the same machine, open a browser session and type in that URL.

Look again, there is the graphical widget running inside the browser!