The OSGi container

The OSGi container provides a set of additional features on top of the OSGi framework, as shown in the following diagram:

Apache Karaf provides the following features:

• It provides the abstraction of the OSGi framework. If you write an OSGi application, you have to package your application tightly coupled with the OSGi framework (such as the Apache Felix framework or Eclipse Equinox). Most of the time, you have to prepare the scripts, configuration files, and so on in order to provide a complete, ready-to-use application. Apache Karaf allows you to focus only on your application. Karaf, by default, provides the packaging (including scripts and so on), and it also abstracts the OSGi framework. Thanks to Karaf, it's very easy to switch from Apache Felix (the default framework in Karaf) to Eclipse Equinox.
• Provides support for the OSGi Blueprint and Spring frameworks. Apache Karaf allows you to directly use Blueprint or Spring as the dependency framework in your bundles. In the new version of Karaf (starting from Karaf 3.0.1), it also supports new dependency frameworks (such as DS, CDI, and so on).
• Apache Karaf provides a complete, Unix-like shell console where you have a lot of commands available to manage and monitor your running container. This shell console works on any system supporting Java and provides a complete Unix-like environment, including completion, contextual help, key bindings, and more. You can access the shell console using SSH. Apache Karaf also provides a complete management layer (using JMX) that is remotely accessible, which means you can perform the same actions as you do using the shell commands with several MBeans.
• In addition to the default root Apache Karaf container, for convenience, Apache Karaf allows you to manage multiple container instances. Apache Karaf provides dedicated commands and MBeans to create the instances, control the instances, and so on.
• Logging is a key layer for any kind of software container. Apache Karaf provides a powerful and very dynamic logging system powered by Pax Logging. In your OSGi application, you are not coupled to a specific logging framework; you can use the framework of your choice (slf4j, log4j, logback, commons-logging, and so on). Apache Karaf uses a central configuration file irrespective of the logging frameworks in use. All changes in this configuration file are made on the fly; no need to restart anything. Again, Apache Karaf provides commands and MBeans dedicated to log management (changing the log level, direct display of the log in the shell console, and so on).
• Hot deployment is also an interesting feature provided by Apache Karaf. By default, the container monitors a deploy folder periodically. When a new file is dropped in the deploy folder, Apache Karaf checks the file type and delegates the deployment logic for this file to a deployer. Apache Karaf provides different deployers by default (spring, blueprint, features, war, and so on).
• If Java Authentication and Authorization Service (JAAS) is the Java implementation of Pluggable Authentication Modules (PAM), it's not very OSGi compliant by default. Apache Karaf leverages JAAS, exposing realm and login modules as OSGi services. Again, Apache Karaf provides dedicated JAAS shell commands and MBeans. The security framework is very flexible, allowing you to define the chain of login modules that you want for authentication. By default, Apache Karaf uses a PropertiesLoginModule using the etc/users.properties file for storage. The security framework also provides support for password encryption (you just have to enable encryption in the etc/org.apache.karaf.jaas.cfg configuration file). The new Apache Karaf version (3.0.0) also provides a complete Role Based Access Control (RBAC) system, allowing you to configure the users who can run commands, call MBeans, and so on.
• Apache Karaf is an enterprise-ready container and provides features dedicated to enterprise. The following enterprise features are not installed by default (to minimize the size and footprint of the container by default), but a simple command allows you to extend the container with enterprise functionalities:
  • WebContainer allows you to deploy a Web Application Bundle (WAB) or WAR file. Apache Karaf is a complete HTTP server with JSP/servlet support, thanks to Pax Web.
  • Java Naming and Directory Interface (JNDI) adds naming context support in Apache Karaf. You can bind an OSGi service to a JNDI name and look up these services using the name, thanks to Aries and Xbean naming.
  • Java Transaction API (JTA) allows you to add a transaction engine (exposed as an OSGi service) in Apache Karaf, thanks to Aries JTA.
  • Java Persistence API (JPA) allows you to add a persistence adapter (exposed as an OSGi service) in Apache Karaf, thanks to Aries JPA. Ready-to-use persistence engines can also be installed very easily (especially Apache OpenJPA and Hibernate).
  • Java Database Connectivity (JDBC) or Java Message Service (JMS) are convenient features, allowing you to easily create JDBC DataSources or JMS ConnectionFactories and use them directly in the shell console.
• If you can completely administrate Apache Karaf using the shell commands and the JMX MBeans, you can also install Web Console. This Web Console uses the Felix Web Console and allows you to manage Karaf with a simple browser.

Thanks to these features, Apache Karaf is a complete, rich, and enterprise-ready container. We can consider Apache Karaf as an OSGi application server.

Provisioning in Apache Karaf

In addition, Apache Karaf provides three core functionalities that can be used both internally in Apache Karaf or can be used by external applications deployed in the container:

• OSGi bundle management
• Configuration management
• Provisioning using Karaf Features

