Oscar Usage

Release version: 1.0.5 - May 13, 2005

Starting Oscar

To start Oscar, execute the appropriate shell script for your computer: oscar.bat for Windows or oscar.sh for UNIX-based operating systems. For UNIX-based systems you will need to do "chmod +x oscar.sh" to make the script executable. A better alternative is to execute Oscar from the installation directory by typing:


    java -jar lib/oscar.jar

After executing the above command, you will be prompted to enter a profile name; a profile is a simple way to organize sets of installed bundles and any arbitrary name will suffice. By default, Oscar creates a directory, called .oscar, in your home directory and inside of this directory Oscar creates a separate sub-directory for each profile; this behavior is configurable, see the bundle caching document for more details. After you have specified a profile name, either the text-based user interface or the GUI-based user interface is started, depending on your choice when installing Oscar. If you are not satisfied with your installation-time choice of shell user interface, it is possible to change your default shell user interface.

Oscar Shell

The main way to interact with Oscar is via its shell service. Oscar's shell service is implemented as an OSGi service that can have any number of user interfaces; see the shell service documentation for more details. When you installed Oscar, you were asked to select between a text-based or GUI-based shell; the shell functionality is the same in both user interfaces. After starting Oscar, type help into the shell to see the list of the available commands; these are the default commands:


	bundlelevel <level> <id> ... | <id> - set or get bundle start level.
	cd [<base-URL>]                     - change or display base URL.
	headers [<id> ...]                  - display bundle header properties.
	help                                - display shell commands.
	install <URL> [<URL> ...]           - install bundle(s).
	obr help                            - Oscar bundle repository.
	packages [<id> ...]                 - list exported packages.
	ps [-l]                             - list installed bundles.
	refresh                             - refresh packages.
	services [-u] [-a] [<id> ...]       - list registered or used services.
	shutdown                            - shutdown Oscar.
	start <id> [<id< <URL> ...]         - start bundle(s).
	startlevel [<level>]                - get or set framework start level.
	stop <id> [<id> ...]                - stop bundle(s).
	uninstall <id> [<id> ...]           - uninstall bundle(s).
	update <id> [<URL>]                 - update bundle.
	version                             - display version of Oscar.

For a detailed description of how to install bundles into Oscar refer to the next sub-section; the remainder of this 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 want 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 are loaded will automatically be reloaded the next time you start the associated profile. Additionally, any bundles that are active, will be reactivated the next time you start the associated profile.

Installing 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 and package sharing.

Oscar is packaged with seven bundles, which are located in the bundle/ directory of the Oscar installation directory. Six of these bundles are used for implementing the Oscar shell and its text and GUI user interface. The seventh bundle, simple.jar, is an example bundle that illustrates many aspects of bundle development. In additional to these bundles, many other bundles are available from Oscar's bundle repository for easy installation. Access to the bundle repository is provided by one of the included bundles in the form of an Oscar shell command, named obr; see the bundle repository documentation for more details.

Before installing any bundles, it is important to understand how bundles are deployed into the framework. Bundles are deployed in two stages; first they are installed, then they are started. To install a bundle use the install shell command followed by a bundle URL. For example, to install the simple.jar bundle you type (assuming you have started Oscar from its installation directory):


    install file:bundle/simple.jar

Once a bundle is installed, it can then be started by using the start command and the bundle identifier of the desired bundle. The ps shell command is used to list all installed bundles and to obtain the bundle's identifier. The following Oscar shell session capture illustrates how to start the simple.jar bundle:


	-> install file:bundle/simple
	-> ps
	START LEVEL 1
	   ID   State         Level  Name
	[   0] [Active     ] [    0] System Bundle (1.0.0)
	[   1] [Active     ] [    1] Shell Service (1.0.0)
	[   2] [Active     ] [    1] Shell TUI (1.0.0)
	[   3] [Active     ] [    1] Bundle Repository (1.0.0)
	[   4] [Installed  ] [    1] Simple (1.0.0)
	-> start 4
	Simple Bundle 4 has started.
	From native: Hello!
	From embedded JAR: Hello!
	Resource = null
	The 'javax.servlet.http' package is not available.
	The 'javax.servlet' package is not available.
	->

The stop command is used to stop a bundle and the uninstall command is used to remove a bundle from Oscar. As an alternative to using the install and start commands explicitly, it is also possible to install and start a bundle in one step by using the start command with a bundle URL.

Bundles can be updated using the update command. The update command allows you to specify a URL from which to retrieve the updated bundle, but if one is not specified it will try to update the bundle from the bundle's Bundle-UpdateLocation manifest attribute, if present, or the bundle's original location URL.

Important: When you update or uninstall a bundle, the changes appear to take effect immediately, but in reality the changes are only partially enacted. If a bundle is updated or uninstalled and it was exporting packages, these packages are not removed until the framework is refreshed using the PackageAdmin service. The Oscar shell offers a convenient refresh command for this purpose.

