Bundle: util
Version 4.1.0


Library of miscellaneous utility classes.


Native Executable

The bundle activator utility class ExecutableBundleActivator can be used if you need to package an executable binary in your bundle that should be extracted and started when the bundle starts.

Depending on your needs you can either write your own bundle activator that extends ExecutableBundleActivator or use it directly without writing any Java code at all. If you use it directly, all you need to do is to add custom headers to your manifest that controls the behavior of ExecutableBundleActivator.

The following are the required headers for a simple example.

 Manifest-Version: 1.0
 Bundle-ManifestVersion: 2
 Bundle-SymbolicName: org.knopflerfish.bundle.ebaexample
 Bundle-Activator: org.knopflerfish.util.framework.ExecutableBundleActivator
 Import-Package = org.knopflerfish.util.framework,org.osgi.framework
 Bundle-Start-Executable: notepad.exe ; processor=x86 ; osname=WindowsXP

In this case there is only one custom header, Bundle-Start-Executable. It declares that if the native environment matches OS = Windows XP and processor architecture = x86, the resource named notepad.exe should be extracted from the bundle, written to the local file system and launched using java.lang.Runtime.exec() when the bundle is started.

The exec:ed process will be terminated when the bundle stops. If the process is terminated, the bundle will be stopped (this is the default behavior).

Complete list of custom headers for this utility class:

List of native environments (OS, processor, etc) and native executables for those environments. If there is a match for the current native environment, the executable is copied to the local file system and started in the start method of ExecutableBundleActivator. The syntax for this header is the same as for the OSGi specified Bundle-NativeCode header but instead of naming a shared library you name a native executable. The Bundle-NativeCode header is described in the core OSGi specification chapter 3.9.
Arguments (separated with spaces) for the bundle start executable.
Similar to Bundle-Start-Executable but the executable is launched when the bundle stops.
Arguments (separated with spaces) for the bundle stop executable.
List of extra resources (separated with comma) that should be copied from the bundle jar file to the local file system.
Set this to false if you do not want the bundle to be stopped when the process that was launched in start() is terminated.

In many cases you want to write your own activator that extends ExecutableBundleActivator. You can then for example override logging which is on and to stdout by default. Also, you need to write your own activator if you want your bundle to do more than starting a native executable.

Files that are extracted (executables and other resources) are written to the bundle's persistent storage area. Cleanup of the files takes place when the bundle is uninstalled.

Bundle Jar docs


Exported Packages