Apache Karaf environment and Assembly

Introduction

The OSGI environment in the Platform is provided by Apache Karaf, a powerful Application Framework built on-top of bare OSGI. This page details how we build our customized Karaf Assembly, where it lives in the product and how to add features to it in the proper way.

Karaf Assembly

Karaf has a default distribution available which has some basic functionality configured out-of-the-box. We add our customizations to the default assembly through two Maven Assembly projects: pentaho-karaf-assembly and pentaho-karaf-ee-assembly. Both are variants of the Karaf Custom Distribution documented here: Karaf Custom Distribution. The execution overview of both projects is the same:

Download the standard Karaf assembly
Overlay customized configuration files
Pre-populate the /system maven repository with bundles required by the default feature set
Package the result

Both assemblies actually perform two runs each, one for the BA/DI Server which is classified as "-server", and another intended for inclusion in non-server environments (Spoon, etc.) classified as "-client". They differ primarily in which features are installed by default.

pentaho-karaf-assembly

The pentaho-karaf-assembly project contains the Karaf assembly as well as two submodules, pentaho-blueprint-activators and pentaho-karaf-features.

pentaho-karaf-features contains the Pentaho Karaf Feature files for Open (standard) and EE (enterprise). Each feature file is published with it's own classifier pentaho-karaf-features-[classifier].

pentaho-blueprint-activators contains OSGI Blueprint files with activation bean definitions. These are referenced by Pentaho features and are intended to bootstrap the feature environment. Each file is published with it's own classifier such that the artifact is pentaho-blueprint-activators-[classifier]. Add activators as needed to support your features. However, if the feature contains a Pentaho Bundle which can house the activator file, please do so rather than adding it here.

The main assembly builds the features and activators modules first.

pentaho-karaf-ee-assembly

The Enterprise assembly builds upon the pentaho-karaf-assembly, overlaying some configuration files and installing enterprise features by default. It also produces two classified artifacts: client and server.

Adding Features

You should not have to add more feature files, rather add to one of the two existing files (standard and enterprise). If your feature needs to be activated by default, you'll need to modify the assembly pom.xml files so that the bundles are downloaded and added to the /system repo by the assembly. This ensures they're available without Karaf having to go out to public maven repos to fine them.

Locate the features-maven-plugin plugin section, note there's one for client and another for server.
If you're adding a feature from a new feature file (not one of the standard Karaf or Pentaho ones), locate the <descriptors> section and add a <descriptor> for the feature file you're using.
Find the <features> section, it should be right below the <descriptors>. Add a new <feature> child node for each feature you want installed by default.
Open the features configuration file for client or server pentaho-karaf-assembly/src/main/filtered-resources/etc-[server|client]/org.apache.karaf.features.cfg
Add your new features xml file to featuresRepositories.
Add your features to featuresBoot.

Importing System Packages

The OSGI Container is both Server and Client setups is running embedded inside a non-OSGI environment (Pentaho Platform, PDI). There are times when bundles within the OSGI environment need to reference classes from these outside environments. This access can be allowed by adding the package names containing these classes to a list which is "imported" into OSGI. To add to this list modify the pentaho-karaf-assembly/src/main/filtered-resources/etc/custom.properties file and add your package to the *org.osgi.framework.system.packages.extra *setting

BA and DI Servers

Both servers unpack the Karaf assembly to pentaho-solutions/system/karaf.

Clients (Spoon)

Karaf is embedded within a Kettle Plugin at plugins/pdi-osgi-bridge/karaf

http://ci.pentaho.com/job/pentaho-karaf-ee-assembly/

Pentaho Engineering