For an introduction to writing bundles and services, refer to the Oscar bundle tutorial or the tutorials provided by Sun for Windows and Solaris.

Installing Bundles and Proxies

If you use a proxy for Web access, then you may run into difficulty using the Oscar shell to install bundles from a remote URL. To remedy this situation, certain system properties must be set to make Oscar work with your proxy. These properties are:

These system properties can be set directly on the command line when starting the JVM using the standard "-D<prop>=<value>" syntax or you can put them in the lib/system.properties file of your Oscar installation; see documentation on configuring Oscar for more information.

Configuring Oscar

Oscar uses properties to configure certain aspects of its behavior. When you run Oscar from the command line, it tries to find all of its configuration properties using System.getProperty(). To configure Oscar via system properties, you can specify system properties when you type the java command to execute Oscar using the standard "-D<prop>=<value>" syntax. You can also specify system properties in Oscar's system.properties file, which is located in the same directory as oscar.jar (i.e., lib/ by default). Any property placed in the system.properties file will be made accessible at run time via System.getProperty(). The properties file uses standard Java property file syntax (i.e., attribute-value pairs).

As stated above, the system.properties file is located in the same directory as the oscar.jar file. It is possible to change this location by specifying a new location value using the oscar.system.properties property, which defines the full path and name of the desired property file. Note: It is not possible to set this property value inside of the system.properties file, since Oscar needs this value to start execution; this command must be specified on the command line when starting Oscar. All remaining configuration properties can be set either at the command line or in the system.properties file. Note: Command-line properties are overwritten by properties in the system.properties file.

There is another way to specify Oscar's configuration properties, but to do so you must manually instantiate an instance of Oscar, rather than executing Oscar's JAR file. When you instantiate an instance of Oscar you are able to pass in configuration properties via Oscar's constructor. If an Oscar instance receives properties in its constructor, then it will only use these properties and all system properties (i.e., System.getProperty()) are ignored. This is helpful in situations where you want to create multiple or nested instances of Oscar.

The following properties are all of Oscar's configuration properties:

The above properties are standard for the Oscar framework, but properties also exist to configure Oscar's default bundle cache. The bundle cache properties are dependent on the cache implementation you are using, which can be specified via the oscar.cache.class property described above. If you are using the default bundle cache, then you may specify the following properties on the command line, in the system.properties file, or to Oscar's constructor:

The Oscar installation contains a default system.properties file in the lib/ directory for automatically starting the shell service and shell user interface. The next section describes configuration properties can be used to configure installed bundles.

Changing the Command Shell User Interface

Oscar's shell service supports multiple user interface implementations; the default shell user interface is text-based, but a simple graphical shell is also provided. To change the default shell user interface, you must modify the oscar.auto.start property in the system.properties file in the lib/ directory of your Oscar installation. For the text-based user interface, the property value should look like this:


    oscar.auto.start.1=file:bundle/shell.jar file:bundle/shelltui.jar \
        file:bundle/bundlerepository.jar

This property value instructs Oscar to automatically start the shell service, the shell textual user interface, and the bundle repository. (Note: The "\" character at the end of the above line indicated that the property value continues on the next line; it is also possible to specify the property value on one line.) For the GUI-based shell user interface, the property value should look like this:


    oscar.auto.start=file:bundle/shell.jar file:bundle/bundlerepository.jar \
        file:bundle/tablelayout.jar file:bundle/shellgui.jar \
        file:bundle/shellplugin.jar

This property value instructs Oscar to automatically start the shell service, the bundle repository, the table layout library (needed by the shell GUI bundle), the shell GUI, and the GUI shell components.

Configuring Bundles

Some bundles use properties to configure certain aspects of their behavior. As an example, the default URL for the cd command of the shell service can be specified using the property oscar.shell.baseurl. It is a good idea, when implementing bundles, to parameterize them with properties where appropriate. To learn about the configuration options for specific bundles, refer to the documentation that accompanies them.

Bundle properties are set by using the bundle.properties property file. Any property placed in this file will be accessible via BundleContext.getProperty() at run time. The property file uses the standard Java property file syntax (i.e., attribute-value pairs). By default, the bundle.properties file is located in the same directory as the oscar.jar file. It is possible to change this location by specifying a new location value using the oscar.bundle.properties system property (described in the previous section), which should contain the full path and name of the desired property file.

Bundles cannot directly access system properties via BundleContext.getProperty(), but it is possible to push system properties into the bundle property values. This is achieved through system property substitution, which is instigated by marking text in the bundle property value with ${...}, where "..." is the name of a system property. When such a property value is retrieved by a bundle, the system property value will be substituted into the bundle property value as appropriate.

Using Oscar with Eclipse

For those people using the Eclipse IDE, there are instructions available for using Eclipse and Oscar together.

Feedback

If you have comments or suggestions, feel free to contact me at heavy@ungoverned.org.

Richard S. Hall