I Often take a look at different projects in Apache or JBoss projects list to know about newly added projects and be informed about the latest updates. One of my favourite ones is Apache Karaf which makes life easier for developers working with OSGi. In this post I’ll try to explain the role that Karaf plays in OSGi world. So the reader has to have some basic knowledge about OSGi and its related technologies.
What is Apache Karaf?
As stated in project’s homepage:
Apache Karaf is a small OSGi based runtime which provides a lightweight container onto which various components and applications can be deployed
Apache Karaf is not another OSGi implementation, but acts like a wrapper on top of an already existing OSGi runtimes like Apache Felix or Eclipse Equinox. You can configure it to use one of these OSGi implementations as a basis. The Karaf offers some value added services on top these runtimes. Most of these services have been designed as OSGi bundles which are getting deployed on container when Apache Karaf starts. Features like central logging, manipulating configuration through commands, accessing OSGi runtime remotely using SSH, integration with OS and Apache Karaf’s extensible command shell are some of the most important capabilities that an OSGi application can benefit from.
What Does Apache Karaf Composed of?
The diagram below pictures the high level overview of the Apache Karaf and some of its main components. As you see, the OSGi container acts like a backbone and all other modules have arranged on top of that. Now let’s take a closer look at each block.
Apache Karaf from 10k feet
Deployer
The Deployer is one of the most important modules in Apache Karaf. It provides an extensible mechanism to retrieve bundles through different protocols and repositories to install them on underlying OSGi container. If you have ever tried to install bundles in an OSGi container directly, you know that in order to install your bundle, the main option would be through the file system (file:// protocol). When using Apache Karaf, thanks to different protocol handlers included by default, you can access bundles from different repositories like your Maven local repository. There is also a hot deployment option which enables you to just drop your bundle in deploy folder and let the Apache Karaf do the rest for you. Any changes to bundles deployed in this way will be detected and automatically applied. So it boosts your productivity in development phase.
The following diagram highlights the overall artifact deployment process. The deployment mechanism mainly constitutes of Handlers and Transformers. Handlers are responsible for accessing different repositories or URL schemes to retrieve an artifact from. Accessing an artifact in local maven repository is implemented as a maven handler implementation. In cases that an artifact (accessed through Handler) is not actually an OSGi bundle, Transformers may be used. Transformers (as their name implies) enables Apache Karaf to transform an artifact to a bundle on the fly. There is already transformers for artifacts like Blueprint XML files, Spring dm configuration files, WAR files or even ordinary JAR files.
Artifact Deployment Process
The provisioning in OSGi world is the process of locating and downloading bundles required to run an application. In Apache Karaf, there is a concept named Feature that could be used to define an application. It’s simply a descriptor (in XML) that specifies a collection of bundles that have to be installed together. When you install a Feature in Apache Karaf, it tries to provision all bundles specified in it and installs them on the OSGi container. This way, an application could be defined as a Feature referring all its bundles and also bundles they depend on. The provisioning mechanism provided by Apache Karaf doesn’t detect bundle’s dependencies. So you have to specify all the dependencies of your application when preparing its Feature XML file.
Features can also be nested. This way, you can for example define dependencies of your application as a separate Feature and include it in the main one. Some third party frameworks like Eclipse RAP, Apache Camel or Apache ActiveMQ have already defined their required bundles as a Feature XML file that could be used to include their services in any application at runtime. Usually installing a Feature is a two step process. At first the Feature XML (which could be a collection of Feature definitions) has to be introduced to Apache Karaf and then each item defined in it could be installed separately. In Apache Karaf vocabulary, when you add a new feature XML file, you’re actually defining a new repository which could be used to search for when you’re trying to install a new feature. The provisioning process heavily depends on the deployer services mentioned above. The sample XML below, defines a feature named my_feature consisting three bundles.
<features>
<feature name='my_feature' version='1.0'>
<bundle>mvn:project_group_id/bundle1/1.0.0/bundle1-1.0.0</bundle>
<bundle>mvn:project_group_id/bundle2/1.1.0/bundle2-1.1.0</bundle>
<bundle>mvn:project_group_id/bundle3/1.0.0/bundle3-1.0.0</bundle>
</feature>
</features>
Apache Karaf also introduced a new archive format named KAR or Karaf Archive file. It’s a jar file containing a set of Feature XML files and required bundles as jar files. The Deployer service can process a KAR file and base on information provided in Feature XML files, tries to deploy requested bundles (including those embedded into KAR file). This way an application could be packaged in a single KAR file and distributed more easily.
Admin
Apache Karaf administration features enables a user to instantiate multiple instances of Karaf that work beside each other smoothly. Having multiple instances enables you to achieve high availability, fail over and similar non functional requirements. The administration services enable you to start, stop, create new instance or even delete it. It also let you access instances remotely using SSH protocol, so you can connect to an instance from anywhere using a SSH client. There is also a special client utility provided as an administration tool by Apache Karaf to connect to an already running instance (local or remote). When you have access to Apache Karaf console, using client utility or through SSH, you can issue any command just like when you’re using its console locally.
Logging
The OSGi compendium specification defines a basic logging service to be implemented by OSGi containers. The Pax Logging project is an implementation of OSGi log service (as a bundle) with some added features and supports most of well known logging APIs like Log4J, Apache Commons Logging API, JDK Logging API, SLF4J, etc. The Apache Karaf uses Pax Logging as basis to provide higher level logging facilities required by most enterprise applications. It redirects all logging output to a single file and provides some basic console commands to access last logged messages and exceptions or change the log level at runtime.
Security
The security service provided by Apache Karaf is primarily based on JAAS. The authentication mechanism mainly applied when trying to access Apache Karaf by SSH console, JMX Management layer or Web console. The default authentication process is done through checking a property file named users.properties in {karaf_home}/etc folder which contains list of users, passwords and user roles. There is also some other LoginModule implementation embedded with Apache Karaf, including JDBCLoginModule which authenticates users by querying a database, PublicKeyLoginModule which provides authentication process using certificates, LDAPLoginModule which authenticates users by asking a LDAP server and OSGIConfigLoginModule that uses configuration service of OSGi to access list of users, passwords and roles.
Configuration
As specified in compendium specification of OSGi, a Configuration Admin service is responsible to store bundle configurations and give them back to services who need them. Apache Karaf provides some console commands which let you access these configuration at runtime and manipulate them. Configurations are stored as simple property files in {karaf_home}/etc folder with .cfg extension and its contents could be altered directly.
Console
Apache Karaf console acts as the main interaction mechanism between user and the system. Almost all services mentioned above could be controlled by commands provided through the console. Thanks to extendability mechanism provided by Apache Karaf, every bundle can add its own commands to the console. This way, you can interact with your bundle through console and manipulate its behaviour in runtime. For example, the logging service provides commands like log:display to display the latest logs or log:set to set the logging level of Apache Karaf.
Who’s using Apache Karaf?
Apache Karaf had started as Apache ServiceMix kernel and after a while became subproject of Apache Felix. Now it’s a top level project in Apache. It’s currently being used as container for Red Hat JBoss Fuse (named Fuse ESB before FuseSource becomes a part of Red Hat). It’s a well known ESB in open source community. Also Talend, has an ESB product based on Apache Karaf. Its developers are active contributors of Apache projects like ServiceMix, CXF, Camel and Karaf. They have developed a polished ecosystem on top of these Apache projects.
What’s next?
There is a lot to explain about Apache Karaf features and how to use its full capabilities. I’ll try to cover them as step by step tutorials in upcoming posts.
