Http Whiteboard – Simply Simple – Part III

This is the next part in the series about the OSGi http whiteboard. In my last post I explained how to create an own application servlet context and how to register web components with this context.

Bundle Resources

Doing as outlined in that post, resource handling (the get resource methods on the servlet context) might not work as you expect as you can’t get resources from the bundle where you web component is defined in. If you want this, you need first of all need to register your ServletContextHelper with the service scope Bundle – this ensures that every using bundle gets its own instance of the ServletContextHelper. And with that a servlet from bundle A gets only resources from bundle A, while the servlet from bundle B gets only the resources from that bundle – although they are registered within the same servlet context.

Now using DS this looks a little bit complicated, here is the code:

import java.net.URL;
import java.util.Set;

import org.osgi.service.component.ComponentContext;
import org.osgi.service.component.annotations.Activate;
import org.osgi.service.component.annotations.Component;
import org.osgi.service.component.annotations.ServiceScope;
import org.osgi.service.http.context.ServletContextHelper;
import org.osgi.service.http.whiteboard.HttpWhiteboardConstants;

@Component(
        service = ServletContextHelper.class,
        scope = ServiceScope.BUNDLE,
        property = {
                HttpWhiteboardConstants.HTTP_WHITEBOARD_CONTEXT_NAME + "=" + AppServletContext.NAME,
                HttpWhiteboardConstants.HTTP_WHITEBOARD_CONTEXT_PATH + "=/guessinggame"
        })
public class AppServletContext extends ServletContextHelper {

    public static final String NAME = "game";

    private ServletContextHelper delegatee;

    @Activate
    private void activate(final ComponentContext ctx) {
        delegatee = new ServletContextHelper(ctx.getUsingBundle()) {};
    }

    @Override
    public URL getResource(String name) {
        return delegatee.getResource(name);
    }

    @Override
    public String getMimeType(String name) {
        return delegatee.getMimeType(name);
    }

    @Override
    public Set<String> getResourcePaths(String path) {
        return delegatee.getResourcePaths(path);
    }

    @Override
    public String getRealPath(String path) {
        return delegatee.getRealPath(path);
    }

As you can see in the above example, the ServletContextHelper is registered with the Bundle scope. In order to use the provided functionality of the abstract class ServletContextHelper in the activate method a delegatee is created with the bundle using the ServletContextHelper. The different methods then delegate to the delegatee.

This example looks a little bit complicated, but it is due to the fact that ServletContextHelper only provides to set the bundle through the constructor. And with Declarative Services this is currently a little bit more work to do. But for the upcoming OSGi R7 release, constructor injection is planned, then this should look much cleaner.

Http Whiteboard – Simply Simple – Part II

Developing web components with OSGi can be very simple if you’re using the OSGi Http Whiteboard Specification (see OSGi Compendium Chapter 140). For example the Apache Felix Http Implementation supports this standard.

Building your own Application

With traditional web application development, you usually package your application into its own web application archive (war file) and deploy this into an application server (servlet engine). Each application has its own servlet context and is mounted at some path. You can either mount an application at the root or any other path, e.g. at /my-app.

Using OSGI and the OSGi Http Whiteboard Specification, when you develop a web application you usually but the web components into a bundle and deploy this bundle. Depending on your needs you might also split up the web components into different bundles. But how do you create the equivalent of a servlet context known from web archive deployments?

You can create an own servlet context for your application through the Http Whiteboard. But there is no special deployment format, you simply deploy your app through bundles. And in contrast to traditional webapp deployment, this is leveraging all the well-known OSGi features. And of course source a context is represented through a service.

Let’s start with creating a simple application. The first thing you do is you create your own servlet context. This is done by registering a ServletContextHelper service (again for the examples I’m using Declarative Services and the corresponding annotations):

@Component(
        service = ServletContextHelper.class,
        property = {
                HttpWhiteboardConstants.HTTP_WHITEBOARD_CONTEXT_NAME + "=" + AppServletContext.NAME,
                HttpWhiteboardConstants.HTTP_WHITEBOARD_CONTEXT_PATH + "=/guessinggame"
        }
)
public class AppServletContext extends ServletContextHelper {}

As you can see from the example, ServletContextHelper is not an interface but an abstract class and your implementation gets all the default behaviour by simply extending this class. An abstract class has been chosen over the interface in order to be able to add methods to the service without breaking existing implementations. More important are the two required properties: a unique name and a context paths. The path is equivalent to the context path of a normal web application. The name is used to reference this servlet context. If you want to associate a servlet, resource, servlet filter, or listener to this context, you can do this by adding an additional property to select this context:

@Component(service = Servlet.class,
           property = { HttpWhiteboardConstants.HTTP_WHITEBOARD_SERVLET_PATTERN + "=/game",
                        HttpWhiteboardConstants.HTTP_WHITEBOARD_CONTEXT_SELECT + "=(" + HttpWhiteboardConstants.HTTP_WHITEBOARD_CONTEXT_NAME +"=" + AppServletContext.NAME + ")"})
public class GameServlet extends HttpServlet {...}

The context select property defines a filter expression to select the servlet context. While you can use any filter expression there, it is pretty common to simply filter against the name of the servlet context. If the context select property is missing, your web component is added to the default context.

The path of the servlet context is prepended before the path of the web component, so in the example above the servlet is mounted at “guessinggame/game”.

Building OSGi Bundles with Apache Maven

It seems that still today some developers think that creating an OSGi bundle is complicated – in contrast to simply creating a jar. Well, an OSGi bundle is a jar. The factor which distinguishes the two is that an OSGi bundle has additional manifest entries. Adding those using the right tooling is really simple.

The more difficult part is creating good modules: clearly separating public API from the implementation and correctly version the API based on the changes you made. But this is a general problem not related to OSGi at all and applies to any Java coding. There are some simple guidelines:

