Configuration Options

Basics

A Pax Exam test is configured either by means of configuration methods annotated by @Configuration with return type Option[], or by a ConfigurationFactory, see next section.

Option is nothing but a marker interface. Options are created by static methods in org.ops4j.pax.exam.CoreOptions. Pax Exam users should never directly work with classes implementing Option.

Not all options are supported by every container, in fact most options are for OSGi containers only.

Pax Exam containers log a warning for each unsupported option type. Make sure to set up logging correctly to avoid missing these warnings.

Shared Default Configuration

To reuse the same configuration for all test classes in a suite and to avoid copying configuration methods, Pax Exam supports a ConfigurationFactory SPI.

If a test class does not have any @Configuration method, Pax Exam loads an implementation of the ConfigurationFactory interface (which must be unique) via the java.util.ServiceLoader and invokes the createConfiguation() method of this factory to obtain the configuration for the current test class.

Thus, to provide a default configuration of your test classes, create a class, e.g. com.example.MyConfigurationFactory, which implements org.ops4j.pax.exam.ConfigurationFactory, and a resource META-INF/services/org.ops4j.pax.exam.ConfigurationFactory containing the fully qualified class name of your configuration factory implementation.

Option Categories

Roughly speaking, options can be categorized into

provisioning options
property options

Provisioning options are used to provision bundles to the OSGi framework under test. Usually, each provisioning option (e.g. bundle()) provisions a single bundle, but there are some convenience options (e.g. junitBundles()) which provision groups of related bundles.

Property options are used to set system properties, OSGi framework properties or VM arguments for a forked Java Virtual Machine, where applicable.

Option Overview

Option Details

bootDelegationPackage

Containers: Native, Forked

Adds a package name to the org.osgi.framework.bootdelegation framework property.
```
bootDelegationPackage("sun.*")
```

bootDelegationPackages

Containers: Native, Forked

Adds multiple package names to the org.osgi.framework.bootdelegation framework property.
```
bootDelegationPackages(
 "sun.*",
 "com.sun.*"
)
```

bundle

Containers: Native, Forked

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

from http

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

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

cleanCaches

Containers: Native, Forked

clean the caches of downloaded and provisioned bundles when Pax Exam terminates
```
cleanCaches()
```

cleanCaches(true)

keep the caches
```
cleanCaches(false)
```

The last case is equivalent to keepCaches()

composite

Containers: Native, Forked

Groups multiple options into one composite option. This is useful to build your own option methods, e.g.

public static Option baseBundles() {
    return combine(
        mavenBundle("com.example.foo", "common", "1.0.0"),
        mavenBundle("com.example.foo", "util", "1.0.0"));
}

frameworkProperty

Containers: Native, Forked

Sets a framework property for the OSGi framework launched by the container. This is not in general equivalent to setting a system property of the same name.
```
frameworkProperty("osgi.console").value("6666")
```

frameworkStartLevel

Containers: Native, Forked

set the OSGi framework start level to a given value (a positive number).
```
frameworkStartLevel(6)
```

jarProbe

Since: 3.5.0

Containers: All CDI containers.

Lets the user assemble a bean archive with well-defined classes and resources instead of simply using the test class path by default. This option has additional arguments which are documented on a separate page.

junitBundles

Containers: Native, Forked (see note on Karaf)

provisions a default version of JUnit and its dependencies.
```
junitBundles()
```

The current version is org.ops4j.pax.tipi:org.ops4j.pax.tipi.junit:4.11.0.1. This is the original junit:junit:4.11 artifact repackaged as an OSGi bundle. The hamcrest-core dependency is also provisioned as an OSGi bundle.

This option is recommended when using the JUnit driver. If you wish to use a different version, replace this option by any other provisioning option specifying an explicit version of an OSGified JUnit artifact.

Karaf: Note that Karaf will by default provision default versions of JUnit and its dependencies unless KarafDistributionOption.overrideJUnitBundles() is used.

keepCaches

Containers: Native, Forked

keep the caches of downloaded and provisioned bundles, which are deleted by default when Pax Exam terminates
```
keepCaches()
```

This is equivalent to cleanCaches(false).

maven

Containers: Native, Forked

reference a non-OSGi Maven artifact in terms of its Maven coordinates

maven().groupId("postgresql").artifactId("postgresql").version("8.4-701.jdbc4")

shortcut:

maven("postgresql", "postgresql", "8.4-701.jdbc4")

reference the latest version of a non-OSGi Maven artifact in terms Maven groupId and artifactId
```
maven().groupId("postgresql").artifactId("postgresql")
```

shortcut:
```
maven("postgresql", "postgresql")
```

mavenBundle

Containers: Native, Forked

You can provision a bundle in terms of its Maven coordinates. Pax Exam uses the official Maven APIs to resolve an artifact from its coordinates from any of the repositories configured in Maven settings or by other Pax Exam options.

This option makes use of Mvn Protocol url protocol handler.

specifying an exact version

mavenBundle().groupId("org.ops4j.pax.web").artifactId("pax-web-service").version("0.5.1")

a snapshot version

mavenBundle().groupId("org.ops4j.pax.web").artifactId("pax-web-service").version("0.5.2-SNAPSHOT")

