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 theupdate()
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 theupdate()
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 bundlebundleSymbolicName(String)
specify the
Bundle-Version
of the wrapped bundlebundleVersion(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"));