  • Leverage packages – put the API in a different package than your implementation. It’s also good still to use a package name for your implementation which makes clear that this is the implementation, e.g. by using impl as one part of the package name.
  • Start private and only make public if necessary. Once something is public, you never can make it private without breaking your clients. Starting private makes things easier.
  • Use semantic versioning. Whenever you change your public API, make sure to correctly increase the package version depending on the type of change you made.

Again, these are general guidelines and have nothing to do with OSGi. But OSGi uses headers in the manifest of your jar to know which packages from inside the jar are public API and the version of those packages. This is the export package header. Packages not listed there are private and not accessible to other modules. The other important header is the import package header, specifying which other packages this module is using. This usually comes with a version range, like a bundle is using package foo.bar version 1.1 or higher up to but not including 2.0.

Therefore, the only required thing to make a bundle out of your jar is more or less calculating these export and import packages headers and adding them to the manifest. But don’t fear, the tooling does this automatically for you. Let’s build a bundle/jar.

Using Apache Maven to Create a OSGi Bundle

There is always the year old debate on which build tool is the best one, I will not get into this discussion. I simply use what I know best and what I’m forced to use anyway: Apache Maven.

By default, Maven is not adding the additional manifest information to the jar, but there are different plugins for Maven available. For this tutorial, I’ll use the newer bnd Maven Plugin from the bnd project.

Add the following two plugin configurations to your pom. It’s usually a good idea to put this into your parent pom:

  <plugin>
     <groupId>biz.aQute.bnd</groupId>
     <artifactId>bnd-maven-plugin</artifactId>
     <version>3.2.0</version>
     <executions>
         <execution>
             <goals>
                <goal>bnd-process</goal>
             </goals>
         </execution>
     </executions>
     <configuration>
         <bnd><![CDATA[
             -exportcontents: ${packages;VERSIONED}
         ]]></bnd>
     </configuration>
 </plugin>
 <plugin>
     <groupId>org.apache.maven.plugins</groupId>
     <artifactId>maven-jar-plugin</artifactId>
     <configuration>
         <useDefaultManifestFile>true</useDefaultManifestFile>
     </configuration>
 </plugin>

The first adds the bnd maven plugin which creates the manifest data and the second instructs the default jar plugin to use the manifest created by the bnd plugin. And that’s it. If you now build your jar project using Maven you’ll have additional manifest entries in there.

Standard OSGi Bundle Headers

The first entries are standard headers which make your jar a bundle and contain some metadata:

