OPS4J
  Platform - Extender
 Browse Space
Added by Alin Dreghiciu, last edited by Alin Dreghiciu on Mar 06, 2008  (view change)

Labels

 

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 filer 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 (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 Environemnts
Name Description
NONE No aditional packages. Only the boot delegation will be used in this case (java.*)
CDC-1.0/Foundation-1.0 Equal to J2ME Foundation Profile
OSGi/Minimum-1.1 OSGi EE that is a minimal set that allows the implementation of an OSGi Framework
JRE-1.1 Java 1.1.x
J2SE-1.2 Java 2 SE 1.2.x
J2SE-1.3 Java 2 SE 1.3.x
J2SE-1.4 Java 2 SE 1.4.x
J2SE-1.5 Java 2 SE 1.5.x
JavaSE-1.6 Java SE 1.6.x
PersonalJava-1.1 Personal Java 1.1
PersonalJava-1.2 Personal Java 1.2
CDC-1.0/PersonalBasis-1.0 J2ME Personal Basis Profile
CDC-1.0/PersonalJava-1.0 J2ME Personal Java Profile

Installation guide

This bundle is part of Pax Runner so if you are using pax runner you have nothing more to do about.
If you wanna use the bundle as a standalone bundle you could install it using the following methods:

Manual installation
Pax Runner installation

pax-run mvn:org.ops4j.pax.runner/pax-runner-platform

Source code

https://scm.ops4j.org/repos/ops4j/projects/pax/runner/pax-runner-platform ( or browse via FishEye )
This project builds with Apache Maven and uses Apache Felix's maven-bundle-plugin, and Peter Krien's bnd tool.

See also

Pax URL - classpath — classpath: protocol handler. Provides access to classpath resources from your bundle or other bundles installed.
Pax URL - ivy — ivy: protocol handler. Provides access to Ivy artifacts. (not implemented yet)
Pax URL - mvn — mvn: protocol handler. Provide access to maven repository artifacts based on the well known groupId, artifactId, version and type
PAX URL - obr — obr: protocol handler. Make use of OBR bundle repository.
Pax URL - war — war:/war-i: protocol handlers. Automates war deployment.
Pax URL - wrap — wrap: protocol handler. Wraps "classic" jars as OSGi bundles.
Platform - Concierge — Starts up Concierge OSGi framework
Platform - Equinox — Starts up Equinox OSGI framework
Platform - Extender — Installs platform services based via a whiteboard pattern
Platform - Felix — Starts up Felix OSGi framework
Platform - Knopflerfish — Starts up Knopflerfish OSGi framework
Scanner - Bundle — Installs a bundle specified as url.
Scanner - Directory — Install bundles available in a file system directory or zip
Scanner - File — Install bundles listed in a plain text file
Scanner - Maven 2 POM — Installs bundles listed as dependencies in a maven 2 pom.xml file
Scanner - OBR — Resolves and installs bundles references listed in a plain text file