the cajo project
Free, simple, powerful: Transparent Distributed Computing
Exploring the cajo framework
This page will help to get you up and running as quickly as possible. Once you understand its basic components, the possibilities become truly limitless.

The tutorial will start by describing the directory structure project and its components. Next it will move on to building and launching the example server, and their related options. It will conclude by describing the ways of connecting to the server. This should provide a fairly complete introduction to the overall use of the framework.

Note: to best follow along, please download and unzip the project source code.
Directory Structure
The project is organised into the following directories:
/cajo         // install directory
|- /gnu       // GNU root namespace
|
|-- /cajo     // project namespace
|--- /invoke  // architecture core
|--- /utils   // framework of tools
|---- /extra  // for later study...
|
|- /example   // project example
|-- /include  // proxy resource repository
|-- /gui      // proxy graphical widgets
|
|- /docs      // documentation collection
The cajo install directory contains several important files, all of these will be covered in the course of this tutorial. For now, the most important file is either doc.bat, or build.xml. Invoking either the batch file, or the doc Ant target, will scan the project source, and create highly detailed javadoc hypertext documents in the docs subdirectory. This will be a very valuable resource in your development activities. Nearly half of the source code is documentation comments! You can view this helpful resource by opening the file docs/index.html with your favourite browser.

The gnu/cajo/invoke directory houses the three core classes of this framework's architecture. Its files are described at length in the javadoc pages. For now suffice it to say that it defines the standard interface through which all cajo objects communicate.

The gnu/cajo/utils directory applies the invoke package to create the framework. Likewise, these files are covered in detail in the javadoc pages. For now it can be summarised as providing a collection of classes used in the creation of servers.

The cajo/example directory contains the four Java classes comprising the sample server. The file Main.java is the server application itself. The file TestItem is an item, meaning a server-side resource object, which is accessible to remote applications. The file TestProxy is a proxy, meaning a mobile functional object, which is sent to remote clients, and communicates back to its item. Server objects can be made that do not use proxies, it is included to demonstrate how to make one, and what it does. Finally there is the file Builder.java. Strictly speaking the example could have been made without this class also, but it is here to demonstrate the process of configuring proxies at compile time, rather than runtime. It's a little extra work, but it can make the proxies a lot smaller, simpler, and more secure.

The cajo/example/include directory contains miscellaneous data resources used by the proxy. This includes things like properties tables for multiple language support, graphical bitmaps. Essentially it is any non-Java files required for operation of the proxy at its remote host. It is put in its own directory so that it can be included into the proxy's jar file with a simple *.* option.