  • Bundle-ManifestVersion: This header is required and marks the jar as a bundle, the value is always 2 (newer OSGi specifications might add more features in which case the number would be increased).
  • Bundle-Name: A human readable name for your bundle. This defaults to your project name from the pom.
  • Bundle-SymbolicName: In combination with the bundle version (see below) the symbolic name provides a key to uniquely identify a bundle. This name should be based on the reverse domain name convention and defaults to the artifact id of your project. I’ll talk a little bit more about this soon.
  • Bundle-Version: The version of your bundle, this defaults to the version of your project.

There is no magic in the above entries and having them in your jar does not hurt at all. As mentioned above, the symbolic name should be based on the reverse domain name convention. Usually in the Maven world you follow this rule for your group id, like org.mycompany.myproject and then use a simple name for the artifact id like scheduler-api. However a good practice is to use a full qualified name for the artifact id (which usually means you prefix the artifact id with the group id), e.g. org.mycompany.myproject.scheduler-api. Why is this a good idea? It has nothing to do with OSGi and simply makes sure that the final name of the artifact is fully qualified. If you don’t add the group id to the artifact id, the jar filename would be scheduler-api-1.2.3.jar – which is not very descriptive and gives you no clue what this thing is (and it might clash with other projects using the same artifact id).

The bundle version as any version in software development should increase with continued development/releases. For OSGi this information together with the symbolic name provides a unique key for a bundle and allows OSGi to verify if this exact bundle (name and version) is already installed in the OSGi framework. On a technical level, the bundle version information is more a marketing version.

Public API

More important than versioning your bundle (which still is important), it’s more important to correctly version your public API which might be used by others. For this add the following dependency to your pom:

