Core configuration options

Unknown macro: {scrollbar}

In order to configure the various aspects of the OSGi framework started by Pax Exam you can use the following options:

Using Felix as OSGi framework
Using Equinox as OSGi framework
Using Knopflerfish as OSGi framework
Using more OSGi frameworks
Provisioning using a plain url
Provisioning using a maven url
Provisioning a wrapped url
Setting bundle startup options
Setting up system properties
Setting up boot delegation
Setting up system packages

Using optional options

This options can be accessed via the static methods available in org.ops4j.pax.exam.CoreOptions. For more options you can check out the Pax Runner options and JUnit specific options. Also note that this is not a comprehensive set of options.

Some of the examples only shows the option usage and requires that you have a basic knowledge of how to setup a unit test. It also assumes that you have imported statically the CoreOptions class:

import static org.ops4j.pax.exam.CoreOptions.*;

Using Felix as OSGi framework

latest version (will use the latest version by the moment that Pax Exam was released)

        return options(
            frameworks(
                felix()
            )
        );

specific version

        return options(
            frameworks(
                felix().version( "1.0.4" )
            )
        );

more then one version

        return options(
            frameworks(
                felix().version( "1.0.4" ),
                felix().version( "1.4.0" )
            )
        );

all versions (all versions known by the moment that Pax Exam was released)

        return options(
            allFelixVersions()
        );

Using Equinox as OSGi framework

latest version (will use the latest version by the moment that Pax Exam was released)

        return options(
            frameworks(
                equinox()
            )
        );

specific version

        return options(
            frameworks(
                equinox().version( "3.4.0" )
            )
        );

more then one version

        return options(
            frameworks(
                equinox().version( "3.2.1" ),
                equinox().version( "3.4.0" )
            )
        );

all versions (all versions known by the moment that Pax Exam was released)

        return options(
            allEquinoxVersions()
        );

Using Knopflerfish as OSGi framework

latest version (will use the latest version by the moment that Pax Exam was released)

        return options(
            frameworks(
                knopflerfish()
            )
        );

specific version

        return options(
            frameworks(
                knopflerfish().version( "2.2.0" )
            )
        );

more then one version

        return options(
            frameworks(
                knopflerfish().version( "2.1.1" ),
                knopflerfish().version( "2.2.0" )
            )
        );

all versions (all versions known by the moment that Pax Exam was released)

        return options(
            allKnopflerfishVersions()
        );

Using more OSGi frameworks

The above OSGi frameworks can be combined:

latest versions of each framework

        return options(
            frameworks(
                felix(),
                equinox(),
                knopflerfish()
            )
        );

or

        return options(
            allFrameworks()
        );

all versions of all frameworks

        return options(
            allFrameworksVersions()
        );

Provisioning using a plain url

You can provision any bundle by its URL (any known protocols are accepted):

from http

        return options(
            provision(
                bundle( "http://repository.ops4j.org/maven2/org/ops4j/pax/url/pax-web-service/0.5.1/pax-web-service-0.5.1.jar" )
            )
        );

from file

        return options(
            provision(
                bundle( "file:/home/adreghiciu/development/pax-web-service-0.5.1.jar" )
            )
        );

Provisioning using a maven url

If the bundle to be provisioned is available in a Maven repository you may wanna use the maven bundle. This option makes use of Mvn Protocol url protocol handler.

specifying an exact version

        return options(
            provision(
                mavenBundle().groupId( "prg.ops4j.pax.web" ).artifactId( "pax-web-service" ).version( "0.5.1" )
            )
        );

a snapshot version

        return options(
            provision(
                mavenBundle().groupId( "prg.ops4j.pax.web" ).artifactId( "pax-web-service" ).version( "0.5.2-SNAPSHOT" )
            )
        );

latest version (version not specified).

        return options(
            provision(
                mavenBundle().groupId( "prg.ops4j.pax.web" ).artifactId( "pax-web-service" )
            )
        );

This will make maven url handler to search for the latest released version.

using a version range

        return options(
            provision(
                mavenBundle().groupId( "prg.ops4j.pax.web" ).artifactId( "pax-web-service" ).version( "[0.1.0,1.0.0)" )
            )
        );

This will make maven url handler to search for the highest released version between 0.1.0 (inclusive) and 1.0.0 (exclusive).

Provisioning a wrapped url

In some cases you may have a standard jar that you may need to make it OSGi compatible in order to deploy it. You can do this on the fly by using the wrapping provisioning option that makes use of Wrap Protocol url protocol handler.

using a plain url of the jar to be wrapped

        return options(
            provision(
                wrappedBundle( "http://repo2.maven.org/maven2/javax/servlet/servlet-api/2.5/servlet-api-2.5.jar" )
            )
        );

In this case the servlet api specified as a plain url will be downloaded and transformed into an OSGi bundle by adding the necessary metadata.

wrapping any another provision option

        return options(
            provision(
                wrappedBundle( mavenBundle().groupId( "javax.servlet" ).artifactId( "servlet-api" ).version( "2.5" ) )
            )
        );

In this case the same transformation will be applied but downloading (resolving the artifact) will use the maven option explained above.

Setting bundle startup options

All provisioning options (as the ones above) support setting up of:

bundle should be started or not
```
        return options(
             mavenBundle().groupId( "prg.ops4j.pax.web" ).artifactId( "pax-web-service" ).noStart()
        );
```
If noStart() is used then the bundle will not be started. By default ( = noStart() not used) the bundle will be started.

bundle content (jar file) should be updated
```
        return options(
            mavenBundle().groupId( "prg.ops4j.pax.web" ).artifactId( "pax-web-service" ).update()
        );
```
If update() is used then the bundle will be updated, meaning that the content of the bundle will be re-read from the original source (url). By default ( = update() not used) the bundle will not be updated, meaning that a cached bundle will be used from a previous run. There is one exception to this rule. If the provisioning option is a Maven bundle and the version is a SNAPSHOT version, by default the bundle will be updated automatically even if the update() is not used.
The reason behind not updating the bundles by default is related to performance, as re-downloading the bundles can be time consuming process and in most of the cases the bundle content will be the same. So, be sure that on bundles that you know that cange between runs you are using the update() method.

specify the start level
```
        return options(
            mavenBundle().groupId( "prg.ops4j.pax.web" ).artifactId( "pax-web-service" ).startLevel( 10 )
        );
```
By using startLevel(<level>) the bundle will be started at the specified start level, in this example teh start level of the bundle will be 10.

Setting up system properties

one system property

        return options(
            systemProperty( "org.osgi.service.http.port" ).value( "8080" )
        );

many (one or more) system properties

        return options(
            systemProperty( "org.osgi.service.http.port" ).value( "8080" ),
            systemProperty( "org.osgi.service.http.port.secure" ).value( "8443" )
        );

Setting up boot delegation

one boot delegation package

        return options(
            bootDelegationPackage( "sun.*" )
        );

many (one or more) boot delegation packages

        return options(
            bootDelegationPackages(
                "sun.*",
                "com.sun.*"
            )
        );

or

        return options(
            bootDelegationPackage( "sun.*" ),
            bootDelegationPackage( "com.sun.*" )
        );

Setting up system packages

one system package

        return options(
            systemPackage(
                "javax.rmi"
            )
        );

many (one or more) system packages

        return options(
            systemPackages(
                "javax.naming",
                "javax.rmi"
            )
        );

or

        return options(
            systemPackage( "javax.naming" ),
            systemPackage( "javax.rmi" )
        );