the cajo project
Free, simple, powerful: Transparent Distributed Computing
Inside the cajo graphical client
The client class is a generic, general purpose graphical proxy host. It can be used to display and interact with any graphical proxy, without need for any customisation. It can operate in two fundamentally different, but functionally complementary ways; as an applet or as an application. The client uses only the classes in the gnu.cajo.invoke package.

As an applet, on loading by a Java enabled browser, it will connect back to its host and request either the default proxy, or one specified in the browser URL. Next it will initialise the proxy, by calling its init method, providing a reference to the proxy remoted within the context of the plug-in's VM. Finally, the return of this proxy invocation, canonically a descendant of java.awt.Container, is added to the applet's panel. This allows a single client to host an unlimited variety of graphical application proxies, using only one applet class. Best yet, all of the code is provided by the server. The client can also be run as a WebStart applciation!
Applet configuration
The server fully configures the applet using the parameters specified in its tag. The client can provide three of the optional configuration parameters however via its URL when requesting the applet:

proxyName The name of the proxy to request from the server
clientPort The port on which to communicate with the proxy
localPort The client's internal port number, if translated

Normally the default settings will work fine, unless either the client wants a specific port because it is behind a firewall, or wants a specific proxy. The client can tell the server how to set these parameters, via the URL it uses to request the applet. The URL uses the following syntax:
   http://host[:port]/[clientPort][:localPort][-proxyName][!]
The parameters in brackets can be selectively omitted, but the order of arguments is required. Unspecified, the port value will be 80, the clientPort 0 = anonymous (chosen form those free at startup), localPort will be same as clientPort, and proxyName will be "main". To WebStart the client application; simply append an exclamation point (!) to the end of the URL. We like to call it: Starting the application with a bang!
Application configuration
The class can also operate as a local application. This is very useful for testing and development purposes. It is also the fastest and most efficient means to host a remote graphical proxy. It connects to a remote item, requests its proxy, initialises it in the identical manner as the applet does, and if the initialisation returns an awt Component (or a swing JComponent), it will create a Frame (or a JFrame) on the client machine, displaying the result.

The application can take up to five optional parameters. They are in order, from most often changed, to least often, because to change an option, all of the previous options must also be specified; i.e. both order and precedence count.

Here are the options:
  • The URL where to load the intial proxy item
  • The client's external port number, if it's behind a firewall
  • The client's external host name, if it's using NAT
  • The client's internal port number, if it's using translation
  • The client's internal host name, if it has multiple interfaces
The first option has six possibilities to load a proxy:
  • http:// to load it from a web server
  • ftp:// to load it from an ftp server
  • file:// to load it from the local disc
  • path/name to instantiate it from a local class file
  • /path/name to load it as a serialised proxy from disc
  • //host[:port]/[name] to load it from an rmiregistry
The most common client startup invocation looks something like this:
   java -jar client.jar //someHost/
or to use the codebase jar directly:
   java -cp cajo.jar gnu.cajo.invoke.Client //someHost/
This will connect to someHost, and get the item "main", using any available port, not currently in use.
Important details
This client, when run as local a application, is excellent for testing and development purposes in a trusted enviornment. To make its use for development purposes simpler, the client application employs no security manager, this allows any loaded proxy to do anything it wants, on the host's physical machine. Under some circumstances granting proxy items full permissions may be exactly what is needed; on kiosks, or thin client machines, on a protected newtork for example. It has a convenience in that it allows the client to run simply as a single jar file, no security policy file is even needed.

However, to protect the host in untrusted environments, it is critical to start this application with a proper security manager installed. This would require an invocation such as the following:
   java -jar -Djava.security.manager -Djava.security.policy=someURL client.jar ...
The first -D argument places the entire VM, and therefore all its loaded proxies, in an Applet sandbox. The second -D argument is optional. It could be to a policy file, referenced by a URL (or simply [path/]filename). If needed, it would define what additional permissions the downloaded proxies would get.

For example; the following policy file is not as restrictive as the sandbox, it is suitable for many proxies:
grant {
   permission java.net.SocketPermission "*:1024-", "accept;
   permission java.net.SocketPermission "*", connect;
};
This allows loaded proxies to create server sockets on any unused port over 1023, and connect to any server on any port. Additional information on this topic can be found in the answer to question #9 in the FAQ section.

Note: be very sure to use the first -D argument, you don't want to make the same same mistake I did. (Essentially, omission of the first argument, completely negates the effect of the second.)

When launched as an application via WebStart, the client runs in an Applet sandbox, meaning it has no access to the hosting machine's hard disc, and can communicate only back to the host from which it was sent.
Conclusion
The client application runs quite nicely on small Java capable PDAs. With integrated wireless networking, these make excellent user interface devices. As their processing and display capability continue to improve, their value as user interface hosts to a distributed computing collective become even more attractive. Perhaps one day soon these may become the primary tools to interface to computer networks. The best part is, that now you can very accurately model, and develop for, these future devices, using standard desktop and laptop computers.

Client, a useful utility in its own right, especially handy during application development.
© 2004 John Catherino, GNU FDL