20 Projects

Project Properties

There are a number of built in properties that are set by bnd:

Run instructions

Run instructions are used to start OSGi tests and OSGi runs.

Launching

Launching is needed when the project's run action or test action is executed. The project creates a Project Launcher. A Project Launcher must launch a new VM and set up this VM correctly. The VM is launched with the following information.

• java - The command to launch a new VM is bu default java. However, this can be overridden by setting a property called java.
• classpath - The classpath set for the VM is derived from the -runpath property. Notice that this is supposed to contain the JAR with the framework. The -runpath requires bundle symbolic names for the JAR and an optional version range. bnd will use the latest version in the repository. Any packages that should be exported by the system bundle should have an export attribute containing the exported packages, like @@junit.osgi;version=3.8;export="junit.framework;version=3.8,junit.misc;version=3.8".
• vm options - These options can be set in the -runvm property. They are usually in the form of -Dxya=15 or -X:agent=bla. Options should be separated by commas.
• main - The class implementing the main type is defined by the launcher plugin.

And example of a launcher set is:

  -runvm:   -Xmn100M, -Xms500M, -Xmx500M
  -runpath: 	org.apache.felix.framework; version=3.0, \   
	junit.osgi;export="junit.framework;version=3.8"
  -runtrace: true
  -runproperties: launch=42, trace.xyz=true
  -runbundles: org.apache.felix.configadmin,\  
	org.apache.felix.log,\  
	org.apache.felix.scr,\  
	org.apache.felix.http.jetty,\   
	org.apache.felix.metatype,\  
	org.apache.felix.webconsole

Debugging launching is greatly simplified with the -runtrace property set to true. This provides a lot of feedback what the launcher is doing.

Access to arguments

When the launcher is ready it will register itself as a service with the following properties:

Access to main thread

In certain cases it is necessary to grab the main thread after launching. The default launcher will launch all the bundles and then wait for any of those bundles to register a Runnable service with a service property main.thread=true. If such service is registered, the launcher will call the run method and exit when this method returns.

Timeout

The launcher will timeout after an hour. There is currently no way to override this timeout.

Mini Framework

The bnd launcher contains a mini framework that implements the bare bones of an OSGi framework. The purpose of this mini framework is to allow tests and runs that want to launch their own framework. A launch that wants to take advantage of this can launch with the following property:

  -runframework: none

Ant

In ant, the following task provides the run facility.

  <target name="run" depends="compile">
    <bnd command="run" exceptions="true" basedir="${project}" />
  </target>

These targets provide commands for ant run.

Testing

Testing is in principle the same as launching, it actually uses the launcher. Testing commences with the test action in the project. This creates a Project Tester. bnd carries a default Project Tester but this can be overridden.

The basic model of the default Project Tester plugin is to look for bundles that have a Test-Cases manifest header after launching. The value of this header is a comma separated list of JUnit test case class names. For example:

  Test-Cases: test.LaunchTest, test.OtherTest

Maintaining this list can be cumbersome and for that reason the ${classes} macro can be used to calculate its contents:

    Test-Cases : ${classes;extending;junit.framework.TestCase;concrete}

See classes macro for more information.

Ant

  <target name="test" depends="compile">
    <bnd command="test" exceptions="true" basedir="${project}" />
  </target>

Overriding the plugins

Both the Project launcher and Project Tester are plugins. Defaults are provided by bnd itself (bnd carries a mini cache repo that is expanded in the cnf director), it is possible to add new launchers and testers as needed.

Plugins are found on the -runpath or the -testpath properties respectively. bnd will look for an appropriate manifest header. The header has a class name as value. It will then instantiate the class and use as launcher/tester. The classes must extend an abstract base class. Each plugin has access to the Project object, containing all the details of the project.

The plugin gets complete control and can implement many different strategies.