    <dependency>
        <groupId>org.osgi</groupId>
        <artifactId>osgi.annotation</artifactId>
        <version>1.0.0</version>
        <scope>provided</scoped>
    </dependency>

The above dependency adds some annotations to your project – using the scope “provided” is a good practice as this avoids dragging in transitive dependencies.

Your public API should be in a separate Java package than your implementation – again this is a general good style and not tied to OSGi at all. If you want to export a package to be used by others, add a package-info.java file within your package:

@org.osgi.annotation.versioning.Version("1.0")
package org.osoco.software.samples.guessinggame;

If it’s the first version of your package, simply use 1.0 as the version – from now on once you have released this API as version 1.0, follow semantic versioning. Build your project again and you will see a header similar to this:

Export-Package                org.osoco.software.samples.guessinggame;version="1.0"

As you can see creating the export is really easy, just use the above annotation and done. And the imports are even easier. The plugin analyses your classes and calculates the imports for you. For example for my sample project it looks like this:

Import-Package       javax.servlet;version="[3.1,4)",
                     javax.servlet.http;version="[3.1,4)",
                     org.osoco.software.samples.guessinggame;version="[1.0,1.1)"

And that’s it, your jar is now a bundle and can be used in any OSGi installation as a first class citizen. It’s really simple – and in 96% of your cases the automatic calculation by the tooling is sufficient. There are only rare and special cases where you want to have them differently. In that case, you can configure the plugin accordingly.

Migrating from the Apache Felix SCR Annotations to the OSGi Declarative Services Annotations

The Java annotations of the Apache Felix SCR Plugin were one of the first options to use annotations to create the descriptors for OSGi Declarative Services components and OSGi metatype descriptions for the configuration of such components. With the OSGi R6 release from 2015, the annotations of the OSGi specifications provide the same functionality and go even beyond.

Migrating from the Apache Felix SCR Annotations

Whenever there are competing solutions for the same problem, the question of which one to use arises. In this case, the answer is clear: use the official annotations from the OSGi specifications – for one, they are defined in a standard, but equally important these annotations support all features of Declarative Services R6 – while the Apache Felix annotations only support R5 and it is very unlikely that they will be updated. And that’s the other reason why you should not use the Apache Felix annotations – they are in maintenance mode. Of course, should any bug or problem arise, this will be fixed.

The second question usually is: Should I migrate existing code? There is no need to bulk migrate existing code. As said, the Apache Felix plugin is still maintained, is open source and simply works. However, if you have to touch your code, migrating the annotations might be a good idea. It also gives you the chance to simplify your code by leveraging the R6 features. That said, if you do so, this of course ties your implementation to an R6 implementation of Declarative Services, like Apache Felix SCR, version 2.0 or higher.

Mapping to OSGi Declarative Services Annotations

The below table gives you an overview of how to map the annotations.

Annotation Mapping

Apache Felix SCR AnnotationDescriptionOSGi Declarative Services AnnotationDescription
@ComponentThe @Component annotation marks a Java class to be used as a component.@ComponentThis is more or less a strict one-to-one replacement. Only difference is the default behavior for services. See below.
@ServiceMarks the component as a service and optionally lists the provided services (classes)@ComponentThe OSGi annotation has a service attribute which should be used to list the provided services. Be careful, if your component should not provide any service, set this attribute to an empty array.
@ReferenceReference to services, can be used on unary fields or on class level with bind/unbind methods.@ReferenceField references can directly be migrated, for event based references (methods), the @Reference annotation must be put on the bind method. In addition, more options for field references exist.
@Activate, @Deactivate, and @ModifiedMark a method being the activation, deactivation or modified method@Activate, @Deactivate, and @ModifiedStraight one-to-one migration.
@PropertyConfiguration properties and metatype.Component Property Type and metatype annotationsInstead of using a set of @Property annotations, the configuration is described through an annotation (component property type) and OSGi Metatype annotations can be used to add the metatype info.
Mapping between Apache Felix SCR Annotations and OSGi Declarative Services Annotations

The above table is of course just a short reference. You’ll find more information in the OSGi specifications and in my Declarative Services Tutorials: Part I, Part II, and Part III.

Example OSGi Web Application

In some of my OSGi talks I use the “Guessing Game” as the next great web application to conquer the world. It’s a web app that generates a random number and let’s you guess it, telling you whether you made it, are too high or too low.

You can find the latest sample code on github.

Some slides from the last OSGi Community event featuring this app:

Http Whiteboard – Simply Simple – Part I

Developing web components with OSGi can be very simple if you’re using the OSGi Http Whiteboard Specification (see OSGi Compendium Chapter 140). For example the Apache Felix Http Implementation supports this standard.

In this part of the tutorial we start pretty simple and just look at how to develop a servlet and register it as an active web component. In the next parts we’ll cover more details.

For the example we use Declarative Services (DS) to develop our components. This is the easiest and most elegant way of developing OSGi services and is a standard for OSGi component development (see OSGi Compendium Chapter 112). For a tutorial for Declarative Services see OSGi Components Tutorial.

Registering A Servlet with the Http Whiteboard

Let’s have a look at the typical Hello World Example. The below code registers a servlet which simply prints out Hello World if invoked.

@Component(service = Servlet.class, 
           scope=ServiceScope.PROTOTYPE,
           property= "osgi.http.whiteboard.servlet.pattern=/hello")
public class HelloWorldServlet extends javax.servlet.http.HttpServlet {

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

With the @Component annotation the HelloWorldServlet is registered as a service of type Servlet with a prototype scope. Using the prototype scope for servlets is recommended and we’ll see in another part why. The more important property is osgi.http.whiteboard.servlet.pattern which defines the path under which the servlet is available, /hello in this case. Once deployed into an OSGi application which has support for the OSGi Http Whiteboard specification, this servlet is reachable using /hello from your browser.

And that’s all you have to do. So getting a servlet up and running comes down to using the @Component annotations and specifying the path. Everything else is taken care of and you can focus on implementing your business logic. Of course all the nice features of Declarative Services can be used within your servlet, like the @Reference annotation to use other services.

OSGi Components – Simply Simple – Part III

In the previous two parts (Part I and Part II) you learned how to use Declarative Services to develop your own components and services for OSGi. The topics included:

  • Creating components
  • Component lifecycle
  • Component configuration
  • Using services through references
  • Providing services

In this part we’ll cover another interesting topic:

Metatype Generation

The metatype specification (OSGi Compendium Chapter 105) provides a way to describe the configuration for a component. In general an OSGi configuration is just a dictionary with arbitrary key-value pairs. By defining a metatype description for the configuration, the developer of a component can define which properties together with their type the component expects. Such a metatype information can be used at runtime to generate forms to edit/create the configuration of a component. For example the Apache Felix Web Console does exactly that.

Now if you look at Part II of this series, if a component is configurable it contains already a component annotation for its properties:

public @interface MyComponentConfig {
     
