OSGi server tutorial

Table of contents

1. Install Eclipse IDE plug-ins
2. Create a new project
3. Add the Jetty bundle
4. Add a servlet as service component
5. Configure Jetty to serve HTTPs via Configuration Admin

This OSGi tutorial shows how to build a server serving HTTP and HTTPs requests using the Eclipse IDE, the Bndtools OSGi tooling for Eclipse and the OSGi implementation Apache Felix.

1. Install Eclipse IDE plug-ins

Get the latest Eclipse IDE for Java Developers. Install the Bndtools Eclipse plug-ins using Help > Eclipse Marketplace:

OSGi tutorial: Install Bndtools using the marketplace

2. Create a new project

Create a new OSGi bundle project using File > New > Other > OSGi > Bnd OSGi project:

OSGi tutorial: Create Bnd project

The first time you create such a project, Bndtools asks about the cnf configuration project. This project stores a repository with all external project dependencies and global build configuration. So choose to create one:

OSGi tutorial: Create cnf configuration project

Name the project something like com.example.helloworld, pick Component Development (Declarative Services) as default template and keep all the other settings as they are.

You will have two projects now, the bundle project and the cnf project. The bundle project contains the build configuration file bnd.bnd for your project. The MANIFEST.MF will be created automatically from this configuration:

OSGi tutorial: bnd.bnd file and editor

You can also run the OSGi container from the bnd.bnd file.

3. Add the Jetty bundle

Let’s add the org.apache.felix.http.jetty bundle to the list of bundles to run and run the bundle:

OSGi tutorial: Run bundle with Bndtools

This will start up Felix with Jetty serving Http requests:

-> [INFO] Started jetty 6.1.x at port 8080
ps
START LEVEL 1
   ID   State         Level  Name
[   0] [Active     ] [    0] System Bundle (3.0.4)
[   1] [Active     ] [    1] Apache Felix Shell TUI (1.4.1)
[   2] [Active     ] [    1] Apache Felix Declarative Services (1.4.0)
[   3] [Active     ] [    1] Apache Felix Shell Service (1.4.2)
[   4] [Active     ] [    1] com.example.helloworld (0)
[   5] [Active     ] [    1] osgi.cmpn (4.2.1.201001051203)
[   6] [Active     ] [    1] Apache Felix Http Jetty (2.0.4)
->

4. Add a servlet as service component

To use the Servlet class, add a build dependency to the http bundle:

OSGi tutorial: Add build dependency

The Apache Felix HTTP Service Whiteboard bundle makes it very easy to publish Servlets using OSGi services. So download the HTTP Service Whiteboard bundle jar from the Felix Download page and install it into your bundle repository by dragging the jar to the Bndtools Repositories view. Also add it to the list of bundles to run:

OSGi tutorial: Add the whiteboard bundle jar

Create a servlet class and annotate it with Bnd’s @Component annotation to make the servlet a declarative service component (Bnd will generate the configuration.xml for the DS component automatically):

package com.example.helloworld;

import java.io.IOException;

import javax.servlet.*;
import javax.servlet.http.*;

import aQute.bnd.annotation.component.Component;

@Component(provide=Servlet.class, properties = { "alias=/" })
public class HelloWorldServlet extends HttpServlet {

    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp)
            throws ServletException, IOException {
        resp.getWriter().append("Hello World!");
    }

}

Add the newly created package to the list of private packages to make Bnd putting the classes in the resulting bundle jar:

OSGi tutorial: Add private package

Add * as service component. This will make Bnd scan for all classes annotated with @Component and create the configuration xml automatically (ignore the warning that will appear):

OSGi tutorial: Add service component

Run the server again and open http://localhost:8080 in your browser:

OSGi tutorial: Page in browser

The bundle jar is automatically built and deployed when classes are changed. So try to change the servlet, save and reload the page. You should see your changes without restarting the server.

5. Configure Jetty to serve HTTPs via Configuration Admin

Let’s allow encrypted HTTPs connections to our server. Jetty and the Felix-Jetty integration bundle org.apache.felix.http.jetty support secure HTTPS connections out of the box. We only need to enable the Jetty SSL connector using these configuration properties:

org.osgi.service.http.port.secure (by default 443)
org.apache.felix.https.enable (by default false)
org.apache.felix.https.keystore
org.apache.felix.https.keystore.password

Configuration Admin

To configure these properties we can use the OSGi Configuration Admin service. Configuration Admin is an OSGi component that provides a straightforward mechanism to configure components and services.

To configure a service (a ”managed service” to be exact), we need to know its PID. You can look these up in the Services tab of the Felix Web Console. The PID for the http service is org.apache.felix.http:

OSGi tutorial: PID of the http service

Configuration Admin merely provides an API for managing the configuration. There are many tools that allow to configure an OSGi installation by utilizing this service. For example:

Felix Web Console (unfortunately, at the moment this works only when the bundle provides proper metadata)
OSGi console
Felix File Install: This monitors a folder at runtime. Whenever you drop bundle jars or configuration files in this folder, these are picked up automatically. So you can manage bundles and configure them using simple files in a folder.

Configuration using File Install

To use File Install, get the Felix File Install bundle from the Felix Download page and add it to your repository. Add org.apache.felix.fileinstall and org.apache.felix.configadmin to the list of bundles to run (1).

Create a file org.apache.felix.http.cfg in a new folder load/ to configure the org.apache.felix.http managed service (2). File Install will use this folder by default.

OSGi tutorial: File install and configuration admin

org.apache.felix.http.cfg should contain the following properties:

org.apache.felix.http.enable=false
org.apache.felix.https.enable=true
org.osgi.service.http.port.secure=8443
org.apache.felix.https.keystore=/tmp/jetty_key/keystore
org.apache.felix.https.keystore.password=***

Creating the SSL certificate

Jetty’s SSL connector requires a private key and a certificate in a Java keystore.

The certificate can be left unsigned, the browser will show the certificate as ‘dangerous’ because it is not signed by a trusted CA. For testing this is perfectly ok. If you’re operating a public site, you need to buy a certificate signed by CA that is considered trustworthy by the browsers.

To create the certificate for testing, follow the instructions on HTTPs and Jetty. The only thing to pay attention to is that the CN should equal the domain name and that you should not omit any of the passwords:

> openssl genrsa -des3 -out jetty.key
> openssl req -new -x509 -key jetty.key -out jetty.crt
> openssl pkcs12 -inkey jetty.key -in jetty.crt -export -out jetty.pkcs12
> keytool -keystore keystore -import -alias jetty -file jetty.crt -trustcacerts
> keytool -importkeystore -srckeystore jetty.pkcs12 -srcstoretype PKCS12 -destkeystore keystore

Run the application and open http://localhost:8443/. You should be greeted by an encrypted but not trusted page now:

OSGi tutorial: Browser

Apps

Training (DE)

GIT TRAINING

iOS TRAINING