The cajo/example/gui directory contains a small collection of graphical widgets used by the proxy to create its user interface on hosting clients. They are outside the scope of this project as a proxy is free to use the AWT, or Swing, or anything else. Please don't think this is the graphical toolkit you have to use, it is here only for the purposes of this example, and doesn't even merit more detailed examination. (recently there has begun formalisation on the gui framework, you can find detailed and free information here.

The cajo/docs directory, as mentioned previously, is where the auto-generated documentation goes. To save space, initially it does not exist, until you run the doc build.

Note: there is also a directory gnu/cajo/utils/extra. It contains powerful applications of the framework, for later study. Its description will be set aside at this time, as it is not used by the example.
Building the example
There are four distinct ways to build the example, represented by the four batch files: make1, make2, make3, and make4; and their corresponding targets in the build.xml ant script. Each builds the server with identical functionality, however, packaged in fundamentally different ways.

The make1 creates the server in one monolithic jar file. Everything is contained inside it, the server itself, the test item, the test proxy, and even a client applet, which allows browsers to host the proxy. This file, and the security.policy file are all that is needed to deploy the server. All servers use the same policy file by default, so a deployment directory could consist of many server jars, and a single policy file. This is an important part of the paradigm; to allow complex functionality to be modularised into multiple Virtual Machines seamlessly working together. Note: If you should need separate policy files for each server, simply place each server jar and its associated policy into separate directories.

The make2 creates the server in two files: server.jar and client.jar. The client.jar is a stand-alone generic client application, in addition, it is also a generic proxy hosting Applet. Deployment now consists of the server jar, the client jar, and the policy file. All servers built this way reference the same client jar, in the same way as they all reference the same policy file. A stand-alone client not only reduces the server jar file size, which can be helpful if there are many servers in the same directory, it is also very useful in its own right. Using the standard client is a topic of its own, and as such gets its own page.

The make3 creates the server as three files: server.jar, client.jar, and proxy.jar. Now deployment consists of four files, the three jars, and the policy file. The reason to use make3, is if you want to take advantage of the 'hot plugging' capability of the framework. This means you can modify the proxy, or proxies, recompile their jar file(s), and overwrite the existing proxy jars, all whilst the server is still running! All subsequent clients will receive the updated functionality automatically, and the server need not be shut down.

The make4 creates the server as four files: server.jar, client.jar, proxy.jar, and cajo.jar. The cajo.jar file is the standard binary library for the cajo project. By using this jar file, all of the standard functionality is stored in one central repository. This not only reduces the size of the server jar files, but permits library updates without affecting the server files. This is the most common method of deployment.

As you would expect, there is a fifth batch file, and default ant build target; called library. It compiles the project source code and creates the standard cajo.jar library image. Its purpose is to provide the framework functionality to multi-jar classpaths, used by the majority of applications.
Launching the example
Once you have built the example, launching it can be as simple as executing the following command:
    java -jar server.jar
This will start the server using its default settings:
  • client and proxy code delivery on TCP port 80
  • server item communication on TCP port 1099
  • hostname is identical both inside and outside subnet
  • default server network interface is being used
  • the server port is the same both inside and outside the subnet
This should suffice for many users, however these five assumptions can be overridden, as command line arguments. The options above progress from most likely to need overriding, to least.

1. Typically the first problem hit by most users is that port 80 is not available. This can be for a variety of reasons; there is already an http server running on the box, or you are using a *nix system and you are not root, in any case, you are forced to select another port. Fortunately this is the first command argument. In this case, you will have to do something like this:
    java -jar server.jar 8080
This will start the http service for the client and proxy code on port 8080. The only real impact is that the port must now be explicitly specified by the client when connecting to the server, as it is no longer default. This detail will be covered in the next section, connecting.

2. Often the next problem hit is that port 1099 is not available. Typically this is because a central rmiregistry is running on the machine. By default, each cajo server uses its own rmiregistry, operating on the same port as the interface to its items. In any case, another port must be selected:
    java -jar server.jar 8080 1234
This means that clients connect to this server on port 1234. Note: the order and precedence of the arguments is required, meaning that if you want to specify the server port, you must also specify the http port. (yes, arguments could be handled in a more sophisticated fashion, but this is only an example program)

3. The next most common problem is that your server is behind a NAT router. This happens, for example, when you want to share a single connection to the internet. Essentially, the NAT router is giving you a 'fake' IP address valid only inside the subnet. It translates the addresses for you, and everyone else sharing the connection, to the actual network address. This means you need to know your outside IP address. There are simple programs to tell you your actual IP address. A very easy method to find it is to just visit ipchicken. Another highly recommended option, if you are going to be serving a lot, is to get a domain name. This is not nearly as difficult or expensive as it sounds. If you are willing to share one, it is very easy to get one for free. One handy place to do this is dyndns. There you can register a name, something like yourhost.dyndns.com, and they even have a variety of utilities you can run to make sure that name always resolves to your host, even if your ISP is constantly changing your address! If you want to get really fancy, you can always buy your own registered domain name. Anyway, now you will have a command line that looks something like this:
    java -jar server.jar 8080 1234 yourhost.dyndns.com
-or-
    java -jar server.jar 8080 1234 123.123.123.123
Now clients will correctly connect to you on your actual address, not the internal one that the NAT router gave your host.

4. Next, lets assume your computer has two network adapters; a wired connection to your LAN, and a wireless connection to the internet. You may want to specify on which IP address, in this case physical network interface, you want to run: Otherwise, it will operate on all of them, by default. To do this, you would specify the local interface address, even if it is running behind NAT. This would be your command line now:
    java -jar server.jar 8080 1234 123.123.123.123 100.100.100.100
Note: this would also be required if your machine is multi-homed, i.e. has multiple logical network interfaces on a single physical network interface. Generally speaking, multi-homing is guru magic, if you don't know what the term means, it most likely doesn't apply to you.

5. The final, and most obscure option, is used to support port forwarding. Essentially, this is needed when a router is publicly taking connections on one port, and routing it to your internal machine, on another. In this case you would specify the outside port. As the last option, you have probably already guessed it; port forwarding is advanced guru magic. If you are doing this, you already know what the command line would look like; but just for the rest of us, here it is:
    java -jar server.jar 8080 1234 guru.org 100.100.100.100 4321
Here a client connecting on port 4321 of the public address guru.org actually connects to some internal machine at 100.100.100.100 on its port 1234. In this case, if none of this makes any sense, it definitely doesn't apply to you.
Connecting to the server
Connecting to this example is generally done using a browser. You will need to have the Java plugin installed, if you don't the server will cause your browser prompt you if it can install it automatically. This is done to make connections easy for end users, who may be technically unsophisticated. Just as with launching the application, connecting could be as simple as pointing your browser to:
    http://yourserver
The proxy, which is graphical, will load and appear inside your browser, full screen and dynamically resizable.

Just as with the server, there are a similar set of options to configure the client. This time let's start with the complete URL, then explain its optional components:
    http://serverHost[:serverPort]/[clientPort:][localPort-][proxyName][!]
  • The serverPort value is specified when port 80 was not abvailable for the server. Unspecified, it will be port 80. In our example with the server options, it would be 8080.
  • The clientPort value would indicate the inbound TCP port on which the client would like to receive the server callbacks. This would need to be specified if the client was behind a firewall. Unspecified it would be anonymous, meaning randomly chosen by the client, at runtime.
  • The :localPort value would be the client's internal port number if it is being translated from the external port number. Unspecified it will be the same as clientPort. Very few people will ever need this option.
  • The -proxyName value would be used when the server binds more than one item. This is the name under which the item would be bound in the registry. Unspecified the name "main" will be used, as servers typically bind their default item under that name.
  • The ! option will cause the client application to launch as a WebStart application. Around here, we like to call it starting the application with a bang!
The server will correctly configure the client's remaining communications settings, even when the client is operating behind a NAT router.

Connecting can also be done using the generic client application. It is highly recommended to use the client application for server development purposes.
Conclusion
The example will provide a client proxy looking something like this:

cajo generic client applet cajo rated JARS top 25%

Whilst the server console will look rather like this:

cajo example server

This is the proverbial tip of the iceberg, but it should get you started. If you have further questions, there are fora for this project. However, before posting, please do your homework. Most often, the answer you are seeking can can be found in the source documentation, or right here on this site, and usually much more quickly. Otherwise, your questions, comments, and suggestions, are all most welcome.

The deeper you look, the more of the framework's power reveals itself to you.

© 2004 John Catherino, GNU FDL