    String welcome_message() default "Hello World!";
 
    int welcome_count() default 3;
 
    boolean output_goodbye() default true;
}

The above annotation already defines all possible properties together with their default values. Therefore the only thing you have to do is provide some human readable information like a label and a description for both, the configuration as a whole and each property. This can be done with some annotations from the metatype specification:

import org.osgi.service.metatype.annotations.AttributeDefinition;
import org.osgi.service.metatype.annotations.ObjectClassDefinition;

@ObjectClassDefinition(name = "Hello World Configuration",
		description = "The configuration for the hello world component.")
public @interface MyComponentConfig {
     
    @AttributeDefinition(name="Welcome Message", description="This message is displayed on startup of the component.")
    String welcome_message() default "Hello World!";
 
    @AttributeDefinition(name="Welcome Message Count", description="This is the number of times, the welcome message will be displayed. " +
                              "If less than one, no message will be displayed.")
    int welcome_count() default 3;
 
    @AttributeDefinition(name="Output Goodbye", description="Set this if the component should output a goodbye message.")
    boolean output_goodbye() default true;
}

The @ObjectClassDefinition annotation is used on the whole configuration annotation and for each attribute, the @AttributeDefinition annotation is used. With these annotations a metatype description for the MyComponentConfig class will be generated. However, we want to bind this configuration to our component which is a different class. Therefore you have to specify the @Designate annotation on your component class:

import org.osgi.service.metatype.annotations.Designate;

@Component
@Designate( ocd = MyComponentConfig.class )
public class MyFirstComponent {
 
    @Activate
    protected void activate( MyComponentConfig config ) {
    ...
}

And this will generate the metatype information for your component. It’s really easy to do such and it helps the user of your component to easily figure out how your component can be configured.

OSGi Components – Simply Simple – Part II

In part I I motivated that developing OSGi components is plain and simple by Declarative Services and the provided annotations. We learned how to create a component, add lifecycle methods and reference services. If you haven’t read the first part yet, make sure to go there first.

Usually a component takes some configuration. So let’s have a look at this next.

Component Configurations

If you want to make your component configurable, the best way of doing this is to leverage the OSGi Configuration Admin (another spec from the OSGi compendium with again a great implementation at Apache Felix). Configuration Admin is a service persisting configurations – these configurations are dictionaries where the key is a string and the value can be one of the simple Java types or an array or collection of such a type. This is usually sufficient for most components.

Configuration Admin nicely abstracts managing the configuration from your component. As a component developer you don’t need to know where the actual configuration is stored and how it ends up there. Without a component container, you would ask the configuration admin for “your” configuration (though there is some injection support through the ManagedService interface) – but fortunately with DS the container takes care of this and provides your component with the configuration. The component might get the configuration as a parameter for the activate method.

As mentioned Configuration Admin stores configurations as dictionaries. Whereas the names are of type String, the value can be any type. While your component might expect an integer, e.g. for a port, the actual value stored might be of type String holding an integer value. Therefore it is good style to not assume a specific type but try to convert whatever you get into the expected type. To avoid putting the burden of doing this on the component developer and to support type safe configurations, the configuration for a component can be described in Java. While the following might look a little bit out of the ordinary, stick with me, you’ll get used to it pretty soon and simply love it.

The way to describe a configuration is by defining an annotation describing all configuration properties. Let’s assume our component has three configuration properties, then the following annotation would do:

public @interface MyComponentConfig {
    
    String welcome_message() default "Hello World!";

    int welcome_count() default 3;

    boolean output_goodbye() default true;
}

Defining an annotation instead of a simple interface has the advantage that we can directly specify default values for each property. If no value for a property is stored in configuration admin, the default value is used. Let’s see how to use this:

import org.osgi.service.component.annotations.Activate;
import org.osgi.service.component.annotations.Component;

@Component
public class MyFirstComponent {

