Hello, world!

The Hello, world! program is a minimal, complete Jicos program. It defines 2 classes:

The Application class

  • This class is part of the edu.ucsb.cs.jicos.examples package.
  • The import of edu.ucsb.cs.jicos.services.* gives the compiler access to Jicos services classes & interfaces, some of which are accessed from the Application class (e.g., HspAgent).
  • The Application class needs only a public static void main method.
  • The main method throws Exception:
    • RemoteException:Methods that ultimately interact with the hosting service provider are implemented via Remote methods (.e.g, login, compute). These can throw RemoteException. 
    • ComputeException: Tasks that Jicos executes on behalf of the client may throw exceptions. These are propagated to the client applications via the ComputeException (defined within Jicos). 
    • JicosException: Jicos may catch an unexpected runtime exception within its own code - an internal exception. Such exceptions are wrapped within a JicosException, and thrown back to the client application. 
    The application does not have to catch any of these: The main method throws Exception, which covers all possibilities. This generally is how the tutorial examples are written.
Application main methods routinely execute the following sequence:
  1. Get a reference to a Hosting Service Provider (Hsp). 

    2. HspAgent( String )constructs a helper for this purpose. Its argument is the domain name of the machine on which the Hsp is running. The method getHsp() returns a Remote reference to an Hsp.
  2. Login with the Hsp.

    3. The statement:
    Environment environment = new Environment( null, null);
    establishes that this client: 
    1. does not have an input object that is accessible to all tasks (the 1st argument);
    2. does not have an object that is shared among all tasks (the 2nd argument).
    The method login( environment ) readies the Jicos system for receiving computational tasks from this application.
  3. Give 1 or more tasks to the Hsp for processing.
  4. The compute method expects 1 argument: a Task, in this case, the HelloTask. Its returned value is Object. So the return value needs to be cast, as appropriate to the actual return type. In this case, the return type is String.
  5. Do something with the returned value. In this case, we simply print out the returned String value.
  6. Logout from the Hsp.

    7. The logout()method ends the interaction of this application with the Hsp.

The HelloTask class

  • Since this class extends Task, it imports edu.ucsb.cs.jicos.services.*.
  • HelloTask  extends Task.
  • The class is comprised of an execute method.
    • The execute method encapsulates its task's computation.
    Its return value is an Object. Viewing the execute method as a function, its return value is the value of the function it computes. In this case, we have a constant function whose value is the String "Hello, world!".

Compiling your application

This section of the tutorial has several parts:
  • compile the .java files
  • copy the HelloTask .class files to your codebase & make them accessible for download.
  • start the Hsp
  • start a TaskServer
  • start a Host
  • start your application.

Compile the .java files

Because the JavaTM programming language requires a mapping between the fully-qualified package name of a class & the directory path to that class, you should decide on package & directory names before you begin writing any code written in the Java programming language. This mapping allows the compiler for the Java programming language to know which directory contains the class files mentioned in a program. For the programs in this tutorial, the package name is edu.ucsb.cs.jicos.examples.helloworld and the source directory is $HOME/edu/ucsb/cs/jicos/examples/helloworld, where $HOME is set to your home directory. Create the directories needed: 
  • edu
  • edu/ucsb
  • edu/ucsb/cs
  • edu/ucsb/cs/jicos
  • edu/ucsb/cs/jicos/examples
  • edu/ucsb/cs/jicos/examples/helloworld.
The source code for this example is now complete, & the $HOME/edu/ucsb/cs/jicos/examples/helloworld directory has 2 files:
  • Application.java
  • HelloTask.java
In this section, you compile the .java source files to create .class files. Make sure that: 
  • the deployment directory $HOME/classes is readable & writeable
  • and source directory $HOME/edu/ucsb/cs/jicos/examples/helloworld is readable and executable.
When you use the javac compiler, you may specify where the resulting class files should reside. For our example, this directory is $HOME/classes.

To compile the source files, run the javac command as follows:

javac -d $HOME/classes -classpath .:$JICOS/lib/jicos-system.jar *.java
This command creates the directory edu/ucsb/cs/jicos/examples/helloworld (if it does not already exist) in the directory $HOME/classes. The command then writes to that directory the files Application.class & HelloTask.class.

Deploy your application

Deployment consists of:
  1. setting your codebase
  2. starting your application

Setting your codebase

Some web servers allow accessing a user's public_html directory via an HTTP URL constructed as "http://host/~username/". As an alternative, you can use an HTTP URL by setting up a minimal web server on your system; Sun Microsystems has one available for download here.

To make the task classes accessible to Hosts (which will execute them), the task class files are copied from the development directory to the Application's codebase directory. First, create the directories where the class files will go: $HOME/classes/edu/ucsb/cs/jicos/examples/helloworld.

Directories & class files must be readable & executable by all. 
Copy the task class files to the directory:
cp  $HOME/classes/edu/ucsb/cs/jicos/examples/helloworld/*.class
    $HOME/public_html/classes/edu/ucsb/cs/jicos/examples/helloworld
Set file permissions so that the class files can be downloaded by a web server:
chmod 644 $HOME/public_html/classes/edu/ucsb/cs/jicos/examples/helloworld/*.class
Check permissions all the way down the path up to and including the class files themselves. A good way to ensure that the files are accessible via a web server is to point a web client to the directory that contains the files, and see if the files are readable.

Start the HSP, a TaskServer, and a Host

Follow the links on the Administration manual page to start the following Jicos components: Hsp, TaskServer, & at least 1 Host. 

Start the application

Accessing an HSP

If you do not have access to a running JICOS hosting service provider, you will need to start one. (A hosting service provider
comprises an Hsp, at least 1 TaskServer, and at least 1 Host). This is easy. Please see the System Administration Manual.

Launch the JICOS program

To start Application.class, execute (all on 1 line):
    java -cp $HOME/classes/:$JICOS/lib/jicos-system.jar 
     -Djava.rmi.server.codebase=http://<server-domain-name>/~<username>/classes/
     -Djava.security.policy=$JICOS/policy/policy
    edu.ucsb.cs.jicos.examples.helloworld.Application <hsp-machine>
     
  • <server-domain-name> is the domain name of the web server that serves your web page (e.g., cs.ucsb.edu). Please take special note that the codebase URL ends in a "/". 
  • <hsp-machine> is the domain name of the machine on which the HSP is running. 
When starting the application, the java.rmi.server.codebase property must be specified, so that the task classes can be dynamically downloaded by the Jicos system components (Hsp, TaskServer, and Host[s]). If you forget the trailing slash on the codebase property, or if the class files can't be located at the source (they aren't really being made available for download) or if you misspell the property name, a  java.lang.ClassNotFoundException is  thrown.  If you have problems running the example code, please take a look at the RMI and Serialization FAQ.

The output should look like this:

Hello, world!