Getting started

The project code is hosted at github. The development is enviroment is based on the Eclipse Bndtools plugin. If you want to follow the tutorial logic, the easiest way to get started is to clone the repository, checkout branch track1 and then import the projects into a new Eclipse workspace:

git clone https://github.com/Amplifino/nestor
cd nestor
git checkout track1

In order to start we need an OSGI framework implementation. We choose Felix as our reference container, but the examples should also work on Equinox. We add a few standard OSGI services to the bare framework:

• Declarative Services (DS) to publish and consume services
• Config Admin Service allows easy configuration and integrates perfectly with DS
• Metatype Service gives some more information on the configuration parameter of our bundles
• Log Service provides a standardized way to get access to log messages
• Event Admin Service is used to instrument our code and publish events whenever something interesting occurs
• HTTP Service

Note: when deploying servlet based web applications in OSGI one has two options:

• Deploy the servlet as a standard war in a servlet container, and start the OSGI container at web application initialization time. The servlet container will pass incoming HTTP request to the OSGI HTTP Service operating in bridged mode. This approach is often used if one needs to share the HTTP port with other non OSGI servlets. Ironically some servlet containers use OSGI internally without exposing the OSGI API. So you end up with an OSGI container in a servlet container in an OSGI container. It works, and is actually quite popular, but hardly an appealing architecture.
• We will use a standard OSGI container in which we start the HTTP Service. The Felix implementation of the HTTP service wraps an embedded Jetty server with the HTTP service API

Next we need a console to interact with the OSGI framework. We will actually use two, the Gogo (command line) Console and the Apache Felix Web console.

Finally we want to make it easy for bundles to log to the OSGI Log Service.
With Declarative Services it is trivial to reference the log service from a component, but passing the log service reference forward to all objects that need to log is rather cumbersome.
While java.util.logging is probably not the best logging framework, it has the advantage of being accessible from any context.
Hence we create a bundle that adds a handler to java.util.logging's root logger that forwards LogRecords to the OSGI Log Service. By default it will only forward messages with a log level of INFO, but this can be changed using Config Admin. Note that this only configures the handler, not the logger. Loggers have their own level (that also defaults to INFO) and a log message needs to pass both the logger and the handler treshold. Logger log levels can be configured programmatically or through a logging.properties file.

The com.amplifino.nestor.logging.test projects shows how you can create bundle test in Bndtools. To run them select Bnd OSGI Test Launcher (JUnit) from the Run as menu. The required bundles for the test are defined in the bnd.bnd bundle configuration file.

This results in the following bundle list:

• Declarative Services (also known as SCR)
• Config Admin
• Metatype
• Log
• Event Admin
• HTTP Service Bundles
  • HTTP Servlet Api
  • HTTP Service Api
  • HTTP Service Jetty
• Gogo Console Bundles
  • Gogo Runtime
  • Gogo Shell
  • Gogo Command
• Web Console
• A few useful web console plugin bundles:
  • Web Console Declarative Services Plugin
  • Event Admin Plugin
• Amplifino Logging Bridge

The com.amplifino.nestor.logging.test project shows how you can create bundle test in Bndtools. To run them select Bnd OSGI Test Launcher (JUnit) from the Run as menu. The required bundles for the test are defined in the bnd.bnd bundle configuration file. It also contains a runner.bndrun file to start an OSGI container with the above bundle list.