    @Activate
    protected void activate( MyComponentConfig config ) {
        for(int i = 0; i < config.welcome_count(); i++ ) {
            System.out.println(config.welcome_message());
        }
    }
}

When the above component is activated, SCR tries to get a configuration from the configuration admin and converts it into the used annotation type. Therefore the passed in object returns the value in the correct type for each property. As mentioned if there is no value, the default is returned. This makes handling of configurations very simple and avoids all the usual boilerplate code. The OSGi specification for Declarative Services explains in detail how the type conversion is done and what happens if a value can’t be converted. It also defines the conversion rule from the name of a property in the annotation to a property in configuration admin. In the example above we see the underscore in the names, this is acutally converted to a dot in the property name.

Taking configurations is as easy as this: define your set of configuration properties as an annotation and pass it as an argument to the activate method. Of course, if you don’t need configuration, leave out these steps and use the zero argument activate method signature – or if you don’t need the activate method at all, leave it out completely.

With this knowledge we can already develop configurable components capable of using other services. But how do you provide a service for others to be used?

Services

Offering a service usually consists of two steps. First you define the service API and second you implement this API. Of course, in some cases the API might already exist as someone else defined the interface. If you define your own interface, put it into a public package and export this package – however, as already noted above for the component, a service implementation should never be public but in a private package. It depends on your use case, if you put the interface and the implementation in the same bundle or create an API bundle and an implementation bundle. If you’re implementing an existing interface, this usually is already in another bundle and you can just import it. And if you create public API, don’t forget to use proper versioning for these packages. Have a look at the semantic versioning whitepaper!

Offering a service is implementing the corresponding interface and registering the component in the OSGi service registry as the service. With the annotations you can just use the @Component annotation. Assume there is an interface EventHandler and your component should be registered as a service for this interface:

import org.osgi.service.component.annotations.Component;

@Component
public class MyFirstService implements EventHandler {

   ....// implement the EventHandler interface

}

Without further specifying anything at the @Component annotation, a component is registered as a  service for all interfaces it directly implements. In this case this is the EventHandler. While this is very convenient, it comes with the problem, that as soon as your component is implementing an interface directly, it gets registered as this service. In some cases this is not what you want. Therefore I suggest to:

  1. Always explicitely list the service interfaces the component implements:
    @Component(service = EventHandler.class}
  2. As a default always set the service attribute of the component annotations to the empty array. This prevents the automatic registration:
    @Component(service = {})

If you follow these simple rules, you can see directly by looking at the @Component annotation which services this component implements and you avoid accidental service registrations, e.g. when refactoring your implementation.

Lifecycle of a Service

A component which does not provide a service is active for as long as it is satisfied (all referenced services are available and some other conditions we get to later). In contrast, services are instantiated lazy or on demand by DS. This means, as long as no one is using your service, your service is never created nor activated! In most cases this is fine. But there is a catch with this approach one should be aware of: if someone else is starting to use your service, it gets created and activated. As soon as your service is not used anymore, it gets deactivated and destroyed. (The OSGi spec does not mandate this behaviour, it is also possible that your service is kept around for some time until it is disposed. But the current Apache Felix implementation works exactly as described above).

This behaviour might create a performance bottleneck if your service is created/destroyed (very often) for example on each request and/or if your service is doing some computation in the activate method.

To avoid this, you can either think about holding the service by someone else and therefore keep a reference to it around (which in general sounds hacky though there are valid use cases). Or you can use the immediate flag on the @Component:

@Component(service=EventHandler.class, immediate=true)

With immediate set to true, the component is activated as soon as possible and kept as long as possible. Obviously, this increases things like startup time, memory consumption etc. So it should really be used with care and maybe only after problems are encountered in this area. So far, apart from event handlers, we never encountered a real need for using immediate!
If you are implementing an OSGi event handler, service org.osgi.service.event.EventHandler, you should make your service immediate as otherwise it is potentially created/destroyed with each event for this handler! However, even this is up to the implementation of the event admin, the latest Apache Felix event admin implementation and the Equinox event admin implementation do not create/destroy the instance on each request, they rather create it once the first event for this component arrives and keep a reference to it from that point on. But as this is implementation specific, the above advice stands. And again, only use immediate if really required.

And with this the simple introduction to Declarative Services ends: you now know:

