5.4.1. Pax Runner - Platform - Extender

Overview

The platform extender tracks registration of platform builders. Once such a platform builder gets registred will install a new platform service corresponding to the platform builder. If a platform builder is unregistered will unregister the corresponding platform.
Distinction between the platforms can be done by using a filter while resolving the platform, filter based on the following platform properties:

  • provider: the platform provider; expect something as equinox, felix or knopflerfish
  • version: the platform version; dependes on the platfoem provider version.
    Onec you have a platform you can start it up via the start method with your bundles, properties and specific configuration options. Look to Javadoc for details.
Examples
  • Get any platform
    bundleContext.getServiceReference( Platform.class.getName() );
    
  • Get a felix platform
    bundleContext.getServiceReference( Platform.class.getName(), "(provider=felix)" );
    
  • Get a felix platform with a specific version
    bundleContext.getServiceReference( Platform.class.getName(), "&(provider=felix)(version=1.0.0)" );
    

Platform Definition file

The platform definition file is an xml file file that is used to define the parts that makes up the platform.
The file has the following syntax:

<platform>
  <name>system_package_name</name>
  <system>system_package_url<system>
  <packages>system_packages_list</packages>
  <profile name="profile_name" default="true/false" [extends="parent_profile_name"]>
    <bundle>
      <name>bundle_name</name>
      <url>bundle_url</url>
    </bundle>
    ...
  </profiles>
</platform>

where:

  • system_package_name : a nice name for the system package; optional (if not set the url is used as name)
  • system_package_url : the url of the system package
  • system_packages_list : optional; a comma separated list of packages to be appended to system packages
  • profile_name : name of the profile
  • default : one of the profiles should be marked as default. This is the profile to be used if no other profile is specified.
  • parent_profile_name : name of the profile that is extended by this profile. Is optional and facilitates reuse
  • bundle_name : a nice name for the bundle; optional (if not set the url is used as name)
  • bundle_url : url of the bundle that makes up the profile. There can be more bundles in a profile.

To validate a definition file you could use the following XSD: TODO

Profiles

Profiles are a set of predefined set of bundles for a particular common usage scope. Such profiles could be minimal (default profile), logging, configuration, web,...
Every platform supports it's own set of profiles in platform specific way = using as much as possible platform specific bundles to archieve the intent of profile.
Each platform supports a default profile, profile that will be used when no profile option is specified. Checkout the platforms for a list of supported profiles.
The list of profiles to use can be specified via a configuration option (see bellow).

Configuration

The service can be configured in three ways, each having precedence over th other in the order thay are enumerated: via properties used when starting up the platform, via configuration admin if available and via framework/system properties.

Option key

Description

org.ops4j.pax.runner.platform.bootDelegation

optional; same as setting system property org.osgi.framework.bootdelegation. Read about in the core OSGi spcs.
Since 0.8.0.

org.ops4j.pax.runner.platform.bundleStartLevel

optional; the start level at which the installed bundles will be started. Default value is "5". Note that this apply only to those installed bundles that do not have a custom set start level. See different scanners for details.

org.ops4j.pax.runner.platform.classpath

optional; a File.pathSeparator separated list of classpath entries to be appended to the framework classpath which consists out of the framework system jar.

org.ops4j.pax.runner.platform.clean

optional; use this option to the working directory removed prior starting the platform.

org.ops4j.pax.runner.platform.console

optional; true/false; whether the platform console should be started. Default value is "true".

org.ops4j.pax.runner.platform.debugClassLoading

optional; use this option to enable platform class loader logs. Supported on Equinox only as org.eclipse.osgi/debug/loader=true in debug .options file. Default value is "false".

org.ops4j.pax.runner.platform.downloadFeedback

optional; use this option to enable / supress extensive download progress information on downloaded bundles. Default value is "true".

org.ops4j.pax.runner.platform.definitionURL

optional; url to the xml file containing the #definition of the platform (system bundle, profiles).

org.ops4j.pax.runner.platform.ee

optional; the targeted execution environment = ee (ops4j:see list bellow for possible values. If the option is pecified and does not map to one of the names bellow then the provided value is considered an URL to a text based file that contains the packages to be used during execution. The packages must be specified as one package per line.
Default the execution environment is determined based on the jdk version version runner is working on.
Note that the nave of the execution environment is not case sensitive.

org.ops4j.pax.runner.platform.frameworkProfile

optional; name of the framework profile to use. Note that currently only Felix supports profiles. Default value "runner".

org.ops4j.pax.runner.platform.javaHome

optional; the home for the version specified above. If no version was specified then first the value of system property "JAVA_HOME" is used. If that is not set then teh value of system property "java.home" will be used (=same with the home in which runner is running).

org.ops4j.pax.runner.platform.overwrite

optional; use this option to force overwrite the content of the bundles, Default will not be over written.

org.ops4j.pax.runner.platform.overwriteUserBundles

optional; use this option to force overwrite the content of the user bundles = bundles that are suplied by the user via scanners. Default user bundles will not be overwritten.
The overwrite option above has priority over this option.

org.ops4j.pax.runner.platform.overwriteSystemBundles

optional; use this option to force overwrite the content of the system bundles = bundles that are making up the target bundles. Default system bundles will not be overwritten.
The overwrite option above has priority over this option.

org.ops4j.pax.runner.platform.profiles

optional; a comma separated list of profiles to be used. if not set the default profile form definition it will be used. See #profiles section for details.

org.ops4j.pax.runner.platform.profileStartLevel

optional; the start level at which the platform bundles from the selected profiles will be started. Default value is "1".

org.ops4j.pax.runner.platform.startLevel

optional; the platform start level. Default value is "6".

org.ops4j.pax.runner.platform.systemPackages

optional; a comma separated list of packages that should be exported by the framework bundles, in addition to the standard packages list. The standard packages list depends on the ee option (see above).

org.ops4j.pax.runner.platform.usePersistedState

optional; true/false; whether the platform should use the persisted state from a previous run. Default value is false = the platform will be will not reuse the persisted state.

org.ops4j.pax.runner.platform.vmOptions

optional; virtual machine options to be used for the VM that will be started for the platform. Note that the -cp vm machine option is not supported here as the platform starter makes use of this option. If you need the -cp option you will have to use the classpath option described above.

org.ops4j.pax.runner.platform.workingDirectory

optional; a file path where the platform specific artifacts will be stored. Default value "runner".

Execution Environments

Name

Description

(tick)
NONE

No aditional packages. Only the boot delegation will be used in this case (java.*)

(tick)
CDC-1  .0/Foundation-1.0

Equal to J2ME Foundation Profile

(tick)
OSGi/Minimum-1.1

OSGi EE that is a minimal set that allows the implementation of an OSGi Framework

(warning)
JRE-1  .1

Java 1.1.x

(warning)
J2SE-1.2

Java 2 SE 1.2.x

(tick)
J2SE-1.3

Java 2 SE 1.3.x

(tick)
J2SE-1.4

Java 2 SE 1.4.x

(tick)
J2SE-1.5

Java 2 SE 1.5.x

(tick)
JavaSE-1.6

Java SE 1.6.x

(warning)
PersonalJava-1.1

Personal Java 1.1

(warning)
PersonalJava-1.2

Personal Java 1.2

(warning)
CDC-1  .0/PersonalBasis-1.0

J2ME Personal Basis Profile

(warning)
CDC-1  .0/PersonalJava-1.0

J2ME Personal Java Profile