Launching Framework

The bnd Build aspect is capable of starting another VM to run a project (launching) and to run tests in it (testing). The testing is based on the launching model. Some examples:

-runpath: org.apache.felix.main; version=latest
-runtrace: true
-runbundles: com.foo.bar;version="[1.2.3,2)", com.foo.baz; version=snapshot

This example will launch a Felix framework and then install two bundles. If a test is run, this example will use the default tester. This will launch the framework and then search for bundles that have the Test-Cases header set. All class names in this header will be tested and a report can be found in the target directory.

Background

As always, these facilities must work in ant, Eclipse, and other tools. As the requirements are diverse and numerous, bnd uses an extension mechanisms to allow different needs to be handled by different bundles. It also includes a default launcher and tester that have the following features:

• ee.minimum based. This means they run on minimal VMs.
• Uses JUnit 3 to also support minimal VMs
• Can launch without starting a framework. This is sometimes necessary to test launching and distributed code.
• Tester runs outside the framework, thereby not disturbing test code with extraneous bundles

However, both the launcher and tester are completely replaceable.

Usage

The following properties can be used to specify the launch/test procedures.

Option	Type	Defalt	Description
-runpath	BUNDLES	biz.aQute.launcher	Specifies bundles on the classpath of the to be launched VM
-testpath	BUNDLES	biz.aQute.tester	Specifies bundles to be added to the classpath of a VM used in testing.
-runvm	PROPS		Provides VM arguments for testing.
-runproperties	PROPS		Can be used to set general properties that are available as system properties in the launched VM
-runframework	none or services	Is either none or services.
-runsystempackages	CLAUSE		Add additional packages
-runbundles	BUNDLES		A list of bundles that will be installed/updated in the launched framework.
-runtrace	true or false	false	If set to true will trace the launching process in detail.

-runpath

A list of bundle specifiers. These ‘bundles’ are placed on the classpath of the to be launched VM. The first bundle that specifies the Launcher-Plugin manifest header is picked as the launcher. Bundles can be specified just like the -buildpath option, that is, with symbolic names and version ranges. If no launcher is specified in this list then the biz.aQute.|auncher is used, which is embedded in the bnd jar. The -runpath option shou|d contain the framework jar that follows the OSGi launching API. Any exports of any of the found bundles are added to the system packages that will be exported from the classpath.

-testpath

A list of bundle specifiers. These ‘bundles’ are placed on the class path of the to be launched VM when a test runs. The first bundle that has the Tester-Plugin manifest header is picked as the tester. If this header is empty or not specified then the default biz.aQute.tester is used. Any exports of any of the found bundles are added to the system packages that will be exported from the classpath.

-runframework

Specifies if the framework instance should be found with the launching API using META-INF/services or if it should not start a framework. No framework means no BundleContext availability! The no framework mode is required for certain kinds of tests.

-runsystempackages

Packages that will be added to the org.osgi.framework.system.packages.extra property. These packages will be exported by the framework and should be available by any of the system class loader or any of the included bundles in -runpath or, if applicable, -testpath.

This is implemented in master now. Project now has getProjectTester and getProjectLauncher. By default they return the handlers for biz.aQute.launcher and biz.aQute.junit. These can be used as examples. You can add your own jars on the -runpath (for the launcher) and -testpath (for the tester). If such a JAR has a manifest header specifying the Tester-Plugin or Launcher-Plugin then an instance of the given class is made. This instance should extend ProjectLauncher or ProjectTester. This instance can then setup the classpath, vm args, etc.

Simplest config is:

-runpath: org.apache.felix.main

The ProjectLauncher and ProjectTester base classes specify an API to control the launching. They can be used by Eclipse (e.g.) to get the VM args, classpath, etc. to obtain the settings needed in the Eclipse launcher architecture. However, the launcher and tester can work independently from this, the launcher implements a launch method and the tester implements a test method that will launch a new VM properly setup.