Getting StartedWith this post I am beginning a series of posts about Apache Karaf. So what is Karaf and why should you be interested in it? Karaf is an OSGi container based on Equinox or Felix. The main difference to these fine containers is that it brings excellent management features with it.
Outstanding features of Karaf:
- Extensible Console with Bash like completion features
- ssh console
- deployment of bundles and features from maven repositories
- easy creation of new instances from command line
All together these features make developing server based OSGi applications almost as easy as regular java applications. Deployment and management is on a level that is much better than all applications servers I have seen till now. All this is combined with a small footprint as well of karaf as the resulting applications. In my opinion this allows a light weight development style like JEE 6 together with the flexibility of spring applications.
Installation and first startup
- Download Karaf 3.0.3 from the Karaf web site.
- Extract and start with bin/karaf
You should see the welcome screen:
Some handy commands
|Shows all installed bundles|
|Shows the active OSGi services. This list is quite long. Here it is quite handy that you can use unix pipes like "ls | grep admin"|
|Shows exported packages and bundles providing them. This helps to find out where a package may come from.|
|Shows which features are installed and can be installed.|
Install features (a list of bundles and other features). Using the above command we install the Karaf webconsole.
It can be reached at http://localhost:8181/system/console . Log in with karaf/karaf and take some time to see what it has to offer.
|log:tail||Show the log. Use ctrl-c to go back to Console|
|Ctrl-d||Exit the console. If this is the main console karaf will also be stopped.|
Tasklist - A small osgi application
Without any useful application Karaf is a nice but useless container. So let´s create our first application. The good news is that creating an OSGi application is quite easy and
maven can help a lot. The difference to a normal maven project is quite small. To write the application I recommend to use Eclipse 4 with the m2eclipse plugin which is installed by default on current versions.
Get the source code
- Clone the example using git clone firstname.lastname@example.org:cschneider/Karaf-Tutorial.git
- download the sample project from https://github.com/cschneider/Karaf-Tutorial/zipball/master and extract to a directory
Import into Eclipse
- Start Eclipse
- In Eclipse Package explorer: Import -> Existing maven project -> Browse to the extracted directory into the tasklist sub dir
- Eclipse will show all maven projects it finds
- Click through to import with defaults
Eclipse will now import the projects and wire all dependencies using m2eclipse.
The tasklist example consists of three projects
|tasklist-model||Service interface and Task class|
|tasklist-persistence||Simple persistence implementation that offers a TaskService|
|tasklist-ui||Servlet that displays the tasklist using a TaskService|
|tasklist-features||Features descriptor for the application that makes installing in Karaf very easy|
This project contains the domain model and the service implementation. The model is the Task class and a TaskService interface. The persistence implementation TaskServiceImpl manages tasks in a simple HashMap.
The TaskService is published as an OSGi service using a blueprint context. Blueprint is an OSGi standard for dependency injection and is very similar to a spring context.
The bean tag creates a single instance of the TaskServiceImpl. The service tag publishes this instance as an OSGi service with the TaskService interface.
The pom.xml is of packaging bundle and the maven-bundle-plugin creates the jar with an OSGi Manifest. By default the plugin imports all packages that are imported in java files or referenced in the blueprint context.
It also exports all packages that do not contain the string impl or internal. In our case we want the model package to be imported but not the persistence.impl package. As the naming convention is used
we need no additional configuration.
The ui project contains a small servlet TaskServlet to display the tasklist and individual tasks. To work with the tasks the servlet needs the TaskService.
To inject the TaskService and to publish the servlet the following blueprint context is used:
The reference tag makes blueprint search and eventually wait for a service that implements the TaskService interface and creates a bean "taskService".
The bean taskServlet instantiates the servlet class and injects the taskService. The service tag publishes the servlet as an OSGi service with the HttpServlet interface and sets a property alias.
This way of publishing a servlet is not yet standardized but is supported by the pax web whiteboard extender. This extender registers each service with interface HttpServlet with the OSGi http service. It uses the alias
property to set the path where the servlet is available.
The last project only installs a feature descriptor to the maven repository so we can install it easily in Karaf. The descriptor defines a feature named tasklist and the bundles to be installed from
the maven repository.
A feature can consist of other features that also should be installed and bundles to be installed. The bundles typically use mvn urls. This means they are loaded from the configured maven repositories or your local maven repositiory in ~/.m2/repository.
Installing the Application in Karaf
Add the features descriptor to Karaf so it is added to the available features, then Install and start the tasklist feature. After this command the tasklist application should run
Check that all bundles of tasklist are active. If not try to start them and check the log.
Should show the TaskListServlet. By default the example will start at http://localhost:8181/tasklist .
You can change the port by creating aa text file in "etc/org.ops4j.pax.web.cfg" with the content "org.osgi.service.http.port=8080". This will tell the HttpService to use the port 8080. Now the tasklist application should be available at http://localhost:8080/tasklist
In this tutorial we have installed Karaf and learned some commands. Then we created a small OSGi application that shows servlets, OSGi services, blueprint and the whiteboard pattern.
In the next tutorial we take a look at using Apache Camel and Apache CXF on OSGi.
Back to Karaf Tutorials