latest version (version not specified).

mavenBundle().groupId("org.ops4j.pax.web").artifactId("pax-web-service")

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

using a version range

mavenBundle().groupId("org.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).

Bundle start options

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

bundle should be started or not
```
mavenBundle().groupId("org.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
```
mavenBundle().groupId("org.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
```
mavenBundle().groupId("org.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 the start level of the bundle will be 10.

mavenWar

Containers: All Java EE and Web containers

Deploys a web archive from a Maven repository to the web container, optionally setting the application name or web context root.

mavenWar("org.ops4j.pax.exam.samples", "pax-exam-sample1-web", "3.0.0")
mavenWar("org.ops4j.pax.exam.samples", "pax-exam-sample1-web", "3.0.0").name("pax-exam-sample1").contextRoot("sample1")

propagateSystemProperty

Containers: Forked

Propagates the value of a system property set in the driver VM to the framework VM started by the container.
```
propagateSystemProperty("org.osgi.service.http.port")
```

Propagates multiple system properties

propagateSystemProperties("org.osgi.service.http.port", "org.osgi.service.http.port.secure")

provision

Containers: Native, Forked

Instead of using a URL, you can directly provision a bundle from an input stream. The stream content will be copied to the install area of the framework. This option is particularly useful in combination with Tinybundles.

provision a bundle from an input stream
```
provision(inputStream)
```

provision multiple bundles from input stream
```
provision(is1, is2, is3)
```

repositories

Containers: Forked

repository

Containers: Forked

streamBundle

Containers: Native, Forked

Provisions a bundle from an input stream
```
streamBundle(is)
```

systemPackage

Containers: Native, Forked

Adds a package name to the org.osgi.framework.system.packages framework property.
```
systemPackage("javax.rmi")
```

systemPackages

Containers: Native, Forked

Adds multiple package names to the org.osgi.framework.system.packages framework property.
```
systemPackages("javax.naming",
               "javax.rmi")
```

systemProperty

Containers: Native, Forked

Sets a system property in the framework VM. For the Forked Container, the property is set when the framework VM is started by the container. For the Native Container, this amounts to invoking System.setProperty() in the running VM, which may or may not have the same effect as a -Dkey=value VM argument for some properties defined in the JRE API.
```
systemProperty("org.osgi.service.http.port").value("8080")
```

many (one or more) system properties

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

systemTimeout

Containers: Native, Forked

Specifies a timeout in milliseconds which is used by Pax Exam when waiting for a service to become available or for the framework to reach the requested start level

systemTimeout(5000)

The default value is 3 minutes.

url

Containers: Native, Forked

A synonym for bundle().

vmOption

Containers: Forked

Specifies an argument passed to the Java VM spawned by Forked Container, e.g.

set the heap size
```
vmOption("-Xmx512M")
```

enable remote debugging

vmOption("-Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005")

vmOptions

Containers: Forked

set multiple VM options

vmOptions("-Xmx1G", "-XX:MaxPermSize=128M")

war

Containers: All Java EE and Web containers

Deploys a web archive to the web container, optionally setting the application name or web context root.

war("http://www.acme.com/demos/demo-1.0.war")
war("http://www.acme.com/demos/demo-1.0.war").name("acme-demo").contextRoot("preview")

warProbe

Containers: All Java EE and Web containers

Overrides Pax Exam's default conventions for constructing a WAR probe from the classpath, giving full control to the user. This option has a lot of arguments, which are documented on a separate page.

when

Containers: all

Enable a group of options only under specific conditions, e.g. to enable debugging only when a system property has a given value.

@Configuration
public static Option[] configure()
{
    return options(
        when( Boolean.getBoolean( "isDebugEnabled" ) ).useOptions(
            vmOption( "-Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005" ),
            timeout( 0 )));
}

In the above example the vmOption and timeout options will be included only when there is a system property named isDebugEnabled with a value of true.

If you are using Maven you can then use the following to switch the debug options on:

mvn install -DisDebugEnabled=true

The condition is not limited to just system properties. You can use any expression that evaluates to a boolean or define your own condition.

workingDirectory

Containers: Native, Forked

set the working directory for Pax Exam

workingDirectory("/home/hwellmann/pax-exam")

By default, Pax Exam will use a temporary directory created in ${java.io.tmpdir}.

wrappedBundle

Containers: Native, Forked

In some cases you may have a standard JAR that you may need to make 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

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 other provisioning option

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.

The wrappedBundle() option supports a number of additional arguments which are specified in fluent API syntax, e.g.

wrappedBundle(mavenBundle("javax.servlet", "servlet-api","2.5")
    .bundleSymbolicName("javax.servlet.api")
    .bundleVersion("2.5")

Arguments

specify the Bundle-SymbolicName of the wrapped bundle
```
bundleSymbolicName(String)
```

specify the Bundle-Version of the wrapped bundle
```
bundleVersion(String)
```

specify exported packages
```
exports(String...)
```

specify imported packages
```
imports(String...)
```

specify bnd instructions
```
instructions(String...)
```

Examples

wrappedBundle(mavenBundle("junit", "junit-dep", "4.8.1")).exports("*;version=4.8.1"));