Odyssey Java Code

Here we document the organization and setup of the Java code used by the odyssey-2 package. Code formatting & related standards are in OdysseyJavaCodingStandards.

Introduction

The code that runs in an Odyssey JVM comes from three places:

• External JAR files
• Common Java code
• Specific Java code

External JAR files are symlinked into /software/odyssey-2/java-jar, a regional directory. Java APIs that are not part of the basic Java installation but which are also not specifically part of Odyssey are linked in this way.

Common Java code is supplied in source form in /software/odyssey-2/data/default. It is symlinked into /software/odyssey-2/java-src, a regional directory. This is code which is distributed to all Odyssey installations.

Finally, specific Java code distinguishes the Odyssey installations in each region. It is kept in /software/odyssey-2/java-src.

Execution

When the Odyssey JVM starts, the $CLASSPATH is set to all the .jar files in /software/odyssey-2/java-jar, together with the directory /software/odyssey-2/java-cls. The odysseyClassPath command generates the correct $CLASSPATH.

The /software/odyssey-2/java-cls is compiled from /software/odyssey-2/java-src upon package installation on the regional master.

Compilation

Upon package installation on the regional master, the entire contents of /software/odyssey-2/java-src are recompiled. The compiler output is saved in /software/odyssey-2/data/javac/compileResult. It is then compared to /software/odyssey-2/data/javac/normalCompileResult. If the two are identical, then compilation succeeds and installation completes by updating /software/odyssey-2/java-cls with the .class files generated by the compilation. Otherwise the differences are included in the output of installation.

It does not seem to be feasible to eliminate all the warnings from this compilation process. In particular there is no way to tell javac to ignore specific warnings. So when the code is updated, once it is determined that the new code is correct, the compileResult should be copied to normalCompileResult.

Javadoc Documentation

After the compilation has completely successfully, the Sun javadoc tool is invoked on the entire contents of the java-src directory, to populate the java-doc directory. This directory is symlinked into data/static so that the URL /odyssey-static/java-doc/ will contain the Javadoc documentation for the Java source code running the Odyssey installation in the region of the webserver. For example, the core.cs Odyssey Javadoc is available at http://www.cs.uwaterloo.ca/odyssey-static/java-doc/.

Source Files

Some of the source files in /software/odyssey-2/java-src are "common" code. At present this is the zava package, which contains the framework code, the and uw package, which contains the actual applications.

The code in zava here provides the basic implementation framework used by Odyssey. It is not specific to any particular application or to UW. This should be a symlink to /software/odyssey-2/data/default/zava.

The code in uw implements the various applications available through the Odyssey system. Roughly speaking, each sub-package of uw corresponds to an application. This should be a symlink to /software/odyssey-2/data/default/uw.

Finally, the code in content gives the specific configuration for each region providing an Odyssey interface.

-- IsaacMorland - 24 Jan 2007