  • how to create components
  • how to configure components
  • how to reference services
  • how to provide services

Of course with most of this we only touched the simple case, which is really sufficient for most use cases. I’ll continue this series with more advanced stuff in the future.

OSGi Components – Simply Simple – Part I

There is a lot of prejudice and misunderstanding when it comes to OSGi. As with every technology there is a learning curve and some things might be different than you are used to. But change isn’t necessarily a bad thing.

Component-oriented development is a very common and powerful software engineering style where you assemble your application out of components. A component might offer a service, e.g. a scheduler service. Other components can use this scheduler service.

Or a little bit more formal: a component is a piece of software managed by a (component) container. In Java this means this is an instance, created and managed by a container. Therefore it is not the task of the developer to create or configure these instances. This is the task of the container. If the component uses other services, it is also the task of the container to pass these services to the component. Therefore a service is a component which provides one or more services. In Java this means a service implements one or more interfaces where an interface represents the service description or contract.

OSGi Components with Declarative Services

I will show that developing components with OSGi is really simple and straightforward with no additional cruft – and I think it can’t really get much easier than this. We’ll be using the Declarative Services specification(see OSGi Compendium Chapter 112) in it’s latest version (R6). With the use of the annotations also defined in this specification, components are usually POJOs with all its benefits.

I will not go into the usual tooling discussion – there are different tools out there for your favorite development environment for processing these annotations, like Ant, Maven, Gradle. In contrast to other solutions, all the annotations are build time annotations. They are processed by some tooling and create additional files which are put in the final jar (bundle). I don’t explain everything in every detail and leave out things here and there – it is advisable to read the mentioned specs in addition!

Please note, that using Declarative Services (DS) is one way of developing components and services for OSGi, there are other approaches like Blueprint, Apache Felix iPojo, Apache Felix Dependency Manager etc. Each one of these solutions (including DS) has pros in some areas while it has cons in others. I think, DS is a simple and straightforward way of developing components and its a standard maintained by the OSGi alliance. It’s easy to learn, easy to manage and maintain and provides all required features. However, if you plan to use something different than DS, the real good news is: you can mix and match all these approaches – they’re all based on the OSGi service registry and work well together!

With Declarative Services we have a nice component container managing our components and providing them with configurations and required services. As we’re talking about OSGi here, we’re talking about bundles, so the classes for your component or service go into a bundle. Declarative Services (DS) needs to know which classes are components, what services they might provide etc. Therefore your bundle should contain an XML file for DS which exactly defines this. You might know such XML configuration files from other frameworks – however, the DS format is rather simple and – the good part – you never have to write this by hand and never even have to look at it (ok, if things go wrong, it might sometimes help to check it). At runtime the SCR implementation will read these descriptor files and manage the components and services. Oh, I forgot to explain SCR 🙂 It stands for Service Component Runtime and can be seen as the container defined by DS. Now usually people use SCR and DS as synonyms though that is not quiet correct for the purists amongst us.

So let’s start…

Components

If you want to write a component which is managed by the container, just add the @Component annotation to your class:

package com.mycompany.cool.project.impl;

import org.osgi.service.component.annotations.Component;

@Component
public class MyFirstComponent { }

Build your project, deploy your bundle into an OSGi framework which has SCR running (I recommend the implementation from Apache Felix, version 2.0 or higher) – and your component will be instantiated by the container on bundle start. As a component has never public API but is a private implementation, the class should go into a private package which is not exported by the bundle! It is good style to add impl or similar somewhere in the package name, like com.mycompany.cool.project.impl.

Now, while this component runs and works – it’s not really useful as the component does nothing.

Lifecycle

As noted above, the container manages the lifecycle of the component, its instantiation and removal. In order to make this work, the component class needs the default zero argument constructor. However, if the component wants to do something during the creation or the deletion phase, it can implement an activate and/or deactivate method and mark it with the according annotation:

package com.mycompany.cool.project.impl;

import org.osgi.service.component.annotations.Component;
import org.osgi.service.component.annotations.Activate;
import org.osgi.service.component.annotations.Deactivate;
 
@Component
public class MyFirstComponent {
 
    @Activate
    protected void activate() {
        // do something
    }
 
