Apache Felix Application Demonstration

(This document is a work in progress.)

Apache Felix provides a foundation for creating modular and dynamically extensible applications. This page presents an example application to demonstrate the various approaches to consider when creating a OSGi/Felix-based application.

Potential Approaches

When creating an OSGi-based application there are two main orthogonal issues to consider:

1. Service vs. extender model
2. On top of vs. embedding the framework instance

The first issue is actually a general issue when creating OSGi-based applications. There are two different general approaches that can be used when creating an extensible OSGi application. The service-based approach uses the OSGi service concept and the service registry as the extensibility mechanism. The extender-based approach uses the OSGi installed bundle set as the extensibility mechanism. Both approaches have their advantages and disadvantages and they can be used independently or together.

The second issue is related to whether your application is run completely on top of the OSGi framework as a set of bundles or whether your application acts as a host for an embedded OSGi framework instance. Creating applications completely as a set of bundles is the preferred approach since it allows the application to run on any OSGi framework, but this it not always possible. In such cases where it is not possible or desired, then you may embed a framework instance inside your application, which will likely tie your application to that framework implementation.

The remainder of this document will present variations of an example application that demonstrates these different approaches.

Example Application Overview

The example application is a very simple drawing program that effectively functions identically whether using services/extensions or running embedded. The application, called the host, defines a SimpleShape service/extension that it uses to draw shapes. Different implementations of the SimpleShape can be created to allow the application to draw different shapes. Each shape service/extension has name and icon properties that the application uses for manipulating the services/extensions. Available shapes are displayed in the applications tool bar. To draw a shape, click on its button in the tool bar and then click in the drawing canvas. Shapes cannot be resized, but they can be dragged around. When new shape services/extensions appear they are automatically added to the tool bar and they are automatically removed when the shape services/extensions disappear. Closing the applications window causes the framework and the JVM to shut down. The following is a screen shot of the application.

Service-Based Application on top of the Framework

Currently, the service-based example application is only available in our SVN repository. There are four separate projects that comprise the application, which can be found here:

http://svn.apache.org/repos/asf/felix/trunk/examples/servicebased.host
http://svn.apache.org/repos/asf/felix/trunk/examples/servicebased.circle
http://svn.apache.org/repos/asf/felix/trunk/examples/servicebased.square
http://svn.apache.org/repos/asf/felix/trunk/examples/servicebased.triangle

Check out each project using an appropriate SVN command, such as:

svn co http://svn.apache.org/repos/asf/felix/trunk/examples/servicebased.host

Once you have the projects checked out you can go into each sub-directory and build it using Maven; this assumes you have Maven properly installed. To build, simply perform the following in each project directory:

mvn clean install

Once you have built the projects, start Felix and then install/start the resulting bundle from the target/ directory of each project directory.

Examine the source code to understand the details of the approach. In the future this documentation will hopefully be expanded to described more details.

Service-Based Application embedding the Framework

The host bundle from the previous section also implements the embedded, service-based approach. The host bundle activator has a static main() method that creates an embedded instance of Felix and loads the shape service bundles. The shape service implementations are the same for both bundle-based and stand-alone applications in this case. To execute the stand-alone application, issue the following command:

java -jar target/servicebased.host-1.0.0.jar

To successfully execute the stand-alone version of the application, you must be in the "servicebased.host" project directory when issuing the above command and you must have already built all of the other projects (i.e., circle, square, triangle).

Examine the source code to understand the details of the approach. In the future this documentation will hopefully be expanded to described more details.

Extender-Based Application on top of the Framework

Currently, the extender-based example application is only available in our SVN repository. There are four separate projects that comprise the application, which can be found here:

http://svn.apache.org/repos/asf/felix/trunk/examples/extenderbased.host
http://svn.apache.org/repos/asf/felix/trunk/examples/extenderbased.circle
http://svn.apache.org/repos/asf/felix/trunk/examples/extenderbased.square
http://svn.apache.org/repos/asf/felix/trunk/examples/extenderbased.triangle

Check out each project using an appropriate SVN command, such as:

svn co http://svn.apache.org/repos/asf/felix/trunk/examples/extenderbased.host

Once you have the projects checked out you can go into each sub-directory and build it using Maven; this assumes you have Maven properly installed. To build, simply perform the following in each project directory:

mvn clean install

Once you have built the projects, start Felix and then install/start the resulting bundle from the target/ directory of each project directory.

Examine the source code to understand the details of the approach. In the future this documentation will hopefully be expanded to described more details.

Extender-Based Application embedding the Framework

The host bundle from the previous section also implements the embedded, extender-based approach. The host bundle activator has a static main() method that creates an embedded instance of Felix and loads the shape extension bundles. The shape extension implementations are the same for both bundle-based and stand-alone applications in this case. To execute the stand-alone application, issue the following command:

java -jar target/extenderbased.host-1.0.0.jar

To successfully execute the stand-alone version of the application, you must be in the "extenderbased.host" project directory when issuing the above command and you must have already built all of the other projects (i.e., circle, square, triangle).

Examine the source code to understand the details of the approach. In the future this documentation will hopefully be expanded to described more details.

Feedback

Subscribe to the Felix users mailing list by sending a message to users-subscribe@felix.apache.org; after subscribing, email questions or feedback to users@felix.apache.org.