JOS overview

JOS uses the mechanisms provided by the JKernel core package to build a small operating system environment comprised of a collection of priviledged tasks called subsystems. In general, a subsystem implements trusted services for other applications running in JOS.   Currently, the JOS package contains two standard subsystems: the File subsystem, which exports Java's standard File interface, and the RPC subsystem, which allows JKernel services exported as capabilities to be invoked over the network. In addition, the JServer web server is implemented in JOS as a subsystem. The JServer and its servlets use the File subsystem to perform Java file operations, and the RPC subsystem for remote debugging support.

Subsystems can be loaded at JOS startup time by the JOS's subsystem manager (cornell.slk.jos.manager.SubsystemManager), or dynamically loaded by the JServer through a subsystem loader servlet (cornell.slk.jserver.servlets.SubsystemLoader).

A class implements a subsystem by implementing the Subsystem interface, which has two methods: a start method, which takes initialization parameters stored in a hashtable as argument, and a stop method. Alternatively, a class can also extend the GenericSubsystem abstract class and overwrite the start and stop methods.

Example:

package cornell.slk.jos.test;

import cornell.slk.jos.manager.*;
import java.util.*;
import java.lang.reflect.*;
import java.net.*;
import java.io.*;

public class TestSubsystem extends GenericSubsystem
{
    public void start(Hashtable params) throws SubsystemException
    {
        System.out.println("TestSubsystem start");
        for (Enumeration e = params.keys(); e.hasMoreElements();)
        {
            Object key = e.nextElement();
            Object value = params.get(key);
            System.out.println("key=" + key.toString() + " value=" + value.toString());
        }

        Method[] m = this.getClass().getMethods();
        try
        {
            Socket s = new Socket("128.84.223.121", 9999);
            ObjectInputStream i = new ObjectInputStream(null);
            File f = new File("hello");
        }
        catch (Exception e) {}
    }
    public void stop() throws SubsystemException
    {
        System.out.println("TestSubsystem stop");
    }
}

Subsystem Configurations and JOS Configuration Files

A subsystem runs within a single protecton domain, which controls its namespace using a collection of JKernel resolvers. A subsystem configuration contains information used by the JOS to configure the subsystem task with the appropriate resolvers. A valid subsystem configuration must have the mandatory keywords:

SUBSYSTEM_NAME. A name or handle for the subsystem.

SUBSYSTEM_ENTRY_CLASS. The fully-qualified name of the class that implements the cornell.slk.jos.manager.Subsystem interface

SUBSYSTEM_PACKAGES. All the packages (including the one to which the entry class belong) imported by the subsystem. Use semi-colons as separators.

SUBSYSTEM_PATH. The paths for the entry class, the entry class's package, and other packages imported by the subsystem.  Use semi-colons as separators. The "default" path is the directory from which JOS is launched.

The following are optional keywords:

SUBSYSTEM_CLASSES. Additional classes used by the subsystem, separated by semi-colons. Typically, a class listed here either doesn't belong to any package or belongs a large one. In the latter case, the resolver for the subsystem will be able to resolve only this class from the entire package (unless the package name is included in SUBSYSTEM_PACKAGES).

SUBSYSTEM_RESOLVERS. Names, separated by semi-colons, of any pre-built resolvers that are to be added to the subsystem's task. The following is a list of pre-built resolvers:

SUBSYSTEM_NATIVE. "yes" if the subsystem needs to be able to load native C libraries, "no" otherwise. The default (e.g. when this keyword is not specified) is that a subsystem is not allowed to load native code.

Comment lines are preceded by the character "#". Blank lines are ignored. You can also specify additional arguments to your subsystem by entering key/value pairs in separate lines. These pairs can appear anywhere after the SUBSYSTEM_NAME line.

For example, the following lines constitute a valid configuration for the TestSubsystem:

# TestSubsystem configuration
SUBSYSTEM_NAME=TestSubsystem
SUBSYSTEM_ENTRY_CLASS=cornell.slk.jos.test.TestSubSystem
SUBSYSTEM_PATH=default
SUBSYSTEM_PACKAGES=cornell.slk.jos.test
SUBSYSTEM_CLASSES=
SUBSYSTEM_RESOLVERS=/resolver/reflection;/resolver/net;/resolver/file
SUBSYSTEM_NATIVE=no
# additional arguments for the TestSubsystem
a=0
b=foo

A JOS configuration file is a sequence of one or more subsystem configurations terminated by two lines with the keywords START_ORDER and STOP_ORDER. These keywords specify the order in which the listed subsystems are started and stopped respectively. The following is an example of a valid JOS configuration file (i.e. config/jserver-config.txt). In this example, the RPCSubsystem must be launched before the Client subsystem because: (i) the latter uses the "/resolver/rpc" resolver that is built by the former, and (ii) the latter imports/exports RPC interfaces. The Client subsystem must be stopped before the RPCSubsystem because the former needs to free its resources (interfaces, etc) through the latter. START_ORDER and STOP_ORDER let the programmer deal with these kinds of subsystem dependencies.

# RPCSubsystem configuration
SUBSYSTEM_NAME=RPCSubsystem
SUBSYSTEM_ENTRY_CLASS=cornell.slk.jos.rpc.subsystem.RPCSubsystem
SUBSYSTEM_PATH=default
SUBSYSTEM_PACKAGES=cornell.slk.jos.rpc.core;cornell.slk.jos.rpc.subsystem
SUBSYSTEM_CLASSES=
SUBSYSTEM_RESOLVERS=/resolver/net;/resolver/file
SUBSYSTEM_NATIVE=no
# no additional arguments

# HttpServer configuration
SUBSYSTEM_NAME=HttpServer
SUBSYSTEM_ENTRY_CLASS=cornell.slk.jserver.httpserver.HttpServer
SUBSYSTEM_PATH=default
SUBSYSTEM_PACKAGES=cornell.slk.jserver.httpserver;cornell.slk.util;cornell.slk.jserver.servlet;cornell.slk.jserver.servlet.http
SUBSYSTEM_CLASSES=
SUBSYSTEM_RESOLVERS=/resolver/file;/resolver/net;/resolver/reflection;/resolver/rpc
SUBSYSTEM_NATIVE=yes
# no additional arguments

# the following two lines make this a JOS configuration file
START_ORDER=RPCSubsystem;HttpServer
STOP_ORDER=HttpServer;RPCSubsystem

Starting the JOS

JOS is started by invoking the main method of cornell.slk.jos.manager.Main. The usage is:

cornell.slk.jos.manager.Main -config <config file> [<arg1=value1> <arg2=value2> ... ]

where <config file> is the path and name of a JOS configuration file, and <argN=valueN> key/value pairs that are passed into every subsystem listed in the configuration file.

For example, the command:

c:\slk\jk-0.91\bin> jview /cp:p . cornell.slk.jkernel.std.Main cornell.slk.jos.manager.Main -config config\jserver-config SERVER_TYPE=STANDALONE

launches the JOS according to the config\jserver-config file and passes the SERVER_TYPE=STANDALONE argument to the subsystems.