As we learned earlier, the default artifact in OSGi is the bundle. Again, it's a regular JAR file with additional OSGi metadata in the MANIFEST file. The bundles are directly managed by the OSGi framework, but for convenience, Apache Karaf wraps the usage of bundles in specific commands and MBeans.

A bundle has a specific life cycle. Especially when you install a bundle, the OSGi framework tries to resolve all the dependencies required by your bundle to promote it in a resolved state. The following is the life cycle of a bundle:

The OSGi framework checks whether other bundles provide the packages imported by your bundle. The equivalent action for the OSGi services is performed when you start your bundle. It means that a bundle may require a lot of other bundles to start and so on for the transitive bundles.

Moreover, a bundle may require configuration to work. Apache Karaf proposes a very convenient way to manage the configurations. The etc folder is periodically monitored to discover new configuration files and load the corresponding configurations. On the other hand, you have dedicated shell commands and MBeans to manage configurations (and configuration files). If a bundle requires a configuration to work, you first have to create a configuration file in the etc folder (with the expected filename) or use the config:* shell command or ConfigMBean to create the configuration.

Considering that an OSGi application is a set of bundles, the installation of an OSGi application can be long and painful by hand.

The deployment of an OSGi application is called provisioning as it gathers the following:

• The installation of a set of bundles, including transitive bundles
• The installation of a set of configurations required by these bundles

OBR

OSGi Bundle Repository (OBR) can be the first option to be considered in order to solve this problem. Apache Karaf can connect to the OBR server. The OBR server stores all the metadata for all the bundles, which includes the capabilities, packages, and services provided by a bundle and the requirements, packages, and services needed by a bundle. When you install a bundle via OBR, the OBR server checks the requirement of the installed bundle and finds the bundles that provide the capabilities matching the requirements. The OBR server can automatically install the bundles required for the first one.

Apache Karaf Features

As a lightweight and standalone OSGi container, Apache Karaf proposes another way to provision applications. Apache Karaf Features is the default provisioning solution in Apache Karaf.

Karaf Features describes an application, declaring the following aspects:

• The bundles in the application
• Other Karaf features required by the application
• Configurations required by the application

A Karaf Feature repository is a simple XML file describing a set of Karaf features. A Karaf Feature repository looks like the following:

<features name="my-features">

  <feature name="core-feature" version="1.0">
    <bundle>mvn:bundleA_groupId/bundleA_artifactId/bundleA_version</bundle>
    <bundle>file:/path/to/bundleB</bundle>
    <bundle>http://path/to/bundleC</bundle>
  </feature>

  <feature name="extend-feature" version="1.0">
    <feature version="[1,2)">core-feature</feature>
    <bundle>mvn:bundleD_groupId/bundleD_artifactId/bundleD_version</bundle>
   <config name="my.configuration.pid">
      key1=value1
     key2=value2
   </config>
  </feature>

  <feature name="other-feature" version="1.1">
    <feature version="[1,2)">core-feature</feature>
    <bundle>mvn:bundleE_groupId/bundleE_artifactId/bundleE_version</bundle>
    <configfile finalname="/etc/my.configuration.cfg">
    http://path/to/file/my.cfg
   </configfile>
  </feature>

</features>

Note that Apache Karaf supports different types of URLs, as follows:

• A file URL allows you to install a bundle or a configuration file located in the local filesystem.
• An HTTP URL allows you to download and install a bundle or a configuration file located on an HTTP server.
• An Mvn URL allows you to directly use Maven repositories. The URL uses the Maven information (groupId/artifactId/version/classifier/type) and converts this URL to an HTTP URL relative to different repositories (described in etc/org.ops4j.pax.url.mvn.cfg).

This gives us a very flexible way to get the artifacts required for the application. The artifacts can be local or remote, on a pure HTTP server or on a Maven repository manager (such as Apache Archiva, Nexus, or even Maven Central).

Karaf Features completely describes applications and eventually dependencies between applications and the required configuration. In our example, we can note the following:

• The core-feature feature installs bundle A, bundle B, and bundle C using different protocols: local filesystem for bundle A, downloading from an HTTP server for bundle B, and using Maven for bundle C (from a Maven repository).
• The extend-feature feature requires core-feature. This means that if core-feature is not already installed, Apache Karaf will install it first. Once core-feature is installed, bundle D will be installed (and started) from a Maven repository. This feature also creates a configuration with the my.configuration.pid ID and populates this configuration with the key-value pairs directly defined in the element.
• The other-feature feature also requires core-feature (as for extend-feature, core-feature will be installed if it's not already the case). Bundle E will be installed and started using Maven (from a Maven repository). The other-feature feature will also create a configuration, but this time using a base configuration file installed in the etc folder of Apache Karaf. The configuration file is downloaded using one URL supported by Apache Karaf (in this example, an HTTP URL is used).

Thanks to Karaf Features, provisioning is pretty easy and straightforward.

The first action consists of registering the Karaf Features repository in the container using the features:addurl shell command (or the corresponding operation on FeaturesMBean). Once done, you can see the list of Karaf features available using the features:list command.

To install an OSGi application, just install the corresponding Karaf feature with features:install.