Knopflerfish OSGi framework

Contents

1. Knopflerfish framework.jar startup
2. Initial start vs restart
3. Starting the framework
4. Starting the compact framework
5. Default selection of .xargs
6. Using a HTTP proxy
7. Framework and System Properties
8. OSGi Specified Framework Properties
9. Knopflerfish Specified System Properties
10. Knopflerfish Specified Framework Properties

Knopflerfish framework.jar startup

This is a startup guide for the KF OSGi framework. Note that command-line startup of the framework is not specified by OSGi, and system integrators often need to create a wrapper script for FW startup.

The KF Main startup class is primarily intended to be used in scenarios where current working directory is same as the one containing framework.jar, the framework storage directory and configuration files. In these cases

java -jar framework.jar

...is often enough.

To use features that requires JVM restart, e.g. extension bundles, you can use our example shell start script "kf2". Open a terminal and type

./kf2

Note: the script requires a "sh" shell.

Other uses are possible, but require options and possibly some tweaking of the default startup files.

Initial start vs restart

Two cases of framework startup should be noted:

1. Initial, bootstrap, startup
   An initial startup must contain enough options to install bundles allowing further management, using -install options. If no bundles are installed, an empty framework will be started but nothing can be done with it..
2. Restart of previously initialized framework
   Any OSGi framework can remember its state from previous startup.
   In this case, startup options should only contains system properties and a -launch option for restarting the bundles, but not any -install options.

NB! Framework properties (-Fx=y) supplied at initial startup are saved as part of the framework state, and need not to be supplied again at framework restart. System properties (-Da=b) are not included in the framework state. Since the two different startup cases probably will use separate startup files, care must be taken so system properties are set correctly in both files, when so required.

It is up to a system integrator to decide when to use initial startup or restart. The Main KF class can help somewhat in doing this (see below) but might not be enough. In those cases, wrapper scripts, or modifications to Main.java are recommended.

Starting the framework

The framework can be started using the startup wrapper class

org.knopflerfish.framework.Main

This class is also set a Main-Class in framework.jar's manifest, meaning framework.jar can be started using

 java -jar framework.jar [options] OR ./kf2 [options]

The Main class supports a number of options, which can be displayed using:

java -jar framework.jar -help OR ./kf2 -help

Options can also be specified using the -xargs option, which specifies a .xargs text file containing lines of new options. Typically all options are specified in .xargs files. Combining .xargs files and command line options is possible. .xargs files can also use recursive .xargs files.

When the framework is started, it uses a file system directory for storing the state of all installed bundles, "fwdir". The default directory used for this is:

fwdir

in the current directory. The "fwdir" directory can also be set specifically using the org.osgi.framework.storage property. Note that moving "fwdir" also changes the location for searching for default .xargs files.

If no options are specified (any "-Fx=y", "-Da=b" or "-init" does not count as options in this case) an implicit

-xargs "default"

is added to the options. "default" means that the default .xargs (see below) is selected.

Starting the compact framework

There is a compact version of the framework available for system that has limited amount of resources (memory and storage). This version doesn't contain any support for security and certificates. The internal classes has also been name mangled to save resources.

The compact framework is started and controlled in the same way as the full version. The only difference is that the jar file is called framework_compact.jar.

Default selection of .xargs

If _no_ args are supplied (arguments of the form "-Fx=y", "-Da=b" or "-init" does not count in this case), or a name of "default" is given as -xargs argument, a default .xargs file will be searched for, by the following algorithm:

1. If there exists a previous "fwdir" AND previous options does not contain "-init", use a file in "fwdir" named:
   

   fwprops.xargs

2. If no fwdir exist, OR options contain an "-init", search for a file named:
   1. init_[osname].xargs
   2. init.xargs
   3. remote-init.xargs
   The search is performed in the following directories:
   1. fwdir
   2. The parent directory of fwdir (if any)
   3. The current working directory
   First match wins.
   The [osname]-part of the file name is the unified OS name as specified in Alias.java (see below). Case is important if the file system is case sensitive.
   OS aliases:
   • OS2
   • QNX
   • Windows95
   • Windows98
   • WindowsNT
   • WindowsCE
   • Windows2000
   • WindowsXP

The file fwdir/fwprops.xargs contains saved properties that is used when restarting a framework instance. It is written by the Knopflerfish framework on every startup (unless disabled by setting the property "org.knopflerfish.framework.write.restart.xargs" to false).

Using a HTTP proxy

The standard JVM system properties

• http.proxyHost
• http.proxyPort
• http.nonProxyHosts

should be used to set proxy information. This will be global to all HTTP request from all bundles and the framework.

Additionally, the KF-specific system property

• http.proxyAuth

can be set to a value on the form user:password

If set to non-empty, this will add the Proxy-Authorization header to bundle install http/https requests made from the framework, However, bundles using the URL class internally must explicitly set this header themselves.

Framework and System Properties

Both Framework and Java System properties are used to control the framework.

Framework properties are the standard properties listed in the OSGi specification (section 4.5.3 in r4.core) and proprietary properties for the Knopflerfish framework. Framework properties are also used for configuration of Knopflerfish bundles.

Framework properties are specified on the command line or in .xarg files using "-F". If you have more than one framework instance, each instance has its own set of Framework properties.

A framework property is accessed by using

org.osgi.framework.BundleContext.getProperty(String)

Java System properties are specified on the command line or in .xargs files using "-D". System properties are accessed using

java.lang.System.getProperty(String)

BundleContext.getProperty

Because of the different handling of Framework and System properties when the framework is restarted, it is recommended to use only Framework properties in .xargs files. If you do, and use the default init.xargs/props.xargs files, initial starts and restarts become conveniently short on the command line:

java -jar framework.jar -init  

java -jar framework.jar  

Unfortunately, it is not always possible to avoid using Java System properties. For example, a bundle may include a class library that uses System properties for configuration. Also, properties that are read during start-up, before the framework has been initialized, need to be System properties, see KF System Properties.

OSGi Specified Framework Properties

OSGi Framework properties should be specified using "-F".

Knopflerfish Specified System Properties

Knopflerfish System properties should be specified using "-D".

Knopflerfish Specified Framework Properties

The recommendation is to use "-F" for Knopflerfish Framework properties but "-D" should also work.

> java -jar framework.jar
    -Forg.knopflerfish.framework.main.class.activation=\ 
    file:/foo/bar.jar,http://foo.com/bar.jar ...