    @Deactivate
    protected void deactivate() {
        // do something
    }
}

It is good practice to name these methods activate and deactivate – however you could pick any other name if you want. The methods have to be protected with no return value.

Still, we have a component not doing that much, so lets do something “more” usefull:

package com.mycompany.cool.project.impl;

import org.osgi.service.component.annotations.Activate;
import org.osgi.service.component.annotations.Component;
import org.osgi.service.component.annotations.Deactivate;
 
@Component
public class MyFirstComponent {
 
    private volatile boolean doRun;
 
    @Activate
    protected void activate() {
        final Thread t = new Thread() {
            public void run() {
                doIt();
            }
        };
        t.setDaemon(true);
        doRun = true;
        t.start();
    }
 
    private void doIt() {
        while (doRun) {
            System.out.println("I'm still alive!");
            try {
                Thread.sleep(60 * 1000);
            } catch (InterruptedException e) {}
        }
    }
 
    @Deactivate
    protected void deactivate() {
        doRun = false;
    }
}

We create a new thread in activate and start it – in the thread we print out a message every minute. In addition we use a boolean variable to stop the thread when the component gets deactivated. While this example is not a production ready implementation, it shows that the thread of the activate and deactivate method “belong” to the component container – so the component should return as quickly as possible and do not block this method. Therefore we created an own thread. Please note, that this is just an example to demonstrate something, for things like timed execution, you would rather use a scheduler invoking your component periodically instead of running an own thread inside your component. The Apache Sling scheduler is a great way of doing things like these.

Using Services

A single component alone does usually not make up an application – it is rather assembled of dozens if not hundreds of components interacting. And interaction happens by using services.
So let’s extend our example – we use the event admin (another OSGi compendium spec with a great implementation from the Apache Felix project). The event admin is a service which allows us to send out events in a publish/subscrib kind of way. So each event gets a topic, and subscribers subscribe with the topics they are interested in.

A component can use other services by using the @Reference annotation. The container uses dependency injection and injects references into fields:

package com.mycompany.cool.project.impl;
 
import org.osgi.service.component.annotations.Activate;
import org.osgi.service.component.annotations.Component;
import org.osgi.service.component.annotations.Deactivate;
import org.osgi.service.component.annotations.Reference;
import org.osgi.service.event.Event;
import org.osgi.service.event.EventAdmin;
 
@Component
public class MyFirstComponent {
 
    @Reference
    private EventAdmin eventAdmin;
 
    private volatile boolean doRun;
 
    @Activate
    protected void activate() {
        final Thread t = new Thread() {
            public void run() {
                doIt();
            }
        };
        t.setDaemon(true);
        doRun = true;
        t.start();
    }
 
    private void doIt() {
        while (doRun) {
            final Event event = new Event("alive", null);
            this.eventAdmin.sendEvent(event);
            try {
                Thread.sleep(60 * 1000);
            } catch (InterruptedException e) {}
        }
    }
 
    @Deactivate
    protected void deactivate() {
        doRun = false;
    }
}

The above example looks pretty simple and from a developer’s point of view it is simple. You just declare an instance variable with the type of the service you want (services are registered by the interface(s) they implement) and add the @Reference annotation. Before the component is activated (the activate method is called), this instance field is set with the event admin service from the container. Therefore it is safe to assume that the event admin service is available and setup.

As OSGi is highly dynamic, bundles and services can come and go – so the event admin might be there or not, disappear, reappear etc. You don’t really have to care about this (at least not for the moment). Your component is only active if the event admin is available – if not, your component will either not be activated or will get deactivated. We’ll go deeper into references later on and learn how to cope with all the dynamics of services.

With just these four annotations you already know the building blocks for developing OSGi components and services. I suggest you test out the examples and make yourself familiar with using your favorite development environment. Once you are able to successfully build and deploy these components, you’re ready for the cool fun stuff of DS which I will show in part two.

Stay tuned.

Hello world!

It took some time, but my website has a undergone several changes – which hopefully enable me to blog about interesting stuff in the future. The past has not seen frequent updates from me, the main reason (excuse?) being very old software in my web space. I’ve now removed all that stuff and replaced it with something new…

Let’s see how this works