Oscar Usage

Preliminary release version: 0.3.0 - March 14, 2001

Starting Oscar

In order to start Oscar you must execute one of the appropriate shell scripts: run.bat file for Windows 95/98, run_nt.bat for Windows NT/2000, or run.sh for UNIX-based operating systems. These scripts start Oscar's command-line shell interface; future versions of Oscar will also include a GUI shell. The Oscar shell will prompt you for a user profile name; any user profile name will suffice. Oscar creates a directory called .oscar in your home directory. Inside this directory are separate sub-directories for each user profile.

Using the Oscar Shell

The shell is intended to be similar to a standard Unix shell, but is very simplistic. Type help to get a list of the available commands; these commands are:
    cd <base-URL>          - changes default base URL.
    debug <on | off>       - turn on/off debug messages.
    help                   - print this help message.
    install <URL> [URL...] - install bundle(s).
    printenv               - list registered services.
    ps                     - list installed bundles.
    shutdown               - shutdown Oscar.
    start <id> [id...]     - start bundle(s).
    stop <id> [id...]      - stop bundle(s).
    uninstall <id> [id...] - uninstall bundle(s).
    update <id> [URL]      - update bundle.
    <URL> [URL...]         - install and start bundle(s).
For a detailed description of how to install component bundles into Oscar refer to the next sub-section; this sub-section briefly describes shell behavior. Despite the fact that the Oscar shell tries to mimic a typical Unix-like shell, it is actually quite limited. The notion of cd, for example, is only used to specify a default base URL in order to save typing. To illustrate, assume that you wanted to load several bundles from a directory on your disk, you could type:
    cd file:/c:/projects/oscar/bundle
After issuing this cd command, you no longer need to type the complete URL for bundles located in the above directory, only the name of the bundle JAR file is necessary. Actually, only the root name of the JAR file is necessary since the shell will automatically add .jar if it is not supplied. It is not possible to perform an equivalent ls command to list the contents of the current base URL, since this operation is not possible with URLs. To view all currently installed bundles, use the ps command.

To exit the Oscar shell, simply type shutdown; any bundles that you have loaded will automatically be reloaded the next time you run the associated user profile. Additionally, any bundles that are active, will be reactivated the next time you run the associated user profile.

Loading Bundles

A bundle is the OSGi term for a component for the OSGi framework. A bundle is simply a JAR file containing a manifest and some combination of Java classes, embedded JAR files, native code, and resources. A bundle may provide some specific functionality for the user or it may implement a service that other bundles can use; bundles can only use functionality from other bundles through service interfaces.

The Oscar package includes a few simple example bundles located in the bundle directory of your Oscar installation. For more sophisticated bundles, you are encouraged to download Sun's OSGi implementation, called Java Embedded Server (JES); JES is freely available for experimentation. The bundles included with JES work with Oscar, but not all of them have been thoroughly tested. JES includes bundle implementations for an HTTP service and a remote management servlet, among others, both of which are very useful when playing with Oscar. In the future, it is the goal to have implementations of similar bundles included with Oscar.

Important: OSGi does not specifically intend bundles to be used to create end-user applications (i.e., applications that open windows, etc.), but the Oscar project is looking at using the OSGi framework for such purposes. OSGi intends bundles to provide user interfaces via HTTP or some similar protocol. There are many possible ways to create user interfaces for bundles, feel free to experiment.

For an introduction to writing bundles and services, refer to this article. The bundles included in the Oscar package are:

Bundles are executed in two stages; first they are installed, then they are started. To install a bundle use the install command followed by a bundle URL. Once a bundle is installed, it can then be started by using the start command and the bundle identifier of the desired bundle. Use the ps shell command to print a list of all installed bundles and to obtain the bundle's identifier. Use the stop command followed by a bundle identifier to stop a bundle and the uninstall command to remove a bundle from Oscar. Instead of using the install and start commands explicitly, it is possible to install and start a bundle in one step by simply typing the bundle URL at the Oscar shell command prompt.

Configuring Oscar

Currently, there are no configuration options for Oscar.

Configuring Services

Some services are configurable. Currently, the only way to configure services is to use the management servlet provided in Sun's OSGi implementation, called Java Embedded Server (JES). I highly recommend downloading JES, since its management bundles are very useful. In order to use the management facilities of JES, you will need to load the following bundles from the bundles directory of the JES distribution: servlet.jar, tcatjspcruntime.jar, http.jar, httpauth.jar, httpusers.jar, and jesmp.jar. To access the management interface, use your Web browser to access http://localhost:8080/admin, which will access the HTTP service now running inside of Oscar; the default user is admin and the default password is also admin. In the future, the goal is to include similar functionality in the Oscar package.

Final Comments

Oscar is not yet 100% compliant with the OSGi implementation, but it is getting very close. The goal is 100% compliance with the core specification, including core services. In the future I intend to extend the specification in ways that are beneficial to my goals, but I will do so in ways that allow strict OSGi compliance as an option. If you have comments or suggestions, feel free to contact me at heavy@ungoverned.org

Richard S. Hall